Comprensione dei contenuti multimediali

OpenClaw può riassumere i contenuti multimediali in ingresso (immagini/audio/video) prima dell'esecuzione della pipeline di risposta, in modo che l'analisi dei comandi e l'instradamento operino su testo breve anziché su byte non elaborati. La comprensione rileva automaticamente gli strumenti locali o le chiavi dei fornitori, oppure è possibile configurare modelli espliciti. I contenuti multimediali originali vengono sempre inviati al modello come di consueto; se la comprensione non riesce o è disabilitata, il flusso di risposta prosegue senza modifiche.

I Plugin dei fornitori registrano i metadati delle funzionalità (quale fornitore supporta ciascun tipo di contenuto multimediale, modello predefinito, priorità). Il nucleo di OpenClaw gestisce la configurazione condivisa tools.media, l'ordine dei fallback e l'integrazione con la pipeline di risposta.

Funzionamento

Configurazione

tools.media contiene un elenco condiviso di modelli e sostituzioni specifiche per funzionalità:

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

Chiavi specifiche per funzionalità (image/audio/video):

Le opzioni specifiche di Deepgram vanno inserite in providerOptions.deepgram (il campo di primo livello deepgram: { detectLanguage, punctuate, smartFormat } è deprecato, ma viene ancora letto).

Voci dei modelli

Ogni voce models[] è una voce fornitore (predefinita) o una voce 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"],}

Credenziali del fornitore

La comprensione dei contenuti multimediali tramite fornitore usa la stessa risoluzione dell'autenticazione delle normali chiamate ai modelli: profili di autenticazione, variabili d'ambiente e infine models.providers.<providerId>.apiKey. Le voci tools.media.*.models[] non accettano un campo apiKey incorporato.

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

Vedere Strumenti e fornitori personalizzati per profili, variabili d'ambiente e URL di base personalizzati.

Regole e comportamento

• I contenuti multimediali che superano maxBytes fanno ignorare quel modello e passare al successivo.
• I file audio inferiori a 1024 byte vengono considerati vuoti o danneggiati e ignorati prima della trascrizione; l'agente riceve invece una trascrizione segnaposto deterministica.
• Se il modello principale attivo per le immagini supporta già nativamente la visione, OpenClaw omette il blocco di riepilogo [Image] e passa direttamente al modello l'immagine originale. MiniMax costituisce un'eccezione: minimax, minimax-cn, minimax-portal e minimax-portal-cn instradano sempre la comprensione delle immagini tramite il fornitore multimediale MiniMax-VL-01 gestito dal Plugin, anche se i metadati legacy delle chat MiniMax M2.x dichiarano il supporto per l'input di immagini (solo MiniMax-M3 e versioni successive sono considerate dotate di funzionalità di visione native).
• Se il modello principale di Gateway/WebChat supporta solo il testo, gli allegati immagine vengono conservati come riferimenti esternalizzati media://inbound/*, affinché gli strumenti per immagini/PDF o un modello per immagini configurato possano comunque esaminarli anziché perdere l'allegato.
• Il comando esplicito openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) esegue direttamente il fornitore/modello con supporto per le immagini, inclusi riferimenti Ollama come ollama/qwen2.5vl:7b quando un modello corrispondente con supporto per le immagini è configurato in models.providers.ollama.models[].
• Se <capability>.enabled non è false ma non sono configurati modelli, OpenClaw prova il modello di risposta attivo quando il relativo fornitore supporta la funzionalità.

Rilevamento automatico (impostazione predefinita)

Quando tools.media.<capability>.enabled non è false e non sono configurati modelli, OpenClaw prova le seguenti opzioni nell'ordine indicato e si arresta alla prima funzionante:

Per disabilitare il rilevamento automatico per una funzionalità:

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

Supporto proxy (chiamate dei fornitori per audio/video)

