--- read_when: - Проєктування або рефакторинг розуміння медіаконтенту - Налаштування попередньої обробки вхідних аудіо, відео та зображень sidebarTitle: Media understanding summary: Розпізнавання вхідних зображень, аудіо та відео (необов’язково) з резервними варіантами через провайдера та CLI title: Розуміння медіа x-i18n: generated_at: "2026-07-12T13:25:05Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 4ea61063948ed7d058c3f11f53f7afd443bbb970b0c0cb050f35cfba210ea81b source_path: nodes/media-understanding.md workflow: 16 --- OpenClaw може підсумовувати вхідні медіафайли (зображення/аудіо/відео) до запуску конвеєра відповіді, щоб розбір команд і маршрутизація працювали з коротким текстом, а не з необробленими байтами. Розпізнавання автоматично виявляє локальні інструменти або ключі провайдерів; також можна явно налаштувати моделі. Оригінальні медіафайли завжди передаються моделі у звичайному режимі; якщо розпізнавання завершується помилкою або вимкнене, процес відповіді триває без змін. Плагіни постачальників реєструють метадані можливостей (який провайдер підтримує який тип медіа, модель за замовчуванням, пріоритет). Ядро OpenClaw керує спільною конфігурацією `tools.media`, порядком резервних варіантів та інтеграцією з конвеєром відповіді. ## Як це працює Збирає вхідні вкладення (`MediaPaths`, `MediaUrls`, `MediaTypes`). Для кожної ввімкненої можливості (зображення/аудіо/відео) вибирає вкладення відповідно до політики `attachments` (за замовчуванням — лише перше вкладення). Вибирає перший придатний запис моделі (розмір + можливість + доступна автентифікація). Якщо модель повертає помилку, перевищує час очікування або розмір медіафайлу перевищує `maxBytes`, використовується наступний запис. `Body` перетворюється на блок `[Image]`, `[Audio]` або `[Video]`. Для аудіо також задається `{{Transcript}}`; для розбору команд використовується текст підпису, якщо він наявний, інакше — транскрипція. Підписи зберігаються всередині блоку як `User text:`. ## Конфігурація `tools.media` містить спільний список моделей і перевизначення для окремих можливостей: ```json5 { 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` | - | - | Перевизначення запиту провайдера; див. [Інструменти та власні провайдери](/uk/gateway/config-tools) | | `attachments` | об’єкт | `{ mode: "first", maxAttachments: 1 }` | Див. [Політика вкладень](#attachment-policy) | | `scope` | об’єкт | не задано | Обмеження за каналом/chatType/keyPrefix | | `echoTranscript` | `boolean` | `false` | Лише аудіо: надсилає транскрипцію назад у чат до обробки агентом | | `echoFormat` | `string` | `'📝 "{transcript}"'` | Лише аудіо: заповнювач `{transcript}` | Параметри, специфічні для Deepgram, розміщуються в `providerOptions.deepgram` (поле верхнього рівня `deepgram: { detectLanguage, punctuate, smartFormat }` застаріле, але все ще зчитується). ### Записи моделей Кожен запис `models[]` є записом **провайдера** (за замовчуванням) або записом **CLI**: ```json5 { 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", } ``` ```json5 { 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..apiKey`. Записи `tools.media.*.models[]` не приймають вбудоване поле `apiKey`. ```json5 { models: { providers: { openai: { apiKey: "" }, moonshot: { apiKey: "" }, }, }, } ``` Відомості про профілі, змінні середовища та власні базові URL-адреси див. у розділі [Інструменти та власні провайдери](/uk/gateway/config-tools). ## Правила та поведінка - Якщо розмір медіафайлу перевищує `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 --model ` (псевдонім: `openclaw capability image describe`) безпосередньо запускає відповідного провайдера/модель із підтримкою зображень, включно з посиланнями Ollama на кшталт `ollama/qwen2.5vl:7b`, якщо відповідну модель із підтримкою зображень налаштовано в `models.providers.ollama.models[]`. - Якщо `.enabled` не має значення `false`, але моделі не налаштовані, OpenClaw намагається використати активну модель відповіді, коли її провайдер підтримує цю можливість. ### Автоматичне виявлення (за замовчуванням) Якщо `tools.media..enabled` не має значення `false` і моделі не налаштовані, OpenClaw послідовно випробовує наведені нижче варіанти й зупиняється на першому працездатному: Основні/резервні посилання `agents.defaults.imageModel`, якщо активна модель відповіді ще не підтримує комп’ютерний зір нативно. Надавайте перевагу посиланням `provider/model`; прості посилання доповнюються даними з налаштованих записів моделей провайдера з підтримкою зображень, лише якщо збіг однозначний. Активна модель відповіді, якщо її провайдер підтримує цю можливість. Налаштовані записи `models.providers.*`, що підтримують аудіо, випробовуються перед локальними CLI. Порядок пріоритету вбудованих провайдерів (за однакового пріоритету — за алфавітом ідентифікатора провайдера): Groq/OpenAI → xAI → Deepgram → OpenRouter → Google/SenseAudio → Deepinfra/ElevenLabs → Mistral. Готові локальні виконувані файли утворюють упорядкований список резервних варіантів: - `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 Перший установлений виконуваний файл `agy` або `antigravity` (можна перевизначити через `OPENCLAW_ANTIGRAVITY_CLI`), ізольований у межах каталогу медіафайлу. Щоб вимкнути автоматичне виявлення для певної можливості: ```json5 { 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..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 заявляють про підтримку введення зображень. ## Рекомендації щодо вибору моделі - Якщо важливі якість і безпека, віддавайте перевагу найпотужнішій моделі поточного покоління для кожної можливості обробки медіа. - Для агентів із підтримкою інструментів, які обробляють ненадійні вхідні дані, уникайте старіших або слабших медіамоделей. - Зберігайте щонайменше один резервний варіант для кожної можливості, щоб забезпечити доступність (якісна модель + швидша або дешевша модель). - Резервні варіанти CLI (`whisper-cli`, `whisper`, `gemini`) допомагають, коли API постачальників недоступні. - Відомі режими виведення у файл є визначальними: порожній або відсутній очікуваний файл транскрипції не створює транскрипції замість переходу до виведення перебігу роботи CLI. - `parakeet-mlx`: використовуйте `--output-format txt` (або `all`) разом із `--output-dir` і стандартним шаблоном виведення `{filename}`. Також підтримуються змінні середовища `PARAKEET_OUTPUT_FORMAT` і `PARAKEET_OUTPUT_TEMPLATE` з основного проєкту. OpenClaw читає `/.txt`; стандартний формат `srt`, інші формати та власні шаблони виведення й надалі використовують stdout. ## Політика вкладень Параметр `attachments` для кожної можливості визначає, які вкладення обробляються: Обробляти лише перше вибране вкладення або всі вкладення. Обмежує кількість оброблюваних вкладень. Визначає пріоритет вибору серед вкладень-кандидатів. Коли задано `mode: "all"`, результати позначаються як `[Зображення 1/2]`, `[Аудіо 2/2]` тощо. ### Видобування вмісту з файлових вкладень - Видобутий із файлу текст перед додаванням до медіазапиту обгортається як ненадійний зовнішній вміст із використанням межових маркерів на кшталт `<<>>` / `<<>>` і рядка метаданих `Source: External`. - У цьому шляху навмисно пропущено довгий банер `SECURITY NOTICE:`, щоб медіазапит залишався коротким; межові маркери та метадані все одно застосовуються. - Для файлу, з якого неможливо видобути текст, використовується `[No extractable text]`. - Якщо для PDF застосовується резервний варіант із рендерингом зображень сторінок, OpenClaw передає ці зображення моделям відповідей із підтримкою комп’ютерного зору та зберігає заповнювач `[PDF content rendered to images]` у блоці файлу. ## Приклади конфігурації ```json5 { 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, }, }, }, } ``` ```json5 { 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.", ], }, ], }, }, }, } ``` ```json5 { 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.", ], }, ], }, }, }, } ``` ```json5 { 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: ```bash openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info ``` ## Примітки - Розпізнавання виконується за принципом найкращих зусиль. Помилки не блокують відповіді. - Вкладення все одно передаються моделям, навіть коли розпізнавання вимкнено. - Використовуйте `scope`, щоб обмежити місця виконання розпізнавання (наприклад, лише приватними повідомленнями). ## Пов’язані матеріали - [Конфігурація](/uk/gateway/configuration) - [Підтримка зображень і медіа](/uk/nodes/images)