Розуміння медіа

OpenClaw може підсумовувати вхідні медіа (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично виявляє, коли доступні локальні інструменти або ключі провайдерів, і його можна вимкнути або налаштувати. Якщо розуміння вимкнене, моделі все одно отримують оригінальні файли/URL як зазвичай.

Поведінка медіа, специфічна для постачальників, реєструється Plugin-ами постачальників, тоді як ядро OpenClaw відповідає за спільну конфігурацію tools.media, порядок резервного fallback та інтеграцію з конвеєром відповіді.

# Цілі

• Необов’язково: попередньо перетравлювати вхідні медіа в короткий текст для швидшої маршрутизації + кращого розбору команд.
• Зберігати доставку оригінальних медіа до моделі (завжди).
• Підтримувати API провайдерів і CLI fallback-и.
• Дозволяти кілька моделей з упорядкованим fallback (помилка/розмір/тайм-аут).

# Загальна поведінка

Якщо розуміння не вдається або вимкнене, потік відповіді продовжується з оригінальним тілом + вкладеннями.

# Огляд конфігурації

tools.media підтримує спільні моделі плюс перевизначення для окремих можливостей:

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

# Записи моделей

Кожен запис models[] може бути провайдером або CLI:

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.5",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, used for multi-modal entries
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

# Типові значення та обмеження

Рекомендовані типові значення:

• maxChars: 500 для зображення/відео (коротко, зручно для команд)
• maxChars: не задано для аудіо (повний транскрипт, якщо ви не встановите ліміт)
• maxBytes:
  • зображення: 10MB
  • аудіо: 20MB
  • відео: 50MB

# Автовиявлення розуміння медіа (типово)

Якщо tools.media.<capability>.enabled не встановлено в false і ви не налаштували моделі, OpenClaw автовиявляє в такому порядку й зупиняється на першому робочому варіанті:

Щоб вимкнути автовиявлення, задайте:

{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}

# Підтримка proxy-середовища (моделі провайдерів)

Коли ввімкнене медіарозуміння аудіо та відео на основі провайдерів, OpenClaw враховує стандартні змінні середовища вихідного proxy для HTTP-викликів провайдера:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

Якщо env vars proxy не задані, медіарозуміння використовує прямий вихід. Якщо значення proxy має неправильний формат, OpenClaw записує попередження в журнал і повертається до прямого fetch.

# Можливості (необов’язково)

Якщо ви задаєте capabilities, запис запускається лише для цих типів медіа. Для спільних списків OpenClaw може вивести типові значення:

• openai, anthropic, minimax: зображення
• minimax-portal: зображення
• moonshot: зображення + відео
• openrouter: зображення
• google (Gemini API): зображення + аудіо + відео
• qwen: зображення + відео
• mistral: аудіо
• zai: зображення
• groq: аудіо
• xai: аудіо
• deepgram: аудіо
• Будь-який каталог models.providers.<id>.models[] із моделлю, що підтримує зображення: зображення

Для записів CLI задавайте capabilities явно, щоб уникнути неочікуваних збігів. Якщо ви пропускаєте capabilities, запис є придатним для списку, в якому він з’являється.

# Матриця підтримки провайдерів (інтеграції OpenClaw)

# Поради щодо вибору моделі

• Надавайте перевагу найсильнішій доступній моделі останнього покоління для кожної медіаможливості, коли якість і безпека мають значення.
• Для агентів із увімкненими інструментами, які обробляють недовірені вхідні дані, уникайте старіших/слабших медіамоделей.
• Тримайте принаймні один fallback для кожної можливості задля доступності (якісна модель + швидша/дешевша модель).
• CLI fallback-и (whisper-cli, whisper, gemini) корисні, коли API провайдерів недоступні.
• Примітка parakeet-mlx: з --output-dir OpenClaw читає <output-dir>/<media-basename>.txt, коли формат виводу txt (або не вказаний); формати не txt повертаються до stdout.

# Політика вкладень

attachments для кожної можливості керує тим, які вкладення обробляються:

Коли mode: "all", вихідні дані позначаються [Image 1/2], [Audio 2/2] тощо.

# Приклади конфігурації

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.5", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
        {
          type: "cli",
          command: "gemini",
          args: [
            "-m",
            "gemini-3-flash",
            "--allowed-tools",
            "read_file",
            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
          },
        ],
      },
      video: {
        enabled: true,
        maxChars: 500,
        models: [
          { provider: "google", model: "gemini-3-flash-preview" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.5" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

{
  tools: {
    media: {
      image: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      audio: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      video: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
    },
  },
}

# Вивід стану

Коли працює розуміння медіа, /status містить короткий рядок підсумку:

📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)

Це показує результати для кожної можливості та вибраного провайдера/модель, коли це застосовно.

# Примітки

• Розуміння виконується за принципом найкращих зусиль. Помилки не блокують відповіді.
• Вкладення все одно передаються моделям, навіть коли розуміння вимкнено.
• Використовуйте scope, щоб обмежити, де виконується розуміння (наприклад, лише в особистих повідомленнях).

# Пов’язане

• Конфігурація
• Підтримка зображень і медіа