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 fournisseurs 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 à chaque fournisseur est enregistré par les plugins de fournisseur, tandis que 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.

# Objectifs

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

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

# 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 média (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 des environnements proxy (modèles de fournisseur)

Lorsque la compréhension média 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 proxy n’est définie, la compréhension média 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 (facultatif)

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

• 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
• 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é comptent.
• Pour les agents avec outils qui traitent des entrées non fiables, évitez les modèles média plus anciens/faibles.
• Gardez au moins un repli par capacité pour la disponibilité (modèle de qualité + modèle plus rapide/moins cher).
• Les replis CLI (whisper-cli, whisper, gemini) sont utiles lorsque les API de fournisseurs sont indisponibles.
• 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 reviennent à stdout.

# Stratégie de pièces jointes

Le paramètre attachments par capacité 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 des médias 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 lorsqu’il y a lieu.

# Notes

• La compréhension est effectuée 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 DM).

# Connexe

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