CLI de modèles

Rotation du profil d’authentification, temps de refroidissement et interaction avec les basculements.

Aperçu rapide des fournisseurs et exemples.

OpenClaw, Codex et autres runtimes de boucle d’agent.

Clés de configuration du modèle.

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 passe par le runtime du serveur d’application Codex par défaut sur le fournisseur OpenAI officiel. Les références Copilot d’abonnement (github-copilot/*) peuvent en outre être activées pour le plugin de runtime d’agent Copilot GitHub externe — ce chemin reste explicite (pas de repli auto). Les remplacements explicites de runtime appartiennent à la stratégie de fournisseur/modèle, et non à l’agent entier ou à la session. En mode runtime Codex, la référence openai/gpt-* n’implique pas la facturation par clé API ; l’authentification peut provenir d’un compte Codex ou d’un profil OAuth openai. Voir Runtimes d’agent et Runtime d’agent Copilot GitHub.

Fonctionnement de la sélection de modèle

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

Modèle principal
agents.defaults.model.primary (ou agents.defaults.model).
Replis
agents.defaults.model.fallbacks (dans l’ordre).
Provider auth failover
Le basculement d’authentification se produit à l’intérieur d’un fournisseur avant de passer au modèle suivant.

Surfaces de modèles associés

agents.defaults.models est la liste d’autorisation/le catalogue des modèles que OpenClaw peut utiliser (plus les alias). Utilisez les entrées provider/* pour limiter les fournisseurs visibles tout en gardant la découverte de fournisseurs dynamique.
agents.defaults.imageModel est utilisé uniquement lorsque le modèle principal ne peut pas accepter d’images.
agents.defaults.pdfModel est utilisé par l’outil pdf. S’il est omis, l’outil revient à agents.defaults.imageModel, puis au modèle de session/défaut résolu.
agents.defaults.imageGenerationModel est utilisé par la capacité partagée de génération d’images. S’il est omis, image_generate peut quand même déduire un fournisseur par défaut avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les fournisseurs de génération d’images enregistrés restants dans l’ordre des ID de fournisseur. Si vous définissez un fournisseur/modèle spécifique, configurez également la clé d’auth/API de ce fournisseur.
agents.defaults.musicGenerationModel est utilisé par la capacité partagée de génération de musique. S’il est omis, music_generate peut quand même déduire un fournisseur par défaut avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les fournisseurs de génération de musique enregistrés restants dans l’ordre des ID de fournisseur. Si vous définissez un fournisseur/modèle spécifique, configurez également la clé d’auth/API de ce fournisseur.
agents.defaults.videoGenerationModel est utilisé par la capacité partagée de génération de vidéo. S’il est omis, video_generate peut quand même déduire un fournisseur par défaut avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les fournisseurs de génération de vidéo enregistrés restants dans l’ordre des ID de fournisseur. Si vous définissez un fournisseur/modèle spécifique, configurez également la clé d’auth/API de ce fournisseur.
Les valeurs par défaut par agent peuvent remplacer agents.defaults.model via agents.list[].model plus des liaisons (voir Multi-agent routing).

Source de sélection et comportement de repli

Le même provider/model peut signifier différentes choses selon sa provenance :

Les valeurs par défaut configurées (agents.defaults.model.primary et les principaux spécifiques aux agents) sont le point de départ normal et utilisent agents.defaults.model.fallbacks.
Les sélections de repli automatique 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 sonder un principal défaillant à chaque fois ; OpenClaw sonde périodiquement le principal original à nouveau, efface la sélection automatique lorsqu’il récupère, et annonce les transitions de repli/récupération une fois par changement d’état.
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 le provider/modèle sélectionné est inaccessible, OpenClaw échoue visiblement au lieu de basculer vers un autre modèle configuré.
Modifier agents.defaults.model.primary ne réécrit pas les sélections de session existantes. Si le statut indique This session is pinned to X; config primary Y will apply to new/unpinned sessions., basculez la session actuelle avec /model Y ou effacez l’état de session obsolète avec /reset.
Le Cron --model / le payload model est un principal par tâche. Il utilise toujours les replis configurés, sauf si la tâche fournit un payload explicite fallbacks (utilisez fallbacks: [] pour une exécution Cron stricte).
Les sélecteurs de modèle par défaut et de liste d’autorisation 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èles configurée : agents.defaults.models si présent, y compris les entrées provider/* à l’échelle du provider, sinon models.providers.*.models explicites plus les providers avec une auth utilisable. Le catalogue intégré complet est réservé aux vues de navigation explicites telles que models.list avec view: "all" ou openclaw models list --all.

Politique rapide de modèle

Définissez votre principal comme étant le modèle le plus puissant de la dernière génération qui vous est disponible.
Utilisez les replis pour les tâches sensibles aux coûts/à la latence et les discussions moins critiques.
Pour les agents avec outils ou les entrées non fiables, évitez les niveaux de modèle plus anciens ou plus faibles.

Onboarding (recommandé)

Si vous ne souhaitez pas modifier la configuration à la main, lancez l’onboarding :

openclaw onboard

Il peut configurer le modèle + l’auth pour les providers courants, y compris l’abonnement OpenAI Code (Codex) (OAuth) et Anthropic (clé API ou Claude CLI).

Clés de configuration (aperçu)

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 (allowlist + alias + paramètres de provider + entrées de provider dynamiques provider/*)
models.providers (providers personnalisés écrits dans models.json)

Safe allowlist edits

Use additive writes when updating agents.defaults.models by hand:

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

Clobber protection rules

openclaw config set protects model/provider maps from accidental clobbers. A plain object assignment to agents.defaults.models, models.providers, or `models.providers.

.modelsis rejected when it would remove existing entries. Use—mergefor additive changes; use—replace` only when the provided value should become the complete target value.

Interactive provider setup and `openclaw configure --section model` also merge provider-scoped selections into the existing allowlist, so adding Codex, Ollama, or another provider does not drop unrelated model entries. Configure preserves an existing `agents.defaults.model.primary` when provider auth is re-applied. Explicit default-setting commands such as `openclaw models auth login --provider

—set-defaultandopenclaw models set

still replaceagents.defaults.model.primary`.

“Model is not allowed” (and why replies stop)

If agents.defaults.models is set, it becomes the allowlist for /model and for session overrides. When a user selects a model that isn’t in that allowlist, OpenClaw returns:

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 comprenait une priorité d’exécution telle que /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 de Codex, le modèle sélectionné est toujours openai/gpt-5.5 ; l’exécution 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 avec le préfixe du 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 souhaitez limiter les fournisseurs sans lister manuellement chaque modèle, ajoutez des entrées provider/* à agents.defaults.models :

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

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

Exemple de configuration de la 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 en cours sans redémarrer :

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

Comportement du sélecteur

/model (et /model list) est un sélecteur compact numéroté (famille de modèles + fournisseurs disponibles).
Sur Discord, /model et /models ouvrent un sélecteur interactif avec des listes déroulantes pour le fournisseur et le modèle, ainsi qu’une étape de validation.
Sur Telegram, les sélections du sélecteur /models sont limitées à la session ; elles ne modifient pas la valeur par défaut persistante de l’agent dans openclaw.json.
/models add est obsolète et renvoie désormais un message d’obsolescence au lieu d’enregistrer des modèles depuis le chat.
/model <#> effectue une sélection depuis ce sélecteur.

Persistence and live switching

/model enregistre immédiatement la nouvelle sélection de session.
Si l’agent est inactif, la prochaine exécution utilise immédiatement le nouveau modèle.
Si une exécution est déjà en cours, OpenClaw marque le basculement en direct comme en attente et redémarre uniquement avec le nouveau modèle à un point de réessai propre.
Si l’activité de l’outil ou la sortie de la réponse a déjà commencé, le basculement en attente peut rester en file d’attente jusqu’à une prochaine opportunité de réessai ou au prochain tour de l’utilisateur.
Une référence /model sélectionnée par l’utilisateur est stricte pour cette session : si le fournisseur/modèle sélectionné est inaccessible, la réponse échoue visiblement au lieu de répondre silencieusement depuis agents.defaults.model.fallbacks. Cela diffère des valeurs par défaut configurées et des principales tâches cron, qui peuvent toujours utiliser des chaînes de repli.
/model status est la vue détaillée (candidats d’authentification et, lorsqu’ils sont configurés, point de terminaison du fournisseur baseUrl + mode api).

Ref parsing

Les références de modèle sont analysées en divisant sur le premier /. Utilisez provider/model lors de la saisie de `/model

. - Si l'ID du modèle lui-même contient /(style OpenRouter), vous devez inclure le préfixe du fournisseur (exemple :/model openrouter/moonshotai/kimi-k2`). - Si vous omettez le fournisseur, OpenClaw résout l’entrée dans cet ordre : 1. correspondance d’alias 2. correspondance unique de fournisseur configuré pour cet ID de modèle exact sans préfixe 3. repli déprécié vers le fournisseur par défaut configuré — si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient plutôt au premier fournisseur/modèle configuré pour éviter d’afficher une valeur par défaut obsolète d’un fournisseur supprimé.

Comportement/configuration complète des commandes : Slash commands.

Commandes CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw 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 les models configurés/disponibles via auth par défaut. Indicateurs utiles :

Catalogue complet. Inclut les lignes du catalogue statique détenu par le provider groupé avant que l'auth ne soit configurée, afin que les vues de découverte uniquement puissent afficher les models qui sont indisponibles jusqu'à ce que vous ajoutiez des identifiants de provider correspondants. Providers locaux uniquement. Filtrer par id de provider, par exemple `moonshot`. Les étiquettes d'affichage des sélecteurs interactifs ne sont pas acceptées. Un model par ligne. Sortie lisible par machine.

`models status`

Affiche le model principal résolu, les secours (fallbacks), le model d’image, et un aperçu de l’auth des providers configurés. Il affiche également le statut d’expiration OAuth pour les profils trouvés dans le magasin d’auth (avertit dans les 24h par défaut). --plain n’imprime que le model principal résolu.

Comportement de l'authentification et des sondages

Le statut OAuth est toujours affiché (et inclus dans la sortie de --json). Si un provider configuré n’a pas d’identifiants, models status imprime une section Missing auth.
Le JSON inclut auth.oauth (fenêtre d’avertissement + profils) et auth.providers (authentification effective par provider, y compris les identifiants basés sur des variables d’environnement). auth.oauth concerne uniquement la santé des profils de stockage d’authentification ; les providers basés uniquement sur des variables d’environnement n’y apparaissent pas.
Utilisez --check pour l’automatisation (exit 1 en cas d’absence ou d’expiration, 2 en cas d’expiration imminente).
Utilisez --probe pour les vérifications d’authentification en direct ; les lignes de sondage peuvent provenir de profils d’authentification, d’identifiants d’environnement ou de models.json.
Si un `auth.order.

explicite omet un profil stocké, le sondage signaleexcluded_by_auth_orderau lieu de l'essayer. Si une authentification existe mais qu'aucun modèle sondeable ne peut être résolu pour ce provider, le sondage signalestatus: no_model`.

Exemple (Claude CLI) :

claude auth login
openclaw models status

Balayage (modèles gratuits OpenRouter)

openclaw models scanOpenRouter inspecte le catalogue de modèles gratuits d’OpenRouter et peut sonder optionnellement les modèles pour le support des outils et des images.

Ignorer les sondages en direct (métadonnées uniquement). Taille minimale des paramètres (milliards). Ignorer les modèles plus anciens. Filtre de préfixe de fournisseur. Taille de la liste de repli. Définir `agents.defaults.model.primary` sur la première sélection. Définir `agents.defaults.imageModel.primary` sur la première sélection d'image.

Les résultats de l’analyse sont classés par :

Support des images
Latence des outils
Taille du contexte
Nombre de paramètres

Entrée :

Liste OpenRouter /models (filtre :free)
Les sondes en direct nécessitent une clé API OpenRouterAPI des profils d’authentification ou OPENROUTER_API_KEY (voir Environment variables)
Filtres optionnels : --max-age-days, --min-params, --provider, --max-candidates
Contrôles de requête/sondage : --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 contenant uniquement des métadonnées sont informatifs ; --set-default et --set-imageOpenClawOpenRouter nécessitent des sondes en direct, donc OpenClaw ne configure pas de modèle OpenRouter sans clé inutilisable.

Registre des modèles (`models.json`)

Les providers personnalisés dans models.providers sont écrits dans models.json sous le répertoire de l’agent (par défaut ~/.openclaw/agents/<agentId>/agent/models.json). Les catalogues de plugins de provider sont stockés sous forme de fragments de catalogue appartenant au plugin générés sous l’état du plugin de l’agent et chargés automatiquement. Ce fichier est fusionné par défaut, sauf si models.mode est défini sur replace.

Priorité du mode de fusion

Priorité du mode de fusion pour les ID de fournisseur correspondants :

Un baseUrl non vide déjà présent dans le models.json de l’agent l’emporte.
Un apiKey non vide dans le models.json de l’agent l’emporte uniquement lorsque ce fournisseur n’est pas géré par SecretRef dans le contexte de configuration/profil d’authentification actuel.
Les valeurs apiKey du fournisseur géré par SecretRef sont actualisées à partir des marqueurs source (ENV_VAR_NAME pour les références d’env, secretref-managed pour les références de fichier/exec) au lieu de conserver les secrets résolus.
Les valeurs d’en-tête du fournisseur géré par SecretRef sont actualisées à partir des marqueurs source (secretref-env:ENV_VAR_NAME pour les références d’env, secretref-managed pour les références de fichier/exec).
Les apiKey/baseUrl de l’agent vides ou manquants reviennent à la configuration models.providers.
Les autres champs du fournisseur sont actualisés à partir de la configuration et des données du catalogue normalisées.

Connexes

Agent runtimes — OpenClaw, Codex et autres runtimes de boucle d’agent
Configuration reference — clés de configuration de modèle
Image generation — configuration du modèle d’image
Model failover — chaînes de repli
Model providers — routage et authentification des providers
Music generation — configuration du modèle de musique
Video generation — configuration du modèle vidéo