PDF 工具

pdf 分析一个或多个 PDF 文档并返回文本。它在 Anthropic 和 Google 模型上使用原生文档输入，并对其他所有提供商回退到文本/图像提取。

可用性¶

代理可以在自动模型选择完成之前注册该工具。执行时，模型解析遵循以下顺序：

1. agents.defaults.pdfModel（显式主/回退）
2. agents.defaults.imageModel（显式主/回退）
3. 来自默认模型提供商的视觉模型，如果该提供商支持原生 PDF 输入（Anthropic、Google）
4. 具有可用身份验证的自动候选项：原生 PDF 提供商优先，然后是支持图像/视觉的提供商以及声明支持 PDF 文本提取的提供商。默认提供商声明的文本提取模型优先于通用图像候选项。
5. 当前会话模型，如果没有更早的候选项解析成功，它支持图像，其提供商具有可用身份验证，并且其提供商未禁用 PDF 图像提取（documentModels.pdf.image: false）。这包括未单独配置 pdfModel 或 imageModel 的具有视觉能力的 OpenRouter 模型。

自动候选项在选择前会进行身份验证检查。显式 PDF/图像设置保留其配置的优先级，并在执行时进行身份验证。如果延迟解析找不到可用模型，调用会在打开 PDF 之前以 No PDF model configured. 失败。

PDF 分析使用所选模型配置的提供商凭据或已连接账户。它不需要单独的 PDF API 密钥。

输入参考¶

pdf string (path)

一个 PDF 路径或 URL。

pdfs string[] (path)

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

prompt string (path) 默认：Analyze this PDF document.

分析提示词。

pages string (path)

页面过滤器，例如 1-5 或 1,3,7-9。原生提供商模式不支持。

password string (path)

加密 PDF 的密码。适用于请求中的每个 PDF；仅由提取回退模式使用。

model string (path)

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

maxBytesMb number (path)

每个 PDF 的大小上限（MB）。默认为 agents.defaults.pdfMaxMb，未设置时为 10。

注意：

• pdf 和 pdfs 在加载前合并并去重；至少需要其中一个。
• pages 解析为从 1 开始的页码，去重并排序。agents.defaults.pdfMaxPages（默认 20）限制所选页面的数量，而不是页码；如果较大的选择被截短，PDF 模型和调用模型都会收到部分文档通知。

支持的 PDF 引用¶

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

其他 URI 方案（例如 ftp://）返回 details.error = "unsupported_pdf_reference"。当工具在沙箱中运行时，会拒绝远程 http(s) URL。启用仅限工作区的文件策略后，允许根目录之外的本地路径会被拒绝；OpenClaw 入站媒体存储下的受管入站引用和重放路径仍然允许。

data: URL 不受支持。被识别为其他文档类型的文件（例如纯文本或 JSON）会在模型分发前被拒绝。

相对路径从任务的工作目录解析，包括所选的 Git worktree。本地读取使用会话已批准的文件系统根目录；参见 本地媒体文件。

执行模式¶

原生提供商模式¶

用于提供商 anthropic 和 google（目前唯一声明支持原生 PDF 文档的提供商）。每个文件的原始 PDF 字节会作为原生文档/内联 PDF 部分直接发送到提供商 API。

限制：

• pages 不受支持；如果设置，工具会抛出 pages is not supported with native PDF providers。
• password 不受支持；如果设置，工具会抛出 password is not supported with native PDF providers。对加密 PDF 使用非原生模型。

提取回退模式¶

用于其他所有提供商。

1. 通过捆绑的 document-extract 插件从所选页面提取文本（最多 agents.defaults.pdfMaxPages，默认 20），该插件使用 clawpdf 包（PDFium WebAssembly）进行文本和图像提取。
2. 对于每个提取文本少于 200 个字符的所选页面，将该页面渲染为 PNG 图像。文本丰富的页面不会抑制其他所选页面的图像回退。渲染预算总计为 4,000,000 像素，在所有需要图像的页面之间共享（按剩余页面比例分配，而不是按页面分配），因此已有足够文本的文本页面会完全跳过渲染。
3. 将提取的文本（以及任何渲染的图像）加上提示词发送到所选模型。

详情：

• 本地提取在可复用工作线程中运行，因此 PDF 文本和图像处理不会阻塞 Gateway。取消代理运行会停止排队中或正在进行的提取。
• 加密 PDF 使用顶层 password 参数打开。
• 如果模型没有图像输入且没有可提取的文本，工具会报错。
• 如果图像渲染失败，OpenClaw 会丢弃图像并继续使用提取的文本。
• 如果目标模型仅支持文本且提取生成了图像，OpenClaw 会丢弃图像并仅发送文本。
• 如果页面、文本或图像限制导致提取不完整，OpenClaw 会在分析上下文和工具结果中包含简短的部分文档通知。

配置¶

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

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

输出详情¶

该工具会在 content[0].text 和 details.text 中返回分析结果，因此 Code Mode 和 Tool Search 可以读取相同的结果。

常见的 details 字段：

• text：分析文本
• model：解析后的模型引用（provider/model）
• native：原生提供商模式为 true，回退模式为 false
• attempts：成功之前失败的回退尝试次数

路径字段：

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

错误行为¶

示例¶

单个 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"
}

带提取回退的加密 PDF：

{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}

相关¶

• 工具概览 - 所有可用的代理工具
• 配置参考 - pdfMaxMb 和 pdfMaxPages 配置