Перейти к основному содержанию

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

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

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