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 ツールは認証済みの他の プロバイダーへフォールバックする前にそれを再利用します。

# 入力リファレンス

pdfstring

1つの PDF パスまたは URL。

pdfsstring[]

複数の PDF パスまたは URL。合計で最大 10 個。

promptstring

解析プロンプト。

pagesstring

1-5 または 1,3,7-9 のようなページフィルター。

modelstring

provider/model 形式の任意のモデルオーバーライド。

maxBytesMbnumber

PDF ごとのサイズ上限 (MB)。デフォルトは agents.defaults.pdfMaxBytesMb または 10 です。

入力に関する注記:

• pdf と pdfs は読み込み前にマージされ、重複排除されます。
• PDF 入力が指定されていない場合、ツールはエラーになります。
• pages は 1 始まりのページ番号として解析され、重複排除、ソート、設定済み最大ページ数へのクランプが行われます。
• maxBytesMb のデフォルトは agents.defaults.pdfMaxBytesMb または 10 です。

# サポートされる PDF 参照

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

参照に関する注記:

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

# 実行モード

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

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

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

• pages はサポートされていません。設定されている場合、ツールはエラーを返します。
• 複数 PDF 入力がサポートされています。各 PDF は、プロンプトの前にネイティブドキュメントブロック / インライン PDF パートとして送信されます。

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

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

フロー:

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

フォールバックの詳細:

• ページ画像の抽出では、4,000,000 のピクセル予算を使用します。
• 対象モデルが画像入力をサポートしておらず、抽出可能なテキストもない場合、ツールはエラーになります。
• テキスト抽出に成功しているものの、画像抽出に text-only モデルで vision が必要になる場合、OpenClaw はレンダリングされた画像を破棄し、 抽出されたテキストで続行します。
• 抽出フォールバックは、同梱の document-extract Plugin を使用します。この Plugin が pdfjs-dist を所有します。@napi-rs/canvas は、画像レンダリングフォールバックが 利用可能な場合にのみ使用されます。

# 設定

{
  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"
}

# 関連

• ツール概要 - 利用可能なすべてのエージェントツール
• 設定リファレンス - pdfMaxBytesMb と pdfMaxPages の設定