---
read_when:
- Ви хочете аналізувати PDF-файли від агентів
- Вам потрібні точні параметри та обмеження PDF-інструмента
- Ви налагоджуєте нативний режим PDF порівняно з резервним вилученням
summary: Аналізуйте один або кілька PDF-документів із нативною підтримкою провайдера та резервним видобуванням даних
title: Інструмент PDF
x-i18n:
generated_at: "2026-06-27T18:27:38Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 6cce4328a7457f30b8c64abdcfa94b6a5d5649c2bcdfde3187288b11a0e154b1
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`.
Пароль для зашифрованих 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
{
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"
}
```
Зашифрований PDF із резервним витягуванням:
```json
{
"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