PDF 工具

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

可用性

仅当 OpenClaw 能够为智能体解析出支持 PDF 的模型时，才会注册此工具。解析顺序如下：

1. agents.defaults.pdfModel（显式指定的主模型/回退模型）
2. agents.defaults.imageModel（显式指定的主模型/回退模型）
3. 智能体解析后的会话模型/默认模型，前提是其提供商支持原生 PDF 输入（Anthropic、Google），或已配置视觉模型
4. 自动检测具有可用身份验证的图像/视觉提供商，并优先选择原生支持 PDF 的提供商

使用前会检查每个回退候选项的身份验证，因此只有当 OpenClaw 能够为该智能体向相应提供商完成身份验证时，已配置的 provider/model 才算有效。如果无法解析出可用模型，则不会公开 pdf 工具。

输入参考

注意：

• 加载前会合并 pdf 和 pdfs 并去重；至少需要提供其中一个。
• pages 会解析为从 1 开始的页码，并进行去重、排序，再限制到 agents.defaults.pdfMaxPages（默认为 20）。如果范围内没有任何有效页码，则会在调用模型前报错。

支持的 PDF 引用

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

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

执行模式

原生提供商模式

用于提供商 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 使用顶层 password 参数打开。
• 如果模型不支持图像输入，且没有可提取的文本，工具会报错。
• 如果图像渲染失败，OpenClaw 会丢弃图像，并继续使用提取的文本。
• 如果目标模型仅支持文本，而提取过程生成了图像，OpenClaw 会丢弃图像，仅发送文本。

配置

{  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": "/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"}

相关内容

• 工具概览 - 所有可用的智能体工具
• 配置参考 - pdfMaxBytesMb 和 pdfMaxPages 配置