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 de 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 média propre aux vendeurs est enregistré par les plugins vendeurs, 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

• Optionnel : pré-digérer les médias entrants en texte court 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 et les pièces jointes d’origine.

Aperçu 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"],}

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 : 10MB
  • audio : 20MB
  • vidéo : 50MB

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 détecte automatiquement 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 de proxy (modèles fournisseur)

Lorsque la compréhension des médias audio et vidéo basée sur un 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 consigne un avertissement et revient à une récupération directe.

Capacités (optionnel)

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 admissible 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é média lorsque la qualité et la sécurité importent.
• Pour les agents avec outils traitant des entrées non fiables, évitez les modèles médias plus anciens/plus faibles.
• Conservez au moins un repli par capacité pour la disponibilité (modèle de qualité + modèle plus rapide/moins coûteux).
• Les replis CLI (whisper-cli, whisper, gemini) sont utiles lorsque les API fournisseur ne sont pas disponibles.
• Note 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 quelles pièces jointes sont 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é ainsi que le fournisseur/modèle choisi, le cas échéant.

Notes

• La compréhension fonctionne 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 l’endroit où la compréhension s’exécute (par exemple, uniquement dans les DM).

Connexe

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