Rozumienie multimediów

OpenClaw może podsumowywać przychodzące multimedia (obrazy/dźwięk/wideo) przed uruchomieniem potoku odpowiedzi, dzięki czemu analizowanie poleceń i trasowanie działają na krótkim tekście zamiast na nieprzetworzonych bajtach. Mechanizm rozumienia automatycznie wykrywa lokalne narzędzia lub klucze dostawców; można też skonfigurować konkretne modele. Oryginalne multimedia są zawsze jak zwykle przekazywane do modelu; gdy mechanizm rozumienia zawiedzie lub jest wyłączony, przepływ odpowiedzi jest kontynuowany bez zmian.

Pluginy dostawców rejestrują metadane możliwości (który dostawca obsługuje dany typ multimediów, model domyślny i priorytet). Rdzeń OpenClaw odpowiada za współdzieloną konfigurację tools.media, kolejność mechanizmów rezerwowych oraz integrację z potokiem odpowiedzi.

Jak to działa

Konfiguracja

tools.media zawiera współdzieloną listę modeli oraz ustawienia zastępujące dla poszczególnych możliwości:

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

Klucze poszczególnych możliwości (image/audio/video):

Opcje specyficzne dla Deepgram należy umieszczać w providerOptions.deepgram (pole najwyższego poziomu deepgram: { detectLanguage, punctuate, smartFormat } jest przestarzałe, ale nadal odczytywane).

Wpisy modeli

Każdy wpis models[] jest wpisem dostawcy (domyślnie) albo wpisem CLI:

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared 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"],}

Dane uwierzytelniające dostawcy

Mechanizm rozumienia multimediów dostawcy korzysta z tego samego sposobu ustalania uwierzytelniania co zwykłe wywołania modeli: profile uwierzytelniania, zmienne środowiskowe, a następnie models.providers.<providerId>.apiKey. Wpisy tools.media.*.models[] nie przyjmują pola apiKey bezpośrednio we wpisie.

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

Informacje o profilach, zmiennych środowiskowych i niestandardowych bazowych adresach URL zawiera sekcja Narzędzia i niestandardowi dostawcy.

Reguły i zachowanie

• Multimedia przekraczające maxBytes powodują pominięcie danego modelu i wypróbowanie następnego.
• Pliki dźwiękowe mniejsze niż 1024 bajty są uznawane za puste lub uszkodzone i pomijane przed transkrypcją; agent otrzymuje zamiast tego deterministyczny tekst zastępczy transkrypcji.
• Jeśli aktywny podstawowy model obrazu już natywnie obsługuje widzenie, OpenClaw pomija blok podsumowania [Image] i przekazuje oryginalny obraz bezpośrednio do modelu. MiniMax stanowi wyjątek: minimax, minimax-cn, minimax-portal i minimax-portal-cn zawsze kierują rozumienie obrazu przez należącego do Pluginu dostawcę multimediów MiniMax-VL-01, nawet jeśli starsze metadane czatu MiniMax M2.x deklarują obsługę obrazów wejściowych (za natywnie obsługujące widzenie uznawane są tylko MiniMax-M3 i nowsze).
• Jeśli podstawowy model Gateway/WebChat obsługuje tylko tekst, załączniki graficzne są zachowywane jako przeniesione odwołania media://inbound/*, aby narzędzia obrazów/PDF lub skonfigurowany model obrazu nadal mogły je sprawdzić, zamiast utracić załącznik.
• Jawne polecenie openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) uruchamia bezpośrednio dostawcę/model obsługujący obrazy, w tym odwołania Ollama, takie jak ollama/qwen2.5vl:7b, gdy odpowiedni model obsługujący obrazy jest skonfigurowany w models.providers.ollama.models[].
• Jeśli <capability>.enabled nie ma wartości false, ale nie skonfigurowano żadnych modeli, OpenClaw próbuje użyć aktywnego modelu odpowiedzi, jeśli jego dostawca obsługuje daną możliwość.

Automatyczne wykrywanie (domyślne)

Gdy tools.media.<capability>.enabled nie ma wartości false i nie skonfigurowano żadnych modeli, OpenClaw wypróbowuje kolejno poniższe opcje i zatrzymuje się na pierwszej działającej:

Aby wyłączyć automatyczne wykrywanie dla danej możliwości:

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

Obsługa serwera proxy (wywołania dostawcy dla dźwięku/wideo)

