Rozumienie multimediów

OpenClaw może podsumowywać przychodzące media (obrazy/audio/wideo), zanim uruchomi się potok odpowiedzi. Automatycznie wykrywa, kiedy dostępne są narzędzia lokalne lub klucze dostawców, i można tę funkcję wyłączyć albo dostosować. Jeśli rozumienie jest wyłączone, modele nadal otrzymują oryginalne pliki/adresy URL jak zwykle. Zachowanie mediów specyficzne dla dostawcy jest rejestrowane przez Pluginy dostawców, natomiast rdzeń OpenClaw odpowiada za współdzieloną konfigurację tools.media, kolejność fallbacków oraz integrację z potokiem odpowiedzi.

Cele

Opcjonalnie: wstępnie przetwarzaj przychodzące media na krótki tekst, aby przyspieszyć routing i poprawić parsowanie poleceń.
Zawsze zachowuj dostarczenie oryginalnych mediów do modelu.
Obsługuj API dostawców i fallbacki CLI.
Pozwalaj na wiele modeli z uporządkowanym fallbackiem (błąd/rozmiar/timeout).

Zachowanie wysokiego poziomu

Zbierz załączniki

Zbierz przychodzące załączniki (MediaPaths, MediaUrls, MediaTypes).

Wybierz według możliwości

Dla każdej włączonej możliwości (obraz/audio/wideo) wybierz załączniki zgodnie z polityką (domyślnie: pierwszy).

Wybierz model

Wybierz pierwszy kwalifikujący się wpis modelu (rozmiar + możliwość + uwierzytelnianie).

Fallback przy niepowodzeniu

Jeśli model zawiedzie lub media są zbyt duże, przejdź awaryjnie do następnego wpisu.

Zastosuj blok sukcesu

Po powodzeniu:

Body staje się blokiem [Image], [Audio] lub [Video].
Audio ustawia {{Transcript}}; parsowanie poleceń używa tekstu podpisu, gdy jest obecny, w przeciwnym razie transkrypcji.
Podpisy są zachowywane jako User text: wewnątrz bloku.

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

Przegląd konfiguracji

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

Klucze najwyższego poziomu

tools.media.models: lista modeli współdzielonych (użyj capabilities do bramkowania).
tools.media.image / tools.media.audio / tools.media.video:
- wartości domyślne (prompt, maxChars, maxBytes, timeoutSeconds, language)
- nadpisania dostawcy (baseUrl, headers, providerOptions)
- opcje audio Deepgram przez tools.media.audio.providerOptions.deepgram
- kontrolki echa transkrypcji audio (echoTranscript, domyślnie false; echoFormat)
- opcjonalna lista models dla danej możliwości (preferowana przed modelami współdzielonymi)
- polityka attachments (mode, maxAttachments, prefer)
- scope (opcjonalne bramkowanie według kanału/chatType/klucza sesji)
tools.media.concurrency: maksymalna liczba współbieżnych uruchomień możliwości (domyślnie 2).

