​

Basculement de modèle

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 du runtime

1. Le modèle de session actuellement sélectionné.
2. Les agents.defaults.model.fallbacks configurés dans l’ordre.
3. Le modèle principal configuré à la fin lorsque l’exécution a commencé depuis un remplacement.

1. Résoudre le modèle de session actif et la préférence de profil d’authentification.
2. Construire la chaîne de candidats de modèle.
3. Essayer le fournisseur actuel avec les règles de rotation/cooldown des profils d’authentification.
4. Si ce fournisseur est épuisé avec une erreur justifiant un basculement, passer au candidat de modèle suivant.
5. Persister le remplacement de repli sélectionné avant que la nouvelle tentative ne démarre afin que les autres lecteurs de session voient le même fournisseur/modèle que celui que l’exécuteur s’apprête à utiliser.
6. Si le candidat de repli échoue, annuler uniquement les champs de remplacement de session détenus par le repli lorsqu’ils correspondent encore à ce candidat en échec.
7. Si tous les candidats échouent, lever une FallbackSummaryError avec le détail de chaque tentative et l’expiration de cooldown la plus proche lorsqu’elle est connue.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Stockage des authentifiants (clés + OAuth)

• Les secrets se trouvent dans ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (hérité : ~/.openclaw/agent/auth-profiles.json).
• La config auth.profiles / auth.order contient uniquement les métadonnées + le routage (pas de secrets).
• Fichier OAuth hérité réservé à l’import : ~/.openclaw/credentials/oauth.json (importé dans auth-profiles.json lors du premier usage).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl pour certains fournisseurs)

​

ID de profil

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

​

Ordre de rotation

1. Configuration explicite : auth.order[provider] (si défini).
2. Profils configurés : auth.profiles filtrés par fournisseur.
3. Profils stockés : entrées dans auth-profiles.json pour le fournisseur.

• Clé primaire : type de profil (OAuth avant les clés API).
• Clé secondaire : usageStats.lastUsed (le plus ancien d’abord, au sein de chaque type).
• Les profils en cooldown/désactivés sont déplacés à la fin, triés par expiration la plus proche.

​

Persistance de session (favorable au cache)

• la session soit réinitialisée (/new / /reset)
• une compaction se termine (le compteur de compaction s’incrémente)
• le profil soit en cooldown/désactivé

​

Pourquoi OAuth peut « sembler perdu »

• Épinglez avec auth.order[provider] = ["provider:profileId"], ou
• Utilisez un remplacement par session via /model … avec un remplacement de profil (lorsque pris en charge par votre surface UI/chat).

​

Cooldowns

• OpenClaw enregistre cooldownModel pour les échecs de limitation de débit lorsque l’ID du modèle en échec est connu.
• Un modèle frère chez le même fournisseur peut encore être essayé lorsque le cooldown est limité à un autre modèle.
• Les fenêtres de facturation/désactivation bloquent toujours l’ensemble du profil sur tous les modèles.

• 1 minute
• 5 minutes
• 25 minutes
• 1 heure (plafond)

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

​

Désactivations de facturation

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

• Le backoff de facturation commence à 5 heures, double à chaque échec de facturation et est plafonné à 24 heures.
• Les compteurs de backoff sont réinitialisés si le profil n’a pas échoué depuis 24 heures (configurable).
• Les nouvelles tentatives en surcharge autorisent 1 rotation de profil chez le même fournisseur avant le repli de modèle.
• Les nouvelles tentatives en surcharge utilisent un backoff de 0 ms par défaut.

​

Repli de modèle

​

Règles de la chaîne de candidats

• Le modèle demandé est toujours en premier.
• Les replis configurés explicites sont dédupliqués mais non filtrés par la liste d’autorisation des modèles. Ils sont traités comme une intention explicite de l’opérateur.
• Si l’exécution actuelle est déjà sur un repli configuré dans la même famille de fournisseur, OpenClaw continue d’utiliser la chaîne complète configurée.
• Si l’exécution actuelle est sur un fournisseur différent de celui de la configuration et que ce modèle actuel ne fait pas déjà partie de la chaîne de repli configurée, OpenClaw n’ajoute pas des replis configurés non liés d’un autre fournisseur.
• Lorsque l’exécution a commencé depuis un remplacement, le modèle principal configuré est ajouté à la fin afin que la chaîne puisse revenir vers la valeur par défaut normale une fois les candidats précédents épuisés.

​

Quelles erreurs font avancer le repli

• les échecs d’authentification
• les limites de débit et l’épuisement des cooldowns
• les erreurs de surcharge/fournisseur occupé
• les erreurs de type timeout justifiant un basculement
• les désactivations de facturation
• LiveSessionModelSwitchError, qui est normalisée dans un chemin de basculement afin qu’un modèle persistant obsolète ne crée pas de boucle externe de nouvelle tentative
• les autres erreurs non reconnues lorsqu’il reste encore des candidats

• les abandons explicites qui ne sont pas de type timeout/basculement
• les erreurs de dépassement de contexte qui doivent rester dans la logique de compaction/nouvelle tentative (par exemple request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model, ou ollama error: context length exceeded)
• une erreur inconnue finale lorsqu’il ne reste plus de candidats

​

Comportement d’ignorance de cooldown vs sondage

• Les échecs d’authentification persistants ignorent immédiatement tout le fournisseur.
• Les désactivations de facturation sont généralement ignorées, mais le candidat principal peut encore être sondé avec limitation afin que la récupération soit possible sans redémarrage.
• Le candidat principal peut être sondé près de l’expiration du cooldown, avec une limitation par fournisseur.
• Les modèles frères de repli chez le même fournisseur peuvent être tentés malgré le cooldown lorsque l’échec semble transitoire (rate_limit, overloaded, ou inconnu). C’est particulièrement pertinent lorsqu’une limitation de débit est limitée à un modèle et qu’un modèle frère peut encore se rétablir immédiatement.
• Les sondages transitoires en cooldown sont limités à un par fournisseur et par exécution de repli afin qu’un seul fournisseur ne bloque pas le repli inter-fournisseurs.

​

Remplacements de session et changement de modèle en direct

• Seuls les changements de modèle explicites pilotés par l’utilisateur marquent un changement en direct en attente. Cela inclut /model, session_status(model=...) et sessions.patch.
• Les changements de modèle pilotés par le système, comme la rotation de repli, les remplacements heartbeat, ou la compaction, ne marquent jamais à eux seuls un changement en direct en attente.
• Avant qu’une nouvelle tentative de repli ne commence, l’exécuteur de réponse persiste les champs de remplacement du repli sélectionné dans l’entrée de session.
• La réconciliation de session en direct préfère les remplacements de session persistés aux champs de modèle obsolètes du runtime.
• Si la tentative de repli échoue, l’exécuteur annule uniquement les champs de remplacement qu’il a écrits, et seulement s’ils correspondent encore à ce candidat en échec.

1. Le modèle principal échoue.
2. Un candidat de repli est choisi en mémoire.
3. Le stockage de session indique encore l’ancien modèle principal.
4. La réconciliation de session en direct lit l’état obsolète de la session.
5. La nouvelle tentative est ramenée à l’ancien modèle avant même que la tentative de repli ne commence.

​

Observabilité et résumés d’échec

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

• les limitations de débit limitées à d’autres modèles sont ignorées pour la chaîne fournisseur/modèle tentée
• si le blocage restant est une limitation de débit limitée au modèle correspondant, OpenClaw signale la dernière expiration correspondante qui bloque encore ce modèle

​

Configuration associée

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel routing