> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Інструмент PDF
`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`.
Пароль для зашифрованих PDF у резервному режимі витягування.
Необов’язкове перевизначення моделі у формі `provider/model`.
Обмеження розміру для кожного PDF у МБ. Типове значення — `agents.defaults.pdfMaxBytesMb` або `10`.
Примітки щодо введення:
* `pdf` і `pdfs` об’єднуються та дедуплікуються перед завантаженням.
* Якщо PDF-введення не надано, інструмент повертає помилку.
* `pages` розбирається як номери сторінок із нумерацією від 1, дедуплікується, сортується й обмежується налаштованою максимальною кількістю сторінок.
* `password` застосовується до кожного PDF у запиті та використовується лише резервним режимом витягування.
* `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` не підтримується. Якщо встановлено, інструмент повертає помилку.
* `password` не підтримується. Використовуйте ненативну модель для аналізу зашифрованих PDF.
* Множинне PDF-введення підтримується; кожен PDF надсилається як нативний блок документа /
вбудована PDF-частина перед запитом.
### Резервний режим витягування
Резервний режим використовується для ненативних провайдерів.
Потік:
1. Витягнути текст із вибраних сторінок (до `agents.defaults.pdfMaxPages`, типово `20`).
2. Якщо довжина витягнутого тексту менша за `200` символів, відтворити вибрані сторінки як PNG-зображення та включити їх.
3. Надіслати витягнутий вміст разом із запитом до вибраної моделі.
Деталі резервного режиму:
* Витягування зображень сторінок використовує піксельний бюджет `4,000,000`.
* Зашифровані PDF можна відкрити за допомогою параметра верхнього рівня `password`.
* Якщо цільова модель не підтримує введення зображень і немає тексту, який можна витягнути, інструмент повертає помилку.
* Якщо витягування тексту успішне, але витягування зображень потребувало б зору на
текстовій моделі, OpenClaw відкидає відтворені зображення й продовжує з
витягнутим текстом.
* Резервне витягування використовує вбудований Plugin `document-extract`. Plugin володіє
`clawpdf`, який забезпечує витягування тексту та рендеринг зображень через PDFium
WebAssembly.
## Конфігурація
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "/tmp/report.pdf",
"prompt": "Summarize this report in 5 bullets"
}
```
Кілька PDF:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
"prompt": "Compare risks and timeline changes across both documents"
}
```
Резервна модель із фільтром сторінок:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "https://example.com/report.pdf",
"pages": "1-3,7",
"model": "openai/gpt-5.4-mini",
"prompt": "Extract only customer-impacting incidents"
}
```
Зашифрований PDF із резервним витягуванням:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "/tmp/locked.pdf",
"password": "example-password",
"model": "openai/gpt-5.4-mini",
"prompt": "Summarize this contract"
}
```
## Пов’язане
* [Огляд інструментів](/uk/tools) - усі доступні інструменти агента
* [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) - конфігурація pdfMaxBytesMb і pdfMaxPages