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

# Поддержка изображений и медиа

# Поддержка изображений и медиа — 2025-12-05

Канал WhatsApp работает через **Baileys Web**. В этом документе зафиксированы текущие правила обработки медиа для отправки, Gateway (шлюз) и ответов агентов.

## Цели

* Отправлять медиа с необязательными подписями через `openclaw message send --media`.
* Разрешить автоответам из веб‑входящих включать медиа вместе с текстом.
* Сохранять разумные и предсказуемые лимиты для каждого типа.

## Поверхность CLI

* `openclaw message send --media <path-or-url> [--message <caption>]`
  * `--media` — необязательно; подпись может быть пустой для отправок «только медиа».
  * `--dry-run` выводит разрешённый payload; `--json` эмитирует `{ channel, to, messageId, mediaUrl, caption }`.

## Поведение канала WhatsApp Web

* Вход: локальный путь к файлу **или** HTTP(S) URL.
* Поток: загрузка в Buffer, определение типа медиа и сборка корректного payload:
  * **Изображения:** изменение размера и перекодирование в JPEG (макс. сторона 2048px) с целью `agents.defaults.mediaMaxMb` (по умолчанию 5 MB), с жёстким пределом 6 MB.
  * **Аудио/голос/видео:** сквозная передача до 16 MB; аудио отправляется как голосовое сообщение (`ptt: true`).
  * **Документы:** всё остальное, до 100 MB, с сохранением имени файла при наличии.
* GIF‑подобное воспроизведение в WhatsApp: отправляйте MP4 с `gifPlayback: true` (CLI: `--gif-playback`), чтобы мобильные клиенты зацикливали воспроизведение inline.
* Определение MIME сначала по сигнатурам (magic bytes), затем по заголовкам, затем по расширению файла.
* Подпись берётся из `--message` или `reply.text`; пустая подпись допускается.
* Логирование: без подробного режима показывает `↩️`/`✅`; подробный режим включает размер и путь/URL источника.

## Контейнер автоответа

* `getReplyFromConfig` возвращает `{ text?, mediaUrl?, mediaUrls? }`.
* При наличии медиа веб‑отправитель разрешает локальные пути или URL, используя тот же конвейер, что и `openclaw message send`.
* Если передано несколько медиа‑элементов, они отправляются последовательно.

## Входящие медиа для команд (Pi)

* Когда входящие веб‑сообщения содержат медиа, OpenClaw загружает их во временный файл и предоставляет переменные шаблонизации:
  * `{{MediaUrl}}` — псевдо‑URL для входящего медиа.
  * `{{MediaPath}}` — локальный временный путь, записанный перед запуском команды.
* При включённой per‑session Docker sandbox входящее медиа копируется в рабочее пространство sandbox, а `MediaPath`/`MediaUrl` переписываются в относительный путь вида `media/inbound/<filename>`.
* Понимание медиа (если настроено через `tools.media.*` или общий `tools.media.models`) выполняется до шаблонизации и может вставлять блоки `[Image]`, `[Audio]` и `[Video]` в `Body`.
  * Аудио устанавливает `{{Transcript}}` и использует транскрипт для парсинга команд, чтобы слэш‑команды продолжали работать.
  * Описания видео и изображений сохраняют любой текст подписи для парсинга команд.
* По умолчанию обрабатывается только первое совпадающее вложение изображения/аудио/видео; установите `tools.media.<cap>.attachments`, чтобы обрабатывать несколько вложений.

## Ограничения и ошибки

**Лимиты исходящей отправки (WhatsApp web send)**

* Изображения: предел \~6 MB после перекодирования.
* Аудио/голос/видео: предел 16 MB; документы: предел 100 MB.
* Слишком большой или нечитаемый медиафайл → понятная ошибка в логах, ответ пропускается.

**Лимиты понимания медиа (транскрипция/описание)**

* Изображения по умолчанию: 10 MB (`tools.media.image.maxBytes`).
* Аудио по умолчанию: 20 MB (`tools.media.audio.maxBytes`).
* Видео по умолчанию: 50 MB (`tools.media.video.maxBytes`).
* При превышении размера понимание пропускается, но ответы всё равно отправляются с исходным телом.

## Примечания для тестов

* Покрыть сценарии отправки и ответов для изображений/аудио/документов.
* Проверить перекодирование изображений (ограничение размера) и флаг голосового сообщения для аудио.
* Убедиться, что ответы с несколькими медиа разворачиваются в последовательные отправки.