OpenClaw PDF工具使用教程

OpenClaw PDF工具

2026-04-30 29

OpenClaw 提供了专门用于处理 PDF 文档的工具 pdf，可对一个或多个 PDF 文件进行分析并输出文本内容。该工具支持灵活输入、多模型适配以及智能回退机制，能够满足多种文档处理需求。

一、工具能力概览

PDF 工具主要具备以下特点：

支持分析单个或多个 PDF 文档
每次调用最多处理 10 个 PDF
根据模型提供商自动选择处理模式
可输出文本内容及结构化元数据

在不同模型环境下，工具会自动选择最合适的执行方式，以确保分析效果。

二、可用性机制

PDF 工具是否启用，取决于系统是否能够解析可用的模型配置。其优先级如下：

使用 agents.defaults.pdfModel
回退到 agents.defaults.imageModel
再回退到基于当前认证信息可用的默认模型

如果系统无法找到可用模型，则 PDF 工具不会被注册或暴露。

三、输入参数说明

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）：指定模型（可选）
maxBytesMb（number）：单个 PDF 文件大小上限

输入规则说明：

pdf 与 pdfs 会在处理前合并并去重
必须提供至少一个 PDF，否则会报错
页码从 1 开始，自动排序并限制在最大页数范围内
默认大小限制为 10MB（或配置值）

四、支持的 PDF 引用方式

工具支持以下几种 PDF 来源：

本地文件路径（支持 ~ 展开）
file:// URL
http:// 和 https:// URL

限制说明：

不支持 ftp:// 等其他协议
沙箱环境中禁止访问远程 URL
启用工作区限制时，禁止访问外部路径

五、执行模式详解

1. 原生提供商模式

适用于 Anthropic 和 Google 模型。

特点：

直接将 PDF 原始数据发送至模型处理
处理效率更高

限制：

不支持 pages 参数
如果设置页码过滤，会直接报错

2. 提取回退模式

适用于非原生模型，是默认的兼容方案。

执行流程如下：

从指定页面中提取文本（默认最多 20 页）
如果文本少于 200 字符，则将页面渲染为图片
将文本或图片连同提示词发送给模型处理

回退机制说明：

页面图像总像素限制为 400 万
如果模型不支持图像且无法提取文本，则会报错
依赖 pdfjs-dist 和 @napi-rs/canvas

六、配置示例

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

该配置定义了默认模型、文件大小限制以及最大处理页数。

七、输出结果说明

PDF 工具返回两类数据：

文本内容：位于 content[0].text
结构化信息：位于 details 字段

常见字段包括：

model：实际使用的模型
native：是否使用原生模式
attempts：回退尝试次数

路径信息：

单个 PDF：details.pdf
多个 PDF：details.pdfs[]

八、错误处理机制

常见错误情况如下：

未提供 PDF：返回 “pdf required” 错误
PDF 数量超过限制：返回 too_many_pdfs
不支持的引用方式：返回 unsupported_pdf_reference
原生模式使用 pages：直接报错

九、使用示例

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