Mediabegrip

OpenClaw kan binnenkomende media (afbeelding/audio/video) samenvatten voordat de antwoordpijplijn wordt uitgevoerd, zodat opdrachtinterpretatie en routering met korte tekst werken in plaats van met onbewerkte bytes. Media-interpretatie detecteert automatisch lokale hulpprogramma's of providersleutels, maar u kunt ook expliciete modellen configureren. De oorspronkelijke media worden zoals gebruikelijk altijd aan het model geleverd; wanneer de interpretatie mislukt of is uitgeschakeld, gaat de antwoordstroom ongewijzigd verder.

Leveranciersplugins registreren metagegevens over mogelijkheden (welke provider welk mediatype ondersteunt, standaardmodel, prioriteit). De kern van OpenClaw beheert de gedeelde configuratie tools.media, de terugvalvolgorde en de integratie met de antwoordpijplijn.

Werking

Configuratie

tools.media bevat een gedeelde modellenlijst en overschrijvingen per mogelijkheid:

{  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 */},    },  },}

Sleutels per mogelijkheid (image/audio/video):

Deepgram-specifieke opties staan onder providerOptions.deepgram (het veld deepgram: { detectLanguage, punctuate, smartFormat } op het hoogste niveau is verouderd, maar wordt nog steeds gelezen).

Modelvermeldingen

Elke vermelding in models[] is een providervermelding (standaard) of een CLI-vermelding:

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

Providerreferenties

Media-interpretatie via providers gebruikt dezelfde authenticatieoplossing als normale modelaanroepen: authenticatieprofielen, omgevingsvariabelen en vervolgens models.providers.<providerId>.apiKey. Vermeldingen in tools.media.*.models[] accepteren geen inlineveld apiKey.

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

Zie Hulpprogramma's en aangepaste providers voor profielen, omgevingsvariabelen en aangepaste basis-URL's.

Regels en gedrag

• Media die maxBytes overschrijden, slaan dat model over en proberen het volgende.
• Audiobestanden kleiner dan 1024 bytes worden als leeg/beschadigd beschouwd en vóór transcriptie overgeslagen; de agent ontvangt in plaats daarvan een deterministisch tijdelijk transcript.
• Als het actieve primaire afbeeldingsmodel al systeemeigen beeldherkenning ondersteunt, slaat OpenClaw het samenvattingsblok [Image] over en geeft het de oorspronkelijke afbeelding rechtstreeks aan het model door. MiniMax vormt een uitzondering: minimax, minimax-cn, minimax-portal en minimax-portal-cn routeren afbeeldingsinterpretatie altijd via de door de plugin beheerde mediaprovider MiniMax-VL-01, zelfs als verouderde chatmetagegevens van MiniMax M2.x aangeven dat afbeeldingsinvoer wordt ondersteund (alleen MiniMax-M3 en latere versies worden beschouwd als modellen met systeemeigen beeldherkenning).
• Als een primair Gateway/WebChat-model alleen tekst ondersteunt, blijven afbeeldingsbijlagen behouden als uitbestede verwijzingen media://inbound/*, zodat afbeeldings-/PDF-hulpprogramma's of een geconfigureerd afbeeldingsmodel ze nog steeds kunnen inspecteren in plaats van de bijlage te verliezen.
• Een expliciete aanroep van openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) voert die provider/dat model met afbeeldingsmogelijkheden rechtstreeks uit, inclusief Ollama-verwijzingen zoals ollama/qwen2.5vl:7b wanneer een overeenkomend model met afbeeldingsmogelijkheden is geconfigureerd onder models.providers.ollama.models[].
• Als <capability>.enabled niet false is maar er geen modellen zijn geconfigureerd, probeert OpenClaw het actieve antwoordmodel wanneer de provider daarvan de mogelijkheid ondersteunt.

Automatische detectie (standaard)

Wanneer tools.media.<capability>.enabled niet false is en er geen modellen zijn geconfigureerd, probeert OpenClaw de volgende opties in deze volgorde en stopt het bij de eerste werkende optie:

Automatische detectie voor een mogelijkheid uitschakelen:

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

Proxyondersteuning (provider-aanroepen voor audio/video)

