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

OpenClaw может суммаризировать входящие медиа (изображения/аудио/видео) до запуска конвейера ответа. Он автоматически определяет, доступны ли локальные инструменты или ключи провайдера, и его можно отключить или настроить. Если понимание отключено, модели по-прежнему получают исходные файлы/URL как обычно.

Поведение медиа, специфичное для вендора, регистрируется Plugin вендора, а ядро OpenClaw отвечает за общую конфигурацию tools.media, порядок fallback и интеграцию с конвейером ответа.

Цели

• Опционально: предварительно преобразовывать входящие медиа в краткий текст для более быстрой маршрутизации и лучшего разбора команд.
• Сохранять доставку исходных медиа модели (всегда).
• Поддерживать API провайдеров и CLI fallback.
• Разрешать несколько моделей с упорядоченным fallback (ошибка/размер/таймаут).

Высокоуровневое поведение

Если понимание завершается с ошибкой или отключено, поток ответа продолжается с исходным body + вложениями.

Обзор конфигурации

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

{  tools: {    media: {      models: [        /* shared list */      ],      image: {        /* optional overrides */      },      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {        /* optional overrides */      },    },  },}

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

Каждая запись models[] может быть provider или CLI:

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.5",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, used for multi-modal 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"],}

Учетные данные провайдера (apiKey)

Понимание медиа провайдером использует то же разрешение авторизации провайдера, что и обычные вызовы моделей: профили авторизации, переменные окружения, затем models.providers.<providerId>.apiKey.

Записи tools.media.*.models[] не принимают встроенное поле apiKey. Значение provider в записи модели медиа, например openai или moonshot, должно иметь учетные данные, доступные через один из стандартных источников авторизации провайдера.

Минимальный пример:

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

Полную справку по авторизации провайдера, включая профили, переменные окружения и пользовательские базовые URL, см. в Инструменты и пользовательские провайдеры.

Значения по умолчанию и лимиты

Рекомендуемые значения по умолчанию:

• maxChars: 500 для изображений/видео (кратко, удобно для команд)
• maxChars: не задано для аудио (полный транскрипт, если вы не зададите лимит)
• maxBytes:
  • изображение: 10MB
  • аудио: 20MB
  • видео: 50MB

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

Если tools.media.<capability>.enabled не задано как false и вы не настроили модели, OpenClaw автоматически определяет в этом порядке и останавливается на первом рабочем варианте:

Чтобы отключить автоопределение, задайте:

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

Поддержка прокси через окружение (модели провайдеров)

Когда включено понимание медиа аудио и видео на основе провайдера, OpenClaw учитывает стандартные переменные окружения исходящего прокси для HTTP-вызовов провайдера:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

Если переменные окружения прокси не заданы, понимание медиа использует прямой исходящий доступ. Если значение прокси имеет неверный формат, OpenClaw записывает предупреждение в журнал и возвращается к прямой загрузке.

Возможности (опционально)

Если вы задаете capabilities, запись запускается только для этих типов медиа. Для общих списков OpenClaw может вывести значения по умолчанию:

• openai, anthropic, minimax: изображение
• minimax-portal: изображение
• moonshot: изображение + видео
• openrouter: изображение + аудио
• google (Gemini API): изображение + аудио + видео
• qwen: изображение + видео
• mistral: аудио
• zai: изображение
• groq: аудио
• xai: аудио
• deepgram: аудио
• Любой каталог models.providers.<id>.models[] с моделью, поддерживающей изображения: изображение

Для записей CLI задавайте capabilities явно, чтобы избежать неожиданных совпадений. Если вы опустите capabilities, запись будет подходящей для списка, в котором она находится.

Матрица поддержки провайдеров (интеграции OpenClaw)

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

• Предпочитайте самую сильную модель последнего поколения, доступную для каждой медиа-возможности, когда важны качество и безопасность.
• Для агентов с инструментами, обрабатывающих недоверенный ввод, избегайте старых или более слабых медиа-моделей.
• Держите как минимум один резервный вариант для каждой возможности ради доступности (качественная модель + более быстрая или дешевая модель).
• Резервные варианты CLI (whisper-cli, whisper, gemini) полезны, когда API провайдеров недоступны.
• Примечание по parakeet-mlx: с --output-dir OpenClaw читает <output-dir>/<media-basename>.txt, когда формат вывода равен txt (или не указан); форматы не txt используют stdout как резервный вариант.

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

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

Когда mode: "all", результаты помечаются как [Image 1/2], [Audio 2/2] и т. д.

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

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.5", 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.5" },          { provider: "anthropic", model: "claude-opus-4-6" },          {            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.4) · audio skipped (maxBytes)

Она показывает результаты по каждой возможности и выбранного провайдера/модель, когда применимо.

Примечания

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

Связанные материалы

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