English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

快速开始

PDF 工具

pdf 分析一个或多个 PDF 文档并返回文本。

快速行为：

  • Anthropic 和 Google 模型提供商使用原生提供商模式。
  • 其他提供商使用提取回退模式（先提取文本，必要时再提取页面图像）。
  • 支持单个（pdf）或多个（pdfs）输入，每次调用最多 10 个 PDF。

可用性

只有当 OpenClaw 能为智能体解析出支持 PDF 的模型配置时，才会注册该工具：

  1. agents.defaults.pdfModel
  2. 回退到 agents.defaults.imageModel
  3. 回退到智能体已解析的会话/默认模型
  4. 如果原生 PDF 提供商由凭证支持，则优先于通用图像回退候选项

如果无法解析出可用模型，则不会暴露 pdf 工具。

可用性说明：

  • 回退链会感知凭证。配置的 provider/model 只有在 OpenClaw 确实能为该智能体认证该提供商时才会计入。
  • 当前原生 PDF 提供商是 Anthropic 和 Google。
  • 如果已解析的会话/默认提供商已经配置了视觉/PDF 模型，PDF 工具会先复用该模型，再回退到其他由凭证支持的 提供商。

输入参考

pdfstring

一个 PDF 路径或 URL。

pdfsstring[]

多个 PDF 路径或 URL，总数最多 10 个。

promptstring

分析提示词。

pagesstring

类似 1-5 或 1,3,7-9 的页面过滤器。

modelstring

可选模型覆盖，格式为 provider/model。

maxBytesMbnumber

每个 PDF 的大小上限，单位为 MB。默认值为 agents.defaults.pdfMaxBytesMb 或 10。

输入说明：

  • pdf 和 pdfs 会在加载前合并并去重。
  • 如果未提供 PDF 输入，工具会报错。
  • pages 会按从 1 开始的页码解析、去重、排序，并钳制到配置的最大页数。
  • maxBytesMb 默认值为 agents.defaults.pdfMaxBytesMb 或 10。

支持的 PDF 引用

  • 本地文件路径（包括 ~ 展开）
  • file:// URL
  • http:// 和 https:// URL
  • OpenClaw 管理的入站引用，例如 media://inbound/<id>

引用说明：

  • 其他 URI 方案（例如 ftp://）会被拒绝，并返回 unsupported_pdf_reference。
  • 在沙箱模式下，远程 http(s) URL 会被拒绝。
  • 启用仅工作区文件策略后，允许根目录之外的本地文件路径会被拒绝。
  • 在仅工作区文件策略下，允许使用 OpenClaw 入站媒体存储中的受管入站引用和重放路径。

执行模式

原生提供商模式

提供商为 anthropic 和 google 时会使用原生模式。 该工具会将原始 PDF 字节直接发送到提供商 API。

原生模式限制：

  • 不支持 pages。如果设置了该字段，工具会返回错误。
  • 支持多 PDF 输入；每个 PDF 都会在提示词之前作为原生文档块 / 内联 PDF 部分发送。

提取回退模式

非原生提供商会使用回退模式。

流程：

  1. 从选定页面提取文本（最多 agents.defaults.pdfMaxPages 页，默认 20）。
  2. 如果提取的文本长度少于 200 个字符，则将选定页面渲染为 PNG 图像并包含这些图像。
  3. 将提取内容和提示词发送给选定模型。

回退详情：

  • 页面图像提取使用 4,000,000 的像素预算。
  • 如果目标模型不支持图像输入且没有可提取文本，工具会报错。
  • 如果文本提取成功，但图像提取需要视觉能力，而目标是 纯文本模型，则 OpenClaw 会丢弃渲染图像并继续使用 提取的文本。
  • 提取回退使用内置 document-extract 插件。该插件拥有 pdfjs-dist；仅当图像渲染回退可用时，才会使用 @napi-rs/canvas。

配置

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}

完整字段详情请参阅配置参考。

输出详情

该工具会在 content[0].text 中返回文本，并在 details 中返回结构化元数据。

常见 details 字段：

  • model：已解析的模型引用（provider/model）
  • native：原生提供商模式为 true，回退模式为 false
  • attempts：成功前失败的回退尝试

路径字段：

  • 单个 PDF 输入：details.pdf
  • 多个 PDF 输入：details.pdfs[]，其中包含 pdf 条目
  • 沙箱路径重写元数据（适用时）：rewrittenFrom

错误行为

  • 缺少 PDF 输入：抛出 pdf required: provide a path or URL to a PDF document
  • PDF 过多：在 details.error = "too_many_pdfs" 中返回结构化错误
  • 不支持的引用方案：返回 details.error = "unsupported_pdf_reference"
  • 原生模式下使用 pages：抛出明确的 pages is not supported with native PDF providers 错误

示例

单个 PDF：

{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}

多个 PDF：

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}

带页面过滤器的回退模型：

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Extract only customer-impacting incidents"
}

相关内容