--- read_when: - Изменение конвейера обработки медиафайлов или вложений summary: Правила обработки изображений и медиафайлов для отправки, Gateway и ответов агента title: Поддержка изображений и мультимедиа x-i18n: generated_at: "2026-07-13T18:21:50Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 41d5bbd174b4fb35b616a9e90930485fd76dc8cfbad2e178f0823e6fb40c36f8 source_path: nodes/images.md workflow: 16 --- Канал WhatsApp работает на базе Baileys Web. На этой странице описаны правила обработки медиафайлов при отправке, работе Gateway и ответах агента. ## Цели - Отправлять медиафайлы с необязательной подписью через `openclaw message send --media`. - Разрешить автоматическим ответам из веб-папки входящих сообщений включать медиафайлы вместе с текстом. - Обеспечить разумные и предсказуемые ограничения для каждого типа. ## Интерфейс CLI `openclaw message send --target --media [--message ]` - `--media ` — прикрепить медиафайл (изображение, аудио, видео или документ); принимает локальные пути или URL. Необязательно; для отправки только медиафайла подпись может быть пустой. - `--gif-playback` — воспроизводить видео как GIF-анимацию (только WhatsApp). - `--force-document` — отправить медиафайл как документ, чтобы избежать сжатия каналом (Telegram, WhatsApp); применяется к изображениям, GIF-анимациям и видео. - `--reply-to `, `--thread-id `, `--pin`, `--silent` — параметры доставки и ветвления, общие с отправкой только текста. - `--dry-run` — вывести сформированную полезную нагрузку и пропустить отправку. - `--json` — вывести результат в формате JSON: `{ action, channel, dryRun, handledBy, messageId?, payload }` (`payload` содержит результат отправки для конкретного канала, включая ссылку на медиафайл, если она есть). ## Поведение веб-канала WhatsApp - Входные данные: путь к локальному файлу **или** URL HTTP(S). - Процесс: загрузить данные в буфер, определить тип медиафайла, затем сформировать исходящую полезную нагрузку в соответствии с типом: - **Изображения:** оптимизируются до размера менее `channels.whatsapp.mediaMaxMb` (по умолчанию 50 МБ). Непрозрачные изображения повторно сжимаются в JPEG (начальная длина стороны по умолчанию — 2048 пикселей; при повторном превышении размера она постепенно уменьшается); изображения с прозрачностью сохраняются в формате PNG. Если исходный файл уже является допустимым JPEG, PNG или WebP и укладывается в ограничения по размеру файла и длине стороны, исходные байты сохраняются без изменений вместо повторного сжатия. Анимированные GIF-файлы никогда не перекодируются, а только проверяются по размеру. - **Аудио/голос:** если аудиофайл ещё не имеет собственного голосового формата (`.ogg`/`.opus` или `audio/ogg`/`audio/opus`), перед отправкой исходящее аудио перекодируется с помощью `ffmpeg` в Opus/OGG (48 кГц, моно, 64 кбит/с, продолжительность не более 20 минут), а затем отправляется как голосовое сообщение (`ptt: true`). - **Видео:** передаётся без изменений, если размер не превышает 16 МБ. - **Документы:** любые остальные файлы размером до 100 МБ; имя файла сохраняется, если оно доступно. - Воспроизведение в стиле GIF в WhatsApp: отправьте MP4 с `gifPlayback: true` (CLI: `--gif-playback`), чтобы мобильные клиенты циклически воспроизводили его непосредственно в сообщении. - При определении MIME-типа сначала проверяются сигнатуры содержимого, затем расширение файла, а после — заголовки ответа; общий контейнер, определённый по сигнатуре (`application/octet-stream`, `zip`), никогда не переопределяет более точное сопоставление по расширению (например, XLSX и ZIP). - Подпись берётся из `--message` или `reply.text`; допускается пустая подпись. - Журналирование: в обычном режиме отображаются `↩️`/`✅`; в подробном режиме также указываются размер и исходный путь или URL. Указанные выше ограничения в 16 МБ для аудио и видео и 100 МБ для документов — это общие значения по умолчанию для соответствующих типов медиафайлов, используемые, когда явное ограничение в байтах не задано. При отправке через WhatsApp задаётся явное ограничение из `channels.whatsapp.mediaMaxMb` (по умолчанию 50 МБ), которое одинаково применяется ко всем типам для этой учётной записи. ## Конвейер автоматических ответов - `getReplyFromConfig` возвращает полезную нагрузку ответа (или массив полезных нагрузок), содержащую, помимо прочих полей, `text?`, `mediaUrl?` и `mediaUrls?`. - При наличии медиафайла веб-отправитель разрешает локальные пути или URL с помощью того же конвейера, что и `openclaw message send`. - Если указано несколько медиафайлов, они отправляются последовательно. ## Передача входящих медиафайлов командам - Когда входящие веб-сообщения содержат медиафайлы, OpenClaw загружает их во временный файл и предоставляет переменные шаблонизации: - `{{MediaUrl}}` — псевдо-URL входящего медиафайла. - `{{MediaPath}}` — локальный временный путь, в который файл записывается перед выполнением команды. - Когда включена изолированная среда Docker для каждого сеанса, входящий медиафайл копируется в рабочее пространство изолированной среды, а `MediaPath`/`MediaUrl` заменяются путём относительно изолированной среды, например `media/inbound/`. - Распознавание содержимого медиафайлов (настраиваемое через `tools.media.*` или общий параметр `tools.media.models`) выполняется до шаблонизации и может вставлять блоки `[Image]`, `[Audio]` и `[Video]` в `Body`. - Для аудио устанавливается `{{Transcript}}`, а расшифровка используется при разборе команд, поэтому команды с косой чертой продолжают работать. - Описания видео и изображений сохраняют текст подписи, если он есть, для разбора команд. - Если активная основная модель уже имеет встроенную поддержку изображений, OpenClaw пропускает сводный блок `[Image]` и вместо него передаёт модели исходное изображение. - По умолчанию обрабатывается только первое подходящее вложение с изображением, аудио или видео; чтобы обработать несколько вложений, задайте `tools.media..attachments`. ## Ограничения и ошибки **Ограничения исходящей отправки (отправка через веб-канал WhatsApp)** - Изображения: до `channels.whatsapp.mediaMaxMb` (по умолчанию 50 МБ) после оптимизации. - Аудио и видео: ограничение 16 МБ (общее значение по умолчанию; при отправке через WhatsApp переопределяется параметром `mediaMaxMb`). - Документы: ограничение 100 МБ (общее значение по умолчанию; при отправке через WhatsApp переопределяется параметром `mediaMaxMb`). - Если медиафайл слишком велик или не читается, в журнале появляется понятное сообщение об ошибке, а ответ пропускается. **Ограничения распознавания содержимого медиафайлов (расшифровка/описание)** - Изображение по умолчанию: 10 МБ (`tools.media.image.maxBytes`). - Аудио по умолчанию: 20 МБ (`tools.media.audio.maxBytes`). - Видео по умолчанию: 50 МБ (`tools.media.video.maxBytes`). - Для слишком больших медиафайлов распознавание содержимого пропускается, но ответ всё равно отправляется с исходным телом. ## Примечания для тестов - Проверить процессы отправки и ответа для изображений, аудио и документов. - Проверить соблюдение ограничений размера после оптимизации изображения и флаг голосового сообщения для аудио. - Убедиться, что ответы с несколькими медиафайлами разделяются на последовательные отправки. ## Связанные материалы - [Съёмка с камеры](/ru/nodes/camera) - [Распознавание содержимого медиафайлов](/ru/nodes/media-understanding) - [Аудио и голосовые сообщения](/ru/nodes/audio)