Mediabegrip

OpenClaw kan binnenkomende media (afbeelding/audio/video) samenvatten voordat de antwoordpijplijn wordt uitgevoerd, zodat opdrachtparsing en routering werken met korte tekst in plaats van onbewerkte bytes. Begrip detecteert automatisch lokale tools of providersleutels, of je kunt expliciete modellen configureren. De oorspronkelijke media worden zoals gewoonlijk altijd aan het model geleverd; wanneer begrip mislukt of is uitgeschakeld, gaat de antwoordflow ongewijzigd verder.

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

Hoe het werkt

Configuratie

tools.media bevat één modelleerlijst met mogelijkheidstags en enkele kleine bedieningselementen per mogelijkheid:

{  tools: {    media: {      concurrency: 2, // maximaal aantal gelijktijdige uitvoeringen van mogelijkheden (standaard)      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

Sleutels per mogelijkheid (image/audio/video):

Prompts, limieten, taalhints, aanvraagoverschrijvingen en provideropties kunnen als standaardwaarden voor mogelijkheden worden ingesteld of per afzonderlijke tools.media.models[]-vermelding worden overschreven. Standaardwaarden voor mogelijkheden gelden ook voor automatisch gedetecteerde providers wanneer geen expliciet model is geconfigureerd.

Modelvermeldingen

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

{  type: "provider", // standaard indien weggelaten  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Beschrijf de afbeelding in <= 500 tekens.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"],  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "Lees de media op {{AttachmentPath}} en beschrijf deze in <= {{MaxChars}} tekens.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

Providerreferenties

Mediabegrip door providers gebruikt dezelfde authenticatieoplossing als normale modelaanroepen: authenticatieprofielen, omgevingsvariabelen en vervolgens models.providers.<providerId>.apiKey. tools.media.models[]-vermeldingen accepteren geen inline apiKey-veld.

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

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

Regels en gedrag

• Media die groter zijn dan maxBytes slaan dat model over en proberen het volgende.
• Audiobestanden kleiner dan 1024 bytes worden als leeg/beschadigd behandeld en vóór transcriptie overgeslagen; de agent krijgt in plaats daarvan een deterministisch tijdelijk transcript.
• Als het actieve primaire afbeeldingsmodel standaard al visuele invoer ondersteunt, slaat OpenClaw het [Image]-samenvattingsblok over en geeft het de oorspronkelijke afbeelding rechtstreeks door aan het model. MiniMax is een uitzondering: minimax, minimax-cn, minimax-portal en minimax-portal-cn routeren afbeeldingsbegrip altijd via de door de plugin beheerde MiniMax-VL-01-mediaprovider, zelfs als verouderde MiniMax M2.x-chatmetagegevens beweren afbeeldingsinvoer te ondersteunen (alleen MiniMax-M3 en hoger worden beschouwd als modellen met standaard visuele ondersteuning).
• Als een primair Gateway-/WebChat-model alleen tekst ondersteunt, blijven afbeeldingsbijlagen behouden als uitbestede media://inbound/*-referenties, zodat afbeeldings-/PDF-tools of een geconfigureerd afbeeldingsmodel ze nog steeds kunnen inspecteren in plaats van de bijlage kwijt te raken.
• Expliciete openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) voert die provider/dat model met afbeeldingsondersteuning rechtstreeks uit, inclusief Ollama-referenties zoals ollama/qwen2.5vl:7b wanneer een overeenkomend model met afbeeldingsondersteuning 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 uitschakelen voor een mogelijkheid:

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

Proxyondersteuning (provideroproepen voor audio/video)

Providergebaseerd begrip van audio en video respecteert standaardomgevingsvariabelen voor uitgaande proxy's, waaronder omzeilingsregels voor 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 geen van deze is ingesteld, gebruikt mediabegrip een directe uitgaande verbinding; als de proxywaarde onjuist is, registreert OpenClaw een waarschuwing en valt het terug op rechtstreeks ophalen. Afbeeldingsbegrip loopt niet via dit proxypad.

Mogelijkheden

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

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 of zwakkere mediamodellen voor agents met ingeschakelde tools die niet-vertrouwde invoer verwerken.
• Houd voor beschikbaarheid ten minste één terugvaloptie per mogelijkheid aan (een kwaliteitsmodel en een 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 CLI-voortgangsuitvoer.
• 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", krijgen uitvoerresultaten de labels [Image 1/2], [Audio 2/2], enzovoort.

Extractie van bestandsbijlagen

• Geëxtraheerde bestandstekst wordt als niet-vertrouwde externe inhoud verpakt 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;>> en 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 [No extractable text].
• Als een PDF terugvalt op gerenderde pagina-afbeeldingen, stuurt OpenClaw die afbeeldingen door naar antwoordmodellen met beeldondersteuning en behoudt het de tijdelijke aanduiding [PDF content rendered to images] in het bestandsblok.

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",            "Lees de media op {{AttachmentPath}} en beschrijf deze in <= {{MaxChars}} tekens.",          ],          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", "{{AttachmentPath}}"],          },        ],      },      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",              "Lees de media op {{AttachmentPath}} en beschrijf deze in <= {{MaxChars}} tekens.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-5" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "Lees de media op {{AttachmentPath}} en beschrijf deze in <= {{MaxChars}} tekens.",            ],          },        ],      },    },  },}

{  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: afbeelding geslaagd (openai/gpt-5.6-sol) · audio geslaagd (whisper-cli waargenomen=metal)

Voer voor de preflight-inventarisatie openclaw capability audio providers uit. Lokale rijen tonen de lokale winnaar van de terugvalopties afzonderlijk van de algemene providerselectie, gereedheid en afzonderlijke backendvelden voor geschikt/aangevraagd/waargenomen. Dezelfde lokale selectie is beschikbaar als informatieve doctor-bevinding:

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

Opmerkingen

• Begrip wordt naar beste vermogen uitgevoerd. 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 DM's).

Gerelateerd

• Configuratie
• Ondersteuning voor afbeeldingen en media