Инструмент 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) извлекается текст с помощью встроенного плагина 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": "Сведите содержание этого отчёта к 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