Basculement de modèle

OpenClaw gère les échecs en deux étapes :

1. Rotation des profils d’authentification au sein du fournisseur actuel.
2. Repli de modèle vers le modèle suivant dans agents.defaults.model.fallbacks.

Flux d’exécution

Ce comportement est volontairement plus ciblé que « enregistrer et restaurer toute la session ». Le processus d’exécution des réponses n’enregistre que les champs de sélection de modèle dont il est responsable pour le repli : providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Cela empêche une nouvelle tentative de repli ayant échoué d’écraser des modifications de session plus récentes et sans rapport, comme un changement manuel avec /model ou une mise à jour de rotation de session survenue pendant la tentative.

Politique selon la source de sélection

La source de la sélection détermine si la chaîne de repli est autorisée :

• Valeur par défaut configurée : agents.defaults.model.primary utilise agents.defaults.model.fallbacks.
• Modèle principal de l’agent : agents.list[].model est strict, sauf si l’objet de modèle de cet agent contient ses propres fallbacks. Utilisez fallbacks: [] pour rendre explicitement ce comportement strict, ou une liste non vide pour autoriser le repli de modèle pour cet agent.
• Remplacement automatique par un modèle de repli : lors d’un repli à l’exécution, OpenClaw écrit providerOverride, modelOverride, modelOverrideSource: "auto" et le modèle d’origine sélectionné avant de réessayer. Ce remplacement continue de parcourir la chaîne de repli configurée sans tester le modèle principal à chaque message, mais OpenClaw teste l’origine configurée toutes les 5 minutes (ce délai n’est pas configurable) et supprime le remplacement dès qu’elle est de nouveau opérationnelle. /new, /reset et sessions.reset suppriment également les remplacements provenant d’une sélection automatique. Les exécutions Heartbeat sans heartbeat.model explicite suppriment les remplacements automatiques directs lorsque leur origine ne correspond plus à la valeur par défaut actuellement configurée.
• Remplacement de session par l’utilisateur : /model, le sélecteur de modèle, session_status(model=...) et sessions.patch écrivent modelOverrideSource: "user". Il s’agit d’une sélection exacte pour la session. Si le fournisseur ou le modèle sélectionné échoue avant de produire une réponse, OpenClaw signale l’échec au lieu de répondre à l’aide d’un modèle de repli configuré sans rapport.
• Ancien remplacement de session : les anciennes entrées de session peuvent contenir modelOverride sans modelOverrideSource. OpenClaw les traite comme des remplacements effectués par l’utilisateur afin qu’une ancienne sélection explicite ne soit pas silencieusement convertie en comportement de repli.
• Modèle de charge utile Cron : le payload.model ou l’option --model d’une tâche Cron définit le modèle principal de la tâche, et non un remplacement de session par l’utilisateur. Il utilise les replis configurés, sauf si la tâche fournit payload.fallbacks ; payload.fallbacks: [] rend l’exécution Cron stricte.

OpenClaw mémorise les tests récents du modèle principal pour chaque session et chaque modèle principal afin de ne pas réessayer un modèle principal défaillant à chaque tour. Il envoie une notification visible lorsqu’une session passe à un modèle de repli, puis une autre lorsqu’elle revient au modèle principal sélectionné ; il ne répète pas cette notification à chaque tour restant sur le même modèle de repli.

Cache d’exclusion après un échec d’authentification

Par défaut, chaque nouveau tour conserve le comportement existant de nouvelle tentative de repli : OpenClaw réessaie chaque modèle candidat de repli configuré, y compris les candidats non principaux qui ont récemment échoué avec auth ou auth_permanent.

Pour éviter la répétition des échecs d’authentification, activez cette option avec :

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Lorsqu’elle est activée, OpenClaw enregistre en mémoire un marqueur d’exclusion propre à la session pour un modèle candidat de repli non principal après un échec de la catégorie authentification. Ce marqueur est indexé par identifiant de session, fournisseur et modèle. Les candidats principaux ne sont jamais exclus, afin qu’une sélection explicite de modèle par l’utilisateur continue d’afficher la véritable erreur d’authentification. Le cache est local au processus et est vidé au redémarrage du Gateway.

La valeur est une durée de vie en millisecondes. La valeur 0 ou l’absence de valeur désactive le cache. Les valeurs positives sont limitées à une plage comprise entre 1 seconde et 10 minutes.

