PDF tool

analyzes one or more PDF documents and returns text.

Quick behavior:

• Native provider mode for Anthropic and Google model providers.
• Extraction fallback mode for other providers (extract text first, then page images when needed).
• Supports single (
  text

  Copy

  pdf
  ) or multi (
  text

  Copy

  pdfs
  ) input, max 10 PDFs per call.

Availability

The tool is only registered when OpenClaw can resolve a PDF-capable model config for the agent:

1. text

   Copy

   agents.defaults.pdfModel
2. fallback to
   text

   Copy

   agents.defaults.imageModel
3. fallback to the agent's resolved session/default model
4. if native-PDF providers are auth-backed, prefer them ahead of generic image fallback candidates

If no usable model can be resolved, the

tool is not exposed.

Availability notes:

• The fallback chain is auth-aware. A configured
  text

  Copy

  provider/model
  only counts if OpenClaw can actually authenticate that provider for the agent.
• Native PDF providers are currently Anthropic and Google.
• If the resolved session/default provider already has a configured vision/PDF model, the PDF tool reuses that before falling back to other auth-backed providers.

Input reference

One PDF path or URL. Multiple PDF paths or URLs, up to 10 total. Analysis prompt. Page filter like `1-5` or `1,3,7-9`. Optional model override in `provider/model` form. Per-PDF size cap in MB. Defaults to `agents.defaults.pdfMaxBytesMb` or `10`.

Input notes:

• text

  Copy

  pdf
  and
  text

  Copy

  pdfs
  are merged and deduplicated before loading.
• If no PDF input is provided, the tool errors.
• text

  Copy

  pages
  is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
• text

  Copy

  maxBytesMb
  defaults to
  text

  Copy

  agents.defaults.pdfMaxBytesMb
  or
  text

  Copy

  10
  .

Supported PDF references

• local file path (including
  text

  Copy

  ~
  expansion)
• text

  Copy

  file://
  URL
• text

  Copy

  http://
  and
  text

  Copy

  https://
  URL
• OpenClaw-managed inbound refs such as
  text

  Copy

  media://inbound/<id>

Reference notes:

• Other URI schemes (for example
  text

  Copy

  ftp://
  ) are rejected with
  text

  Copy

  unsupported_pdf_reference
  .
• In sandbox mode, remote
  text

  Copy

  http(s)
  URLs are rejected.
• With workspace-only file policy enabled, local file paths outside allowed roots are rejected.
• Managed inbound refs and replayed paths under OpenClaw's inbound media store are allowed with workspace-only file policy.

Execution modes

Native provider mode

Native mode is used for provider

and . The tool sends raw PDF bytes directly to provider APIs.

Native mode limits:

• text

  Copy

  pages
  is not supported. If set, the tool returns an error.
• Multi-PDF input is supported; each PDF is sent as a native document block / inline PDF part before the prompt.

Extraction fallback mode

Fallback mode is used for non-native providers.

Flow:

1. Extract text from selected pages (up to
   text

   Copy

   agents.defaults.pdfMaxPages
   , default
   text

   Copy

   20
   ).
2. If extracted text length is below
   text

   Copy

   200
   chars, render selected pages to PNG images and include them.
3. Send extracted content plus prompt to the selected model.

Fallback details:

• Page image extraction uses a pixel budget of
  text

  Copy

  4,000,000
  .
• If the target model does not support image input and there is no extractable text, the tool errors.
• If text extraction succeeds but image extraction would require vision on a text-only model, OpenClaw drops the rendered images and continues with the extracted text.
• Extraction fallback uses the bundled
  text

  Copy

  document-extract
  plugin. The plugin owns
  text

  Copy

  pdfjs-dist
  ;
  text

  Copy

  @napi-rs/canvas
  is used only when image rendering fallback is available.

Config

json5
Copy
{
  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

and structured metadata in .

Common

fields:

• text

  Copy

  model
  : resolved model ref (
  text

  Copy

  provider/model
  )
• text

  Copy

  native
  :
  text

  Copy

  true
  for native provider mode,
  text

  Copy

  false
  for fallback
• text

  Copy

  attempts
  : fallback attempts that failed before success

Path fields:

• single PDF input:
  text

  Copy

  details.pdf
• multiple PDF inputs:
  text

  Copy

  details.pdfs[]
  with
  text

  Copy

  pdf
  entries
• sandbox path rewrite metadata (when applicable):
  text

  Copy

  rewrittenFrom

Error behavior

• Missing PDF input: throws
  text

  Copy

  pdf required: provide a path or URL to a PDF document
• Too many PDFs: returns structured error in
  text

  Copy

  details.error = "too_many_pdfs"
• Unsupported reference scheme: returns
  text

  Copy

  details.error = "unsupported_pdf_reference"
• Native mode with
  text

  Copy

  pages
  : throws clear
  text

  Copy

  pages is not supported with native PDF providers
  error

Examples

Single PDF:

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

Multiple PDFs:

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

Page-filtered fallback model:

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

Related

• Tools Overview — all available agent tools
• Configuration Reference — pdfMaxBytesMb and pdfMaxPages config