Comprensione dei media

OpenClaw può riassumere i media in ingresso (immagini/audio/video) prima dell'esecuzione della pipeline di risposta. Rileva automaticamente quando sono disponibili strumenti locali o chiavi dei provider e può essere disabilitato o personalizzato. Se la comprensione è disattivata, i modelli ricevono comunque i file/URL originali come di consueto.

Il comportamento dei media specifico del fornitore viene registrato dai Plugin del fornitore, mentre il core di OpenClaw gestisce la configurazione condivisa tools.media, l'ordine di fallback e l'integrazione con la pipeline di risposta.

Obiettivi

• Opzionale: pre-elaborare i media in ingresso in testo breve per un instradamento più rapido e una migliore analisi dei comandi.
• Conservare sempre la consegna dei media originali al modello.
• Supportare API dei provider e fallback CLI.
• Consentire più modelli con fallback ordinato (errore/dimensione/timeout).

Comportamento generale

Se la comprensione non riesce o è disabilitata, il flusso di risposta continua con il corpo e gli allegati originali.

Panoramica della configurazione

tools.media supporta modelli condivisi più override per capability:

{  tools: {    media: {      models: [        /* shared list */      ],      image: {        /* optional overrides */      },      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {        /* optional overrides */      },    },  },}

Voci modello

Ogni voce models[] può essere provider o 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"],}

Credenziali del provider (apiKey)

La comprensione dei media tramite provider usa la stessa risoluzione dell'autenticazione del provider delle normali chiamate al modello: profili di autenticazione, variabili d'ambiente, poi models.providers.<providerId>.apiKey.

Le voci tools.media.*.models[] non accettano un campo apiKey inline. Il valore provider in una voce di modello media, come openai o moonshot, deve avere credenziali disponibili tramite una delle sorgenti standard di autenticazione del provider.

Esempio minimo:

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

Per il riferimento completo sull'autenticazione dei provider, inclusi profili, variabili d'ambiente e URL base personalizzati, consulta Strumenti e provider personalizzati.

Valori predefiniti e limiti

Valori predefiniti consigliati:

• maxChars: 500 per immagine/video (breve, adatto ai comandi)
• maxChars: non impostato per audio (trascrizione completa a meno che non imposti un limite)
• maxBytes:
  • immagine: 10 MB
  • audio: 20 MB
  • video: 50 MB

Rilevamento automatico della comprensione dei media (predefinito)

Se tools.media.<capability>.enabled non è impostato su false e non hai configurato modelli, OpenClaw rileva automaticamente in quest'ordine e si ferma alla prima opzione funzionante:

Per disabilitare il rilevamento automatico, imposta:

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

Supporto dell'ambiente proxy (modelli provider)

Quando la comprensione dei media audio e video basata su provider è abilitata, OpenClaw rispetta le variabili d'ambiente proxy outbound standard per le chiamate HTTP ai provider:

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

Se non sono impostate variabili d'ambiente proxy, la comprensione dei media usa egress diretto. Se il valore del proxy non è valido, OpenClaw registra un avviso e torna al recupero diretto.

Capability (opzionale)

Se imposti capabilities, la voce viene eseguita solo per quei tipi di media. Per gli elenchi condivisi, OpenClaw può inferire i valori predefiniti:

• openai, anthropic, minimax: immagine
• minimax-portal: immagine
• moonshot: immagine + video
• openrouter: immagine + audio
• google (API Gemini): immagine + audio + video
• qwen: immagine + video
• mistral: audio
• zai: immagine
• groq: audio
• xai: audio
• deepgram: audio
• Qualsiasi catalogo models.providers.<id>.models[] con un modello con capacità immagine: immagine

Per le voci CLI, imposta capabilities esplicitamente per evitare corrispondenze inattese. Se ometti capabilities, la voce è idonea per l'elenco in cui compare.

Matrice di supporto dei provider (integrazioni OpenClaw)

Indicazioni per la selezione dei modelli

• Preferisci il modello di ultima generazione più potente disponibile per ogni capacità multimediale quando qualità e sicurezza sono importanti.
• Per agenti abilitati agli strumenti che gestiscono input non attendibili, evita modelli multimediali più vecchi o più deboli.
• Mantieni almeno un fallback per capacità per la disponibilità (modello di qualità + modello più veloce/economico).
• I fallback CLI (whisper-cli, whisper, gemini) sono utili quando le API dei provider non sono disponibili.
• Nota su parakeet-mlx: con --output-dir, OpenClaw legge <output-dir>/<media-basename>.txt quando il formato di output è txt (o non specificato); i formati non txt ricadono su stdout.

Criteri per gli allegati

Per ogni capacità, attachments controlla quali allegati vengono elaborati:

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

Esempi di configurazione

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

Output di stato

Quando la comprensione multimediale viene eseguita, /status include una breve riga di riepilogo:

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

Questo mostra gli esiti per capacità e il provider/modello scelto quando applicabile.

Note

• La comprensione è best-effort. Gli errori non bloccano le risposte.
• Gli allegati vengono comunque passati ai modelli anche quando la comprensione è disabilitata.
• Usa scope per limitare dove viene eseguita la comprensione (ad esempio solo nei DM).

Correlati

• Configurazione
• Supporto per immagini e media