使用 OpenClaw PDF 工具：快速解析多份文件內容

處理 PDF 檔案對開發者來說通常很頭痛，尤其是要從中提取乾淨的文字或處理圖片內容。pdf 工具讓你輕鬆分析一個或多個 PDF 文件並獲取文字內容，省去你自己寫解析邏輯的麻煩。

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

快速特性：

• 針對 Anthropic 和 Google 模型供應商提供原生模式 (Native provider mode)。
• 針對其他供應商提供擷取回退模式 (Extraction fallback mode)，先提取文字，必要時再提取頁面圖片。
• 支援單一 (pdf) 或多個 (pdfs) 輸入，每次呼叫最多支援 10 個 PDF。

可用性 (Availability)

只有當 OpenClaw 能為 agent 解析出具備 PDF 處理能力的模型配置時，此工具才會被註冊：

1. agents.defaults.pdfModel
2. 回退至 agents.defaults.imageModel
3. 根據可用的認證資訊，回退至最佳的供應商預設值

如果無法解析出可用的模型，pdf 工具就不會釋出。

輸入參數說明 (Input reference)

• 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 參照方式 (Supported PDF references)

• 本地檔案路徑（包含 ~ 路徑擴充）
• file:// URL
• http:// 和 https:// URL

參照注意事項：

• 其他 URI 方案（例如 ftp://）會被拒絕並回傳 unsupported_pdf_reference。
• 在 sandbox 模式下，遠端 http(s) URL 會被拒絕。
• 若啟用了僅限工作區 (workspace-only) 的檔案政策，位於允許根目錄之外的本地檔案路徑會被拒絕。

執行模式 (Execution modes)

原生供應商模式 (Native provider mode)

原生模式適用於 anthropic 和 google 供應商。 工具會直接將原始 PDF 位元組發送到供應商 API。

原生模式限制：

• 不支援 pages 參數。如果設定了此參數，工具會回傳錯誤。

擷取回退模式 (Extraction fallback mode)

回退模式用於非原生支援的供應商。

流程如下：

1. 從選定的頁面提取文字（最多到 agents.defaults.pdfMaxPages，預設為 20）。
2. 如果提取的文字長度低於 200 個字元，則將選定的頁面渲染為 PNG 圖片並包含在內。
3. 將提取的內容連同提示詞發送給選定的模型。

回退細節：

• 頁面圖片擷取使用 4,000,000 的像素預算。
• 如果目標模型不支援圖片輸入且沒有可提取的文字，工具會報錯。
• 擷取回退模式需要 pdfjs-dist（以及用於圖片渲染的 @napi-rs/canvas）。

配置 (Config)

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

完整欄位細節請參考 Configuration Reference。

輸出細節 (Output details)

工具會在 content[0].text 中回傳文字，並在 details 中回傳結構化元數據。

常見的 details 欄位：

• model: 解析出的模型參照 (provider/model)
• native: 原生供應商模式為 true，回退模式為 false
• attempts: 成功前失敗的回退嘗試次數

路徑欄位：

• 單一 PDF 輸入：details.pdf
• 多個 PDF 輸入：details.pdfs[] 包含各個 pdf 項目
• sandbox 路徑重寫元數據（適用時）：rewrittenFrom

錯誤處理 (Error behavior)

• 缺少 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 錯誤

範例 (Examples)

單一 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"
}

相關連結 (Related)

• Tools Overview — 所有可用的 agent 工具
• Configuration Reference — pdfMaxBytesMb 與 pdfMaxPages 配置

如果你在設定過程中遇到任何問題，可以詢問 AI Setup Assistant 獲取即時幫助。

下一步

• 了解如何配置 Agent Defaults
• 查看 Image Tool 處理其他媒體格式