PDFツール

pdf は 1 つ以上の PDF ドキュメントを分析し、テキストを返します。

クイック動作:

• Anthropic と Google モデルプロバイダー向けのネイティブプロバイダーモード。
• その他のプロバイダー向けの抽出フォールバックモード (まずテキストを抽出し、必要に応じてページ画像を抽出)。
• 単一 (pdf) または複数 (pdfs) の入力に対応し、1 回の呼び出しにつき最大 10 個の PDF。

利用可否

このツールは、OpenClaw がエージェント用に PDF 対応モデル設定を解決できる場合にのみ登録されます。

1. agents.defaults.pdfModel
2. agents.defaults.imageModel へのフォールバック
3. エージェントの解決済みセッション/デフォルトモデルへのフォールバック
4. ネイティブ PDF プロバイダーが認証に基づく場合、汎用画像フォールバック候補より優先

使用可能なモデルを解決できない場合、pdf ツールは公開されません。

利用可否に関する注記:

• フォールバックチェーンは認証を考慮します。設定済みの provider/model は、 OpenClaw がそのエージェントに対して実際にそのプロバイダーを認証できる場合のみ有効です。
• ネイティブ PDF プロバイダーは現在 Anthropic と Google です。
• 解決済みのセッション/デフォルトプロバイダーに、設定済みの vision/PDF モデルがすでにある場合、PDF ツールは他の認証済みプロバイダーにフォールバックする前にそれを再利用します。

入力リファレンス

入力に関する注記:

• pdf と pdfs は読み込み前にマージされ、重複排除されます。
• PDF 入力が指定されていない場合、ツールはエラーになります。
• pages は 1 始まりのページ番号として解析され、重複排除、ソートされ、設定済みの最大ページ数に制限されます。
• password はリクエスト内のすべての PDF に適用され、抽出フォールバックモードでのみ使用されます。
• maxBytesMb のデフォルトは agents.defaults.pdfMaxBytesMb または 10 です。

対応 PDF 参照

• ローカルファイルパス (~ 展開を含む)
• file:// URL
• http:// および https:// URL
• media://inbound/<id> などの OpenClaw 管理のインバウンド参照

参照に関する注記:

• その他の URI スキーム (例: ftp://) は unsupported_pdf_reference で拒否されます。
• サンドボックスモードでは、リモートの http(s) URL は拒否されます。
• ワークスペース限定ファイルポリシーが有効な場合、許可されたルート外のローカルファイルパスは拒否されます。
• 管理対象のインバウンド参照と、OpenClaw のインバウンドメディアストア配下の再生パスは、ワークスペース限定ファイルポリシーでも許可されます。

実行モード

ネイティブプロバイダーモード

ネイティブモードは、プロバイダー anthropic と google に対して使用されます。 このツールは生の PDF バイトをプロバイダー API に直接送信します。

ネイティブモードの制限:

• pages はサポートされません。設定されている場合、ツールはエラーを返します。
• password はサポートされません。暗号化 PDF を分析するには非ネイティブモデルを使用してください。
• 複数 PDF 入力に対応しています。各 PDF は、プロンプトの前にネイティブドキュメントブロック / インライン PDF パートとして送信されます。

抽出フォールバックモード

フォールバックモードは非ネイティブプロバイダーに対して使用されます。

フロー:

1. 選択されたページからテキストを抽出します (最大 agents.defaults.pdfMaxPages、デフォルト 20)。
2. 抽出されたテキストの長さが 200 文字未満の場合、選択されたページを PNG 画像としてレンダリングして含めます。
3. 抽出されたコンテンツとプロンプトを選択されたモデルに送信します。

フォールバックの詳細:

• ページ画像抽出では 4,000,000 のピクセル予算を使用します。
• 暗号化 PDF はトップレベルの password パラメーターで開けます。
• 対象モデルが画像入力に対応しておらず、抽出可能なテキストもない場合、ツールはエラーになります。
• テキスト抽出には成功したものの、画像抽出によりテキスト専用モデルで vision が必要になる場合、 OpenClaw はレンダリング画像を破棄し、抽出済みテキストで続行します。
• 抽出フォールバックは同梱の document-extract Plugin を使用します。この Plugin は PDFium WebAssembly を通じてテキスト抽出と画像レンダリングを提供する clawpdf を所有します。

設定

{  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 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.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 の設定