{
  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:

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

Szablony CLI mogą również używać:

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

Dane uwierzytelniające dostawcy (`apiKey`)

Rozumienie mediów przez dostawcę używa tego samego rozwiązywania uwierzytelniania dostawcy co zwykłe wywołania modeli: profili uwierzytelniania, zmiennych środowiskowych, a następnie models.providers.<providerId>.apiKey. Wpisy tools.media.*.models[] nie akceptują pola inline apiKey. Wartość provider we wpisie modelu mediów, taka jak openai lub moonshot, musi mieć dane uwierzytelniające dostępne przez jedno ze standardowych źródeł uwierzytelniania dostawcy. Minimalny przykład:

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

Pełne informacje o uwierzytelnianiu dostawców, w tym profile, zmienne środowiskowe i niestandardowe bazowe adresy URL, znajdziesz w Narzędziach i niestandardowych dostawcach.

Wartości domyślne i limity

Zalecane wartości domyślne:

maxChars: 500 dla obrazu/wideo (krótkie, przyjazne poleceniom)
maxChars: nieustawione dla audio (pełna transkrypcja, chyba że ustawisz limit)
maxBytes:
- obraz: 10MB
- audio: 20MB
- wideo: 50MB

Reguły

Jeśli media przekraczają 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ą przez dostawcę/CLI; przychodzący kontekst odpowiedzi otrzymuje deterministyczny zastępczy tekst transkrypcji, aby agent wiedział, że notatka była zbyt mała.
Jeśli model zwróci więcej niż maxChars, wynik zostanie przycięty.
prompt domyślnie to proste „Describe the .” oraz wskazówka maxChars (tylko obraz/wideo).
Jeśli aktywny główny model obrazu już natywnie obsługuje wizję, OpenClaw pomija blok podsumowania [Image] i zamiast tego przekazuje oryginalny obraz do modelu.
Jeśli główny model Gateway/WebChat jest wyłącznie tekstowy, załączniki obrazów są zachowywane jako odciążone odwołania media://inbound/*, aby narzędzia obrazów/PDF lub skonfigurowany model obrazu nadal mogły je zbadać, zamiast utracić załącznik.
Jawne żądania openclaw infer image describe --model <provider/model> są inne: uruchamiają bezpośrednio tego dostawcę/model obsługujący obraz, w tym odwołania Ollama takie jak ollama/qwen2.5vl:7b.
Jeśli <capability>.enabled: true, ale nie skonfigurowano modeli, OpenClaw próbuje użyć aktywnego modelu odpowiedzi, gdy jego dostawca obsługuje daną możliwość.

Automatyczne wykrywanie rozumienia mediów (domyślnie)

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:

Aktywny model odpowiedzi

Aktywny model odpowiedzi, gdy jego dostawca obsługuje daną możliwość.

agents.defaults.imageModel

Główne/fallbackowe odwołania agents.defaults.imageModel (tylko obraz). Preferuj odwołania provider/model. Nagie odwołania są kwalifikowane z wpisów skonfigurowanych modeli dostawców obsługujących obraz tylko wtedy, gdy dopasowanie jest jednoznaczne.

Lokalne CLI (tylko audio)

Lokalne CLI (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 dołączonego modelu tiny)
whisper (Python CLI; pobiera modele automatycznie)

Gemini CLI

gemini używające read_many_files.

Uwierzytelnianie dostawcy

Skonfigurowane wpisy models.providers.*, które obsługują daną możliwość, są próbowane przed dołączoną kolejnością fallbacków.
Dostawcy skonfigurowani tylko dla obrazów z modelem obsługującym obraz automatycznie rejestrują się do rozumienia mediów, nawet gdy nie są dołączonym Pluginem dostawcy.
Rozumienie obrazów Ollama jest dostępne po jawnym wybraniu, na przykład przez agents.defaults.imageModel lub openclaw infer image describe --model ollama/<vision-model>.

Dołączona kolejność fallbacków:

Audio: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
Obraz: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
Wideo: Google → Qwen → Moonshot

Aby wyłączyć automatyczne wykrywanie, ustaw:

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

Wykrywanie binariów działa na zasadzie best-effort w macOS/Linux/Windows; upewnij się, że CLI znajduje się w PATH (rozwijamy ~) albo ustaw jawny model CLI z pełną ścieżką polecenia.

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

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

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

Jeśli nie ustawiono żadnych zmiennych środowiskowych proxy, rozumienie mediów używa bezpośredniego wyjścia. Jeśli wartość proxy jest nieprawidłowo sformułowana, OpenClaw zapisuje ostrzeżenie w logu i wraca do bezpośredniego pobierania.

Możliwości (opcjonalnie)

Jeśli ustawisz capabilities, wpis uruchamia się tylko dla tych typów mediów. Dla list współdzielonych OpenClaw może wywnioskować wartości domyślne:

openai, anthropic, minimax: obraz
minimax-portal: obraz
moonshot: obraz + wideo
openrouter: obraz + audio
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)

