Розуміння медіа

OpenClaw може узагальнювати вхідні медіа (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдерів, і його можна вимкнути або налаштувати. Якщо розуміння вимкнено, моделі все одно отримують оригінальні файли/URL, як зазвичай.

Поведінка медіа, специфічна для постачальника, реєструється Plugin постачальників, тоді як ядро OpenClaw відповідає за спільну конфігурацію tools.media, порядок резервного переходу та інтеграцію з конвеєром відповіді.

Цілі

• Необов’язково: попередньо стискати вхідні медіа в короткий текст для швидшої маршрутизації + кращого розбору команд.
• Зберігати доставку оригінальних медіа до моделі (завжди).
• Підтримувати API провайдерів і резервні варіанти CLI.
• Дозволяти кілька моделей з упорядкованим резервним переходом (помилка/розмір/тайм-аут).

Загальна поведінка

Якщо розуміння не вдається або вимкнене, потік відповіді продовжується з оригінальним тілом + вкладеннями.

Огляд конфігурації

tools.media підтримує спільні моделі та перевизначення для окремих можливостей:

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

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

Кожен запис models[] може бути провайдером або 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, щоб обмежити, де виконується розуміння (наприклад, лише приватні повідомлення).

Пов’язане

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