Инструмент PDF

pdf анализирует один или несколько PDF-документов и возвращает текст. Для моделей Anthropic и Google он использует нативный ввод документов, а для всех остальных провайдеров — резервное извлечение текста и изображений.

Доступность

Инструмент регистрируется, только если OpenClaw может определить для агента модель с поддержкой PDF. Порядок определения:

agents.defaults.pdfModel (явно заданные основная и резервные модели)
agents.defaults.imageModel (явно заданные основная и резервные модели)
Определённая модель сеанса или модель агента по умолчанию, если её провайдер поддерживает нативный ввод PDF (Anthropic, Google) либо для неё уже настроена модель компьютерного зрения
Автоматически обнаруженные провайдеры с поддержкой изображений или компьютерного зрения и пригодной аутентификацией; приоритет отдаётся провайдерам с нативной поддержкой PDF

Перед использованием для каждой резервной модели проверяется аутентификация, поэтому настроенная provider/model учитывается, только если OpenClaw может аутентифицировать агента у этого провайдера. Если пригодную модель определить не удаётся, инструмент pdf недоступен.

Справочник входных параметров

string

Один путь к PDF или URL.

string[]

Несколько путей к PDF или URL, не более 10 в общей сложности.

string

по умолчанию:"Проанализируйте этот PDF-документ."

Запрос для анализа.

string

Фильтр страниц, например 1-5 или 1,3,7-9. Не поддерживается в режиме нативного провайдера.

string

Пароль для зашифрованных PDF. Применяется ко всем PDF в запросе; используется только в резервном режиме извлечения.

string

Необязательное переопределение модели в формате provider/model.

number

Ограничение размера каждого PDF в МБ. По умолчанию используется agents.defaults.pdfMaxBytesMb или 10, если значение не задано.

Примечания:

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 используйте модель без нативной поддержки.

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

Используется для всех остальных провайдеров.

Из выбранных страниц (не более agents.defaults.pdfMaxPages, по умолчанию 20) извлекается текст с помощью встроенного плагина document-extract, который использует пакет clawpdf (PDFium WebAssembly) для извлечения текста и изображений.
Если извлечённый текст короче 200 символов, те же страницы визуализируются как изображения PNG. Общий бюджет визуализации составляет 4,000,000 пикселей и распределяется между всеми страницами, для которых нужны изображения (пропорционально между оставшимися страницами, а не отдельно на каждую страницу), поэтому страницы, уже содержащие достаточно текста, вообще не визуализируются.
Извлечённый текст (и все визуализированные изображения) вместе с запросом отправляется выбранной модели.

Подробности:

Зашифрованные PDF открываются с помощью параметра верхнего уровня password.
Если модель не поддерживает ввод изображений и извлекаемый текст отсутствует, инструмент выдаёт ошибку.
Если визуализация изображений завершается ошибкой, OpenClaw отбрасывает изображения и продолжает работу с извлечённым текстом.
Если целевая модель поддерживает только текст, а при извлечении были получены изображения, OpenClaw отбрасывает изображения и отправляет только текст.

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

{
  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.

Полные сведения о полях см. в справочнике по конфигурации.

Сведения о выходных данных

Инструмент возвращает текст в 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:

{
  "pdf": "/tmp/report.pdf",
  "prompt": "Сведите содержание этого отчёта к 5 пунктам"
}

Несколько PDF:

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Сравните риски и изменения сроков в обоих документах"
}

Резервная модель с фильтрацией страниц:

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Извлеките только инциденты, затрагивающие клиентов"
}

Зашифрованный PDF с резервным извлечением:

{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Кратко изложите содержание этого договора"
}

Связанные материалы

Обзор инструментов — все доступные инструменты агента
Справочник по конфигурации — конфигурация pdfMaxBytesMb и pdfMaxPages

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Инструмент PDF

Доступность

Справочник входных параметров

Поддерживаемые ссылки на PDF

Режимы выполнения

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

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

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

Сведения о выходных данных

Обработка ошибок

Примеры

Связанные материалы

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

​Справочник входных параметров

​Поддерживаемые ссылки на PDF

​Режимы выполнения

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

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

​Конфигурация

​Сведения о выходных данных

​Обработка ошибок

​Примеры

​Связанные материалы

Доступность

Справочник входных параметров

Поддерживаемые ссылки на PDF

Режимы выполнения

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

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

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

Сведения о выходных данных

Обработка ошибок

Примеры

Связанные материалы