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

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

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

Як це працює

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

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):

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

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

Кожен запис models[] є записом провайдера (за замовчуванням) або записом 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"],}

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

Для розпізнавання медіа через провайдера використовується той самий порядок визначення автентифікації, що й для звичайних викликів моделей: профілі автентифікації, змінні середовища, потім 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 послідовно випробовує наведені нижче варіанти й зупиняється на першому працездатному:

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

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

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

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

Можливості

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

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

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

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

• Якщо важливі якість і безпека, віддавайте перевагу найпотужнішій моделі поточного покоління для кожної можливості обробки медіа.
• Для агентів із підтримкою інструментів, які обробляють ненадійні вхідні дані, уникайте старіших або слабших медіамоделей.
• Зберігайте щонайменше один резервний варіант для кожної можливості, щоб забезпечити доступність (якісна модель + швидша або дешевша модель).
• Резервні варіанти CLI (whisper-cli, whisper, gemini) допомагають, коли API постачальників недоступні.
• Відомі режими виведення у файл є визначальними: порожній або відсутній очікуваний файл транскрипції не створює транскрипції замість переходу до виведення перебігу роботи CLI.
• parakeet-mlx: використовуйте --output-format txt (або all) разом із --output-dir і стандартним шаблоном виведення {filename}. Також підтримуються змінні середовища PARAKEET_OUTPUT_FORMAT і PARAKEET_OUTPUT_TEMPLATE з основного проєкту. OpenClaw читає <output-dir>/<media-basename>.txt; стандартний формат srt, інші формати та власні шаблони виведення й надалі використовують stdout.

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

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

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

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

• Видобутий із файлу текст перед додаванням до медіазапиту обгортається як ненадійний зовнішній вміст із використанням межових маркерів на кшталт <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> і рядка метаданих 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, щоб обмежити місця виконання розпізнавання (наприклад, лише приватними повідомленнями).

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

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