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 Codex app-server sur le fournisseur OpenAI officiel. Les références Copilot par abonnement (github-copilot/*) peuvent en outre être activées dans le plugin runtime d’agent GitHub Copilot externe — ce chemin reste explicite (pas de repli auto). Les remplacements explicites de runtime relèvent de la politique fournisseur/modèle, pas de l’agent ou de la session entière. En mode runtime Codex, la référence openai/gpt-* n’implique pas une facturation par clé API ; l’authentification peut provenir d’un compte Codex ou d’un profil OAuth openai. Consultez Runtimes d’agent et runtime d’agent GitHub Copilot.

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 de repli automatiques 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 à chaque fois un modèle principal connu comme défaillant ; OpenClaw sonde périodiquement à nouveau le modèle principal d’origine, efface la sélection automatique lorsqu’il récupère et annonce les transitions de repli/récupération une seule 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 fournisseur/modèle sélectionné est inaccessible, OpenClaw échoue de manière visible 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 l’état indique This session is pinned to X; config primary Y will apply to new/unpinned sessions., effacez la sélection de la session actuelle avec /model default afin qu’elle hérite à nouveau du modèle principal configuré.
• Cron --model / charge utile model est un modèle principal par tâche. Il utilise toujours les solutions de repli configurées, sauf si la tâche fournit une charge utile explicite fallbacks (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’il est présent, y compris les entrées provider/* couvrant tout un 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 telles que 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 les solutions de repli 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.

Intégration (recommandée)

Si vous ne voulez pas modifier la configuration à la main, lancez l’intégration :

openclaw onboard

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

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 (liste d’autorisation + alias + paramètres de fournisseur + entrées dynamiques de fournisseur provider/*)
• models.providers (fournisseurs personnalisés écrits dans models.json)

Modifications sûres de 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

« Le modèle n’est pas autorisé » (et pourquoi les réponses s’arrêtent)

Si agents.defaults.models est défini, il devient la liste d’autorisation pour /model et les remplacements 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 un remplacement de runtime tel 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 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 dans la liste d’autorisation la référence complète préfixée par le fournisseur, 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 seuls 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/*": {},        "vllm/*": {},      },    },  },}

Avec cette politique, /model, /models et les sélecteurs de modèle 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 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 la conversation (/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 default/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 par authentification. Options 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 une vue d’ensemble de l’authentification des fournisseurs configurés. Il expose aussi l’état d’expiration OAuth des profils trouvés dans le magasin d’authentification (avertissement dans les 24 h par défaut). --plain affiche uniquement le modèle principal résolu.

Exemple (CLI Claude) :

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 depuis les profils d’authentification ou 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 TUI, 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 de métadonnées seules 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 (par défaut ~/.openclaw/agents/<agentId>/agent/models.json). Les catalogues des Plugin de fournisseur sont stockés comme fragments de catalogue générés appartenant au Plugin sous l’état Plugin de l’agent et chargés automatiquement. Ce fichier est fusionné par défaut sauf si models.mode est défini sur replace.

Connexe

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