Rozumienie multimediów

OpenClaw może podsumowywać przychodzące multimedia (obraz/audio/wideo), zanim uruchomi się potok odpowiedzi. Automatycznie wykrywa dostępność lokalnych narzędzi lub kluczy dostawców i można to wyłączyć albo dostosować. Jeśli rozumienie jest wyłączone, modele nadal otrzymują oryginalne pliki/adresy URL jak zwykle.

Zachowanie multimediów specyficzne dla dostawcy jest rejestrowane przez pluginy dostawców, natomiast rdzeń OpenClaw odpowiada za wspólną konfigurację tools.media, kolejność awaryjnego wyboru oraz integrację z potokiem odpowiedzi.

# Cele

• Opcjonalnie: wstępnie streścić przychodzące multimedia do krótkiego tekstu, aby przyspieszyć routing i poprawić parsowanie poleceń.
• Zachować oryginalne przekazanie multimediów do modelu (zawsze).
• Obsługiwać interfejsy API dostawców i awaryjne CLI.
• Umożliwić wiele modeli z uporządkowanym wyborem awaryjnym (błąd/rozmiar/limit czasu).

# Zachowanie ogólne

Jeśli rozumienie zawiedzie lub jest wyłączone, przepływ odpowiedzi jest kontynuowany z oryginalną treścią + załącznikami.

# Przegląd konfiguracji

tools.media obsługuje wspólne modele oraz nadpisania dla poszczególnych możliwości:

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

# Wpisy modeli

Każdy wpis models[] może być typu dostawca albo 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"],
}

# Wartości domyślne i limity

Zalecane wartości domyślne:

• maxChars: 500 dla obrazu/wideo (krótko, przyjaźnie dla poleceń)
• maxChars: nieustawione dla audio (pełna transkrypcja, chyba że ustawisz limit)
• maxBytes:
  • obraz: 10MB
  • audio: 20MB
  • wideo: 50MB

# Automatyczne wykrywanie rozumienia multimediów (domyślne)

Jeśli tools.media.<capability>.enabled nie jest ustawione na false i nie skonfigurowano modeli, OpenClaw wykrywa automatycznie w tej kolejności i zatrzymuje się na pierwszej działającej opcji:

Aby wyłączyć automatyczne wykrywanie, ustaw:

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

# Obsługa środowiska proxy (modele dostawców)

Gdy włączone jest rozumienie multimediów audio i wideo oparte na dostawcach, OpenClaw honoruje standardowe zmienne środowiskowe wychodzącego proxy dla wywołań HTTP dostawców:

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

Jeśli nie ustawiono zmiennych środowiskowych proxy, rozumienie multimediów używa bezpośredniego wyjścia. Jeśli wartość proxy jest niepoprawnie sformatowana, OpenClaw zapisuje ostrzeżenie w logu i wraca do bezpośredniego pobierania.

# Możliwości (opcjonalne)

Jeśli ustawisz capabilities, wpis działa tylko dla tych typów multimediów. Dla list wspólnych OpenClaw może wywnioskować wartości domyślne:

• openai, anthropic, minimax: obraz
• minimax-portal: obraz
• moonshot: obraz + wideo
• openrouter: obraz
• google (Gemini API): obraz + audio + wideo
• qwen: obraz + wideo
• mistral: audio
• zai: obraz
• groq: audio
• xai: audio
• deepgram: audio
• Dowolny katalog models.providers.<id>.models[] z modelem obsługującym obraz: obraz

Dla wpisów CLI ustaw capabilities jawnie, aby uniknąć zaskakujących dopasowań. Jeśli pominiesz capabilities, wpis kwalifikuje się dla listy, w której się znajduje.

# Macierz obsługi dostawców (integracje OpenClaw)

# Wskazówki dotyczące wyboru modelu

• Preferuj najmocniejszy dostępny model najnowszej generacji dla każdej możliwości multimediów, gdy ważna jest jakość i bezpieczeństwo.
• Dla agentów z włączonymi narzędziami, które obsługują niezaufane dane wejściowe, unikaj starszych/słabszych modeli multimedialnych.
• Zachowaj co najmniej jeden model awaryjny dla każdej możliwości, aby zapewnić dostępność (model jakościowy + szybszy/tańszy model).
• Awaryjne CLI (whisper-cli, whisper, gemini) są przydatne, gdy interfejsy API dostawców są niedostępne.
• Uwaga dotycząca parakeet-mlx: przy --output-dir OpenClaw odczytuje <output-dir>/<media-basename>.txt, gdy format wyjściowy to txt (lub nie został określony); formaty inne niż txt wracają do stdout.

# Polityka załączników

attachments dla każdej możliwości kontroluje, które załączniki są przetwarzane:

Gdy mode: "all", wyniki są oznaczane jako [Image 1/2], [Audio 2/2] itd.

# Przykłady konfiguracji

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

# Dane wyjściowe statusu

Gdy działa rozumienie mediów, /status zawiera krótki wiersz podsumowania:

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

Pokazuje to wyniki dla poszczególnych możliwości oraz wybranego dostawcę/model, gdy ma to zastosowanie.

# Uwagi

• Rozumienie działa na zasadzie best-effort. Błędy nie blokują odpowiedzi.
• Załączniki nadal są przekazywane do modeli nawet wtedy, gdy rozumienie jest wyłączone.
• Użyj scope, aby ograniczyć miejsca, w których działa rozumienie (np. tylko DM).

# Powiązane

• Konfiguracja
• Obsługa obrazów i mediów