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

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

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

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

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

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

{  tools: {    media: {      concurrency: 2, // максимальное число одновременно выполняемых операций возможностей (по умолчанию)      models: [/* shared list, gate with capabilities */],      image: {/* необязательные переопределения */},      audio: {        /* необязательные переопределения */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* необязательные переопределения */},    },  },}

Ключи для отдельных возможностей (image/audio/video):

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

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

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

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

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

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

Параметр attachments для каждой возможности определяет, какие вложения обрабатываются:

Когда mode: "all", результаты помечаются как [Image 1/2], [Audio 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",            "Прочитайте медиафайл по пути {{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, чтобы ограничить область выполнения распознавания (например, только личными сообщениями).

См. также

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