Tools

Інструмент для PDF

pdf аналізує один або кілька PDF-документів і повертає текст.

Коротка поведінка:

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

Доступність

Інструмент реєструється лише тоді, коли OpenClaw може визначити конфігурацію моделі з підтримкою PDF для агента:

agents.defaults.pdfModel
резервний варіант agents.defaults.imageModel
резервний варіант визначеної для агента моделі сеансу/моделі за замовчуванням
якщо нативні PDF-провайдери мають автентифікаційну підтримку, надавати їм перевагу перед загальними кандидатами резервного варіанта для зображень

Якщо придатну модель не можна визначити, інструмент pdf не надається.

Примітки щодо доступності:

Резервний ланцюжок враховує автентифікацію. Налаштований provider/model враховується лише якщо OpenClaw справді може автентифікувати цього провайдера для агента.
Нативні PDF-провайдери наразі: Anthropic і Google.
Якщо визначений провайдер сеансу/за замовчуванням уже має налаштовану модель для зору/PDF, інструмент PDF повторно використовує її перед переходом до інших провайдерів з автентифікаційною підтримкою.

Довідник вхідних параметрів

pdfstring

Один шлях до PDF або URL.

pdfsstring[]

Кілька шляхів до PDF або URL, загалом до 10.

promptstring

Промпт для аналізу.

pagesstring

Фільтр сторінок на кшталт 1-5 або 1,3,7-9.

modelstring

Необов'язкове перевизначення моделі у формі provider/model.

maxBytesMbnumber

Обмеження розміру для кожного PDF у МБ. За замовчуванням agents.defaults.pdfMaxBytesMb або 10.

Примітки щодо вхідних даних:

pdf і pdfs об'єднуються та дедуплікуються перед завантаженням.
Якщо вхідний PDF не надано, інструмент повертає помилку.
pages розбирається як номери сторінок із нумерацією від 1, дедуплікується, сортується та обмежується налаштованою максимальною кількістю сторінок.
maxBytesMb за замовчуванням дорівнює agents.defaults.pdfMaxBytesMb або 10.

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

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

Примітки щодо посилань:

Інші схеми URI (наприклад, ftp://) відхиляються з unsupported_pdf_reference.
У режимі пісочниці віддалені URL http(s) відхиляються.
Коли ввімкнено файлову політику лише для робочого простору, локальні шляхи до файлів поза дозволеними коренями відхиляються.
Керовані вхідні посилання та відтворені шляхи в сховищі вхідних медіа OpenClaw дозволені за файлової політики лише для робочого простору.

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

Режим нативного провайдера

Нативний режим використовується для провайдерів anthropic і google. Інструмент надсилає необроблені байти PDF безпосередньо до API провайдера.

Обмеження нативного режиму:

pages не підтримується. Якщо задано, інструмент повертає помилку.
Вхід із кількома PDF підтримується; кожен PDF надсилається як нативний блок документа / вбудована PDF-частина перед промптом.

Резервний режим вилучення

Резервний режим використовується для ненативних провайдерів.

Потік:

Вилучити текст із вибраних сторінок (до agents.defaults.pdfMaxPages, за замовчуванням 20).
Якщо довжина вилученого тексту менша за 200 символів, відрендерити вибрані сторінки в PNG-зображення та включити їх.
Надіслати вилучений вміст разом із промптом до вибраної моделі.

Деталі резервного режиму:

Вилучення зображень сторінок використовує піксельний бюджет 4,000,000.
Якщо цільова модель не підтримує вхідні зображення та немає тексту, який можна вилучити, інструмент повертає помилку.
Якщо вилучення тексту успішне, але вилучення зображень вимагало б зору на текстовій моделі, OpenClaw відкидає відрендерені зображення та продовжує з вилученим текстом.
Резервний режим вилучення використовує вбудований Plugin document-extract. Plugin володіє pdfjs-dist; @napi-rs/canvas використовується лише коли доступний резервний рендеринг зображень.

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

{
  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 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"
}

Пов'язане

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

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

# Довідник вхідних параметрів

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

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

# Режим нативного провайдера

# Резервний режим вилучення

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

# Деталі виводу

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

# Приклади

# Пов'язане