File size: 4,484 Bytes
fc93158 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | ---
title: "PDF Tool"
summary: "Analyze one or more PDF documents with native provider support and extraction fallback"
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 tool
`pdf` 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 (`pdf`) or multi (`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. `agents.defaults.pdfModel`
2. fallback to `agents.defaults.imageModel`
3. fallback to best effort provider defaults based on available auth
If no usable model can be resolved, the `pdf` tool is not exposed.
## Input reference
- `pdf` (`string`): one PDF path or URL
- `pdfs` (`string[]`): multiple PDF paths or URLs, up to 10 total
- `prompt` (`string`): analysis prompt, default `Analyze this PDF document.`
- `pages` (`string`): page filter like `1-5` or `1,3,7-9`
- `model` (`string`): optional model override (`provider/model`)
- `maxBytesMb` (`number`): per-PDF size cap in MB
Input notes:
- `pdf` and `pdfs` are merged and deduplicated before loading.
- If no PDF input is provided, the tool errors.
- `pages` is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
- `maxBytesMb` defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
## Supported PDF references
- local file path (including `~` expansion)
- `file://` URL
- `http://` and `https://` URL
Reference notes:
- Other URI schemes (for example `ftp://`) are rejected with `unsupported_pdf_reference`.
- In sandbox mode, remote `http(s)` URLs are rejected.
- With workspace-only file policy enabled, local file paths outside allowed roots are rejected.
## Execution modes
### Native provider mode
Native mode is used for provider `anthropic` and `google`.
The tool sends raw PDF bytes directly to provider APIs.
Native mode limits:
- `pages` is not supported. If set, the tool returns an error.
### Extraction fallback mode
Fallback mode is used for non-native providers.
Flow:
1. Extract text from selected pages (up to `agents.defaults.pdfMaxPages`, default `20`).
2. If extracted text length is below `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 `4,000,000`.
- If the target model does not support image input and there is no extractable text, the tool errors.
- Extraction fallback requires `pdfjs-dist` (and `@napi-rs/canvas` for image rendering).
## Config
```json5
{
agents: {
defaults: {
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5-mini"],
},
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
},
},
}
```
See [Configuration Reference](/gateway/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
- Missing PDF input: throws `pdf required: provide a path or URL to a PDF document`
- Too many PDFs: returns structured error in `details.error = "too_many_pdfs"`
- Unsupported reference scheme: returns `details.error = "unsupported_pdf_reference"`
- Native mode with `pages`: throws clear `pages is not supported with native PDF providers` error
## 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-mini",
"prompt": "Extract only customer-impacting incidents"
}
```
|