Nodes and media

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

Канал WhatsApp працює на Baileys Web. На цій сторінці описано правила обробки медіафайлів для надсилання, Gateway і відповідей агента.

Цілі

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

Інтерфейс CLI

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

--media <path-or-url> — прикріпити медіафайл (зображення, аудіо, відео або документ); приймає локальні шляхи або URL-адреси. Необов’язковий параметр; для надсилання лише медіафайлу підпис може бути порожнім.
--gif-playback — відтворювати відеофайл як GIF-анімацію (лише WhatsApp).
--force-document — надсилати медіафайл як документ, щоб уникнути стиснення каналом (Telegram, WhatsApp); застосовується до зображень, GIF-анімацій і відео.
--reply-to <id>, --thread-id <id>, --pin, --silent — параметри доставлення та гілок обговорення, спільні з надсиланням лише тексту.
--dry-run — вивести визначене корисне навантаження та не виконувати надсилання.
--json — вивести результат у форматі JSON: { action, channel, dryRun, handledBy, messageId?, payload } (payload містить специфічний для каналу результат надсилання, зокрема посилання на медіафайл, якщо воно є).

Поведінка вебканалу WhatsApp

Вхідні дані: локальний шлях до файлу або URL-адреса HTTP(S).
Послідовність: завантажити в буфер, визначити тип медіафайлу, а потім сформувати вихідне корисне навантаження відповідно до типу:
- Зображення: оптимізуються, щоб відповідати обмеженню channels.whatsapp.mediaMaxMb (типово 50 МБ). Непрозорі зображення повторно стискаються у формат JPEG (типова послідовність розмірів сторони починається з 2048 пікселів і зменшується за повторного перевищення розміру); зображення з прозорістю зберігаються у форматі PNG. Якщо джерело вже є прийнятним файлом JPEG, PNG або WebP у межах бюджету розміру файлу та довжини сторони, вихідні байти зберігаються без змін замість повторного стиснення. Анімовані GIF-файли ніколи не перекодовуються, а лише перевіряються на відповідність обмеженню розміру.
- Аудіо/голос: якщо вихідне аудіо ще не має нативного голосового формату (.ogg/.opus або audio/ogg/audio/opus), перед надсиланням як голосової нотатки (ptt: true) воно перекодовується через ffmpeg у Opus/OGG (48 кГц, моно, 64 кбіт/с, тривалістю не більш ніж 20 хвилин).
- Відео: передається без змін, якщо розмір не перевищує 16 МБ.
- Документи: усе інше розміром до 100 МБ; назва файлу зберігається, якщо доступна.
Відтворення у стилі GIF у WhatsApp: надішліть MP4 із gifPlayback: true (CLI: --gif-playback), щоб мобільні клієнти циклічно відтворювали його безпосередньо в повідомленні.
Під час визначення MIME пріоритет мають сигнатурні байти, потім розширення файлу, а далі заголовки відповіді; визначений загальний контейнер (application/octet-stream, zip) ніколи не замінює конкретніше зіставлення за розширенням (наприклад, XLSX на ZIP).
Підпис береться з --message або reply.text; порожній підпис дозволено.
Журналювання: у звичайному режимі показує ↩️/✅; у докладному режимі також містить розмір і вихідний шлях або URL-адресу.

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

getReplyFromConfig повертає корисне навантаження відповіді (або масив корисних навантажень), яке, серед інших полів, містить text?, mediaUrl? і mediaUrls?.
За наявності медіафайлу вебвідправник визначає локальні шляхи або URL-адреси за допомогою того самого конвеєра, що й openclaw message send.
Якщо надано кілька медіафайлів, вони надсилаються послідовно.

Вхідні медіафайли для команд

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

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

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

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

Обмеження аналізу медіафайлів (транскрибування/опис)

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

Примітки щодо тестування

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

Пов’язані матеріали

Was this useful?