Понимание медиа (входящие) — 2026-01-17

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

Цели

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

Поведение высокого уровня

  1. Собрать входящие вложения (MediaPaths, MediaUrls, MediaTypes).
  2. Для каждой включенной возможности (изображение/аудио/видео) выбрать вложения по политике (по умолчанию: первое).
  3. Выбрать первую подходящую запись модели (размер + возможность + аутентификация).
  4. Если модель терпит неудачу или медиа слишком велико, переключиться на следующую запись.
  5. При успехе:
    • Body становится блоком [Image], [Audio] или [Video].
    • Аудио устанавливает \{\{Transcript\}\}; разбор команд использует текст подписи, когда присутствует, иначе транскрипт.
    • Подписи сохраняются как User text: внутри блока.

Если понимание терпит неудачу или отключено, поток ответа продолжается с оригинальным телом + вложениями.

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

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

  • tools.media.models: общий список моделей (используйте capabilities для контроля).
  • tools.media.image / tools.media.audio / tools.media.video:
    • значения по умолчанию (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • переопределения провайдера (baseUrl, headers, providerOptions)
    • опции аудио Deepgram через tools.media.audio.providerOptions.deepgram
    • опциональный список models для каждой возможности (предпочтителен перед общими моделями)
    • политика attachments (mode, maxAttachments, prefer)
    • scope (опциональное управление по каналу/chatType/ключу сессии)
  • tools.media.concurrency: максимальное количество одновременных запусков возможностей (по умолчанию 2).
{
  tools: {
    media: {
      models: [ /* общий список */ ],
      image: { /* опциональные переопределения */ },
      audio: { /* опциональные переопределения */ },
      video: { /* опциональные переопределения */ }
    }
  }
}

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

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

{
  type: "provider",        // по умолчанию если опущено
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  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",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters."
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"]
}

Шаблоны CLI также могут использовать:

  • \{\{MediaDir\}\} (каталог, содержащий медиа файл)
  • \{\{OutputDir\}\} (временный каталог, созданный для этого запуска)
  • \{\{OutputBase\}\} (временный путь к базе файла, без расширения)

Значения по умолчанию и ограничения

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

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

Правила:

  • Если медиа превышает maxBytes, эта модель пропускается, и пробуется следующая модель.
  • Если модель возвращает больше, чем maxChars, вывод обрезается.
  • prompt по умолчанию простое "Describe the {media}." плюс руководство maxChars (только изображение/видео).
  • Если <capability>.enabled: true, но модели не настроены, OpenClaw пробует активную модель ответа, когда ее провайдер поддерживает возможность.

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

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

  1. Локальные CLI (только аудио; если установлены)
    • sherpa-onnx-offline (требуется SHERPA_ONNX_MODEL_DIR с encoder/decoder/joiner/tokens)
    • whisper-cli (whisper-cpp; использует WHISPER_CPP_MODEL или встроенную tiny модель)
    • whisper (Python CLI; автоматически загружает модели)
  2. Gemini CLI (gemini) с использованием read_many_files
  3. Ключи провайдеров
    • Аудио: OpenAI → Groq → Deepgram → Google
    • Изображение: OpenAI → Anthropic → Google → MiniMax
    • Видео: Google

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

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

Примечание: Обнаружение бинарных файлов выполняется с максимальными усилиями для macOS/Linux/Windows; убедитесь, что CLI находится в PATH (мы расширяем ~), или установите явную модель CLI с полным путем к команде.

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

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

  • openai, anthropic, minimax: изображение
  • google (Gemini API): изображение + аудио + видео
  • groq: аудио
  • deepgram: аудио

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

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

ВозможностьИнтеграция провайдераПримечания
ИзображениеOpenAI / Anthropic / Google / другие через pi-aiЛюбая модель с возможностью изображения в реестре работает.
АудиоOpenAI, Groq, Deepgram, GoogleТранскрипция провайдера (Whisper/Deepgram/Gemini).
ВидеоGoogle (Gemini API)Понимание видео провайдера.

Рекомендуемые провайдеры

Изображение

  • Предпочтите вашу активную модель, если она поддерживает изображения.
  • Хорошие значения по умолчанию: openai/gpt-5.2, anthropic/claude-opus-4-5, google/gemini-3-pro-preview.

Аудио

  • openai/gpt-4o-mini-transcribe, groq/whisper-large-v3-turbo или deepgram/nova-3.
  • CLI резервный: whisper-cli (whisper-cpp) или whisper.
  • Настройка Deepgram: Deepgram (audio transcription).

Видео

  • google/gemini-3-flash-preview (быстро), google/gemini-3-pro-preview (богаче).
  • CLI резервный: CLI gemini (поддерживает read_file для видео/аудио).

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

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

  • mode: first (по умолчанию) или all
  • maxAttachments: ограничение количества обработанных (по умолчанию 1)
  • prefer: first, last, path, url

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

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

1) Общий список моделей + переопределения

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", 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
      }
    }
  }
}

2) Только аудио + видео (изображение выключено)

{
  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."
            ]
          }
        ]
      }
    }
  }
}

3) Опциональное понимание изображений

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-5" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters."
            ]
          }
        ]
      }
    }
  }
}

4) Мультимодальная одна запись (явные возможности)

{
  tools: {
    media: {
      image: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] },
      audio: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] },
      video: { models: [{ provider: "google", model: "gemini-3-pro-preview", capabilities: ["image", "video", "audio"] }] }
    }
  }
}

Вывод статуса

Когда работает понимание медиа, /status включает короткую строку сводки:

📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)

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

Примечания

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

Связанные документы

← Назад к документации