La comprensione di audio e video basata sui fornitori rispetta le variabili d'ambiente proxy standard per le connessioni in uscita, incluse le regole di esclusione NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Le variabili in minuscolo hanno la precedenza su quelle in maiuscolo. Se non ne è impostata alcuna, la comprensione dei contenuti multimediali usa una connessione diretta; se il valore del proxy non è valido, OpenClaw registra un avviso e usa come fallback il recupero diretto. La comprensione delle immagini non utilizza questo percorso proxy.

Funzionalità

Impostare capabilities in una voce models[] per limitarla a tipi specifici di contenuti multimediali. Per gli elenchi condivisi, OpenClaw deduce i valori predefiniti per ciascun fornitore incluso:

Per le voci CLI, imposta esplicitamente capabilities per evitare corrispondenze inattese; se omesso, la voce è idonea per ogni elenco di funzionalità in cui compare.

Matrice di supporto dei provider

Indicazioni per la selezione dei modelli

• Preferisci il modello di generazione corrente più potente per ogni funzionalità multimediale quando qualità e sicurezza sono importanti.
• Per gli agenti abilitati all'uso di strumenti che gestiscono input non attendibili, evita i modelli multimediali più vecchi o meno potenti.
• Mantieni almeno un modello di riserva per ogni funzionalità per garantirne la disponibilità (un modello di qualità + un modello più veloce/economico).
• Le alternative CLI (whisper-cli, whisper, gemini) sono utili quando le API dei provider non sono disponibili.
• Le modalità note di output su file sono autorevoli: un file di trascrizione dedotto vuoto o mancante non produce alcuna trascrizione, anziché ricorrere all'output di avanzamento della CLI.
• parakeet-mlx: usa --output-format txt (o all) con --output-dir e il modello di output predefinito {filename}. Sono supportate anche le variabili d'ambiente upstream PARAKEET_OUTPUT_FORMAT e PARAKEET_OUTPUT_TEMPLATE. OpenClaw legge <output-dir>/<media-basename>.txt; il formato predefinito srt, gli altri formati e i modelli di output personalizzati continuano a usare lo standard output.

Criteri per gli allegati

La proprietà attachments specifica per funzionalità controlla quali allegati vengono elaborati:

Quando mode: "all", gli output sono contrassegnati con [Immagine 1/2], [Audio 2/2] e così via.

Estrazione dagli allegati

• Il testo estratto dai file viene racchiuso come contenuto esterno non attendibile prima di essere aggiunto al prompt multimediale, usando delimitatori come <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> e una riga di metadati Source: External.
• Questo percorso omette intenzionalmente il lungo banner SECURITY NOTICE: per mantenere breve il prompt multimediale; i delimitatori e i metadati vengono comunque applicati.
• Un file privo di testo estraibile riceve [Nessun testo estraibile].
• Se per un PDF si ricorre alle immagini renderizzate delle pagine, OpenClaw inoltra tali immagini ai modelli di risposta dotati di capacità visive e mantiene il segnaposto [Contenuto PDF renderizzato come immagini] nel blocco del file.

Esempi di configurazione

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

Output dello stato

Quando viene eseguita la comprensione dei contenuti multimediali, /status include una riga di riepilogo per ogni funzionalità:

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

Per l'inventario preliminare, esegui openclaw capability audio providers. Le righe locali mostrano il risultato locale di riserva separatamente dalla selezione globale del provider, dallo stato di disponibilità e dai campi distinti relativi ai backend compatibili, richiesti e osservati. La stessa selezione locale è disponibile come segnalazione informativa di doctor:

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

Note

• La comprensione viene eseguita in modalità best effort. Gli errori non bloccano le risposte.
• Gli allegati vengono comunque passati ai modelli anche quando la comprensione è disabilitata.
• Usa scope per limitare i contesti in cui viene eseguita la comprensione (ad esempio, solo nei messaggi diretti).

Contenuti correlati

• Configurazione
• Supporto per immagini e contenuti multimediali