Инструмент PDF

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

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

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

Доступность

Инструмент регистрируется только тогда, когда OpenClaw может разрешить конфигурацию модели с поддержкой PDF для агента:

1. agents.defaults.pdfModel
2. резервный переход к agents.defaults.imageModel
3. резервный переход к разрешенной для агента модели сеанса/модели по умолчанию
4. если нативные PDF-провайдеры поддерживаются аутентификацией, они предпочитаются перед универсальными резервными кандидатами для изображений

Если пригодную модель разрешить нельзя, инструмент pdf не предоставляется.

Примечания о доступности:

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

Справочник ввода

Примечания о вводе:

• pdf и pdfs объединяются и дедуплицируются перед загрузкой.
• Если PDF-ввод не указан, инструмент возвращает ошибку.
• pages разбирается как номера страниц с отсчетом от 1, дедуплицируется, сортируется и ограничивается настроенным максимумом страниц.
• password применяется к каждому PDF в запросе и используется только резервным режимом извлечения.
• maxBytesMb по умолчанию равен agents.defaults.pdfMaxBytesMb или 10.

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

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

Примечания о ссылках:

• Другие схемы URI (например, ftp://) отклоняются с unsupported_pdf_reference.
• В sandbox-режиме удаленные URL http(s) отклоняются.
• При включенной файловой политике только для рабочей области локальные пути к файлам вне разрешенных корней отклоняются.
• Управляемые входящие ссылки и воспроизведенные пути внутри хранилища входящих медиа OpenClaw разрешены при файловой политике только для рабочей области.

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

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

Нативный режим используется для провайдеров anthropic и google. Инструмент отправляет необработанные байты PDF напрямую в API провайдера.

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

• pages не поддерживается. Если задано, инструмент возвращает ошибку.
• password не поддерживается. Используйте ненативную модель для анализа зашифрованных PDF.
• Множественный PDF-ввод поддерживается; каждый PDF отправляется как нативный блок документа / встроенная PDF-часть перед промптом.

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

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

Поток:

1. Извлечь текст из выбранных страниц (до agents.defaults.pdfMaxPages, по умолчанию 20).
2. Если длина извлеченного текста меньше 200 символов, отрендерить выбранные страницы в PNG-изображения и включить их.
3. Отправить извлеченное содержимое вместе с промптом выбранной модели.

Подробности резервного режима:

• Извлечение изображений страниц использует пиксельный бюджет 4,000,000.
• Зашифрованные PDF можно открыть с помощью параметра верхнего уровня password.
• Если целевая модель не поддерживает ввод изображений и извлекаемого текста нет, инструмент возвращает ошибку.
• Если извлечение текста успешно, но извлечение изображений потребовало бы зрения у текстовой модели, OpenClaw отбрасывает отрендеренные изображения и продолжает с извлеченным текстом.
• Резервное извлечение использует встроенный Plugin document-extract. Plugin владеет clawpdf, который обеспечивает извлечение текста и рендеринг изображений через PDFium WebAssembly.

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

{  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
• метаданные переписывания пути 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"}

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

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

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

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