Notifications de repli visibles par l’utilisateur

Lorsqu’une session passe à un modèle de repli sélectionné automatiquement, OpenClaw envoie une notification d’état sur la même surface de réponse :

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

Lorsqu’un test ultérieur réussit et que la session revient au modèle principal sélectionné, OpenClaw envoie :

↪️ Model Fallback cleared: <primary> (was <fallback>)

Ces notifications sont des messages opérationnels, et non du contenu de l’assistant. Elles sont envoyées une fois par changement d’état, y compris lorsque cela est possible pendant les tours produisant uniquement des effets secondaires, mais elles ne sont pas répétées lors des tours restant sur le même modèle de repli. Leur envoi contourne la suppression normale des réponses à la source, n’occupe pas le premier emplacement de réponse de l’assistant dans les canaux à fils de discussion et est exclu de la synthèse vocale ainsi que de l’extraction des engagements.

Stockage de l’authentification (clés et OAuth)

OpenClaw utilise des profils d’authentification pour les clés d’API comme pour les jetons OAuth.

• Les secrets et l’état de routage de l’authentification à l’exécution se trouvent dans ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Les paramètres auth.profiles et auth.order contiennent uniquement des métadonnées et des informations de routage (aucun secret).
• Ancien fichier OAuth réservé à l’importation : ~/.openclaw/credentials/oauth.json (importé dans le stockage d’authentification propre à l’agent lors de la première utilisation).
• Les anciens fichiers auth-profiles.json, auth-state.json et les fichiers auth.json propres à chaque agent sont importés par openclaw doctor --fix.

Plus de détails : OAuth

Types d’identifiants :

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl pour certains fournisseurs)
• type: "token" → jeton statique de type porteur, éventuellement assorti d’une expiration ; OpenClaw ne le renouvelle pas (utilisé pour aws-sdk et les autres modes d’authentification reposant sur une chaîne d’identifiants)

Identifiants de profil

Les connexions OAuth créent des profils distincts afin que plusieurs comptes puissent coexister.

• Valeur par défaut : provider:default lorsqu’aucune adresse e-mail n’est disponible.
• OAuth avec adresse e-mail : provider:<email> (par exemple google-antigravity:user@gmail.com).

Les profils se trouvent dans le stockage de profils d’authentification openclaw-agent.sqlite propre à l’agent.

Ordre de rotation

Lorsqu’un fournisseur dispose de plusieurs profils, OpenClaw détermine leur ordre comme suit :

Si aucun ordre explicite n’est configuré, OpenClaw utilise un ordre en rotation circulaire :

• Clé principale : type de profil (OAuth, puis jeton statique, puis clé d’API).
• Clé secondaire : usageStats.lastUsed (du plus ancien au plus récent au sein de chaque type).
• Les profils en temporisation ou désactivés sont placés à la fin, classés selon l’échéance la plus proche.

Affinité de session (favorable au cache)

OpenClaw épingle le profil d’authentification choisi pour chaque session afin de maintenir les caches du fournisseur actifs. Il ne procède pas à une rotation à chaque requête. Le profil épinglé est réutilisé jusqu’à ce que :

• la session soit réinitialisée (/new / /reset)
• une Compaction se termine (le compteur de Compaction augmente)
• le profil soit en temporisation ou désactivé

Une sélection manuelle avec /model …@<profileId> définit un remplacement par l’utilisateur pour cette session et ne fait l’objet d’aucune rotation automatique jusqu’au démarrage d’une nouvelle session.

Abonnement OpenAI Codex avec clé d’API de secours

Pour les modèles d’agent OpenAI, l’authentification et l’environnement d’exécution sont distincts. openai/gpt-* reste dans le banc d’exécution Codex, tandis que l’authentification peut alterner entre un profil d’abonnement Codex et une clé d’API OpenAI de secours.

Utilisez auth.order.openai pour définir l’ordre présenté à l’utilisateur :

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Utilisez openai:* pour les profils OAuth ChatGPT/Codex comme pour les profils de clé d’API OpenAI. Lorsque l’abonnement atteint une limite d’utilisation de Codex, OpenClaw enregistre l’heure exacte de réinitialisation lorsque Codex en fournit une, essaie le profil d’authentification suivant dans l’ordre et maintient l’exécution dans le banc Codex. Une fois l’heure de réinitialisation passée, le profil d’abonnement redevient admissible et la sélection automatique suivante peut y revenir.

