> ## 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.
* Резервный режим извлечения для других провайдеров (сначала извлекается текст, затем изображения страниц, если нужно).
* Поддерживает одиночный (`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-инструмент сначала повторно использует ее, прежде чем переходить к другим
  провайдерам с аутентификацией.

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

<ParamField path="pdf" type="string">
  Один путь к PDF или URL.
</ParamField>

<ParamField path="pdfs" type="string[]">
  Несколько путей к PDF или URL, всего до 10.
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
  Промпт анализа.
</ParamField>

<ParamField path="pages" type="string">
  Фильтр страниц, например `1-5` или `1,3,7-9`.
</ParamField>

<ParamField path="password" type="string">
  Пароль для зашифрованных PDF в резервном режиме извлечения.
</ParamField>

<ParamField path="model" type="string">
  Необязательное переопределение модели в форме `provider/model`.
</ParamField>

<ParamField path="maxBytesMb" type="number">
  Ограничение размера для каждого PDF в МБ. По умолчанию используется `agents.defaults.pdfMaxBytesMb` или `10`.
</ParamField>

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

* `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.

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

```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,
    },
  },
}
```

См. [Справочник конфигурации](/ru/gateway/configuration-reference) для полной информации о полях.

## Подробности вывода

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
```

Несколько PDF:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}
```

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

```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": "Extract only customer-impacting incidents"
}
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}
```

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

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