PDF tool

pdf analyzes one or more PDF documents and returns text. It uses native document input on Anthropic and Google models, and falls back to text/image extraction for every other provider.

Availability

The agent can register the tool before automatic model selection completes. On execution, model resolution follows this order:

1. agents.defaults.pdfModel (explicit primary/fallbacks)
2. agents.defaults.imageModel (explicit primary/fallbacks)
3. A vision model from the default model's provider, if that provider supports native PDF input (Anthropic, Google)
4. Automatic candidates with usable auth: native-PDF providers first, then image/vision-capable providers and providers declaring PDF text-extraction support. A default provider's declared text-extraction model takes precedence over generic image candidates.
5. The active session model, if no earlier candidate resolves, it supports images, its provider has usable auth, and its provider does not disable PDF image extraction (documentModels.pdf.image: false). This includes vision-capable OpenRouter models without separate pdfModel or imageModel configuration.

Automatic candidates are auth-checked before selection. Explicit PDF/image settings retain their configured precedence and are authenticated at execution. If deferred resolution finds no usable model, the call fails with No PDF model configured. before opening the PDF.

PDF analysis uses the selected model's configured provider credentials or connected account. It does not require a separate PDF API key.

Input reference

Notes:

• pdf and pdfs are merged and deduplicated before loading; at least one is required.
• pages is parsed as 1-based page numbers, deduped, and sorted. agents.defaults.pdfMaxPages (default 20) limits the number of selected pages, not their page numbers; if a larger selection is shortened, both the PDF model and the calling model receive a partial-document notice.

Supported PDF references

• Local file path (including ~ expansion)
• file:// URL
• http:// and https:// URL
• OpenClaw-managed inbound refs such as media://inbound/<id>

Other URI schemes (for example ftp://) return details.error = "unsupported_pdf_reference". Remote http(s) URLs are rejected when the tool runs sandboxed. With workspace-only file policy enabled, local paths outside allowed roots are rejected; managed inbound refs and replayed paths under OpenClaw's inbound media store are still allowed.

data: URLs are unsupported. Files identified as other document types, such as plain text or JSON, are rejected before model dispatch.

Relative paths resolve from the task's working directory, including selected Git worktrees. Local reads use the session's approved filesystem root; see Local media files.

Execution modes

Native provider mode

Used for provider anthropic and google (the only providers that currently declare native PDF document support). Raw PDF bytes go directly to the provider API as a native document/inline-PDF part per file.

Limits:

• pages is not supported; if set, the tool throws pages is not supported with native PDF providers.
• password is not supported; if set, the tool throws password is not supported with native PDF providers. Use a non-native model for encrypted PDFs.

Extraction fallback mode

Used for every other provider.

1. Extract text from the selected pages (up to agents.defaults.pdfMaxPages, default 20) via the bundled document-extract plugin, which uses the clawpdf package (PDFium WebAssembly) for text and image extraction.
2. For each selected page with fewer than 200 characters of extracted text, render that page to a PNG image. A text-rich page does not suppress image fallback for other selected pages. The render budget is 4,000,000 pixels total, shared across all pages needing images (allocated proportionally per remaining page, not per page), so text pages that already have enough text skip rendering entirely.
3. Send the extracted text (and any rendered images) plus the prompt to the selected model.

Details:

• Local extraction runs in a reusable worker so PDF text and image processing do not block the Gateway. Cancelling the agent run stops queued or active extraction.
• Encrypted PDFs open with the top-level password parameter.
• If the model has no image input and there is no extractable text, the tool errors.
• If image rendering fails, OpenClaw drops the images and continues with the extracted text.
• If the target model is text-only and extraction produced images, OpenClaw drops the images and sends text only.
• If page, text, or image limits make extraction partial, OpenClaw includes a short partial-document notice in the analysis context and tool result.

Config

{  agents: {    defaults: {      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-mini"],      },      pdfMaxMb: 10,      pdfMaxPages: 20,    },  },}

See Configuration Reference for full field details.

Output details

The tool returns analysis in both content[0].text and details.text, so Code Mode and Tool Search can read the same result.

Common details fields:

• text: the analysis text
• model: resolved model ref (provider/model)
• native: true for native provider mode, false for fallback
• attempts: fallback attempts that failed before success

Path fields:

• Single PDF input: details.pdf
• Multiple PDF inputs: details.pdfs[] with pdf entries
• Sandbox path rewrite metadata (when applicable): rewrittenFrom

Error behavior

Examples

Single PDF:

{  "pdf": "/tmp/report.pdf",  "prompt": "Summarize this report in 5 bullets"}

Multiple PDFs:

{  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],  "prompt": "Compare risks and timeline changes across both documents"}

Page-filtered fallback model:

{  "pdf": "https://example.com/report.pdf",  "pages": "1-3,7",  "model": "openai/gpt-5.4-mini",  "prompt": "Extract only customer-impacting incidents"}

Encrypted PDF with extraction fallback:

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

Related

• Tools Overview - all available agent tools
• Configuration Reference - pdfMaxMb and pdfMaxPages config