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

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

Як це працює

Збирання вкладень

Збирає вхідні вкладення (MediaPaths, MediaUrls, MediaTypes).

Вибір для кожної можливості

Для кожної ввімкненої можливості (зображення/аудіо/відео) вибирає вкладення відповідно до політики attachments (за замовчуванням — лише перше вкладення).

Вибір моделі

Вибирає перший придатний запис моделі (розмір + можливість + доступна автентифікація).

Перехід до резервного варіанта в разі помилки

Якщо модель повертає помилку, перевищує час очікування або розмір медіафайлу перевищує maxBytes, використовується наступний запис.

Застосування в разі успіху

Body перетворюється на блок [Image], [Audio] або [Video]. Для аудіо також задається {{Transcript}}; для розбору команд використовується текст підпису, якщо він наявний, інакше — транскрипція. Підписи зберігаються всередині блоку як User text:.

Конфігурація

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

{
  tools: {
    media: {
      concurrency: 2, // max concurrent capability runs (default)
      models: [/* shared list, gate with capabilities */],
      image: {/* optional overrides */},
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {/* optional overrides */},
    },
  },
}

Ключі для окремих можливостей (image/audio/video):

Ключ	Тип	Значення за замовчуванням	Примітки
`enabled`	`boolean`	автоматично (`false` вимикає)	Установіть `false`, щоб вимкнути автоматичне виявлення для цієї можливості
`models`	масив	немає	Мають пріоритет над спільним списком `tools.media.models`
`prompt`	`string`	`"Describe the {media}."` (+ вказівка щодо maxChars)	За замовчуванням лише для зображень/відео
`maxChars`	`number`	`500` (зображення/відео), не задано (аудіо)	Результат обрізається, якщо модель повертає більше
`maxBytes`	`number`	image `10485760`, audio `20971520`, video `52428800`	Для завеликих медіафайлів використовується наступна модель
`timeoutSeconds`	`number`	`60` (зображення/аудіо), `120` (відео)
`language`	`string`	не задано	Підказка щодо мови транскрибування аудіо
`baseUrl`/`headers`/`providerOptions`/`request`	-	-	Перевизначення запиту провайдера; див. Інструменти та власні провайдери
`attachments`	об’єкт	`{ mode: "first", maxAttachments: 1 }`	Див. Політика вкладень
`scope`	об’єкт	не задано	Обмеження за каналом/chatType/keyPrefix
`echoTranscript`	`boolean`	`false`	Лише аудіо: надсилає транскрипцію назад у чат до обробки агентом
`echoFormat`	`string`	`'📝 "{transcript}"'`	Лише аудіо: заповнювач `{transcript}`

Параметри, специфічні для Deepgram, розміщуються в providerOptions.deepgram (поле верхнього рівня deepgram: { detectLanguage, punctuate, smartFormat } застаріле, але все ще зчитується).

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

Кожен запис models[] є записом провайдера (за замовчуванням) або записом CLI:

Запис провайдера
Запис CLI

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.6-sol",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, for multi-modal shared 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"],
}

Шаблони CLI також можуть використовувати {{MediaDir}} (каталог, що містить медіафайл), {{OutputDir}} (тимчасовий каталог, створений для цього запуску) і {{OutputBase}} (базовий шлях тимчасового файла без розширення).

Облікові дані провайдера

Для розпізнавання медіа через провайдера використовується той самий порядок визначення автентифікації, що й для звичайних викликів моделей: профілі автентифікації, змінні середовища, потім models.providers.<providerId>.apiKey. Записи tools.media.*.models[] не приймають вбудоване поле apiKey.

{
  models: {
    providers: {
      openai: { apiKey: "<OPENAI_API_KEY>" },
      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },
    },
  },
}

Відомості про профілі, змінні середовища та власні базові URL-адреси див. у розділі Інструменти та власні провайдери.

Правила та поведінка