Utilisez un profil épinglé par l’utilisateur uniquement si vous souhaitez imposer un compte ou une clé pour cette session. Les profils épinglés par l’utilisateur sont volontairement stricts et ne passent pas silencieusement à un autre profil.

Temporisations

Lorsqu’un profil échoue à cause d’une erreur d’authentification ou de limitation de débit (ou d’une expiration de délai ressemblant à une limitation de débit), OpenClaw le place en temporisation et passe au profil suivant.

Les délais de récupération ordinaires (hors facturation et échec d’authentification permanent) augmentent selon le nombre d’erreurs récentes du profil :

• 1er échec : 30 secondes
• 2e échec : 1 minute
• 3e échec et suivants : 5 minutes (plafond)

Les compteurs sont réinitialisés une fois la fenêtre d’échec du profil écoulée (auth.cooldowns.failureWindowHours, 24 par défaut).

L’état est stocké dans l’état d’authentification SQLite propre à l’agent, sous usageStats :

{  "usageStats": {    "provider:profile": {      "lastUsed": 1736160000000,      "cooldownUntil": 1736160600000,      "errorCount": 2    }  }}

Désactivations liées à la facturation

Les échecs de facturation ou de crédit (par exemple « crédits insuffisants » / « solde de crédit trop faible ») sont considérés comme justifiant un basculement, mais ils ne sont généralement pas transitoires. Au lieu d’un bref délai de récupération, OpenClaw marque le profil comme désactivé (avec une temporisation plus longue), puis passe au profil ou fournisseur suivant.

Les échecs d’authentification permanents identifiés avec un degré de confiance élevé (clés révoquées ou désactivées, espaces de travail désactivés) suivent une catégorie de désactivation similaire, mais la récupération est beaucoup plus rapide que pour la facturation, car certains fournisseurs renvoient temporairement des réponses ressemblant à des erreurs d’authentification pendant des incidents.

L’état est stocké dans l’état d’authentification SQLite propre à l’agent :

{  "usageStats": {    "provider:profile": {      "disabledUntil": 1736178000000,      "disabledReason": "billing"    }  }}

Valeurs par défaut (auth.cooldowns.*) :

Les erreurs de surcharge et de limite de débit sont gérées plus agressivement que les délais de récupération liés à la facturation : par défaut, OpenClaw autorise une nouvelle tentative avec un autre profil d’authentification du même fournisseur, puis passe au modèle de repli configuré suivant sans attendre.

Repli de modèle

Si tous les profils d’un fournisseur échouent, OpenClaw passe au modèle suivant dans agents.defaults.model.fallbacks. Cela s’applique aux échecs d’authentification, aux limites de débit et aux expirations de délai ayant épuisé la rotation des profils (les autres erreurs ne déclenchent pas le repli suivant). Les erreurs de fournisseur qui ne fournissent pas assez de détails restent étiquetées précisément dans l’état de repli : empty_response signifie que le fournisseur n’a renvoyé aucun message ni état exploitable, no_error_details signifie que le fournisseur a explicitement renvoyé Unknown error (no error details in response), et unclassified signifie qu’OpenClaw a conservé l’aperçu brut, mais qu’aucun classificateur ne lui correspond encore.

Les signaux indiquant qu’un fournisseur est occupé, tels que ModelNotReadyException, sont classés dans la catégorie de surcharge et suivent la même politique consistant en une rotation, puis un repli, que les limites de débit (consultez le tableau des valeurs par défaut ci-dessus).

Lorsqu’une exécution démarre avec le modèle principal configuré par défaut, le modèle principal d’une tâche Cron, le modèle principal d’un agent doté de replis explicites ou un remplacement de repli sélectionné automatiquement, OpenClaw peut parcourir la chaîne de repli configurée correspondante. Les modèles principaux d’agents sans replis explicites et les sélections explicites de l’utilisateur (par exemple /model ollama/qwen3.5:27b, le sélecteur de modèle, sessions.patch ou les remplacements ponctuels de fournisseur/modèle dans la CLI) sont stricts : si ce fournisseur ou modèle est inaccessible ou échoue avant de produire une réponse, OpenClaw signale l’échec au lieu de répondre depuis un repli sans rapport.

Règles de la chaîne de candidats

OpenClaw construit la liste des candidats à partir du provider/model actuellement demandé et des replis configurés.

Erreurs qui déclenchent le repli suivant