Providergebaseerde interpretatie van audio en video respecteert standaardomgevingsvariabelen voor uitgaande proxy's, inclusief omzeilingsregels van NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Variabelen in kleine letters hebben voorrang op variabelen in hoofdletters. Als er geen zijn ingesteld, gebruikt media-interpretatie rechtstreeks uitgaand verkeer; als de proxywaarde ongeldig is, registreert OpenClaw een waarschuwing en valt het terug op rechtstreeks ophalen. Afbeeldingsinterpretatie maakt geen gebruik van dit proxypad.

Mogelijkheden

Stel capabilities in bij een vermelding in models[] om deze te beperken tot specifieke mediatypen. Voor gedeelde lijsten leidt OpenClaw de standaardwaarden per gebundelde provider af:

Stel voor CLI-vermeldingen capabilities expliciet in om onverwachte overeenkomsten te voorkomen; als dit wordt weggelaten, komt de vermelding in aanmerking voor elke mogelijkhedenlijst waarin deze voorkomt.

Ondersteuningsmatrix voor providers

Richtlijnen voor modelselectie

• Geef voor elke mediamogelijkheid de voorkeur aan het krachtigste model van de huidige generatie wanneer kwaliteit en veiligheid belangrijk zijn.
• Vermijd oudere/zwakkere mediamodellen voor agents met hulpmiddelen die niet-vertrouwde invoer verwerken.
• Houd voor beschikbaarheid ten minste één terugvaloptie per mogelijkheid aan (kwaliteitsmodel + sneller/goedkoper model).
• CLI-terugvalopties (whisper-cli, whisper, gemini) helpen wanneer provider-API's niet beschikbaar zijn.
• Bekende bestandsuitvoermodi zijn leidend: een leeg of ontbrekend afgeleid transcriptiebestand levert geen transcriptie op, in plaats van terug te vallen op de voortgangsuitvoer van de CLI.
• parakeet-mlx: gebruik --output-format txt (of all) met --output-dir en de standaarduitvoersjabloon {filename}. De upstream-omgevingsvariabelen PARAKEET_OUTPUT_FORMAT en PARAKEET_OUTPUT_TEMPLATE worden ook gerespecteerd. OpenClaw leest <output-dir>/<media-basename>.txt; de standaardindeling srt, andere indelingen en aangepaste uitvoersjablonen blijven stdout gebruiken.

Beleid voor bijlagen

attachments per mogelijkheid bepaalt welke bijlagen worden verwerkt:

Wanneer mode: "all" is ingesteld, krijgen uitvoerresultaten labels zoals [Afbeelding 1/2], [Audio 2/2], enzovoort.

Extractie van bestandsbijlagen

• Geëxtraheerde bestandstekst wordt verpakt als niet-vertrouwde externe inhoud voordat deze aan de mediaprompt wordt toegevoegd, met grensmarkeringen zoals <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> plus een metadataregel Source: External.
• Dit pad laat bewust de lange banner SECURITY NOTICE: weg om de mediaprompt kort te houden; de grensmarkeringen en metadata blijven van toepassing.
• Een bestand zonder extraheerbare tekst krijgt [Geen extraheerbare tekst].
• Als een pdf terugvalt op gerenderde pagina-afbeeldingen, stuurt OpenClaw die afbeeldingen door naar antwoordmodellen met beeldondersteuning en blijft de tijdelijke aanduiding [PDF-inhoud gerenderd als afbeeldingen] in het bestandsblok staan.

Configuratievoorbeelden

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

Statusuitvoer

Wanneer mediabegrip wordt uitgevoerd, bevat /status een samenvattingsregel per mogelijkheid:

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

Voer voor een inventarisatie vooraf openclaw capability audio providers uit. Lokale rijen tonen de winnaar van de lokale terugvalopties afzonderlijk van de algemene providerselectie, gereedheid en afzonderlijke velden voor geschikte/aangevraagde/waargenomen backends. Dezelfde lokale selectie is beschikbaar als informatieve doctor-bevinding:

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

Opmerkingen

• Begrip werkt op basis van beste inspanning. Fouten blokkeren antwoorden niet.
• Bijlagen worden nog steeds aan modellen doorgegeven wanneer begrip is uitgeschakeld.
• Gebruik scope om te beperken waar begrip wordt uitgevoerd (bijvoorbeeld alleen in privéberichten).

Gerelateerd

• Configuratie
• Ondersteuning voor afbeeldingen en media