> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Инструмент 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** `string`

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

**pdfs** `string[]`

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

**prompt** `string` (default: Проанализируйте этот PDF-документ.)

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

**pages** `string`

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

**password** `string`

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

**model** `string`

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

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

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

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

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

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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. |

Полные сведения о полях см. в [справочнике по конфигурации](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agent-defaults).

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

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

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

Несколько PDF:

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

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

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

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

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

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

* [Обзор инструментов](https://docs2.openclaw.ai/ru/tools.md) — все доступные инструменты агента
* [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agent-defaults) — конфигурация pdfMaxBytesMb и pdfMaxPages