Якщо розмір медіафайлу перевищує maxBytes, ця модель пропускається й використовується наступна.
Аудіофайли розміром менш як 1024 байти вважаються порожніми або пошкодженими та пропускаються до транскрибування; натомість агент отримує детерміновану транскрипцію-заповнювач.
Якщо активна основна модель зображень уже нативно підтримує комп’ютерний зір, OpenClaw пропускає блок підсумку [Image] і передає оригінальне зображення безпосередньо моделі. MiniMax є винятком: minimax, minimax-cn, minimax-portal і minimax-portal-cn завжди спрямовують розпізнавання зображень через медіапровайдер MiniMax-VL-01, яким керує плагін, навіть якщо застарілі метадані чат-моделей MiniMax M2.x заявляють про підтримку введення зображень (лише MiniMax-M3 та новіші моделі вважаються такими, що нативно підтримують комп’ютерний зір).
Якщо основна модель Gateway/WebChat підтримує лише текст, вкладені зображення зберігаються як вивантажені посилання media://inbound/*, щоб інструменти для зображень/PDF або налаштована модель зображень могли й надалі їх перевірити, а вкладення не втрачалося.
Явна команда openclaw infer image describe --file <path> --model <provider/model> (псевдонім: openclaw capability image describe) безпосередньо запускає відповідного провайдера/модель із підтримкою зображень, включно з посиланнями Ollama на кшталт ollama/qwen2.5vl:7b, якщо відповідну модель із підтримкою зображень налаштовано в models.providers.ollama.models[].
Якщо <capability>.enabled не має значення false, але моделі не налаштовані, OpenClaw намагається використати активну модель відповіді, коли її провайдер підтримує цю можливість.

Автоматичне виявлення (за замовчуванням)

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

Налаштована модель зображень (лише зображення)

Основні/резервні посилання agents.defaults.imageModel, якщо активна модель відповіді ще не підтримує комп’ютерний зір нативно. Надавайте перевагу посиланням provider/model; прості посилання доповнюються даними з налаштованих записів моделей провайдера з підтримкою зображень, лише якщо збіг однозначний.

Активна модель відповіді

Активна модель відповіді, якщо її провайдер підтримує цю можливість.

Автентифікація провайдера (лише аудіо, перед локальними CLI)

Налаштовані записи models.providers.*, що підтримують аудіо, випробовуються перед локальними CLI. Порядок пріоритету вбудованих провайдерів (за однакового пріоритету — за алфавітом ідентифікатора провайдера): Groq/OpenAI → xAI → Deepgram → OpenRouter → Google/SenseAudio → Deepinfra/ElevenLabs → Mistral.

Локальні CLI (лише аудіо)

Готові локальні виконувані файли утворюють упорядкований список резервних варіантів:

whisper-cli використовується першим лише після того, як попередній виклик моделі в поточному процесі виявив Metal або CUDA
sherpa-onnx-offline із типовим використанням CPU (потребує SHERPA_ONNX_MODEL_DIR із файлами tokens.txt/encoder.onnx/decoder.onnx/joiner.onnx)
whisper-cli, коли прискорення лише підтримується збіркою або ще не було виявлене
parakeet-mlx на Apple Silicon (підтримує MLX, використання пристрою не виявлене)
whisper (CLI Python; за замовчуванням використовує модель turbo, завантажується автоматично)

Перевірка можливостей бекенду кешується й не завантажує модель. Підтримка збіркою, запитані прапорці бекенду та бекенд, виявлений під час фактичного виклику, залишаються окремими поняттями. Автоматично виявлений whisper.cpp залишає журналювання запуску моделі ввімкненим, щоб можна було записати рядок обраного бекенду від upstream-проєкту. Явні записи CLI зберігають налаштований порядок, прапорці бекенду та прапорці виведення.

Автентифікація провайдера (зображення/відео)

Налаштовані записи models.providers.*, що підтримують відповідну можливість, випробовуються перед вбудованим порядком резервних варіантів. Провайдери конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розпізнавання медіа, навіть якщо вони не є вбудованим плагіном постачальника.Порядок пріоритету вбудованих провайдерів (за однакового пріоритету — за алфавітом ідентифікатора провайдера):

Зображення: Anthropic/OpenAI → Google → MiniMax → Deepinfra → MiniMax Portal → Z.AI
Відео: Google → Qwen → Moonshot

CLI Antigravity (лише зображення/відео)

Перший установлений виконуваний файл agy або antigravity (можна перевизначити через OPENCLAW_ANTIGRAVITY_CLI), ізольований у межах каталогу медіафайлу.

Щоб вимкнути автоматичне виявлення для певної можливості:

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

Виявлення виконуваних файлів у macOS/Linux/Windows виконується за принципом максимально можливих зусиль; переконайтеся, що CLI доступний у PATH (~ розгортається), або задайте явний запис моделі CLI з повним шляхом до команди.

Підтримка проксі (виклики провайдерів аудіо/відео)

Розпізнавання аудіо та відео через провайдерів враховує стандартні змінні середовища вихідного проксі, включно з правилами обходу NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Змінні в нижньому регістрі мають пріоритет над змінними у верхньому регістрі. Якщо жодну з них не задано, розпізнавання медіа використовує пряме вихідне з’єднання; якщо значення проксі має неправильний формат, OpenClaw записує попередження в журнал і переходить до прямого отримання даних. Розпізнавання зображень не використовує цей шлях через проксі.

