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 tool registers only when OpenClaw can resolve a PDF-capable model for the agent. Resolution order:

1. agents.defaults.pdfModel (explicit primary/fallbacks)
2. agents.defaults.imageModel (explicit primary/fallbacks)
3. The agent's resolved session/default model, if its provider supports native PDF input (Anthropic, Google) or already has a configured vision model
4. Auto-detected image/vision-capable providers with usable auth, preferring native-PDF providers first

Every fallback candidate is auth-checked before use, so a configured provider/model only counts if OpenClaw can authenticate that provider for the agent. If no usable model resolves, the pdf tool is not exposed.

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, sorted, and clamped to agents.defaults.pdfMaxPages (default 20). A range that matches no in-bounds pages errors before the model call.

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.

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. If the extracted text is shorter than 200 characters, render the same pages to 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 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:

• 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.

Config

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

See Configuration Reference for full field details.

Output details

The tool returns text in content[0].text and structured metadata in details.

Common details fields:

• 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 - pdfMaxBytesMb and pdfMaxPages config