Ignorer le délai de récupération ou effectuer une sonde

Lorsque tous les profils d’authentification d’un fournisseur sont déjà en délai de récupération, OpenClaw n’ignore pas automatiquement ce fournisseur indéfiniment. Il prend une décision pour chaque candidat :

Remplacements de session et changement de modèle en direct

Les changements de modèle d’une session constituent un état partagé. Le moteur actif, la commande /model, les mises à jour de Compaction ou de session et la réconciliation de session en direct lisent ou écrivent tous des parties de la même entrée de session.

Les nouvelles tentatives de repli doivent donc être coordonnées avec le changement de modèle en direct :

• Seuls les changements de modèle explicitement déclenchés par l’utilisateur signalent un changement en direct en attente. Cela comprend /model, session_status(model=...) et sessions.patch.
• Les changements de modèle déclenchés par le système, tels que la rotation de repli, les remplacements de Heartbeat ou la Compaction, ne signalent jamais à eux seuls un changement en direct en attente.
• Les remplacements de modèle déclenchés par l’utilisateur sont considérés comme des sélections exactes pour la politique de repli. Un fournisseur sélectionné mais inaccessible produit donc une erreur au lieu d’être masqué par agents.defaults.model.fallbacks.
• Avant le début d’une nouvelle tentative de repli, le moteur de réponse enregistre les champs de remplacement du repli sélectionné dans l’entrée de session.
• Les remplacements automatiques de repli restent sélectionnés lors des tours suivants afin qu’OpenClaw ne sonde pas un modèle principal connu comme défaillant à chaque message. OpenClaw sonde périodiquement à nouveau l’origine configurée et efface le remplacement automatique lorsqu’elle est rétablie ; /new, /reset et sessions.reset effacent immédiatement les remplacements d’origine automatique.
• Les réponses adressées à l’utilisateur annoncent les transitions vers un repli et la récupération après suppression du repli une seule fois par changement d’état. Les tours qui conservent le même repli ne répètent pas l’avis.
• /status affiche le modèle sélectionné et, lorsque l’état de repli diffère, le modèle de repli actif et sa raison.
• La réconciliation de session en direct privilégie les remplacements persistants de la session aux champs obsolètes du modèle d’exécution.
• Si une erreur de changement en direct désigne un candidat ultérieur de la chaîne de repli active, OpenClaw passe directement au modèle sélectionné au lieu de parcourir d’abord des candidats sans rapport.
• Si la tentative de repli échoue, le moteur annule uniquement les champs de remplacement qu’il a écrits, et seulement s’ils correspondent encore à ce candidat en échec.

Cela évite la situation de concurrence classique :

Le remplacement de repli enregistré dans l’état persistant referme cette fenêtre, tandis que l’annulation ciblée préserve les modifications manuelles ou d’exécution plus récentes de la session.

Observabilité et résumés des échecs

runWithModelFallback(...) enregistre les détails de chaque tentative qui alimentent les journaux et les messages de délai de récupération destinés aux utilisateurs :

• fournisseur/modèle essayé
• raison (rate_limit, overloaded, billing, auth, model_not_found et raisons similaires de basculement)
• statut/code facultatif
• résumé de l’erreur lisible par un humain

Les journaux structurés model_fallback_decision incluent également des champs plats fallbackStep* lorsqu’un candidat échoue, est ignoré ou qu’un basculement ultérieur réussit. Ces champs rendent explicite la transition tentée (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), afin que les exportateurs de journaux et de diagnostics puissent reconstituer l’échec initial même lorsque le dernier modèle de secours échoue également.

Lorsque tous les candidats échouent, OpenClaw lève FallbackSummaryError. Le gestionnaire externe des réponses peut l’utiliser pour générer un message plus précis, tel que « tous les modèles sont temporairement soumis à une limitation de débit », et indiquer la prochaine expiration du délai de récupération lorsqu’elle est connue.

Ce résumé des délais de récupération tient compte du modèle :

• les limitations de débit limitées à des modèles sans rapport sont ignorées pour la chaîne fournisseur/modèle essayée
• si le blocage restant correspond à une limitation de débit limitée au modèle concerné, OpenClaw indique la dernière expiration correspondante qui bloque encore ce modèle

Configuration associée

Consultez Configuration du Gateway pour :

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• le routage de agents.defaults.imageModel

Consultez Modèles pour une présentation générale de la sélection des modèles et du basculement.