OpenClaw从入门到应用——工具（Tools）：PDF

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

pdf

pdf用于分析一个或多个 PDF 文档并返回文本内容。

快速行为概览：

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

可用性

仅当 OpenClaw 能够为代理解析出支持 PDF 的模型配置时，此工具才会被注册：

1. agents.defaults.pdfModel
2. 回退到agents.defaults.imageModel
3. 回退到基于可用认证的尽力而为的提供商默认值

如果无法解析出可用的模型，则不会公开pdf工具。

输入参考

• pdf（string）：单个 PDF 路径或 URL
• pdfs（string[]）：多个 PDF 路径或 URL，最多总共 10 个
• prompt（string）：分析提示词，默认为Analyze this PDF document.
• pages（string）：页面筛选器，例如1-5或1,3,7-9
• model（string）：可选的模型覆盖（格式为provider/model）
• maxBytesMb（number）：每个 PDF 的大小上限（单位：MB）

输入注意事项：

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

支持的 PDF 引用

• 本地文件路径（包括~展开）
• file://URL
• http://和https://URL

引用注意事项：

• 其他 URI 方案（例如ftp://）会被拒绝，并返回unsupported_pdf_reference。
• 在沙盒模式下，远程http(s)URL 会被拒绝。
• 启用仅工作区文件策略时，位于允许根目录之外的本地文件路径会被拒绝。

执行模式

原生提供商模式

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

原生模式限制：

• 不支持pages。如果设置了pages，工具会返回错误。

提取回退模式

回退模式适用于非原生提供商。

流程：

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

回退模式详情：

• 页面图像提取使用4,000,000的像素预算。
• 如果目标模型不支持图像输入，并且没有可提取的文本，工具会报错。
• 提取回退需要pdfjs-dist（以及用于图像渲染的@napi-rs/canvas）。

配置

{ agents: { defaults: { pdfModel: { primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5-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-mini","prompt":"Extract only customer-impacting incidents"}