Підтримка зображень і медіа

Канал 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 Web

• Вхідні дані: локальний шлях до файлу або 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.
• Кілька медіаелементів надсилаються послідовно, якщо їх надано.

# Вхідні медіа до команд (Pi)

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

# Обмеження та помилки

Обмеження вихідного надсилання (надсилання через WhatsApp Web)

• Зображення: до 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).
• Завелике медіа пропускає розуміння, але відповіді все одно проходять з оригінальним тілом.

# Примітки для тестів

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

# Пов’язане

• Захоплення з камери
• Розуміння медіа
• Аудіо та голосові нотатки