メインコンテンツへスキップ
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
string
1 つの PDF パスまたは URL。
​
pdfs
string[]
複数の PDF パスまたは URL。合計 10 件まで。
​
prompt
string
デフォルト:"Analyze this PDF document."
解析プロンプト。
​
pages
string
1-5 または 1,3,7-9 のようなページフィルター。ネイティブプロバイダーモードではサポートされません。
​
password
string
暗号化 PDF のパスワード。リクエスト内のすべての PDF に適用されます。抽出フォールバックモードでのみ使用されます。
​
model
string
provider/model 形式の任意のモデルオーバーライド。
​
maxBytesMb
number
PDF ごとのサイズ上限 (MB)。デフォルトは agents.defaults.pdfMaxBytesMb、未設定の場合は 10 です。
注:
  • pdf と pdfs は読み込み前にマージされ、重複排除されます。少なくとも 1 つは必須です。
  • pages は 1 始まりのページ番号として解析され、重複排除、ソートされたうえで agents.defaults.pdfMaxPages (デフォルト 20) に丸められます。範囲内のページに一致しない範囲は、モデル呼び出し前にエラーになります。

​
サポートされる 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,
    },
  },
}
キーデフォルト意味
agents.defaults.pdfModel未設定明示的なプライマリ/フォールバック PDF モデル。imageModel、続いてセッションモデルにフォールバックします。
agents.defaults.pdfMaxBytesMb10PDF ごとのサイズ上限 (MB)。
agents.defaults.pdfMaxPages20PDF ごとに処理される最大ページ数。
すべてのフィールド詳細については、設定リファレンス を参照してください。

​
出力の詳細

ツールは content[0].text にテキストを返し、details に構造化メタデータを返します。 一般的な details フィールド:
  • model: 解決済みモデル参照 (provider/model)
  • native: ネイティブプロバイダーモードの場合は true、フォールバックの場合は false
  • attempts: 成功前に失敗したフォールバック試行
パスフィールド:
  • 単一 PDF 入力: details.pdf
  • 複数 PDF 入力: pdf エントリを持つ details.pdfs[]
  • サンドボックスパス書き換えメタデータ (該当する場合): rewrittenFrom

​
エラー動作

条件結果
PDF 入力なしpdf required: provide a path or URL to a PDF document をスロー
10 件を超える PDFdetails.error = "too_many_pdfs"
サポートされない参照スキームdetails.error = "unsupported_pdf_reference"
ネイティブプロバイダーでの pagespages is not supported with native PDF providers をスロー
ネイティブプロバイダーでの passwordpassword 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"
}

​
関連