PDF Tool: Analyze Documents with Native Provider Support

pdf takes one or more PDF files and returns their textual content. For Anthropic and Google models it uses native document input, while for all other providers it falls back to text and image extraction.

Availability

This tool is registered only when OpenClaw can identify a PDF-capable model for the agent. The resolution follows this order:

1. agents.defaults.pdfModel (explicit primary and fallback models)
2. agents.defaults.imageModel (explicit primary and fallback models)
3. The agent's resolved session or default model, provided its provider supports native PDF input (Anthropic, Google) or already has a configured vision model
4. Auto-detected image and vision-capable providers with usable authentication, prioritizing native-PDF providers

Every fallback candidate undergoes authentication checks before use, so a configured provider/model counts only if OpenClaw can authenticate that provider for the agent. If no usable model resolves, the pdf tool remains unavailable.

Input reference

• pdf (string), A single PDF file path or URL.

• pdfs (string[]), Multiple PDF paths or URLs, with a maximum of 10.

• prompt (string, default: Analyze this PDF document.), The prompt used for analysis.

• pages (string), A page filter such as 1-5 or 1,3,7-9. Not available in native provider mode.

• password (string), Password for encrypted PDFs. Applies to all PDFs in the request and works only in extraction fallback mode.

• model (string), Optional model override formatted as provider/model.

• maxBytesMb (number), Size cap per PDF in MB. Defaults to agents.defaults.pdfMaxMb, or 10 when not specified.

Notes:

• pdf and pdfs are merged and deduplicated before loading; at least one must be provided.
• pages is interpreted as 1-based page numbers, deduplicated, sorted, and clamped to agents.defaults.pdfMaxPages (default 20). A range that matches no valid pages produces an error before the model call.

Supported PDF references

• Local file path (including ~ expansion)
• file:// URL
• http:// and https:// URL
• OpenClaw-managed inbound references like 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 in sandboxed mode. With workspace-only file policy enabled, local paths outside allowed roots are rejected, though managed inbound references and replayed paths under OpenClaw's inbound media store remain permitted.

Execution modes

Native provider mode

Used for provider anthropic and google, the only providers that currently support native PDF document input. Raw PDF bytes are sent directly to the provider API as a native document or inline-PDF part per file.

Limits:

• pages is unsupported; setting it causes the tool to throw pages is not supported with native PDF providers.
• password is unsupported; setting it causes the tool to throw password is not supported with native PDF providers. For encrypted PDFs, use a non-native model instead.

Extraction fallback mode

Used for all other providers.

1. Text is extracted from the selected pages (up to agents.defaults.pdfMaxPages, default 20) using the bundled document-extract plugin, which relies on the clawpdf package (PDFium WebAssembly) for both text and image extraction.
2. If the extracted text is shorter than 200 characters, the same pages are rendered as PNG images. The render budget is 4,000,000 pixels total, shared across all pages needing images (allocated proportionally per remaining page, not per page), so pages with sufficient text skip rendering entirely.
3. The extracted text (and any rendered images) along with the prompt are sent to the selected model.

Details:

• Encrypted PDFs are opened using the top-level password parameter.
• If the model lacks image input and no text can be extracted, the tool produces an error.
• If image rendering fails, OpenClaw discards the images and proceeds with the extracted text.
• If the target model is text-only and extraction generated images, OpenClaw discards the images and sends only text.

Config

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

See Configuration Reference for complete field details.

Output details

The tool produces text content as content[0].text and organized metadata as details.

Frequently used details fields:

• model: the final model reference (provider/model)
• native: true when using the native provider, false when fallback is active
• attempts: number of fallback attempts that failed before a successful one

Path-related fields:

• For a single PDF input: details.pdf
• For multiple PDF inputs: details.pdfs[] containing pdf entries
• Sandbox path rewrite metadata (if present): rewrittenFrom

Error behavior

Examples

Working with one PDF:

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

Working with multiple PDFs:

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

Fallback model filtered by page:

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

Encrypted PDF using extraction fallback:

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

Related

• Tools Overview - describes every agent tool
• Configuration Reference - explains pdfMaxBytesMb and pdfMaxPages settings