Поддержка изображений и медиа

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

Цели

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

Интерфейс командной строки (CLI)

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

Поведение канала WhatsApp Web

• Входные данные: локальный путь к файлу или HTTP(S) URL.
• Процесс: загрузка в Buffer, определение типа медиа и формирование правильного пакета данных:
  • Изображения: изменение размера и повторное сжатие в JPEG (максимальная сторона 2048px) с целью уложиться в agents.defaults.mediaMaxMb (по умолчанию 5 МБ), ограничение — 6 МБ.
  • Аудио/Голосовые сообщения/Видео: передача как есть до 16 МБ; аудио отправляется как голосовое сообщение (ptt: true).
  • Документы: всё остальное, до 100 МБ, с сохранением имени файла, если оно доступно.
• Воспроизведение в стиле GIF для WhatsApp: отправьте MP4 с gifPlayback: true (CLI: --gif-playback), чтобы мобильные клиенты зацикливали его встроенным образом.
• Определение MIME-типа предпочитает "магические" байты, затем заголовки, затем расширение файла.
• Подпись берется из --message или reply.text; пустая подпись разрешена.
• Логирование: без флага verbose показывает ↩️/✅; с verbose включает размер и исходный путь/URL.

Конвейер автоответов

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

Входящие медиа в команды (Pi)

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

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

Ограничения на отправку (отправка через WhatsApp web)

• Изображения: ограничение ~6 МБ после повторного сжатия.
• Аудио/голосовые сообщения/видео: ограничение 16 МБ; документы: ограничение 100 МБ.
• Слишком большой размер или нечитаемое медиа → четкая ошибка в логах, и ответ пропускается.

Ограничения анализа медиа (транскрипция/описание)

• Изображения по умолчанию: 10 МБ (tools.media.image.maxBytes).
• Аудио по умолчанию: 20 МБ (tools.media.audio.maxBytes).
• Видео по умолчанию: 50 МБ (tools.media.video.maxBytes).
• Медиа, превышающие лимит, пропускают этап анализа, но ответы всё равно отправляются с исходным телом сообщения.

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

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

Анализ медиаАудио и голосовые сообщения