PDF 工具（PDF 文档分析）

概述

pdf 工具分析一个或多个 PDF 文档并返回文本。支持原生 provider 模式（Anthropic、Google）和提取回退模式（其他 provider）。每次调用最多处理 10 个 PDF。工具仅在能解析到 PDF 能力模型配置时才注册。

核心功能

两种执行模式

原生 provider 模式（Anthropic、Google）：

• 直接将 PDF 字节发送给 provider API
• 不支持 pages 参数
• 支持多 PDF 输入

提取回退模式（其他 provider）：

1. 从选定页面提取文本（最多 pdfMaxPages，默认 20 页）
2. 若提取文本 < 200 字符，渲染页面为 PNG 图像
3. 将提取内容 + prompt 发送给选定模型

支持的 PDF 引用格式

• 本地文件路径（支持 ~ 展开）
• file:// URL
• http:// 和 https:// URL
• OpenClaw 管理的入站 ref（media://inbound/<id>）

模型解析顺序

1. agents.defaults.pdfModel
2. 回退到 agents.defaults.imageModel
3. 回退到 Agent 的会话/默认模型
4. 若原生 PDF provider 有认证，优先于通用图像回退候选

配置/权限

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

沙箱限制：沙箱模式下拒绝远程 http(s) URL；启用 workspace-only 文件策略时，工作区外的本地路径被拒绝。

工具参数：

• pdf / pdfs：单个或多个 PDF 路径/URL
• prompt：分析提示（默认 “Analyze this PDF document.“）
• pages：页面过滤（如 1-5 或 1,3,7-9，1-based）
• model：可选模型覆盖（provider/model 格式）
• maxBytesMb：per-PDF 大小上限（MB）

相关页面

• models — 模型配置与故障转移
• tool-image-generation — 图像生成工具（PDF 图像回退依赖视觉模型）