​

Rozumienie mediów - przychodzące (2026-01-17)

​

Cele

• Opcjonalnie: wstępnie przetwarzać przychodzące media do krótkiego tekstu dla szybszego routingu i lepszego parsowania poleceń.
• Zawsze zachowywać dostarczanie oryginalnych mediów do modelu.
• Obsługiwać API providerów i fallbacki CLI.
• Umożliwiać wiele modeli z uporządkowanym fallbackiem (błąd/rozmiar/timeout).

​

Zachowanie na wysokim poziomie

1. Zbierz przychodzące załączniki (MediaPaths, MediaUrls, MediaTypes).
2. Dla każdej włączonej możliwości (obraz/audio/wideo) wybierz załączniki zgodnie z polityką (domyślnie: pierwszy).
3. Wybierz pierwszy kwalifikujący się wpis modelu (rozmiar + możliwość + auth).
4. Jeśli model zawiedzie lub medium jest zbyt duże, przejdź do następnego wpisu.
5. Po sukcesie:
   • Body staje się blokiem [Image], [Audio] lub [Video].
   • Audio ustawia {{Transcript}}; parsowanie poleceń używa tekstu podpisu, jeśli istnieje, w przeciwnym razie transkryptu.
   • Podpisy są zachowywane jako User text: wewnątrz bloku.

​

Przegląd konfiguracji

