---
read_when:
    - Зміна медіапайплайна або вкладень
summary: Правила обробки зображень і медіа для надсилання, Gateway та відповідей агента
title: Підтримка зображень і медіа
x-i18n:
    generated_at: "2026-04-27T07:08:36Z"
    model: gpt-5.4
    provider: openai
    source_hash: 1eb07bc638a755be5597e78c07041a52cfc0297b00d70c5adbfe5f3ad8c1a372
    source_path: nodes/images.md
    workflow: 15
---

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

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

## Цілі

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

## Поверхня 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? }`.
- Коли присутні медіа, вебвідправник обробляє локальні шляхи або URL через той самий пайплайн, що й `openclaw message send`.
- Якщо вказано кілька медіаелементів, вони надсилаються послідовно.

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

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

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

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

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

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

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

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

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

## Пов’язане

- [Захоплення з камери](/uk/nodes/camera)
- [Розуміння медіа](/uk/nodes/media-understanding)
- [Аудіо та голосові повідомлення](/uk/nodes/audio)
