Понимание медиаконтента

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

Как это работает

Сбор вложений

Собирает входящие вложения (MediaPaths, MediaUrls, MediaTypes).

Выбор для каждой возможности

Для каждой включённой возможности (изображения, аудио и видео) выбирает вложения согласно политике attachments (по умолчанию — только первое вложение).

Выбор модели

Выбирает первую подходящую запись модели (с учётом размера, возможности и наличия аутентификации).

Резервный вариант при ошибке

Если модель возвращает ошибку, превышает время ожидания или размер медиа превышает maxBytes, пробует следующую запись.

Применение при успешном результате

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

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

tools.media содержит общий список моделей и переопределения для отдельных возможностей:

{
  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`	-	-	Переопределения запроса провайдера; см. Инструменты и пользовательские провайдеры
`attachments`	объект	`{ mode: "first", maxAttachments: 1 }`	См. Политика вложений
`scope`	объект	не задано	Ограничение по channel/chatType/keyPrefix
`echoTranscript`	`boolean`	`false`	Только аудио: отправить расшифровку обратно в чат до обработки агентом
`echoFormat`	`string`	`'📝 "{transcript}"'`	Только аудио: заполнитель `{transcript}`

Параметры, относящиеся к Deepgram, задаются в providerOptions.deepgram (поле верхнего уровня deepgram: { detectLanguage, punctuate, smartFormat } устарело, но по-прежнему считывается).

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

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

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

{
  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",
}

{
  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.<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 оставляет журналы запуска модели включёнными, чтобы можно было записать строку выбранного бэкенда от вышестоящего компонента. Явные записи 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", результаты помечаются как [Image 1/2], [Audio 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",
            "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.",
          ],
          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",
              "Прочитайте медиафайл по пути {{MediaPath}} и опишите его не более чем {{MaxChars}} символами.",
            ],
          },
        ],
      },
    },
  },
}

{
  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}} символами.",
            ],
          },
        ],
      },
    },
  },
}

{
  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. В локальных строках победивший локальный резервный вариант отображается отдельно от глобального выбора провайдера, готовности и отдельных полей доступного, запрошенного и обнаруженного бэкенда. Тот же локальный выбор доступен как информационный результат диагностики:

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

Примечания

Распознавание выполняется по мере возможности. Ошибки не блокируют ответы.
Вложения всё равно передаются моделям, даже когда распознавание отключено.
Используйте scope, чтобы ограничить область выполнения распознавания (например, только личными сообщениями).

Gateway

Remote access

Security

Nodes and media

Web interfaces

Понимание медиаконтента

Как это работает

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

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

Учётные данные провайдера

Правила и поведение

Автообнаружение (по умолчанию)

Поддержка прокси (вызовы провайдеров аудио/видео)

Возможности

Матрица поддержки провайдеров

Рекомендации по выбору модели

Политика вложений

Извлечение данных из файловых вложений

Примеры конфигурации

Вывод состояния

Примечания

См. также

​Как это работает

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

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

​Учётные данные провайдера

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

​Автообнаружение (по умолчанию)

​Поддержка прокси (вызовы провайдеров аудио/видео)

​Возможности

​Матрица поддержки провайдеров

​Рекомендации по выбору модели

​Политика вложений

​Извлечение данных из файловых вложений

​Примеры конфигурации

​Вывод состояния

​Примечания

​См. также

Как это работает

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

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

Учётные данные провайдера

Правила и поведение

Автообнаружение (по умолчанию)

Поддержка прокси (вызовы провайдеров аудио/видео)

Возможности

Матрица поддержки провайдеров

Рекомендации по выбору модели

Политика вложений

Извлечение данных из файловых вложений

Примеры конфигурации

Вывод состояния

Примечания

См. также