Поддержка изображений и медиа — 2025-12-05

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

Цели

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

Интерфейс CLI

  • openclaw message send --media <путь-или-url> [--message <подпись>]
    • --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; пустая подпись разрешена.
  • Логирование: не-подробное показывает ↩️/✅; подробное включает размер и исходный путь/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).
  • Слишком большие медиа пропускают понимание, но ответы все равно проходят с исходным телом.

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

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