​

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 d’exécution

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 démarré à partir d’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/refroidissement des profils d’authentification.
4. Si ce fournisseur est épuisé avec une erreur justifiant un basculement, passer au candidat de modèle suivant.
5. Conserver le remplacement de repli sélectionné avant le début de la nouvelle tentative afin que les autres lecteurs de session voient le même fournisseur/modèle que celui que l’exécuteur est sur le point d’utiliser.
6. Si le candidat de repli échoue, restaurer uniquement les champs de remplacement de session appartenant au repli lorsqu’ils correspondent encore à ce candidat en échec.
7. Si tous les candidats échouent, lever une FallbackSummaryError avec les détails par tentative et l’expiration de refroidissement la plus proche lorsqu’elle est connue.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Stockage d’authentification (clés + OAuth)

• Les secrets sont stockés dans ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (hérité : ~/.openclaw/agent/auth-profiles.json).
• L’état d’exécution du routage d’authentification est stocké dans ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• La configuration auth.profiles / auth.order correspond uniquement aux métadonnées et au routage (pas aux secrets).
• Fichier OAuth hérité utilisé uniquement pour l’importation : ~/.openclaw/credentials/oauth.json (importé dans auth-profiles.json lors de la première utilisation).

• 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, dans chaque type).
• Les profils en refroidissement/désactivés sont déplacés à la fin, triés par expiration la plus proche.

​

Affinité de session (favorable au cache)

• la session soit réinitialisée (/new / /reset)
• une compaction se termine (le compteur de compaction augmente)
• le profil soit en refroidissement/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 (lorsqu’il est pris en charge par votre surface UI/chat).

​

Périodes de refroidissement

• OpenClaw enregistre cooldownModel pour les échecs de limite de débit lorsque l’ID du modèle en échec est connu.
• Un modèle frère sur le même fournisseur peut toujours être essayé lorsque le refroidissement 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é pendant 24 heures (configurable).
• Les nouvelles tentatives pour surcharge autorisent 1 rotation de profil du même fournisseur avant le repli de modèle.
• Les nouvelles tentatives pour surcharge utilisent un backoff de 0 ms par défaut.

​

Repli de modèle

​

Règles de chaîne de candidats

• Le modèle demandé est toujours en premier.
• Les replis configurés explicites sont dédupliqués mais ne sont pas filtrés par la liste d’autorisation de modèles. Ils sont traités comme une intention explicite de l’opérateur.
• Si l’exécution actuelle se trouve déjà sur un repli configuré dans la même famille de fournisseurs, OpenClaw continue d’utiliser la chaîne configurée complète.
• Si l’exécution actuelle est sur un fournisseur différent 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 de replis configurés non liés provenant d’un autre fournisseur.
• Lorsque l’exécution a démarré à partir d’un remplacement, le modèle principal configuré est ajouté à la fin afin que la chaîne puisse revenir à 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 du refroidissement
• les erreurs de surcharge/fournisseur occupé
• les erreurs de basculement de type délai d’attente
• les désactivations de facturation
• LiveSessionModelSwitchError, qui est normalisée en chemin de basculement afin qu’un modèle conservé obsolète ne crée pas de boucle de nouvelle tentative externe
• les autres erreurs non reconnues lorsqu’il reste encore des candidats

• les abandons explicites qui ne sont pas de type délai d’attente/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 de saut de refroidissement vs sondage

• Les échecs d’authentification persistants sautent immédiatement l’ensemble du fournisseur.
• Les désactivations de facturation sont généralement sautées, mais le candidat principal peut quand même être sondé avec limitation afin que la récupération reste possible sans redémarrage.
• Le candidat principal peut être sondé près de l’expiration du refroidissement, avec une limitation par fournisseur.
• Les modèles frères de repli sur le même fournisseur peuvent être tentés malgré le refroidissement lorsque l’échec semble transitoire (rate_limit, overloaded, ou inconnu). Cela est particulièrement pertinent lorsqu’une limite de débit est limitée au modèle et qu’un modèle frère peut encore se rétablir immédiatement.
• Les sondages de refroidissement transitoire 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 basculement de modèle en direct

• Seuls les changements de modèle explicites initié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 initiés par le système tels que la rotation de repli, les remplacements de heartbeat, ou la compaction ne marquent jamais à eux seuls un changement en direct en attente.
• Avant le début d’une nouvelle tentative de repli, le moteur de réponse conserve les champs de remplacement de repli sélectionnés dans l’entrée de session.
• La réconciliation de session en direct préfère les remplacements de session conservés aux champs de modèle d’exécution obsolètes.
• Si la tentative de repli échoue, l’exécuteur restaure 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. Le 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 de session obsolète.
5. La nouvelle tentative revient à l’ancien modèle avant le début de la tentative de repli.

​

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

• fournisseur/modèle tenté
• 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 limites de débit non liées et limitées à d’autres modèles sont ignorées pour la chaîne fournisseur/modèle tentée
• si le blocage restant est une limite de débit limitée au modèle correspondante, 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
• le routage de agents.defaults.imageModel