Skip to main content
Канал 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.
Указанные выше ограничения в 16 МБ для аудио и видео и 100 МБ для документов — это общие значения по умолчанию для соответствующих типов медиафайлов, используемые, когда явное ограничение в байтах не задано. При отправке через WhatsApp задаётся явное ограничение из channels.whatsapp.mediaMaxMb (по умолчанию 50 МБ), которое одинаково применяется ко всем типам для этой учётной записи.

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

  • 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).
  • Для слишком больших медиафайлов распознавание содержимого пропускается, но ответ всё равно отправляется с исходным телом.

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

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

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