---
read_when:
    - Вы хотите анализировать PDF-файлы от агентов
    - Вам нужны точные параметры и ограничения инструмента PDF
    - Вы отлаживаете нативный режим PDF и резервное извлечение
summary: Анализируйте один или несколько PDF-документов с нативной поддержкой провайдера и резервным извлечением
title: Инструмент PDF
x-i18n:
    generated_at: "2026-06-28T23:54:16Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6cce4328a7457f30b8c64abdcfa94b6a5d5649c2bcdfde3187288b11a0e154b1
    source_path: tools/pdf.md
    workflow: 16
---

`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
{
  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
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
```

Несколько PDF:

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

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

```json
{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Extract only customer-impacting incidents"
}
```

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

```json
{
  "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