Можливості

Установіть capabilities у записі models[], щоб обмежити його певними типами медіа. Для спільних списків OpenClaw визначає значення за замовчуванням для кожного вбудованого провайдера:

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

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

Матриця підтримки постачальників

Можливість	Постачальники	Примітки
Зображення	Anthropic, Codex app-server, Deepinfra, Google, MiniMax, MiniMax Portal, Moonshot, OpenAI, OpenAI Codex OAuth, OpenRouter, Qwen, Z.AI, постачальники з конфігурації	Плагіни постачальників реєструють підтримку зображень; `openai/` може використовувати маршрутизацію за ключем API або Codex OAuth; `codex/` використовує обмежений цикл Codex app-server; постачальники з конфігурації, що підтримують зображення, реєструються автоматично.
Аудіо	Deepgram, Deepinfra, ElevenLabs, Google, Groq, Mistral, OpenAI, OpenRouter, SenseAudio, xAI	Транскрибування постачальником (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
Відео	Google, Moonshot, Qwen	Розпізнавання відео постачальником через плагіни постачальників; розпізнавання відео Qwen використовує стандартні кінцеві точки DashScope.

Примітка щодо MiniMax: розпізнавання зображень для minimax, minimax-cn, minimax-portal і minimax-portal-cn завжди забезпечує належний плагіну медіапостачальник MiniMax-VL-01, навіть якщо застарілі метадані чату MiniMax M2.x заявляють про підтримку введення зображень.

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

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

"first" | "all"

за замовчуванням:"first"

Обробляти лише перше вибране вкладення або всі вкладення.

number

за замовчуванням:"1"

Обмежує кількість оброблюваних вкладень.

"first" | "last" | "path" | "url"

Визначає пріоритет вибору серед вкладень-кандидатів.

Коли задано mode: "all", результати позначаються як [Зображення 1/2], [Аудіо 2/2] тощо.

Видобування вмісту з файлових вкладень

Видобутий із файлу текст перед додаванням до медіазапиту обгортається як ненадійний зовнішній вміст із використанням межових маркерів на кшталт <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> і рядка метаданих Source: External.
У цьому шляху навмисно пропущено довгий банер SECURITY NOTICE:, щоб медіазапит залишався коротким; межові маркери та метадані все одно застосовуються.
Для файлу, з якого неможливо видобути текст, використовується [No extractable text].
Якщо для PDF застосовується резервний варіант із рендерингом зображень сторінок, OpenClaw передає ці зображення моделям відповідей із підтримкою комп’ютерного зору та зберігає заповнювач [PDF content rendered to images] у блоці файлу.

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

Спільні моделі та перевизначення
Лише аудіо та відео
Лише зображення
Єдиний мультимодальний запис

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },
          { provider: "anthropic", model: "claude-opus-4-8" },
          {
            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.6-sol) · audio ok (whisper-cli observed=metal)

Щоб заздалегідь переглянути доступні можливості, виконайте openclaw capability audio providers. Локальні рядки окремо показують переможця серед локальних резервних варіантів, глобальний вибір постачальника, готовність, а також окремі поля придатного, запитаного й фактично використаного бекенду. Той самий локальний вибір доступний як інформаційний результат перевірки doctor:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Примітки

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

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

Як це працює

Конфігурація

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

Облікові дані провайдера

Правила та поведінка

Автоматичне виявлення (за замовчуванням)

Підтримка проксі (виклики провайдерів аудіо/відео)

Можливості

Матриця підтримки постачальників

Рекомендації щодо вибору моделі

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

Видобування вмісту з файлових вкладень

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

Виведення стану

Примітки

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

​Як це працює

​Конфігурація

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

​Облікові дані провайдера

​Правила та поведінка

​Автоматичне виявлення (за замовчуванням)

​Підтримка проксі (виклики провайдерів аудіо/відео)

​Можливості

​Матриця підтримки постачальників

​Рекомендації щодо вибору моделі

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

​Видобування вмісту з файлових вкладень

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

​Виведення стану

​Примітки

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

Як це працює

Конфігурація

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

Облікові дані провайдера

Правила та поведінка

Автоматичне виявлення (за замовчуванням)

Підтримка проксі (виклики провайдерів аудіо/відео)

Можливості

Матриця підтримки постачальників

Рекомендації щодо вибору моделі

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

Видобування вмісту з файлових вкладень

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

Виведення стану

Примітки

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