CLI des modèles

Les références de modèle choisissent un fournisseur et un modèle. Elles ne choisissent généralement pas le runtime d’agent de bas niveau. Les références d’agent OpenAI sont la principale exception : openai/gpt-5.5 s’exécute par défaut via le runtime de serveur d’application Codex sur le fournisseur OpenAI officiel. Les substitutions explicites de runtime relèvent de la politique fournisseur/modèle, pas de l’agent ou de la session dans son ensemble. En mode runtime Codex, la référence openai/gpt-* n’implique pas une facturation par clé d’API ; l’authentification peut provenir d’un compte Codex ou d’un profil d’authentification openai-codex. Voir Runtimes d’agent.

Fonctionnement de la sélection de modèle

OpenClaw sélectionne les modèles dans cet ordre :

Source de sélection et comportement de repli

Le même provider/model peut signifier différentes choses selon son origine :

• Les valeurs par défaut configurées (agents.defaults.model.primary et les modèles principaux propres aux agents) sont le point de départ normal et utilisent agents.defaults.model.fallbacks.
• Les sélections automatiques de repli sont un état de récupération temporaire. Elles sont stockées avec modelOverrideSource: "auto" afin que les tours suivants puissent continuer à utiliser la chaîne de repli sans tester d’abord un modèle principal connu comme défaillant.
• Les sélections de session utilisateur sont exactes. /model, le sélecteur de modèle, session_status(model=...) et sessions.patch stockent modelOverrideSource: "user" ; si ce fournisseur/modèle sélectionné est inaccessible, OpenClaw échoue visiblement au lieu de basculer vers un autre modèle configuré.
• Cron --model / payload model est un modèle principal par tâche. Il utilise toujours les replis configurés, sauf si la tâche fournit des fallbacks explicites dans le payload (utilisez fallbacks: [] pour une exécution cron stricte).
• Les sélecteurs de modèle par défaut et de liste d’autorisation de la CLI respectent models.mode: "replace" en listant les models.providers.*.models explicites au lieu de charger le catalogue intégré complet.
• Le sélecteur de modèle de l’interface de contrôle demande au Gateway sa vue de modèle configurée : agents.defaults.models lorsqu’elle est présente, y compris les entrées provider/* à l’échelle du fournisseur, sinon les models.providers.*.models explicites plus les fournisseurs avec une authentification utilisable. Le catalogue intégré complet est réservé aux vues de navigation explicites comme models.list avec view: "all" ou openclaw models list --all.

Politique de modèle rapide

• Définissez votre modèle principal sur le modèle de dernière génération le plus puissant auquel vous avez accès.
• Utilisez des replis pour les tâches sensibles au coût/à la latence et les conversations à moindre enjeu.
• Pour les agents avec outils activés ou les entrées non fiables, évitez les niveaux de modèles plus anciens/plus faibles.

Onboarding (recommandé)

Si vous ne voulez pas modifier la configuration à la main, exécutez l’onboarding :

openclaw onboard

Il peut configurer le modèle et l’authentification pour les fournisseurs courants, notamment OpenAI Code (Codex) subscription (OAuth) et Anthropic (clé d’API ou CLI Claude).

Clés de configuration (vue d’ensemble)

• agents.defaults.model.primary et agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary et agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary et agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary et agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary et agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (liste d’autorisation + alias + paramètres de fournisseur + entrées de fournisseur dynamique provider/*)
• models.providers (fournisseurs personnalisés écrits dans models.json)

Modifications sûres de la liste d’autorisation

Utilisez des écritures additives lorsque vous mettez à jour agents.defaults.models à la main :

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

"Model is not allowed" (et pourquoi les réponses s’arrêtent)

Si agents.defaults.models est défini, il devient la liste d’autorisation pour /model et pour les substitutions de session. Lorsqu’un utilisateur sélectionne un modèle qui ne figure pas dans cette liste d’autorisation, OpenClaw renvoie :

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Lorsque la commande rejetée incluait une substitution de runtime comme /model openai/gpt-5.5 --runtime codex, corrigez d’abord la liste d’autorisation, puis réessayez la même commande /model ... --runtime .... Pour l’exécution native Codex, le modèle sélectionné reste openai/gpt-5.5 ; le runtime codex sélectionne le harnais et utilise l’authentification Codex séparément.

Pour les modèles locaux/GGUF, stockez la référence complète préfixée par le fournisseur dans la liste d’autorisation, par exemple ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf, ou le fournisseur/modèle exact affiché par openclaw models list --provider <provider>. Les noms de fichiers locaux bruts ou les noms d’affichage ne suffisent pas lorsque la liste d’autorisation est active.

Si vous voulez limiter les fournisseurs sans lister manuellement chaque modèle, ajoutez des entrées provider/* à agents.defaults.models :

{  agents: {    defaults: {      models: {        "openai-codex/*": {},        "vllm/*": {},      },    },  },}

Avec cette politique, /model, /models et les sélecteurs de modèle affichent le catalogue découvert pour ces fournisseurs uniquement. Les nouveaux modèles des fournisseurs sélectionnés peuvent apparaître sans modifier la liste d’autorisation. Des entrées exactes provider/model peuvent être combinées avec des entrées provider/* lorsque vous avez besoin d’un modèle précis d’un autre fournisseur.

Exemple de configuration de liste d’autorisation :

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

Changer de modèle dans le chat (/model)

Vous pouvez changer de modèle pour la session actuelle sans redémarrer :

/model/model list/model 3/model openai/gpt-5.4/model status

Comportement/configuration complète des commandes : Commandes slash.

Commandes CLI

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (sans sous-commande) est un raccourci pour models status.

models list

Affiche par défaut les modèles configurés/disponibles via authentification. Indicateurs utiles :

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtrer par ID de fournisseur, par exemple moonshot. Les libellés d’affichage des sélecteurs interactifs ne sont pas acceptés.

models status

Affiche le modèle principal résolu, les replis, le modèle d’image et un aperçu d’authentification des fournisseurs configurés. Affiche également l’état d’expiration OAuth des profils trouvés dans le magasin d’authentification (avertit par défaut dans les 24 h). --plain affiche uniquement le modèle principal résolu.

Exemple (Claude CLI) :

claude auth loginopenclaw models status

Analyse (modèles gratuits OpenRouter)

openclaw models scan inspecte le catalogue de modèles gratuits d’OpenRouter et peut éventuellement sonder les modèles pour la prise en charge des outils et des images.

Les résultats d’analyse sont classés par :

1. Prise en charge des images
2. Latence des outils
3. Taille du contexte
4. Nombre de paramètres

Entrée :

• Liste OpenRouter /models (filtre :free)
• Les sondes en direct nécessitent une clé API OpenRouter provenant de profils d’authentification ou de OPENROUTER_API_KEY (voir Variables d’environnement)
• Filtres facultatifs : --max-age-days, --min-params, --provider, --max-candidates
• Contrôles de requête/sonde : --timeout, --concurrency

Lorsque les sondes en direct s’exécutent dans un TTY, vous pouvez sélectionner les replis de manière interactive. En mode non interactif, passez --yes pour accepter les valeurs par défaut. Les résultats limités aux métadonnées sont informatifs ; --set-default et --set-image nécessitent des sondes en direct afin qu’OpenClaw ne configure pas un modèle OpenRouter sans clé inutilisable.

Registre des modèles (models.json)

Les fournisseurs personnalisés dans models.providers sont écrits dans models.json sous le répertoire de l’agent (~/.openclaw/agents/<agentId>/agent/models.json par défaut). Ce fichier est fusionné par défaut sauf si models.mode est défini sur replace.

Connexe

• Runtimes d’agent — PI, Codex et autres runtimes de boucle d’agent
• Référence de configuration — clés de configuration des modèles
• Génération d’images — configuration du modèle d’image
• Basculement de modèle — chaînes de repli
• Fournisseurs de modèles — routage et authentification des fournisseurs
• Génération de musique — configuration du modèle musical
• Génération de vidéo — configuration du modèle vidéo