PDFツール

pdf は1つ以上の 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）を上限として制限されます。範囲内のページに1つも一致しない場合、モデル呼び出し前にエラーになります。

サポートされる PDF リファレンス

• ローカルファイルパス（~ の展開を含む）
• file:// URL
• http:// および https:// URL
• media://inbound/<id> などの OpenClaw 管理の受信リファレンス

その他の 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 Plugin を介して、選択されたページ（agents.defaults.pdfMaxPages、デフォルト 20 まで）からテキストを抽出します。この Plugin はテキストと画像の抽出に 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 入力：pdf エントリを含む details.pdfs[]
• サンドボックスのパス書き換えメタデータ（該当する場合）：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 の設定