Встроенные инструменты

Инструмент PDF

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

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

Доступность

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

agents.defaults.pdfModel
резервный вариант agents.defaults.imageModel
резервный вариант — лучшие настройки провайдера по умолчанию на основе доступной аутентификации

Если не удается разрешить пригодную для использования модель, инструмент 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 в МБ

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

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

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

локальный путь к файлу (включая раскрытие ~)
URL с file://
URL с http:// и https://

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

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

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

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

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

pages не поддерживается. Если установлен, инструмент возвращает ошибку.

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

Резервный режим используется для провайдеров, не поддерживающих нативный режим. Процесс:

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

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

Для извлечения изображений страниц используется бюджет пикселей 4,000,000.
Если целевая модель не поддерживает ввод изображений и нет извлекаемого текста, инструмент возвращает ошибку.
Для резервного режима извлечения требуется pdfjs-dist (и @napi-rs/canvas для рендеринга изображений).

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

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-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-mini",
  "prompt": "Extract only customer-impacting incidents"
}

Сравнения Привилегированный режим