openclaw/docs/tools/pdf.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Analyze one or more PDF documents with native provider support and extraction fallback"
title: "PDF tool"
read_when:
  - You want to analyze PDFs from agents
  - You need exact pdf tool parameters and limits
  - You are debugging native PDF mode vs extraction fallback
---

`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

<ParamField path="pdf" type="string">
One PDF path or URL.
</ParamField>

<ParamField path="pdfs" type="string[]">
Multiple PDF paths or URLs, up to 10 total.
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
Analysis prompt.
</ParamField>

<ParamField path="pages" type="string">
Page filter like `1-5` or `1,3,7-9`. Not supported in native provider mode.
</ParamField>

<ParamField path="password" type="string">
Password for encrypted PDFs. Applies to every PDF in the request; only used by extraction fallback mode.
</ParamField>

<ParamField path="model" type="string">
Optional model override in `provider/model` form.
</ParamField>

<ParamField path="maxBytesMb" type="number">
Per-PDF size cap in MB. Defaults to `agents.defaults.pdfMaxMb`, or `10` if unset.
</ParamField>

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](/tools/media-overview#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

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

| Key                           | Default | Meaning                                                                                   |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `agents.defaults.pdfModel`    | unset   | Explicit primary/fallback PDF models; falls back to `imageModel`, then the session model. |
| `agents.defaults.pdfMaxMb`    | `10`    | Per-PDF size cap in MB.                                                                   |
| `agents.defaults.pdfMaxPages` | `20`    | Max pages processed per PDF.                                                              |

See [Configuration Reference](/gateway/config-agents#agent-defaults) for full field details.

## Output details

The tool returns analysis in both `content[0].text` and `details.text`, so [Code Mode](/tools/code-mode) and [Tool Search](/tools/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

| Condition                         | Result                                                         |
| --------------------------------- | -------------------------------------------------------------- |
| No PDF input                      | Throws `pdf required: provide a path or URL to a PDF document` |
| More than 10 PDFs                 | `details.error = "too_many_pdfs"`                              |
| Unsupported reference scheme      | `details.error = "unsupported_pdf_reference"`                  |
| `pages` with a native provider    | Throws `pages is not supported with native PDF providers`      |
| `password` with a native provider | Throws `password is not supported with native PDF providers`   |

## Examples

Single PDF:

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

Multiple PDFs:

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

Page-filtered fallback model:

```json
{
  "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:

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

## Related

- [Tools Overview](/tools) - all available agent tools
- [Configuration Reference](/gateway/config-agents#agent-defaults) - `pdfMaxMb` and `pdfMaxPages` config