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 del 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 vendor è registrato dai plugin dei vendor, 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 routing più rapido e una migliore analisi dei comandi.
• Preservare la consegna dei media originali al modello (sempre).
• Supportare API dei provider e fallback CLI.
• Consentire più modelli con fallback ordinato (errore/dimensione/timeout).

# Comportamento generale

Se la comprensione fallisce o è disabilitata, il flusso di risposta continua con il corpo originale + gli 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 dei modelli

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 l'audio (trascrizione completa, a meno che tu 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 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 dei media basata su provider per audio e video è 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 dei media usa l'egress diretto. Se il valore del proxy è malformato, OpenClaw registra un avviso e ripiega sul recupero diretto.

# Capacità (opzionale)

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

• openai, anthropic, minimax: immagine
• minimax-portal: immagine
• moonshot: immagine + video
• openrouter: immagine
• google (Gemini API): 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 supporto immagini: 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à media quando qualità e sicurezza sono importanti.
• Per agenti con strumenti abilitati che gestiscono input non attendibili, evita modelli media più vecchi/deboli.
• Mantieni almeno un fallback per capacità per la 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 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 ripiegano su stdout.

# Policy degli allegati

Per capacità, attachments controlla quali allegati vengono elaborati:

Quando mode: "all", gli output sono etichettati come [Image 1/2], [Audio 2/2], ecc.

# 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 i risultati per ciascuna funzionalità 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 immagini e media