PDF 工具

pdf 會分析一或多份 PDF 文件並回傳文字。它在 Anthropic 和 Google 模型上使用原生文件輸入，對其他所有供應商則改用文字／影像擷取。

可用性

只有當 OpenClaw 能為代理程式解析出支援 PDF 的模型時，才會註冊此工具。解析順序如下：

1. agents.defaults.pdfModel（明確指定的主要模型／備援模型）
2. agents.defaults.imageModel（明確指定的主要模型／備援模型）
3. 代理程式解析出的工作階段／預設模型，前提是其供應商支援原生 PDF 輸入（Anthropic、Google），或已設定視覺模型
4. 自動偵測具有可用認證且支援影像／視覺的供應商，優先選用原生支援 PDF 的供應商

每個備援候選模型都會在使用前檢查認證，因此已設定的 provider/model 只有在 OpenClaw 能為代理程式向該供應商進行驗證時才算有效。若無法解析出可用模型，便不會公開 pdf 工具。

輸入參考

注意事項：

• pdf 和 pdfs 會在載入前合併並去除重複項目；至少需要提供其中一項。
• pages 會解析為從 1 開始的頁碼、去除重複、排序，並限制在 agents.defaults.pdfMaxPages（預設為 20）範圍內。若範圍未符合任何界內頁面，會在呼叫模型前發生錯誤。

支援的 PDF 參照

• 本機檔案路徑（包括 ~ 展開）
• file:// URL
• http:// 和 https:// URL
• 由 OpenClaw 管理的傳入參照，例如 media://inbound/<id>

其他 URI 配置（例如 ftp://）會回傳 details.error = "unsupported_pdf_reference"。當工具在沙箱中執行時，會拒絕遠端 http(s) URL。啟用僅限工作區的檔案政策時，會拒絕允許根目錄以外的本機路徑；仍允許受管理的傳入參照，以及 OpenClaw 傳入媒體儲存區下的重播路徑。

執行模式

原生供應商模式

用於供應商 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. 將擷取的文字（以及任何算繪出的影像）連同提示詞傳送至所選模型。

詳細資訊：

• 加密 PDF 會使用頂層 password 參數開啟。
• 若模型不支援影像輸入，且沒有可擷取的文字，工具會發生錯誤。
• 若影像算繪失敗，OpenClaw 會捨棄影像，並繼續使用擷取出的文字。
• 若目標模型僅支援文字，而擷取過程產生了影像，OpenClaw 會捨棄影像，只傳送文字。

設定

{  agents: {    defaults: {      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-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": "/tmp/report.pdf",  "prompt": "以 5 個項目符號摘要這份報告"}

多個 PDF：

{  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],  "prompt": "比較這兩份文件中的風險與時程變更"}

經頁面篩選的備援模型：

{  "pdf": "https://example.com/report.pdf",  "pages": "1-3,7",  "model": "openai/gpt-5.4-mini",  "prompt": "僅擷取影響客戶的事件"}

使用擷取備援模式的加密 PDF：

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "摘要這份合約"}

相關內容

• 工具概覽 - 所有可用的代理程式工具
• 設定參考 - pdfMaxBytesMb 和 pdfMaxPages 設定