• tools.media.models: współdzielona lista modeli (użyj capabilities do ograniczania).
• tools.media.image / tools.media.audio / tools.media.video:
  • ustawienia domyślne (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • nadpisania providerów (baseUrl, headers, providerOptions)
  • opcje audio Deepgram przez tools.media.audio.providerOptions.deepgram
  • ustawienia echo transkryptu audio (echoTranscript, domyślnie false; echoFormat)
  • opcjonalna lista models per możliwość (preferowana przed współdzielonymi modelami)
  • polityka attachments (mode, maxAttachments, prefer)
  • scope (opcjonalne ograniczanie według kanału/chatType/klucza sesji)
• tools.media.concurrency: maksymalna liczba równoległych przebiegów dla możliwości (domyślnie 2).

{
  tools: {
    media: {
      models: [
        /* współdzielona lista */
      ],
      image: {
        /* opcjonalne nadpisania */
      },
      audio: {
        /* opcjonalne nadpisania */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* opcjonalne nadpisania */
      },
    },
  },
}

​

Wpisy modeli

{
  type: "provider", // domyślnie, jeśli pominięto
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // opcjonalne, używane dla wpisów multi-modal
  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"],
}

• {{MediaDir}} (katalog zawierający plik mediów)
• {{OutputDir}} (katalog roboczy utworzony dla tego przebiegu)
• {{OutputBase}} (bazowa ścieżka pliku roboczego, bez rozszerzenia)

​

Wartości domyślne i limity

• maxChars: 500 dla obrazów/wideo (krótkie, przyjazne dla poleceń)
• maxChars: nieustawione dla audio (pełny transkrypt, chyba że ustawisz limit)
• maxBytes:
  • obraz: 10MB
  • audio: 20MB
  • wideo: 50MB

• Jeśli medium przekracza maxBytes, ten model jest pomijany i próbowany jest następny model.
• Pliki audio mniejsze niż 1024 bajty są traktowane jako puste/uszkodzone i pomijane przed transkrypcją provider/CLI.
• Jeśli model zwróci więcej niż maxChars, wynik jest przycinany.
• prompt domyślnie ma prostą postać „Describe the .” plus wskazówkę maxChars (tylko dla obrazów/wideo).
• Jeśli aktywny główny model obrazu już natywnie obsługuje vision, OpenClaw pomija blok podsumowania [Image] i zamiast tego przekazuje do modelu oryginalny obraz.
• Jeśli ustawiono <capability>.enabled: true, ale nie skonfigurowano modeli, OpenClaw próbuje użyć aktywnego modelu odpowiedzi, jeśli jego provider obsługuje tę możliwość.

​

Automatyczne wykrywanie rozumienia mediów (domyślne)

1. Aktywny model odpowiedzi, jeśli jego provider obsługuje tę możliwość.
2. agents.defaults.imageModel primary/fallback refs (tylko obraz).
3. Lokalne CLI (tylko audio; jeśli zainstalowane)
   • sherpa-onnx-offline (wymaga SHERPA_ONNX_MODEL_DIR z encoder/decoder/joiner/tokens)
   • whisper-cli (whisper-cpp; używa WHISPER_CPP_MODEL lub bundlowanego modelu tiny)
   • whisper (Python CLI; pobiera modele automatycznie)
4. Gemini CLI (gemini) używające read_many_files
5. Auth providera
   • Skonfigurowane wpisy models.providers.*, które obsługują daną możliwość, są próbowane przed bundlowaną kolejnością fallbacków.
   • Providery skonfigurowane tylko dla obrazów z modelem obsługującym obraz rejestrują się automatycznie dla rozumienia mediów nawet wtedy, gdy nie są bundlowanym pluginem dostawcy.
   • Bundlowana kolejność fallbacków:
     • Audio: OpenAI → Groq → Deepgram → Google → Mistral
     • Obraz: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • Wideo: Google → Qwen → Moonshot

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

​

Obsługa środowiska proxy (modele providerów)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Możliwości (opcjonalne)

• 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
• deepgram: audio
• Dowolny katalog models.providers.<id>.models[] z modelem obsługującym obraz: obraz

​

Macierz obsługi providerów (integracje OpenClaw)

• Rozumienie obrazów minimax i minimax-portal pochodzi z należącego do pluginu providera mediów MiniMax-VL-01.
• Bundlowany katalog tekstowy MiniMax nadal zaczyna się jako wyłącznie tekstowy; jawne wpisy models.providers.minimax materializują referencje czatu M2.7 obsługujące obrazy.

​

Wskazówki dotyczące wyboru modeli

• Preferuj najmocniejszy model najnowszej generacji dostępny dla każdej możliwości mediów, gdy liczy się jakość i bezpieczeństwo.
• Dla agentów z włączonymi narzędziami obsługujących niezaufane dane wejściowe unikaj starszych/słabszych modeli mediów.
• Zachowaj przynajmniej jeden fallback na możliwość dla dostępności (model jakościowy + model szybszy/tańszy).
• Fallbacki CLI (whisper-cli, whisper, gemini) są przydatne, gdy API providerów są niedostępne.
• Uwaga dotycząca parakeet-mlx: z --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

• mode: first (domyślnie) lub all
• maxAttachments: limit liczby przetwarzanych elementów (domyślnie 1)
• prefer: first, last, path, url

• Wyekstrahowany tekst pliku jest opakowywany jako niezaufana treść zewnętrzna, zanim zostanie dołączony do promptu mediów.
• Wstrzykiwany blok używa jawnych znaczników granicznych, takich jak <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>, i zawiera linię metadanych Source: External.
• Ta ścieżka ekstrakcji załączników celowo pomija długi baner SECURITY NOTICE:, aby nie rozdymac promptu mediów; znaczniki graniczne i metadane nadal pozostają.
• Jeśli plik nie ma tekstu możliwego do wyekstrahowania, OpenClaw wstrzykuje [No extractable text].
• Jeśli PDF na tej ścieżce wraca do renderowanych obrazów stron, prompt mediów zachowuje placeholder [PDF content rendered to images; images not forwarded to model], ponieważ ten krok ekstrakcji załączników przekazuje bloki tekstu, a nie renderowane obrazy PDF.

​

Przykłady konfiguracji

​

1) Współdzielona lista modeli + nadpisania

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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) Tylko audio + wideo (obraz wyłączony)

{
  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) Opcjonalne rozumienie obrazów

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { 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.",
            ],
          },
        ],
      },
    },
  },
}

​

4) Pojedynczy wpis multi-modal (jawne capabilities)

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

​

Wynik statusu

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

​

Uwagi

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

​

Powiązana dokumentacja

• Configuration
• Image & Media Support