Compréhension des médias

OpenClaw peut résumer les médias entrants (image/audio/vidéo) avant l’exécution du pipeline de réponse. Il détecte automatiquement quand des outils locaux ou des clés fournisseur sont disponibles, et peut être désactivé ou personnalisé. Si la compréhension est désactivée, les modèles reçoivent toujours les fichiers/URL d’origine comme d’habitude.

Le comportement des médias propre à chaque fournisseur est enregistré par les plugins fournisseurs, tandis que le cœur d’OpenClaw possède la configuration partagée tools.media, l’ordre de repli et l’intégration au pipeline de réponse.

Objectifs

• Facultatif : prétraiter les médias entrants en court texte pour un routage plus rapide et une meilleure analyse des commandes.
• Préserver la livraison des médias d’origine au modèle (toujours).
• Prendre en charge les API fournisseur et les solutions de repli CLI.
• Autoriser plusieurs modèles avec un repli ordonné (erreur/taille/délai d’expiration).

Comportement général

Si la compréhension échoue ou est désactivée, le flux de réponse continue avec le corps d’origine + les pièces jointes.

Vue d’ensemble de la configuration

tools.media prend en charge des modèles partagés ainsi que des remplacements par capacité :

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

Entrées de modèle

Chaque entrée models[] peut être de type fournisseur ou 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"],}

Identifiants fournisseur (apiKey)

La compréhension des médias par fournisseur utilise la même résolution d’authentification fournisseur que les appels de modèle normaux : profils d’authentification, variables d’environnement, puis models.providers.<providerId>.apiKey.

Les entrées tools.media.*.models[] n’acceptent pas de champ apiKey en ligne. La valeur provider dans une entrée de modèle média, comme openai ou moonshot, doit disposer d’identifiants disponibles via l’une des sources d’authentification fournisseur standard.

Exemple minimal :

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

Pour la référence complète sur l’authentification fournisseur, y compris les profils, les variables d’environnement et les URL de base personnalisées, consultez Outils et fournisseurs personnalisés.

Valeurs par défaut et limites

Valeurs par défaut recommandées :

• maxChars : 500 pour image/vidéo (court, adapté aux commandes)
• maxChars : non défini pour l’audio (transcription complète sauf si vous définissez une limite)
• maxBytes :
  • image : 10 Mo
  • audio : 20 Mo
  • vidéo : 50 Mo

Détection automatique de la compréhension des médias (par défaut)

Si tools.media.<capability>.enabled n’est pas défini sur false et que vous n’avez pas configuré de modèles, OpenClaw effectue une détection automatique dans cet ordre et s’arrête à la première option fonctionnelle :

Pour désactiver la détection automatique, définissez :

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

Prise en charge de l’environnement proxy (modèles fournisseur)

Lorsque la compréhension des médias audio et vidéo basée sur fournisseur est activée, OpenClaw respecte les variables d’environnement de proxy sortant standard pour les appels HTTP fournisseur :

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

Si aucune variable d’environnement de proxy n’est définie, la compréhension des médias utilise une sortie directe. Si la valeur du proxy est mal formée, OpenClaw journalise un avertissement et se replie sur une récupération directe.

Capacités (facultatif)

Si vous définissez capabilities, l’entrée ne s’exécute que pour ces types de médias. Pour les listes partagées, OpenClaw peut inférer les valeurs par défaut :

• openai, anthropic, minimax : image
• minimax-portal : image
• moonshot : image + vidéo
• openrouter : image + audio
• google (API Gemini) : image + audio + vidéo
• qwen : image + vidéo
• mistral : audio
• zai : image
• groq : audio
• xai : audio
• deepgram : audio
• Tout catalogue models.providers.<id>.models[] avec un modèle compatible image : image

Pour les entrées CLI, définissez capabilities explicitement afin d’éviter les correspondances surprenantes. Si vous omettez capabilities, l’entrée est éligible pour la liste dans laquelle elle apparaît.

Matrice de prise en charge des fournisseurs (intégrations OpenClaw)

Conseils de sélection des modèles

• Préférez le modèle de dernière génération le plus puissant disponible pour chaque capacité multimédia lorsque la qualité et la sécurité comptent.
• Pour les agents avec outils traitant des entrées non fiables, évitez les modèles multimédias plus anciens ou plus faibles.
• Conservez au moins une solution de repli par capacité pour la disponibilité (modèle de qualité + modèle plus rapide/moins cher).
• Les solutions de repli CLI (whisper-cli, whisper, gemini) sont utiles lorsque les API des fournisseurs ne sont pas disponibles.
• Remarque sur parakeet-mlx : avec --output-dir, OpenClaw lit <output-dir>/<media-basename>.txt lorsque le format de sortie est txt (ou non spécifié) ; les formats non txt se replient sur stdout.

Politique des pièces jointes

Par capacité, attachments contrôle les pièces jointes traitées :

Lorsque mode: "all", les sorties sont étiquetées [Image 1/2], [Audio 2/2], etc.

Exemples de configuration

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

Sortie d’état

Lorsque la compréhension multimédia s’exécute, /status inclut une courte ligne de résumé :

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

Cela affiche les résultats par capacité et le fournisseur/modèle choisi le cas échéant.

Remarques

• La compréhension est fournie au mieux. Les erreurs ne bloquent pas les réponses.
• Les pièces jointes sont toujours transmises aux modèles, même lorsque la compréhension est désactivée.
• Utilisez scope pour limiter les endroits où la compréhension s’exécute (par exemple uniquement les messages directs).

Liens associés

• Configuration
• Prise en charge des images et médias