Nodes and media

Поддержка изображений и мультимедиа

Канал WhatsApp работает на базе Baileys Web. На этой странице описаны правила обработки медиафайлов при отправке, работе Gateway и ответах агента.

Цели

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

Интерфейс CLI

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

--media <path-or-url> — прикрепить медиафайл (изображение, аудио, видео или документ); принимает локальные пути или URL. Необязательно; для отправки только медиафайла подпись может быть пустой.
--gif-playback — воспроизводить видео как GIF-анимацию (только WhatsApp).
--force-document — отправить медиафайл как документ, чтобы избежать сжатия каналом (Telegram, WhatsApp); применяется к изображениям, GIF-анимациям и видео.
--reply-to <id>, --thread-id <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.

Конвейер автоматических ответов

getReplyFromConfig возвращает полезную нагрузку ответа (или массив полезных нагрузок), содержащую, помимо прочих полей, text?, mediaUrl? и mediaUrls?.
При наличии медиафайла веб-отправитель разрешает локальные пути или URL с помощью того же конвейера, что и openclaw message send.
Если указано несколько медиафайлов, они отправляются последовательно.

Передача входящих медиафайлов командам

Когда входящие веб-сообщения содержат медиафайлы, OpenClaw загружает их во временный файл и предоставляет переменные шаблонизации:
- {{MediaUrl}} — псевдо-URL входящего медиафайла.
- {{MediaPath}} — локальный временный путь, в который файл записывается перед выполнением команды.
Когда включена изолированная среда Docker для каждого сеанса, входящий медиафайл копируется в рабочее пространство изолированной среды, а MediaPath/MediaUrl заменяются путём относительно изолированной среды, например media/inbound/<filename>.
Распознавание содержимого медиафайлов (настраиваемое через tools.media.* или общий параметр tools.media.models) выполняется до шаблонизации и может вставлять блоки [Image], [Audio] и [Video] в Body.
- Для аудио устанавливается {{Transcript}}, а расшифровка используется при разборе команд, поэтому команды с косой чертой продолжают работать.
- Описания видео и изображений сохраняют текст подписи, если он есть, для разбора команд.
- Если активная основная модель уже имеет встроенную поддержку изображений, OpenClaw пропускает сводный блок [Image] и вместо него передаёт модели исходное изображение.
По умолчанию обрабатывается только первое подходящее вложение с изображением, аудио или видео; чтобы обработать несколько вложений, задайте tools.media.<capability>.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).
Для слишком больших медиафайлов распознавание содержимого пропускается, но ответ всё равно отправляется с исходным телом.

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

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

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

Was this useful?