Rozumienie multimediów

OpenClaw może streszczać przychodzące multimedia (obraz/audio/wideo), zanim uruchomi się potok odpowiedzi. Automatycznie wykrywa, kiedy dostępne są lokalne narzędzia lub klucze 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 dostawców jest rejestrowane przez pluginy dostawców, natomiast rdzeń OpenClaw odpowiada za wspólną konfigurację tools.media, kolejność zapasową i integrację z potokiem odpowiedzi.

Cele

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

Ogólne zachowanie

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ślnie)

Jeśli tools.media.<capability>.enabled nie jest ustawione na false i nie skonfigurowano modeli, OpenClaw automatycznie wykrywa 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 respektuje standardowe zmienne środowiskowe wychodzącego proxy dla wywołań HTTP do dostawców:

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

Jeśli nie ustawiono żadnych zmiennych środowiskowych proxy, rozumienie multimediów używa bezpośredniego wyjścia sieciowego. Jeśli wartość proxy jest nieprawidłowa, OpenClaw loguje ostrzeżenie i wraca do bezpośredniego pobierania.

Możliwości (opcjonalne)

Jeśli ustawisz capabilities, wpis uruchamia się tylko dla tych typów multimediów. Dla wspólnych list 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 obrazy: obraz

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

Macierz obsługi dostawców (integracje OpenClaw)

Wskazówki dotyczące wyboru modelu

• Preferuj najsilniejszy dostępny model najnowszej generacji dla każdej możliwości multimediów, gdy jakość i bezpieczeństwo mają znaczenie.
• Dla agentów z włączonymi narzędziami, którzy obsługują niezaufane dane wejściowe, unikaj starszych/słabszych modeli multimedialnych.
• Zachowaj co najmniej jeden model zapasowy dla każdej możliwości, aby zapewnić dostępność (model o wyższej jakości + szybszy/tańszy model).
• Zapasowe opcje CLI (whisper-cli, whisper, gemini) są przydatne, gdy API dostawców są niedostępne.
• Uwaga 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 używają zapasowo stdout.

Polityka załączników

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

Gdy mode: "all", dane wyjściowe 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 multimediów, /status zawiera krótki wiersz podsumowania:

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

Pokazuje to wyniki dla każdej 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 gdy rozumienie jest wyłączone.
• Użyj scope, aby ograniczyć miejsca, w których działa rozumienie (np. tylko wiadomości prywatne).

Powiązane

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