Інструмент PDF

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 і pdfs об’єднуються, а дублікати видаляються перед завантаженням; потрібно вказати принаймні один із них.
• pages розбирається як нумерація сторінок від 1; дублікати видаляються, номери сортуються, а їхня кількість обмежується значенням agents.defaults.pdfMaxPages (типово 20). Якщо діапазон не містить жодної сторінки в допустимих межах, помилка виникає до виклику моделі.

Підтримувані посилання на PDF

• Шлях до локального файлу (зокрема з розгортанням ~)
• URL-адреса file://
• URL-адреса http:// або https://
• Керовані OpenClaw вхідні посилання, як-от media://inbound/<id>

Інші схеми 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 відкидає зображення й надсилає лише текст.

Конфігурація

{  agents: {    defaults: {      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-mini"],      },      pdfMaxBytesMb: 10,      pdfMaxPages: 20,    },  },}

Повний опис полів див. у довіднику з конфігурації.

Подробиці виведення

Інструмент повертає текст у content[0].text, а структуровані метадані — у details.

Поширені поля details:

• model: посилання на визначену модель (provider/model)
• native: true для нативного режиму провайдера, false для резервного режиму
• attempts: невдалі резервні спроби перед успішним виконанням

Поля шляхів:

• Введення одного PDF: details.pdf
• Введення кількох PDF: details.pdfs[] із записами pdf
• Метадані переписування шляху в пісочниці (коли застосовно): rewrittenFrom

Поведінка в разі помилок

Приклади

Один PDF:

{  "pdf": "/tmp/report.pdf",  "prompt": "Summarize this report in 5 bullets"}

Кілька PDF:

{  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],  "prompt": "Compare risks and timeline changes across both documents"}

Резервна модель із фільтром сторінок:

{  "pdf": "https://example.com/report.pdf",  "pages": "1-3,7",  "model": "openai/gpt-5.4-mini",  "prompt": "Extract only customer-impacting incidents"}

Зашифрований PDF із резервним вилученням:

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "Summarize this contract"}

Пов’язані матеріали

• Огляд інструментів — усі доступні інструменти агента
• Довідник із конфігурації — налаштування pdfMaxBytesMb і pdfMaxPages