PDF 工具

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

可用性

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

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

每個備援候選模型在使用前都會檢查驗證資訊，因此只有當 OpenClaw 能針對該代理向提供者完成驗證時，已設定的 provider/model 才算有效。若無法解析出可用模型，就不會公開 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": "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.4-mini",  "prompt": "Extract only customer-impacting incidents"}

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

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "Summarize this contract"}

相關內容

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