---
read_when:
- Ви хочете аналізувати PDF-файли від агентів
- Потрібні точні параметри й обмеження інструмента pdf
- Ви налагоджуєте режим нативного PDF порівняно з резервним варіантом витягування
summary: Аналізуйте один або кілька PDF-документів із нативною підтримкою провайдера та резервним механізмом вилучення
title: Інструмент для PDF
x-i18n:
generated_at: "2026-05-06T02:05:46Z"
model: gpt-5.5
provider: openai
source_hash: ac1cbbc363975d5571fe5b46b39e2d897e1b80b5859a1f44ef81050f55554444
source_path: tools/pdf.md
workflow: 16
---
`pdf` аналізує один або кілька PDF-документів і повертає текст.
Коротка поведінка:
- Режим нативного провайдера для провайдерів моделей Anthropic і Google.
- Резервний режим вилучення для інших провайдерів (спочатку вилучення тексту, потім зображення сторінок за потреби).
- Підтримує один (`pdf`) або кілька (`pdfs`) вхідних файлів, максимум 10 PDF за виклик.
## Доступність
Інструмент реєструється лише тоді, коли OpenClaw може визначити конфігурацію моделі з підтримкою PDF для агента:
1. `agents.defaults.pdfModel`
2. резервний варіант `agents.defaults.imageModel`
3. резервний варіант визначеної для агента моделі сеансу/моделі за замовчуванням
4. якщо нативні PDF-провайдери мають автентифікаційну підтримку, надавати їм перевагу перед загальними кандидатами резервного варіанта для зображень
Якщо придатну модель не можна визначити, інструмент `pdf` не надається.
Примітки щодо доступності:
- Резервний ланцюжок враховує автентифікацію. Налаштований `provider/model` враховується лише якщо
OpenClaw справді може автентифікувати цього провайдера для агента.
- Нативні PDF-провайдери наразі: **Anthropic** і **Google**.
- Якщо визначений провайдер сеансу/за замовчуванням уже має налаштовану модель для зору/PDF,
інструмент PDF повторно використовує її перед переходом до інших провайдерів
з автентифікаційною підтримкою.
## Довідник вхідних параметрів
Один шлях до PDF або URL.
Кілька шляхів до PDF або URL, загалом до 10.
Промпт для аналізу.
Фільтр сторінок на кшталт `1-5` або `1,3,7-9`.
Необов'язкове перевизначення моделі у формі `provider/model`.
Обмеження розміру для кожного PDF у МБ. За замовчуванням `agents.defaults.pdfMaxBytesMb` або `10`.
Примітки щодо вхідних даних:
- `pdf` і `pdfs` об'єднуються та дедуплікуються перед завантаженням.
- Якщо вхідний PDF не надано, інструмент повертає помилку.
- `pages` розбирається як номери сторінок із нумерацією від 1, дедуплікується, сортується та обмежується налаштованою максимальною кількістю сторінок.
- `maxBytesMb` за замовчуванням дорівнює `agents.defaults.pdfMaxBytesMb` або `10`.
## Підтримувані посилання на PDF
- шлях до локального файлу (включно з розгортанням `~`)
- URL `file://`
- URL `http://` і `https://`
- керовані OpenClaw вхідні посилання, як-от `media://inbound/`
Примітки щодо посилань:
- Інші схеми URI (наприклад, `ftp://`) відхиляються з `unsupported_pdf_reference`.
- У режимі пісочниці віддалені URL `http(s)` відхиляються.
- Коли ввімкнено файлову політику лише для робочого простору, локальні шляхи до файлів поза дозволеними коренями відхиляються.
- Керовані вхідні посилання та відтворені шляхи в сховищі вхідних медіа OpenClaw дозволені за файлової політики лише для робочого простору.
## Режими виконання
### Режим нативного провайдера
Нативний режим використовується для провайдерів `anthropic` і `google`.
Інструмент надсилає необроблені байти PDF безпосередньо до API провайдера.
Обмеження нативного режиму:
- `pages` не підтримується. Якщо задано, інструмент повертає помилку.
- Вхід із кількома PDF підтримується; кожен PDF надсилається як нативний блок документа /
вбудована PDF-частина перед промптом.
### Резервний режим вилучення
Резервний режим використовується для ненативних провайдерів.
Потік:
1. Вилучити текст із вибраних сторінок (до `agents.defaults.pdfMaxPages`, за замовчуванням `20`).
2. Якщо довжина вилученого тексту менша за `200` символів, відрендерити вибрані сторінки в PNG-зображення та включити їх.
3. Надіслати вилучений вміст разом із промптом до вибраної моделі.
Деталі резервного режиму:
- Вилучення зображень сторінок використовує піксельний бюджет `4,000,000`.
- Якщо цільова модель не підтримує вхідні зображення та немає тексту, який можна вилучити, інструмент повертає помилку.
- Якщо вилучення тексту успішне, але вилучення зображень вимагало б зору на
текстовій моделі, OpenClaw відкидає відрендерені зображення та продовжує з
вилученим текстом.
- Резервний режим вилучення використовує вбудований Plugin `document-extract`. Plugin володіє
`pdfjs-dist`; `@napi-rs/canvas` використовується лише коли доступний резервний
рендеринг зображень.
## Конфігурація
```json5
{
agents: {
defaults: {
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
},
},
}
```
Див. [Довідник із конфігурації](/uk/gateway/configuration-reference) для повних деталей полів.
## Деталі виводу
Інструмент повертає текст у `content[0].text` і структуровані метадані в `details`.
Поширені поля `details`:
- `model`: визначене посилання на модель (`provider/model`)
- `native`: `true` для режиму нативного провайдера, `false` для резервного режиму
- `attempts`: резервні спроби, що завершилися невдачею до успіху
Поля шляхів:
- вхід з одним PDF: `details.pdf`
- вхід із кількома PDF: `details.pdfs[]` із записами `pdf`
- метадані переписування шляху пісочниці (коли застосовно): `rewrittenFrom`
## Поведінка помилок
- Вхідний PDF відсутній: викидає `pdf required: provide a path or URL to a PDF document`
- Забагато PDF: повертає структуровану помилку в `details.error = "too_many_pdfs"`
- Непідтримувана схема посилання: повертає `details.error = "unsupported_pdf_reference"`
- Нативний режим із `pages`: викидає зрозумілу помилку `pages is not supported with native PDF providers`
## Приклади
Один PDF:
```json
{
"pdf": "/tmp/report.pdf",
"prompt": "Summarize this report in 5 bullets"
}
```
Кілька PDF:
```json
{
"pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
"prompt": "Compare risks and timeline changes across both documents"
}
```
Резервна модель із фільтром сторінок:
```json
{
"pdf": "https://example.com/report.pdf",
"pages": "1-3,7",
"model": "openai/gpt-5.4-mini",
"prompt": "Extract only customer-impacting incidents"
}
```
## Пов'язане
- [Огляд інструментів](/uk/tools) - усі доступні інструменти агента
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) - конфігурація pdfMaxBytesMb і pdfMaxPages