​

Підтримка зображень і медіа (2025-12-05)

​

Цілі

• Надсилати медіа з необов’язковими підписами через openclaw message send --media.
• Дозволити автоматичним відповідям із web inbox включати медіа разом із текстом.
• Зберігати обмеження для кожного типу розумними й передбачуваними.

​

Поверхня 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 (максимальна сторона 2048 px) з орієнтацією на channels.whatsapp.mediaMaxMb (типово: 50 МБ).
  • Аудіо/голосові повідомлення/відео: наскрізна передача до 16 МБ; аудіо надсилається як голосове повідомлення (ptt: true).
  • Документи: будь-що інше, до 100 МБ, зі збереженням назви файлу, якщо вона доступна.
• Відтворення в стилі GIF у WhatsApp: надішліть MP4 з gifPlayback: true (CLI: --gif-playback), щоб мобільні клієнти відтворювали його циклічно вбудовано.
• Визначення MIME надає перевагу magic bytes, потім заголовкам, потім розширенню файлу.
• Підпис береться з --message або reply.text; порожній підпис дозволений.
• Журналювання: у не-verbose режимі показуються ↩️/✅; у verbose включаються розмір і вихідний шлях/URL.

​

Конвеєр автовідповідей

• getReplyFromConfig повертає { text?, mediaUrl?, mediaUrls? }.
• Коли медіа присутнє, web sender визначає локальні шляхи або URL, використовуючи той самий конвеєр, що й openclaw message send.
• Якщо надано кілька медіаелементів, вони надсилаються послідовно.

​

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

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

​

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

• Зображення: до channels.whatsapp.mediaMaxMb (типово: 50 МБ) після повторного стиснення.
• Аудіо/голосові повідомлення/відео: обмеження 16 МБ; документи: 100 МБ.
• Надто великі або непридатні для читання медіафайли → зрозуміла помилка в журналах, і відповідь пропускається.

• Типово для зображень: 10 МБ (tools.media.image.maxBytes).
• Типово для аудіо: 20 МБ (tools.media.audio.maxBytes).
• Типово для відео: 50 МБ (tools.media.video.maxBytes).
• Надто великі медіафайли пропускають етап розуміння, але відповіді все одно проходять з оригінальним Body.

​

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

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