--- read_when: - Ви хочете аналізувати PDF-файли від агентів - Вам потрібні точні параметри та обмеження інструмента для роботи з PDF - Ви налагоджуєте нативний режим PDF порівняно з резервним вилученням даних summary: Аналіз одного або кількох PDF-документів із нативною підтримкою провайдера та резервним вилученням даних title: Інструмент PDF x-i18n: generated_at: "2026-07-12T13:47:55Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 54bde94a2b70fd209c70c13a1e75dc81c6cbebca7f6d56776bf37fa62cd78254 source_path: tools/pdf.md workflow: 16 --- `pdf` аналізує один або кілька PDF-документів і повертає текст. Для моделей Anthropic і Google він використовує нативне введення документів, а для всіх інших провайдерів переходить до резервного вилучення тексту та зображень. ## Доступність Інструмент реєструється лише тоді, коли OpenClaw може визначити для агента модель із підтримкою PDF. Порядок визначення: 1. `agents.defaults.pdfModel` (явно задані основна й резервні моделі) 2. `agents.defaults.imageModel` (явно задані основна й резервні моделі) 3. Визначена для сеансу/за замовчуванням модель агента, якщо її провайдер підтримує нативне введення PDF (Anthropic, Google) або вже має налаштовану модель із підтримкою зображень 4. Автоматично виявлені провайдери з підтримкою зображень/комп’ютерного зору та придатною автентифікацією, з пріоритетом для провайдерів із нативною підтримкою PDF Для кожної резервної моделі-кандидата перед використанням перевіряється автентифікація, тому налаштована `provider/model` враховується лише тоді, коли OpenClaw може автентифікувати цього провайдера для агента. Якщо придатну модель визначити неможливо, інструмент `pdf` не надається. ## Довідник вхідних параметрів Один шлях до PDF або URL-адреса. Кілька шляхів до PDF або URL-адрес, загалом до 10. Промпт для аналізу. Фільтр сторінок на кшталт `1-5` або `1,3,7-9`. Не підтримується в нативному режимі провайдера. Пароль для зашифрованих PDF. Застосовується до кожного PDF у запиті; використовується лише в резервному режимі вилучення. Необов’язкове перевизначення моделі у форматі `provider/model`. Обмеження розміру кожного PDF у МБ. Типове значення — `agents.defaults.pdfMaxBytesMb` або `10`, якщо його не задано. Примітки: - `pdf` і `pdfs` об’єднуються, а дублікати видаляються перед завантаженням; потрібно вказати принаймні один із них. - `pages` розбирається як нумерація сторінок від 1; дублікати видаляються, номери сортуються, а їхня кількість обмежується значенням `agents.defaults.pdfMaxPages` (типово `20`). Якщо діапазон не містить жодної сторінки в допустимих межах, помилка виникає до виклику моделі. ## Підтримувані посилання на PDF - Шлях до локального файлу (зокрема з розгортанням `~`) - URL-адреса `file://` - URL-адреса `http://` або `https://` - Керовані OpenClaw вхідні посилання, як-от `media://inbound/` Інші схеми URI (наприклад, `ftp://`) повертають `details.error = "unsupported_pdf_reference"`. Віддалені URL-адреси `http(s)` відхиляються, коли інструмент працює в пісочниці. Якщо ввімкнено політику доступу до файлів лише в робочому просторі, локальні шляхи поза дозволеними кореневими каталогами відхиляються; керовані вхідні посилання та повторно використані шляхи в сховищі вхідних медіафайлів OpenClaw усе одно дозволені. ## Режими виконання ### Нативний режим провайдера Використовується для провайдерів `anthropic` і `google` (єдиних провайдерів, які наразі заявляють про нативну підтримку PDF-документів). Необроблені байти PDF передаються безпосередньо до API провайдера як нативна частина документа або вбудованого PDF для кожного файлу. Обмеження: - `pages` не підтримується; якщо параметр задано, інструмент видає помилку `pages is not supported with native PDF providers`. - `password` не підтримується; якщо параметр задано, інструмент видає помилку `password is not supported with native PDF providers`. Для зашифрованих PDF використовуйте модель без нативної підтримки. ### Резервний режим вилучення Використовується для всіх інших провайдерів. 1. Вилучає текст із вибраних сторінок (до `agents.defaults.pdfMaxPages`, типово `20`) через вбудований Plugin `document-extract`, який використовує пакет `clawpdf` (PDFium WebAssembly) для вилучення тексту та зображень. 2. Якщо вилучений текст коротший за `200` символів, перетворює ті самі сторінки на PNG-зображення. Загальний бюджет візуалізації становить `4,000,000` пікселів і розподіляється між усіма сторінками, для яких потрібні зображення (пропорційно для кожної сторінки, що залишилася, а не окремо для кожної сторінки), тому сторінки, з яких уже вилучено достатньо тексту, взагалі не візуалізуються. 3. Надсилає вилучений текст (і всі візуалізовані зображення) разом із промптом вибраній моделі. Подробиці: - Зашифровані PDF відкриваються за допомогою параметра верхнього рівня `password`. - Якщо модель не підтримує введення зображень і текст неможливо вилучити, інструмент повертає помилку. - Якщо візуалізація зображень не вдається, OpenClaw відкидає зображення й продовжує роботу з вилученим текстом. - Якщо цільова модель підтримує лише текст, а під час вилучення створено зображення, OpenClaw відкидає зображення й надсилає лише текст. ## Конфігурація ```json5 { agents: { defaults: { pdfModel: { primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, pdfMaxBytesMb: 10, pdfMaxPages: 20, }, }, } ``` | Ключ | Типове значення | Значення | | ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- | | `agents.defaults.pdfModel` | не задано | Явно задані основна й резервні моделі PDF; якщо їх немає, використовується `imageModel`, а потім модель сеансу. | | `agents.defaults.pdfMaxBytesMb` | `10` | Обмеження розміру кожного PDF у МБ. | | `agents.defaults.pdfMaxPages` | `20` | Максимальна кількість сторінок, що обробляються в кожному PDF. | Повний опис полів див. у [довіднику з конфігурації](/uk/gateway/config-agents#agent-defaults). ## Подробиці виведення Інструмент повертає текст у `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` | | Понад 10 PDF | `details.error = "too_many_pdfs"` | | Непідтримувана схема посилання | `details.error = "unsupported_pdf_reference"` | | `pages` із нативним провайдером | Видає `pages is not supported with native PDF providers` | | `password` із нативним провайдером | Видає `password 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`