Możliwość	Integracja dostawcy	Uwagi
Obraz	OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, dostawcy z konfiguracji	Pluginy dostawców rejestrują obsługę obrazów; `openai/` może używać routingu przez klucz API lub Codex OAuth; `codex/` używa ograniczonego przebiegu Codex app-server; MiniMax i MiniMax OAuth używają `MiniMax-VL-01`; dostawcy z konfiguracji obsługujący obraz rejestrują się automatycznie.
Audio	OpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistral	Transkrypcja dostawcy (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
Wideo	Google, Qwen, Moonshot	Rozumienie wideo przez dostawcę za pośrednictwem Pluginów dostawców; rozumienie wideo Qwen używa punktów końcowych Standard DashScope.

Uwaga MiniMax

Rozumienie obrazów dla minimax, minimax-cn, minimax-portal i minimax-portal-cn pochodzi z należącego do pluginu dostawcy multimediów MiniMax-VL-01.
Automatyczne routowanie obrazów nadal używa MiniMax-VL-01, nawet jeśli starsze metadane czatu MiniMax M2.x deklarują wejście obrazu.

Wskazówki dotyczące wyboru modelu

Preferuj najsilniejszy dostępny model najnowszej generacji dla każdej funkcji multimedialnej, gdy liczą się jakość i bezpieczeństwo.
W przypadku agentów z włączonymi narzędziami, obsługujących niezaufane dane wejściowe, unikaj starszych/słabszych modeli multimedialnych.
Zachowaj co najmniej jeden model zapasowy dla każdej funkcji, aby zapewnić dostępność (model jakościowy + szybszy/tańszy model).
Modele zapasowe CLI (whisper-cli, whisper, gemini) są przydatne, gdy API dostawcó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.

Zasady załączników

attachments dla poszczególnych funkcji kontroluje, które załączniki są przetwarzane:

mode

"first" | "all"

domyślnie:"first"

Czy przetwarzać pierwszy wybrany załącznik, czy wszystkie.

maxAttachments

number

domyślnie:"1"

Ogranicza liczbę przetwarzanych załączników.

prefer

"first" | "last" | "path" | "url"

Preferencja wyboru spośród kandydujących załączników.

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

Zachowanie wyodrębniania załączników plikowych

Wyodrębniony tekst pliku jest opakowywany jako niezaufana treść zewnętrzna, zanim zostanie dołączony do promptu multimedialnego.
Wstrzyknięty blok używa jawnych znaczników granicznych, takich jak <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>, i zawiera wiersz metadanych Source: External.
Ta ścieżka wyodrębniania załączników celowo pomija długi baner SECURITY NOTICE:, aby uniknąć rozrastania promptu multimedialnego; znaczniki graniczne i metadane nadal pozostają.
Jeśli plik nie ma tekstu możliwego do wyodrębnienia, OpenClaw wstrzykuje [No extractable text].
Jeśli PDF wraca do renderowanych obrazów stron w tej ścieżce, OpenClaw przekazuje te obrazy stron do modeli odpowiedzi obsługujących widzenie i zachowuje placeholder [PDF content rendered to images] w bloku pliku.

Przykłady konfiguracji

Modele współdzielone + nadpisania
Tylko audio + wideo
Tylko obraz
Pojedynczy wpis multimodalny

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

Wynik statusu

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

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

Pokazuje to wyniki dla poszczególnych funkcji 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 gdy rozumienie jest wyłączone.
Użyj scope, aby ograniczyć miejsca, w których działa rozumienie (np. tylko DM-y).

​Cele

​Zachowanie wysokiego poziomu

​Przegląd konfiguracji

​Wpisy modeli

​Dane uwierzytelniające dostawcy (apiKey)

​Wartości domyślne i limity

​Automatyczne wykrywanie rozumienia mediów (domyślnie)

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

​Możliwości (opcjonalnie)

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

​Wskazówki dotyczące wyboru modelu

​Zasady załączników

​Przykłady konfiguracji

​Wynik statusu

​Uwagi

​Powiązane

Cele

Zachowanie wysokiego poziomu

Przegląd konfiguracji

Wpisy modeli

Dane uwierzytelniające dostawcy (`apiKey`)

Wartości domyślne i limity

Automatyczne wykrywanie rozumienia mediów (domyślnie)

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

Możliwości (opcjonalnie)

Macierz obsługi dostawców (integracje OpenClaw)

Wskazówki dotyczące wyboru modelu

Zasady załączników

Przykłady konfiguracji

Wynik statusu

Uwagi

Powiązane