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, afin que l’analyse des commandes et le routage s’appuient sur un texte court plutôt que sur des octets bruts. La compréhension détecte automatiquement les outils locaux ou les clés de fournisseur, mais vous pouvez aussi configurer des modèles explicites. Le média d’origine est toujours transmis au modèle comme d’habitude ; si la compréhension échoue ou est désactivée, le flux de réponse se poursuit sans changement.

Les Plugins de fournisseurs enregistrent les métadonnées de capacité (quel fournisseur prend en charge quel type de média, modèle par défaut, priorité). Le cœur d’OpenClaw gère la configuration partagée tools.media, l’ordre de repli et l’intégration au pipeline de réponse.

Fonctionnement

Configuration

tools.media contient une liste de modèles partagée ainsi que des remplacements propres à chaque capacité :

{  tools: {    media: {      concurrency: 2, // nombre maximal d’exécutions simultanées de capacités (par défaut)      models: [/* liste partagée, filtrée selon les capacités */],      image: {/* remplacements facultatifs */},      audio: {        /* remplacements facultatifs */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* remplacements facultatifs */},    },  },}

Clés propres à chaque capacité (image/audio/video) :

Les options propres à Deepgram se placent sous providerOptions.deepgram (le champ de premier niveau deepgram: { detectLanguage, punctuate, smartFormat } est obsolète, mais reste pris en charge en lecture).

Entrées de modèle

Chaque entrée models[] est une entrée de fournisseur (par défaut) ou une entrée de CLI :

{  type: "provider", // valeur par défaut si omis  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Décrivez l’image en 500 caractères maximum.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // facultatif, pour les entrées partagées multimodales  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "Lisez le média à l’emplacement {{MediaPath}} et décrivez-le en {{MaxChars}} caractères maximum.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

Identifiants des fournisseurs

La compréhension des médias par les fournisseurs utilise la même résolution d’authentification que les appels de modèle ordinaires : profils d’authentification, variables d’environnement, puis models.providers.<providerId>.apiKey. Les entrées tools.media.*.models[] n’acceptent pas de champ apiKey intégré.

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

Consultez Outils et fournisseurs personnalisés pour les profils, les variables d’environnement et les URL de base personnalisées.

Règles et comportement

• Un média dépassant maxBytes est ignoré pour ce modèle, puis le modèle suivant est essayé.
• Les fichiers audio de moins de 1 024 octets sont considérés comme vides ou corrompus et ignorés avant la transcription ; l’agent reçoit à la place une transcription substitutive déterministe.
• Si le modèle d’image principal actif prend déjà en charge la vision nativement, OpenClaw omet le bloc récapitulatif [Image] et transmet directement l’image d’origine au modèle. MiniMax constitue une exception : minimax, minimax-cn, minimax-portal et minimax-portal-cn acheminent toujours la compréhension des images via le fournisseur de médias MiniMax-VL-01 géré par le Plugin, même si les anciennes métadonnées de discussion MiniMax M2.x déclarent accepter les images en entrée (seuls MiniMax-M3 et les modèles ultérieurs sont considérés comme prenant en charge la vision nativement).
• Si le modèle principal du Gateway/WebChat n’accepte que le texte, les pièces jointes d’image sont conservées sous forme de références externalisées media://inbound/*, afin que les outils d’image/PDF ou un modèle d’image configuré puissent toujours les examiner au lieu de perdre la pièce jointe.
• La commande explicite openclaw infer image describe --file <path> --model <provider/model> (alias : openclaw capability image describe) exécute directement ce fournisseur/modèle prenant en charge les images, y compris les références Ollama telles que ollama/qwen2.5vl:7b lorsqu’un modèle correspondant prenant en charge les images est configuré sous models.providers.ollama.models[].
• Si <capability>.enabled n’est pas défini sur false, mais qu’aucun modèle n’est configuré, OpenClaw essaie le modèle de réponse actif lorsque son fournisseur prend en charge la capacité.

Détection automatique (par défaut)

Lorsque tools.media.<capability>.enabled n’est pas défini sur false et qu’aucun modèle n’est configuré, OpenClaw essaie les options suivantes dans l’ordre et s’arrête à la première qui fonctionne :

Pour désactiver la détection automatique d’une capacité :

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

Prise en charge des proxys (appels de fournisseur audio/vidéo)

La compréhension audio et vidéo assurée par un fournisseur respecte les variables d’environnement standard de proxy sortant, y compris les règles d’exclusion NO_PROXY/no_proxy : HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Les variables en minuscules ont priorité sur celles en majuscules. Si aucune n’est définie, la compréhension des médias utilise une sortie directe ; si la valeur du proxy est incorrecte, OpenClaw consigne un avertissement et revient à une récupération directe. La compréhension des images ne passe pas par ce chemin de proxy.

Capacités

Définissez capabilities sur une entrée models[] pour la limiter à des types de médias précis. Pour les listes partagées, OpenClaw déduit les valeurs par défaut pour chaque fournisseur intégré :

Pour les entrées de CLI, définissez explicitement capabilities afin d’éviter les correspondances inattendues ; si cette propriété est omise, l’entrée est admissible pour chaque liste de capacités dans laquelle elle apparaît.

Matrice de prise en charge des fournisseurs

Conseils pour la sélection des modèles

• Privilégiez le modèle de génération actuelle le plus performant pour chaque capacité multimédia lorsque la qualité et la sécurité sont importantes.
• Pour les agents utilisant des outils et traitant des entrées non fiables, évitez les modèles multimédias anciens ou moins performants.
• Conservez au moins un modèle de repli par capacité pour garantir la disponibilité (un modèle de qualité et un modèle plus rapide ou moins coûteux).
• Les solutions de repli de la CLI (whisper-cli, whisper, gemini) sont utiles lorsque les API des fournisseurs sont indisponibles.
• Les modes connus de sortie vers un fichier font autorité : un fichier de transcription déduit vide ou absent ne produit aucune transcription au lieu de se rabattre sur la sortie de progression de la CLI.
• parakeet-mlx : utilisez --output-format txt (ou all) avec --output-dir et le modèle de sortie par défaut {filename}. Les variables d’environnement amont PARAKEET_OUTPUT_FORMAT et PARAKEET_OUTPUT_TEMPLATE sont également prises en compte. OpenClaw lit <output-dir>/<media-basename>.txt ; le format srt par défaut, les autres formats et les modèles de sortie personnalisés continuent d’utiliser la sortie standard.

Politique relative aux pièces jointes

La propriété attachments de chaque capacité détermine les pièces jointes traitées :

Lorsque mode: "all", les sorties portent des libellés tels que [Image 1/2], [Audio 2/2], etc.

Extraction des pièces jointes de type fichier

• Le texte extrait d’un fichier est encapsulé comme contenu externe non fiable avant d’être ajouté à l’invite multimédia, à l’aide de marqueurs de délimitation tels que <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> et d’une ligne de métadonnées Source: External.
• Ce chemin omet volontairement la longue bannière SECURITY NOTICE: afin de garder l’invite multimédia concise ; les marqueurs de délimitation et les métadonnées restent appliqués.
• Un fichier ne comportant aucun texte extractible reçoit [No extractable text].
• Si un PDF se rabat sur des images de pages rendues, OpenClaw transmet ces images aux modèles de réponse compatibles avec la vision et conserve l’espace réservé [PDF content rendered to images] dans le bloc du fichier.

Exemples de configuration

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

Sortie d’état

Lorsque la compréhension multimédia s’exécute, /status inclut une ligne récapitulative par capacité :

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

Pour effectuer l’inventaire préalable, exécutez openclaw capability audio providers. Les lignes locales affichent séparément la solution de repli locale retenue, la sélection globale du fournisseur, l’état de disponibilité ainsi que les champs distincts du moteur compatible, demandé et observé. La même sélection locale est disponible sous forme de constat informatif de doctor :

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

Remarques

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

Voir aussi

• Configuration
• Prise en charge des images et des contenus multimédias