PDF 工具

pdf 分析一或多個 PDF 文件並回傳文字。

快速行為說明：

針對 Anthropic 和 Google 模型供應商使用原生供應商模式。
其他供應商使用提取後備模式（先提取文字，需要時再處理頁面圖片）。
支援單一（pdf）或多個（pdfs）輸入，每次呼叫最多 10 個 PDF。

可用條件

此工具僅在 OpenClaw 能為代理解析出支援 PDF 的模型設定時才會註冊：

agents.defaults.pdfModel
後備至 agents.defaults.imageModel
後備至根據可用認證的盡力供應商預設值

若無法解析出可用的模型，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。如果有設定，工具會回傳錯誤。

提取後備模式

後備模式用於非原生供應商。

流程：

從選取的頁面提取文字（最多 agents.defaults.pdfMaxPages 頁，預設 20）。
如果提取的文字長度低於 200 字元，則將選取的頁面渲染為 PNG 圖片一併送出。
將提取的內容加上提示傳送給選定的模型。

後備模式細節：

頁面圖片提取使用 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"
}