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

​
Цели

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

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

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

​
Поведение веб-канала WhatsApp

  • Ввод: путь к локальному файлу или HTTP(S) URL.
  • Поток: загрузить в Buffer, определить тип медиа и собрать правильную полезную нагрузку:
    • Изображения: изменить размер и повторно сжать в JPEG (максимальная сторона 2048px) с целевым ограничением channels.whatsapp.mediaMaxMb (по умолчанию: 50 MB).
    • Аудио/голос/видео: передавать без изменений до 16 MB; аудио отправляется как голосовая заметка (ptt: true).
    • Документы: все остальное, до 100 MB, с сохранением имени файла, когда оно доступно.
  • Воспроизведение в стиле GIF в WhatsApp: отправьте MP4 с gifPlayback: true (CLI: --gif-playback), чтобы мобильные клиенты зацикливали его прямо в строке.
  • Определение MIME предпочитает магические байты, затем заголовки, затем расширение файла.
  • Подпись берется из --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}} и использует транскрипт для разбора команд, чтобы slash-команды продолжали работать.
    • Описания видео и изображений сохраняют любой текст подписи для разбора команд.
    • Если активная основная модель изображений уже нативно поддерживает зрение, OpenClaw пропускает сводный блок [Image] и вместо этого передает модели исходное изображение.
  • По умолчанию обрабатывается только первое подходящее вложение изображения/аудио/видео; задайте tools.media.<cap>.attachments, чтобы обрабатывать несколько вложений.

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

Ограничения исходящей отправки (веб-отправка WhatsApp)
  • Изображения: до channels.whatsapp.mediaMaxMb (по умолчанию: 50 MB) после повторного сжатия.
  • Аудио/голос/видео: ограничение 16 MB; документы: ограничение 100 MB.
  • Слишком большое или нечитаемое медиа → понятная ошибка в логах, и ответ пропускается.
Ограничения понимания медиа (транскрипция/описание)
  • Изображение по умолчанию: 10 MB (tools.media.image.maxBytes).
  • Аудио по умолчанию: 20 MB (tools.media.audio.maxBytes).
  • Видео по умолчанию: 50 MB (tools.media.video.maxBytes).
  • Слишком большое медиа пропускает понимание, но ответы все равно проходят с исходным телом.

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

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

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