--- read_when: - Проектирование или рефакторинг распознавания медиаконтента - Настройка предварительной обработки входящих аудио, видео и изображений sidebarTitle: Media understanding summary: Распознавание входящих изображений, аудио и видео (необязательно) с резервными вариантами через провайдера и CLI title: Понимание медиаконтента x-i18n: generated_at: "2026-07-13T18:22:19Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 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, // максимальное число одновременно выполняемых операций возможностей (по умолчанию) models: [/* shared list, gate with capabilities */], image: {/* необязательные переопределения */}, audio: { /* необязательные переопределения */ echoTranscript: true, echoFormat: '📝 "{transcript}"', }, video: {/* необязательные переопределения */}, }, }, } ``` Ключи для отдельных возможностей (`image`/`audio`/`video`): | Ключ | Тип | Значение по умолчанию | Примечания | | ----------------------------------------------- | --------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- | | `enabled` | `boolean` | автоматически (`false` отключает) | Задайте `false`, чтобы отключить автообнаружение для этой возможности | | `models` | массив | нет | Имеет приоритет перед общим списком `tools.media.models` | | `prompt` | `string` | `"Describe the {media}."` (+ указания maxChars) | По умолчанию только для изображений и видео | | `maxChars` | `number` | `500` (изображения/видео), не задано (аудио) | Вывод обрезается, если модель возвращает больше | | `maxBytes` | `number` | изображения `10485760`, аудио `20971520`, видео `52428800` | При превышении размера выполняется переход к следующей модели | | `timeoutSeconds` | `number` | `60` (изображения/аудио), `120` (видео) | | | `language` | `string` | не задано | Подсказка для расшифровки аудио | | `baseUrl`/`headers`/`providerOptions`/`request` | - | - | Переопределения запроса провайдера; см. [Инструменты и пользовательские провайдеры](/ru/gateway/config-tools) | | `attachments` | объект | `{ mode: "first", maxAttachments: 1 }` | См. [Политика вложений](#attachment-policy) | | `scope` | объект | не задано | Ограничение по channel/chatType/keyPrefix | | `echoTranscript` | `boolean` | `false` | Только аудио: отправить расшифровку обратно в чат до обработки агентом | | `echoFormat` | `string` | `'📝 "{transcript}"'` | Только аудио: заполнитель `{transcript}` | Параметры, относящиеся к Deepgram, задаются в `providerOptions.deepgram` (поле верхнего уровня `deepgram: { detectLanguage, punctuate, smartFormat }` устарело, но по-прежнему считывается). ### Записи моделей Каждая запись `models[]` является записью **провайдера** (по умолчанию) или записью **CLI**: ```json5 { type: "provider", // значение по умолчанию, если не указано provider: "openai", model: "gpt-5.6-sol", prompt: "Опишите изображение не более чем 500 символами.", maxChars: 500, maxBytes: 10485760, timeoutSeconds: 60, capabilities: ["image"], // необязательно, для общих мультимодальных записей profile: "vision-profile", preferredProfile: "vision-fallback", } ``` ```json5 { type: "cli", command: "gemini", args: [ "-m", "gemini-3-flash", "--allowed-tools", "read_file", "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.", ], 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 см. в разделе [Инструменты и пользовательские провайдеры](/ru/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 оставляет журналы запуска модели включёнными, чтобы можно было записать строку выбранного бэкенда от вышестоящего компонента. Явные записи 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`, другие форматы и пользовательские шаблоны вывода продолжают использовать стандартный вывод. ## Политика вложений Параметр `attachments` для каждой возможности определяет, какие вложения обрабатываются: Обрабатывать только первое выбранное вложение или все вложения. Ограничить количество обрабатываемых вложений. Предпочтение при выборе среди вложений-кандидатов. Когда `mode: "all"`, результаты помечаются как `[Image 1/2]`, `[Audio 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", "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.", ], 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", "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.", ], }, ], }, }, }, } ``` ```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", "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.", ], }, ], }, }, }, } ``` ```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` содержит строку сводки для каждой возможности: ``` 📎 Медиа: изображение — успешно (openai/gpt-5.6-sol) · аудио — успешно (whisper-cli обнаружено=metal) ``` Для предварительной инвентаризации выполните `openclaw capability audio providers`. В локальных строках победивший локальный резервный вариант отображается отдельно от глобального выбора провайдера, готовности и отдельных полей доступного, запрошенного и обнаруженного бэкенда. Тот же локальный выбор доступен как информационный результат диагностики: ```bash openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info ``` ## Примечания - Распознавание выполняется по мере возможности. Ошибки не блокируют ответы. - Вложения всё равно передаются моделям, даже когда распознавание отключено. - Используйте `scope`, чтобы ограничить область выполнения распознавания (например, только личными сообщениями). ## См. также - [Конфигурация](/ru/gateway/configuration) - [Поддержка изображений и медиа](/ru/nodes/images)