Перейти к основному содержимому

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

Инструмент PDF

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

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

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

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

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

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

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

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

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

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

  • Для извлечения изображений страниц используется бюджет пикселей 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"
}

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