​

Compréhension des médias - Entrants (2026-01-17)

​

Objectifs

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

​

Comportement général

1. Collecter les pièces jointes entrantes (MediaPaths, MediaUrls, MediaTypes).
2. Pour chaque capacité activée (image/audio/vidéo), sélectionner les pièces jointes selon la politique (par défaut : la première).
3. Choisir la première entrée de modèle éligible (taille + capacité + authentification).
4. Si un modèle échoue ou si le média est trop volumineux, passer à l’entrée suivante.
5. En cas de succès :
   • Body devient un bloc [Image], [Audio] ou [Video].
   • L’audio définit {{Transcript}} ; l’analyse des commandes utilise le texte de légende lorsqu’il est présent, sinon la transcription.
   • Les légendes sont préservées comme User text: dans le bloc.

​

Vue d’ensemble de la configuration

• tools.media.models : liste de modèles partagés (utilisez capabilities pour les limiter).
• tools.media.image / tools.media.audio / tools.media.video :
  • valeurs par défaut (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • remplacements de fournisseur (baseUrl, headers, providerOptions)
  • options audio Deepgram via tools.media.audio.providerOptions.deepgram
  • contrôles d’écho de transcription audio (echoTranscript, valeur par défaut false ; echoFormat)
  • liste models par capacité facultative (prioritaire sur les modèles partagés)
  • politique attachments (mode, maxAttachments, prefer)
  • scope (limitation facultative par canal/chatType/clé de session)
• tools.media.concurrency : nombre maximal d’exécutions de capacités concurrentes (par défaut 2).

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

​

Entrées de modèle

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.4-mini",
  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"],
}

• {{MediaDir}} (répertoire contenant le fichier média)
• {{OutputDir}} (répertoire temporaire créé pour cette exécution)
• {{OutputBase}} (chemin de base du fichier temporaire, sans extension)

​

Valeurs par défaut et limites

• 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

• Si le média dépasse maxBytes, ce modèle est ignoré et le modèle suivant est essayé.
• Les fichiers audio inférieurs à 1024 bytes sont traités comme vides/corrompus et ignorés avant la transcription via fournisseur/CLI.
• Si le modèle renvoie plus de maxChars, la sortie est tronquée.
• prompt utilise par défaut un simple « Describe the . » plus la consigne maxChars (image/vidéo uniquement).
• Si le modèle d’image principal actif prend déjà en charge nativement la vision, OpenClaw ignore le bloc de résumé [Image] et transmet l’image d’origine au modèle à la place.
• Si <capability>.enabled: true mais qu’aucun modèle n’est configuré, OpenClaw essaie le modèle de réponse actif lorsque son fournisseur prend en charge cette capacité.

​

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

1. Modèle de réponse actif lorsque son fournisseur prend en charge la capacité.
2. agents.defaults.imageModel refs primary/fallback (image uniquement).
3. CLIs locales (audio uniquement ; si installées)
   • sherpa-onnx-offline (nécessite SHERPA_ONNX_MODEL_DIR avec encoder/decoder/joiner/tokens)
   • whisper-cli (whisper-cpp ; utilise WHISPER_CPP_MODEL ou le petit modèle groupé)
   • whisper (CLI Python ; télécharge automatiquement les modèles)
4. Gemini CLI (gemini) en utilisant read_many_files
5. Authentification fournisseur
   • Les entrées configurées models.providers.* qui prennent en charge la capacité sont essayées avant l’ordre de repli groupé.
   • Les fournisseurs configurés image uniquement avec un modèle compatible image s’enregistrent automatiquement pour la compréhension des médias même lorsqu’ils ne sont pas un plugin fournisseur groupé.
   • Ordre de repli groupé :
     • Audio : OpenAI → Groq → Deepgram → Google → Mistral
     • Image : OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • Vidéo : Google → Qwen → Moonshot

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

​

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

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Capacités (facultatif)

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

​

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

• La compréhension d’image minimax et minimax-portal provient du fournisseur média MiniMax-VL-01 appartenant au plugin.
• Le catalogue texte MiniMax groupé reste initialement limité au texte ; des entrées explicites models.providers.minimax matérialisent des refs de chat M2.7 compatibles image.

​

Conseils de sélection de modèle

• Préférez le modèle le plus puissant et de dernière génération disponible pour chaque capacité média lorsque la qualité et la sécurité comptent.
• Pour les agents avec outils gérant des entrées non fiables, évitez les anciens/modèles média 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 de fournisseur ne sont pas disponibles.
• Remarque 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 autres que txt reviennent à stdout.

​

Politique des pièces jointes

• mode : first (par défaut) ou all
• maxAttachments : limite du nombre traité (par défaut 1)
• prefer : first, last, path, url

• Le texte extrait du fichier est encapsulé comme contenu externe non fiable avant d’être ajouté à l’invite média.
• Le bloc injecté utilise des marqueurs de frontière explicites tels que <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> et inclut une ligne de métadonnées Source: External.
• Ce chemin d’extraction de pièce jointe omet volontairement la longue bannière SECURITY NOTICE: pour éviter de gonfler l’invite média ; les marqueurs de frontière et les métadonnées restent toutefois présents.
• Si un fichier ne contient aucun texte extractible, OpenClaw injecte [No extractable text].
• Si un PDF revient à des images de pages rendues dans ce chemin, l’invite média conserve l’espace réservé [PDF content rendered to images; images not forwarded to model] parce que cette étape d’extraction de pièce jointe transmet des blocs de texte, pas les images PDF rendues.

​

Exemples de configuration

​

1) Liste de modèles partagés + remplacements

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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,
      },
    },
  },
}

​

2) Audio + vidéo uniquement (image désactivée)

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

​

3) Compréhension d’image facultative

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { 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.",
            ],
          },
        ],
      },
    },
  },
}

​

4) Entrée multimodale unique (capacités explicites)

{
  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 de statut

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

​

Remarques

• La compréhension est fournie en meilleur effort. 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 ex. uniquement les DMs).

​

Documentation associée

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