Comprensione dei contenuti multimediali

OpenClaw può riassumere i contenuti multimediali 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 multimediale 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 della pipeline di risposta.

Obiettivi

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

Comportamento ad alto livello

Se la comprensione non riesce o è disabilitata, il flusso di risposta continua con il corpo originale + allegati.

Panoramica della configurazione

tools.media supporta modelli condivisi più override per capacità:

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

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 tu non imposti un limite)
• maxBytes:
  • immagine: 10MB
  • audio: 20MB
  • video: 50MB

Rilevamento automatico della comprensione multimediale (predefinito)

Se tools.media.<capability>.enabled non è impostato su false e non hai configurato modelli, OpenClaw rileva automaticamente in questo 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 multimediale audio e video basata su provider è abilitata, OpenClaw rispetta le variabili d'ambiente proxy in uscita 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 multimediale usa l'uscita diretta. Se il valore del proxy è malformato, OpenClaw registra un avviso e torna al recupero diretto.

Capacità (facoltativo)

Se imposti capabilities, la voce viene eseguita solo per quei tipi di contenuto multimediale. 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)

Guida alla selezione dei modelli

• Preferisci il modello più potente di ultima generazione disponibile per ogni capacità multimediale quando qualità e sicurezza sono importanti.
• Per agenti con strumenti abilitati che gestiscono input non attendibili, evita modelli multimediali più vecchi/deboli.
• Mantieni almeno un fallback per capacità per garantire disponibilità (modello di qualità + modello più rapido/economico).
• I fallback CLI (whisper-cli, whisper, gemini) sono utili quando le API dei provider non sono disponibili.
• Nota 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 ripiegano su stdout.

Policy degli allegati

attachments per capacità 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 viene eseguita la comprensione dei media, /status include una breve riga di riepilogo:

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

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