Oparte na dostawcy rozumienie dźwięku i wideo respektuje standardowe zmienne środowiskowe wychodzącego serwera proxy, w tym reguły pomijania NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Zmienne pisane małymi literami mają pierwszeństwo przed zmiennymi pisanymi wielkimi literami. Jeśli żadna nie jest ustawiona, mechanizm rozumienia multimediów korzysta z bezpośredniego połączenia wychodzącego; jeśli wartość serwera proxy jest nieprawidłowa, OpenClaw rejestruje ostrzeżenie i przechodzi na pobieranie bezpośrednie. Rozumienie obrazu nie korzysta z tej ścieżki serwera proxy.

Możliwości

Ustaw capabilities we wpisie models[], aby ograniczyć go do określonych typów multimediów. W przypadku list współdzielonych OpenClaw ustala wartości domyślne dla poszczególnych dostawców w pakiecie:

W przypadku wpisów CLI ustaw capabilities jawnie, aby uniknąć nieoczekiwanych dopasowań; jeśli to pole zostanie pominięte, wpis kwalifikuje się do każdej listy możliwości, na której występuje.

Macierz obsługi dostawców

Wskazówki dotyczące wyboru modelu

• Gdy jakość i bezpieczeństwo mają znaczenie, dla każdej możliwości multimedialnej wybieraj najsilniejszy model bieżącej generacji.
• W przypadku agentów z dostępem do narzędzi, które przetwarzają niezaufane dane wejściowe, unikaj starszych lub słabszych modeli multimedialnych.
• Zachowaj co najmniej jeden model rezerwowy dla każdej możliwości, aby zapewnić dostępność (model wysokiej jakości + szybszy/tańszy model).
• Rezerwowe narzędzia CLI (whisper-cli, whisper, gemini) pomagają, gdy API dostawców są niedostępne.
• Znane tryby zapisu do pliku są rozstrzygające: pusty lub brakujący wywnioskowany plik transkrypcji oznacza brak transkrypcji zamiast użycia wyjścia postępu CLI jako rozwiązania rezerwowego.
• parakeet-mlx: użyj --output-format txt (lub all) wraz z --output-dir oraz domyślnym szablonem wyjściowym {filename}. Obsługiwane są również zmienne środowiskowe projektu nadrzędnego PARAKEET_OUTPUT_FORMAT i PARAKEET_OUTPUT_TEMPLATE. OpenClaw odczytuje <output-dir>/<media-basename>.txt; domyślny format srt, inne formaty oraz niestandardowe szablony wyjściowe nadal korzystają ze standardowego wyjścia.

Zasady dotyczące załączników

Pole attachments dla poszczególnych możliwości określa, które załączniki są przetwarzane:

Gdy ustawiono mode: "all", wyniki są oznaczane jako [Obraz 1/2], [Dźwięk 2/2] itd.

Wyodrębnianie zawartości załączonych plików

• Tekst wyodrębniony z pliku jest opakowywany jako niezaufana zawartość zewnętrzna przed dołączeniem do promptu multimedialnego. Stosowane są znaczniki graniczne, takie jak <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>, oraz wiersz metadanych Source: External.
• Ta ścieżka celowo pomija długi baner SECURITY NOTICE:, aby prompt multimedialny pozostał krótki; znaczniki graniczne i metadane nadal mają zastosowanie.
• Plik bez tekstu możliwego do wyodrębnienia otrzymuje oznaczenie [Brak tekstu możliwego do wyodrębnienia].
• Jeśli dla pliku PDF zostanie użyte rezerwowe renderowanie stron jako obrazów, OpenClaw przekazuje te obrazy modelom odpowiedzi obsługującym analizę obrazu i zachowuje symbol zastępczy [Zawartość PDF wyrenderowana jako obrazy] w bloku pliku.

Przykłady konfiguracji

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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 stanu

Gdy działa rozumienie multimediów, /status zawiera wiersz podsumowania dla każdej możliwości:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Aby wstępnie sprawdzić dostępne zasoby, uruchom openclaw capability audio providers. Wiersze lokalne pokazują zwycięskie lokalne rozwiązanie rezerwowe oddzielnie od globalnego wyboru dostawcy, gotowości oraz osobnych pól obsługiwanego, żądanego i zaobserwowanego zaplecza. Ten sam wybór lokalny jest dostępny jako informacyjny wynik diagnostyczny:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Uwagi

• Rozumienie działa na zasadzie dołożenia wszelkich starań. Błędy nie blokują odpowiedzi.
• Załączniki są nadal przekazywane modelom, nawet gdy rozumienie jest wyłączone.
• Użyj scope, aby ograniczyć miejsca, w których działa rozumienie (na przykład tylko do wiadomości prywatnych).

Powiązane

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