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 l’environnement d’exécution d’agent de bas niveau. Par exemple, openai/gpt-5.5 peut s’exécuter via le chemin normal du fournisseur OpenAI ou via l’environnement d’exécution app-server Codex, selon agents.defaults.agentRuntime.id. En mode d’exécution 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 du profil d’authentification openai-codex. Voir Environnements d’exécution d’agents.

# Fonctionnement de la sélection de modèle

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

# Source de sélection et comportement de secours

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 secours 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 secours 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 de manière visible au lieu de basculer vers un autre modèle configuré.
• Cron --model / charge utile model est un modèle principal par tâche. Il utilise toujours les solutions de secours configurées, sauf si la tâche fournit explicitement des fallbacks dans la charge utile (utilisez fallbacks: [] pour une exécution cron stricte).
• Les sélecteurs CLI de modèle par défaut et de liste d’autorisation respectent models.mode: "replace" en listant les models.providers.*.models explicites au lieu de charger tout le catalogue intégré.
• 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, sinon les models.providers.*.models explicites ainsi que les fournisseurs ayant 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 rapide de modèle

• 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 solutions de secours 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/moins puissants.

# Intégration (recommandé)

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, notamment OpenAI Code (Codex) subscription (OAuth) et Anthropic (clé d’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)
• 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

# « 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 n’est 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 comprenait un remplacement d’environnement d’exécution 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 Codex native, le modèle sélectionné reste openai/gpt-5.5 ; l’environnement d’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 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 seuls ou les noms d’affichage ne suffisent pas lorsque la liste d’autorisation est active.

Exemple de configuration de liste d’autorisation :

{
  agent: {
    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 status

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

# 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 par défaut les modèles configurés/dont l’authentification est disponible. Indicateurs utiles :

--allboolean

Catalogue complet. Inclut les lignes de catalogue statiques groupées appartenant aux fournisseurs avant la configuration de l’authentification, afin que les vues de découverte seule puissent afficher les modèles indisponibles tant que vous n’avez pas ajouté les identifiants de fournisseur correspondants.

--localboolean

Fournisseurs locaux uniquement.

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

--plainboolean

Un modèle par ligne.

--jsonboolean

Sortie lisible par machine.

# models status

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

Exemple (Claude CLI) :

claude auth login
openclaw models status

# Analyse (modèles gratuits OpenRouter)

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

--no-probeboolean

Ignorer les sondages en direct (métadonnées uniquement).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Définir agents.defaults.model.primary sur la première sélection.

--set-imageboolean

Définir agents.defaults.imageModel.primary sur la première sélection d’image.

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 sondages en direct nécessitent une clé API OpenRouter issue des 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/sondage : --timeout, --concurrency

Lorsque les sondages en direct s’exécutent dans un TTY, vous pouvez sélectionner les modèles de secours 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 sondages 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). Ce fichier est fusionné par défaut, sauf si models.mode est défini sur replace.

# Connexe

• Environnements d’exécution d’agent — PI, Codex et autres environnements d’exécution 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 secours
• Fournisseurs de modèles — routage et authentification des fournisseurs
• Génération de musique — configuration du modèle de musique
• Génération de vidéo — configuration du modèle de vidéo