跳转至

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(路径)
单个 PDF 路径或 URL。
pdfs string[](路径)
多个 PDF 路径或 URL,总共最多 10 个。
prompt string(路径)默认值:Analyze this PDF document.
分析提示。
pages string(路径)
页码过滤器,如 1-5 或 1,3,7-9。在原生提供商模式下不支持。
password string(路径)
加密 PDF 的密码。应用于请求中的每个 PDF;仅在提取回退模式下使用。
model string(路径)
可选的模型覆盖,格式为 provider/model。
maxBytesMb number(路径)
每个 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 工作树。本地读取使用会话已批准的文件系统根目录;参见本地媒体文件。

执行模式

原生提供商模式

用于提供商 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. 将提取的文本(以及任何渲染的图像)和提示发送给所选模型。

细节:

  • 本地提取在可重用 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,回退为 false
  • attempts:成功前失败的回退尝试

路径字段:

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw