Перейти до основного вмісту

​
Інструмент PDF

pdf аналізує один або кілька PDF-документів і повертає текст. Коротко про поведінку:
  • Нативний режим провайдера для провайдерів моделей Anthropic і Google.
  • Резервний режим витягування для інших провайдерів (спочатку витягування тексту, потім зображення сторінок за потреби).
  • Підтримує один (pdf) або кілька (pdfs) вхідних PDF, максимум 10 PDF за виклик.

​
Доступність

Інструмент реєструється лише тоді, коли OpenClaw може визначити конфігурацію моделі з підтримкою PDF для агента:
  1. agents.defaults.pdfModel
  2. резервний перехід до agents.defaults.imageModel
  3. резервний перехід до визначеної моделі сесії/типової моделі агента
  4. якщо нативні PDF-провайдери мають автентифікацію, вони мають пріоритет над загальними резервними кандидатами image
Якщо не вдається визначити жодну придатну модель, інструмент pdf не надається. Примітки щодо доступності:
  • Ланцюжок резервного переходу враховує автентифікацію. Налаштований provider/model враховується лише тоді, коли OpenClaw справді може автентифікувати цього провайдера для агента.
  • Нативні PDF-провайдери наразі — Anthropic і Google.
  • Якщо визначений провайдер сесії/типовий провайдер уже має налаштовану модель vision/PDF, інструмент PDF повторно використовує її перед переходом до інших провайдерів з автентифікацією.

​
Довідка щодо вхідних даних

  • pdf (string): один шлях до PDF або URL
  • pdfs (string[]): кілька шляхів до PDF або URL, до 10 загалом
  • prompt (string): запит для аналізу, типово Analyze this PDF document.
  • pages (string): фільтр сторінок на кшталт 1-5 або 1,3,7-9
  • model (string): необов’язкове перевизначення моделі (provider/model)
  • maxBytesMb (number): обмеження розміру одного PDF у MB
Примітки щодо вхідних даних:
  • pdf і pdfs об’єднуються та дедуплікуються перед завантаженням.
  • Якщо не надано жодного PDF, інструмент повертає помилку.
  • pages розбирається як номери сторінок із початком від 1, дедуплікується, сортується та обрізається до налаштованого максимуму сторінок.
  • maxBytesMb за замовчуванням дорівнює agents.defaults.pdfMaxBytesMb або 10.

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

  • локальний шлях до файлу (включно з розгортанням ~)
  • URL file://
  • URL http:// і https://
Примітки щодо посилань:
  • Інші схеми URI (наприклад, ftp://) відхиляються з unsupported_pdf_reference.
  • У режимі sandbox віддалені URL http(s) відхиляються.
  • Якщо ввімкнено політику файлів лише для workspace, локальні шляхи до файлів поза дозволеними коренями відхиляються.

​
Режими виконання

​
Нативний режим провайдера

Нативний режим використовується для провайдерів anthropic і google. Інструмент надсилає сирі байти PDF безпосередньо до API провайдерів. Обмеження нативного режиму:
  • pages не підтримується. Якщо його задано, інструмент повертає помилку.
  • Підтримується вхід із кількома PDF; кожен PDF надсилається як нативний блок документа / inline-частина PDF перед запитом.

​
Резервний режим витягування

Резервний режим використовується для ненативних провайдерів. Потік:
  1. Витягує текст із вибраних сторінок (до agents.defaults.pdfMaxPages, типово 20).
  2. Якщо довжина витягнутого тексту менша за 200 символів, вибрані сторінки рендеряться в PNG-зображення і додаються.
  3. Витягнутий вміст разом із запитом надсилається до вибраної моделі.
Докладніше про резервний режим:
  • Витягування зображень сторінок використовує бюджет пікселів 4,000,000.
  • Якщо цільова модель не підтримує введення зображень і немає тексту, який можна витягти, інструмент повертає помилку.
  • Якщо витягування тексту успішне, але витягування зображень вимагало б vision для текстової моделі, OpenClaw відкидає відрендерені зображення та продовжує роботу з витягнутим текстом.
  • Резервний режим витягування потребує pdfjs-dist (і @napi-rs/canvas для рендерингу зображень).

​
Config

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}
Повні відомості про поля дивіться в Configuration Reference.

​
Відомості про вивід

Інструмент повертає текст у content[0].text і структуровані метадані в details. Поширені поля details:
  • model: визначене посилання на модель (provider/model)
  • native: true для нативного режиму провайдера, false для резервного режиму
  • attempts: резервні спроби, які завершилися невдачею до успішного виконання
Поля шляхів:
  • вхід із одним PDF: details.pdf
  • вхід із кількома PDF: details.pdfs[] із записами pdf
  • метадані переписування шляху sandbox (де застосовується): 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: 
{
  "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"
}

​
Пов’язане