Présentation du paramètre imageModel

Dans OpenClaw, le paramètre imageModel désigne un modèle spécialement optimisé pour l'analyse visuelle. Il fonctionne de manière indépendante du modèle conversationnel principal (model). Dès qu'un contenu graphique est détecté, OpenClaw bascule automatiquement vers le modèle spécifié dans imageModel pour le traitement.

Justification d'une configuration séparée

Le modèle principal (model.primary) peut être limité aux entrées textuelles. Par exemple :

• Un modèle comme MiniMax-M2.5-highspeed ne prend en charge que le texte
• Un modèle comme moonshot/kimi-k2.5 gère les données multimodales (texte + images)

Définir un imageModel dédié permet d'optimiser les performances : utiliser un modèle rapide pour le texte et un modèle multimodal pour les images.

Méthode de configuration

Éditez le fichier de configuration d'OpenClaw (openclaw config edit) :

{
  "agents": {
    "defaults": {
      "model": {
        "principal": "minimax-portal/MiniMax-M2.5-highspeed",
        "alternatives": ["moonshot/kimi-k2.5", "anthropic/claude-opus-4-6"]
      },
      "imageModel": {
        "principal": "moonshot/kimi-k2.5",
        "alternatives": ["openrouter/qwen/qwen-2.5-vl-72b-instruct:free"]
      }
    }
  }
}

Deux syntaxes sont possibles :

// Syntaxe courte (modèle principal seulement)
"imageModel": "moonshot/kimi-k2.5"

// Syntaxe complète (principal + chaîne d'alternatives)
"imageModel": {
  "principal": "moonshot/kimi-k2.5",
  "alternatives": ["openrouter/google/gemini-2.0-flash-vision:free"]
}

Commandes de gestion CLI

# Afficher l'état actuel de imageModel
openclaw models status

# Définir le modèle principal pour les images
openclaw models set-image moonshot/kimi-k2.5

# Gérer la chaîne d'alternatives pour les images
openclaw models image-alternatives list
openclaw models image-alternatives add openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-alternatives remove openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-alternatives clear

Cas d'activation

Logique de repli

La séquence de tentative est :

imageModel.principal → imageModel.alternatives[0] → alternatives[1] → ...

Le premier modèle opérationnel est utilisé. En cas d'échec complet, une erreur est levée :

"Aucun modèle d'image configuré. Définissez agents.defaults.imageModel.principal ou agents.defaults.imageModel.alternatives."

Relation avec le paramètre pdfModel

Priorité de traitement pour les PDF :

PdfModel → imageModel → Valeur par défaut du fournisseur intégré

En l'absence de pdfModel, le traitement des PDF utilise la configuraton définie dans imageModel.

Modèles visuels par défaut intégrés

Lorsqu'aucun imageModel n'est spécifié et que la clé API du fournisseur correspondant est présente, le système utilise les modèles par défaut :

Exemple de configuration complète

{
  "agents": {
    "defaults": {
      "model": {
        "principal": "minimax-portal/MiniMax-M2.5-highspeed",
        "alternatives": ["moonshot/kimi-k2.5", "anthropic/claude-opus-4-6"]
      },
      "imageModel": {
        "principal": "moonshot/kimi-k2.5",
        "alternatives": ["openrouter/google/gemini-2.0-flash-vision:free"]
      },
      "pdfModel": {
        "principal": "anthropic/claude-opus-4-6"
      },
      "models": {
        "moonshot/kimi-k2.5": { "alias": "kimi" },
        "minimax-portal/MiniMax-M2.5-highspeed": { "alias": "mm" }
      }
    }
  }
}

Résultat :

• Conversations textuelles → MiniMax-M2.5-highspeed
• Contenu avec images → moonshot/kimi-k2.5, sinon repli sur gemini-2.0-flash-vision
• Fichiers PDF → claude-opus-4-6, sinon repli sur la chaîne imageModel