PDF 工具
pdf 分析一个或多个 PDF 文档并返回文本。它在 Anthropic 和 Google 模型上使用原生文档输入,并为其他所有提供商回退到文本/图像提取。
可用性¶
代理可以在自动模型选择完成之前注册该工具。执行时,模型解析按以下顺序进行:
agents.defaults.pdfModel(显式主模型/回退模型)agents.defaults.imageModel(显式主模型/回退模型)- 来自默认模型提供商的视觉模型,前提是该提供商支持原生 PDF 输入(Anthropic、Google)
- 具有可用认证的自动候选:首选原生 PDF 提供商,然后是支持图像/视觉的提供商以及声明支持 PDF 文本提取的提供商。默认提供商声明的文本提取模型优先于通用图像候选。
- 活动会话模型,如果前面没有候选解析成功,它支持图像,其提供商具有可用认证,并且其提供商未禁用 PDF 图像提取(
documentModels.pdf.image: false)。这包括没有单独pdfModel或imageModel配置的支持视觉的 OpenRouter 模型。
自动候选在选择前会进行认证检查。显式的 PDF/图像设置保留其配置的优先级,并在执行时进行认证。如果延迟解析找不到可用模型,调用会在打开 PDF 之前以 No PDF model configured. 失败。
PDF 分析使用所选模型配置的提供商凭据或已连接账户。它不需要单独的 PDF API 密钥。
输入参考¶
pdfstring(路径)- 单个 PDF 路径或 URL。
pdfsstring[](路径)- 多个 PDF 路径或 URL,总共最多 10 个。
promptstring(路径)默认值:Analyze this PDF document.- 分析提示。
pagesstring(路径)- 页码过滤器,如
1-5或1,3,7-9。在原生提供商模式下不支持。 passwordstring(路径)- 加密 PDF 的密码。应用于请求中的每个 PDF;仅在提取回退模式下使用。
modelstring(路径)- 可选的模型覆盖,格式为
provider/model。 maxBytesMbnumber(路径)- 每个 PDF 的大小上限(MB)。默认为
agents.defaults.pdfMaxMb,如果未设置则为10。
说明:
pdf和pdfs在加载前会合并并去重;至少需要其中一个。pages按从 1 开始的页码解析,去重并排序。agents.defaults.pdfMaxPages(默认20)限制所选页面的数量,而不是页码;如果较大的选择被缩短,PDF 模型和调用模型都会收到部分文档通知。
支持的 PDF 引用¶
- 本地文件路径(包括
~展开) file://URLhttp://和https://URL- OpenClaw 管理的入站引用,例如
media://inbound/<id>
其他 URI 方案(例如 ftp://)返回 details.error = "unsupported_pdf_reference"。当工具在沙箱中运行时,远程 http(s) URL 会被拒绝。启用仅工作区文件策略后,允许根目录之外的本地路径会被拒绝;OpenClaw 入站媒体存储中受管理的入站引用和重放路径仍然允许。
不支持 data: URL。被识别为其他文档类型的文件(例如纯文本或 JSON)会在模型调度之前被拒绝。
相对路径从任务的工作目录解析,包括选定的 Git 工作树。本地读取使用会话已批准的文件系统根目录;参见本地媒体文件。
执行模式¶
原生提供商模式¶
用于提供商 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,请使用非原生模型。
提取回退模式¶
用于所有其他提供商。
- 通过捆绑的
document-extract插件从所选页面(最多agents.defaults.pdfMaxPages,默认20)提取文本,该插件使用clawpdf包(PDFium WebAssembly)进行文本和图像提取。 - 对于每个提取文本少于
200个字符的所选页面,将该页面渲染为 PNG 图像。文本丰富的页面不会抑制其他所选页面的图像回退。渲染预算总计为4,000,000像素,由所有需要图像的页面共享(按每个剩余页面按比例分配,而不是按每个页面分配),因此已经具有足够文本的文本页面会完全跳过渲染。 - 将提取的文本(以及任何渲染的图像)和提示发送给所选模型。
细节:
- 本地提取在可重用 worker 中运行,因此 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,
},
},
}
| 键 | 默认值 | 含义 |
|---|---|---|
agents.defaults.pdfModel |
未设置 | 显式的主/回退 PDF 模型;回退到 imageModel,然后是会话模型。 |
| 键 | 默认值 | 含义 |
|---|---|---|
agents.defaults.pdfMaxMb |
10 |
单个 PDF 的大小上限(单位:MB)。 |
agents.defaults.pdfMaxPages |
20 |
每个 PDF 处理的最大页数。 |
有关完整字段详情,请参阅 配置参考。
输出详情¶
该工具会在 content[0].text 和 details.text 中返回分析结果,因此 Code Mode 和 Tool Search 可以读取相同的结果。
常见的 details 字段:
text:分析文本model:解析后的模型引用(provider/model)native:原生提供商模式为true,回退为falseattempts:成功前失败的回退尝试
路径字段:
- 单个 PDF 输入:
details.pdf - 多个 PDF 输入:
details.pdfs[],包含pdf条目 - 沙箱路径重写元数据(如适用):
rewrittenFrom
错误行为¶
| 条件 | 结果 |
|---|---|
| 无 PDF 输入 | 抛出 pdf required: provide a path or URL to a PDF document |
| 超过 10 个 PDF | details.error = "too_many_pdfs" |
| 不支持的引用方案 | details.error = "unsupported_pdf_reference" |
使用原生提供商时的 pages |
抛出 pages is not supported with native PDF providers |
使用原生提供商时的 password |
抛出 password is not supported with native PDF providers |
示例¶
单个 PDF:
多个 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"
}
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw