​

Failover del modello

1. Rotazione del profilo di autenticazione all’interno del provider corrente.
2. Fallback del modello al modello successivo in agents.defaults.model.fallbacks.

​

Flusso di runtime

1. Il modello di sessione attualmente selezionato.
2. I agents.defaults.model.fallbacks configurati in ordine.
3. Il modello primario configurato alla fine, quando l’esecuzione è partita da un override.

1. Risolve il modello di sessione attivo e la preferenza del profilo di autenticazione.
2. Costruisce la catena dei candidati modello.
3. Prova il provider corrente con le regole di rotazione/cooldown del profilo di autenticazione.
4. Se quel provider è esaurito con un errore che giustifica il failover, passa al candidato modello successivo.
5. Rende persistente l’override di fallback selezionato prima che inizi il retry, in modo che altri lettori della sessione vedano lo stesso provider/modello che il runner sta per usare.
6. Se il candidato di fallback fallisce, esegue il rollback solo dei campi di override della sessione posseduti dal fallback quando corrispondono ancora a quel candidato fallito.
7. Se tutti i candidati falliscono, genera un FallbackSummaryError con dettagli per tentativo e la scadenza di cooldown più vicina quando è nota.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Archiviazione dell’autenticazione (chiavi + OAuth)

• I segreti sono archiviati in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legacy: ~/.openclaw/agent/auth-profiles.json).
• La configurazione auth.profiles / auth.order contiene solo metadati + instradamento (nessun segreto).
• File OAuth legacy solo per importazione: ~/.openclaw/credentials/oauth.json (importato in auth-profiles.json al primo utilizzo).

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

​

ID profilo

• Predefinito: provider:default quando non è disponibile alcuna email.
• OAuth con email: provider:<email> (ad esempio google-antigravity:user@gmail.com).

​

Ordine di rotazione

1. Configurazione esplicita: auth.order[provider] (se impostata).
2. Profili configurati: auth.profiles filtrati per provider.
3. Profili archiviati: voci in auth-profiles.json per il provider.

• Chiave primaria: tipo di profilo (OAuth prima delle chiavi API).
• Chiave secondaria: usageStats.lastUsed (meno recente per primo, all’interno di ciascun tipo).
• I profili in cooldown/disabilitati vengono spostati in fondo, ordinati per scadenza più vicina.

​

Persistenza di sessione (favorevole alla cache)

• la sessione non viene reimpostata (/new / /reset)
• non viene completata una compattazione (il conteggio di compattazione incrementa)
• il profilo non entra in cooldown/non viene disabilitato

​

Perché OAuth può “sembrare perso”

• Bloccalo con auth.order[provider] = ["provider:profileId"], oppure
• Usa un override per sessione tramite /model … con un override del profilo (quando supportato dalla tua UI/superficie chat).

​

Cooldown

• OpenClaw registra cooldownModel per i fallimenti da rate limit quando l’ID del modello che ha fallito è noto.
• Un modello fratello sullo stesso provider può ancora essere provato quando il cooldown è limitato a un modello diverso.
• Le finestre di billing/disabilitazione continuano invece a bloccare l’intero profilo su tutti i modelli.

• 1 minuto
• 5 minuti
• 25 minuti
• 1 ora (limite massimo)

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

​

Disabilitazioni per billing

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

• Il backoff di billing parte da 5 ore, raddoppia a ogni errore di billing e ha un limite massimo di 24 ore.
• I contatori di backoff si azzerano se il profilo non fallisce per 24 ore (configurabile).
• I retry per overload consentono 1 rotazione dello stesso provider su un altro profilo prima del fallback del modello.
• I retry per overload usano per impostazione predefinita un backoff di 0 ms.

​

Fallback del modello

​

Regole della catena di candidati

• Il modello richiesto è sempre il primo.
• I fallback esplicitamente configurati vengono deduplicati ma non filtrati dalla allowlist dei modelli. Sono trattati come un’esplicita intenzione dell’operatore.
• Se l’esecuzione corrente è già su un fallback configurato nella stessa famiglia di provider, OpenClaw continua a usare l’intera catena configurata.
• Se l’esecuzione corrente è su un provider diverso dalla configurazione e quel modello corrente non fa già parte della catena di fallback configurata, OpenClaw non aggiunge fallback configurati non correlati da un altro provider.
• Quando l’esecuzione è partita da un override, il primario configurato viene aggiunto alla fine in modo che la catena possa tornare al normale valore predefinito una volta esauriti i candidati precedenti.

​

Quali errori fanno avanzare il fallback

• errori di autenticazione
• rate limit ed esaurimento del cooldown
• errori di overload/provider occupato
• errori di failover con forma di timeout
• disabilitazioni per billing
• LiveSessionModelSwitchError, che viene normalizzato in un percorso di failover così che un modello persistente obsoleto non crei un ciclo di retry esterno
• altri errori non riconosciuti quando ci sono ancora candidati rimanenti

• interruzioni esplicite che non hanno forma di timeout/failover
• errori di overflow del contesto che devono restare nella logica di compattazione/retry (ad esempio 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 o ollama error: context length exceeded)
• un errore finale sconosciuto quando non restano candidati

​

Comportamento di salto del cooldown vs probe

• I fallimenti persistenti di autenticazione saltano immediatamente l’intero provider.
• Le disabilitazioni per billing di solito vengono saltate, ma il candidato primario può ancora essere sondato con una limitazione di frequenza, in modo che il recupero sia possibile senza riavviare.
• Il candidato primario può essere sondato vicino alla scadenza del cooldown, con una limitazione per provider.
• I modelli fratelli di fallback sullo stesso provider possono essere provati nonostante il cooldown quando il guasto sembra transitorio (rate_limit, overloaded o sconosciuto). Questo è particolarmente rilevante quando un rate limit è limitato al modello e un modello fratello può ancora recuperare immediatamente.
• I probe di cooldown transitori sono limitati a uno per provider per esecuzione di fallback, così che un singolo provider non blocchi il fallback tra provider diversi.

​

Override di sessione e live model switching

• Solo le modifiche esplicite al modello guidate dall’utente contrassegnano un pending live switch. Questo include /model, session_status(model=...) e sessions.patch.
• Le modifiche al modello guidate dal sistema come rotazione di fallback, override heartbeat o compattazione non contrassegnano mai da sole un pending live switch.
• Prima che inizi un retry di fallback, il reply runner rende persistenti i campi di override del fallback selezionato nella voce di sessione.
• La riconciliazione della sessione live preferisce gli override persistenti della sessione rispetto ai campi runtime del modello obsoleti.
• Se il tentativo di fallback fallisce, il runner esegue il rollback solo dei campi di override che ha scritto, e solo se corrispondono ancora a quel candidato fallito.

1. Il primario fallisce.
2. Il candidato di fallback viene scelto in memoria.
3. L’archivio della sessione dice ancora il vecchio primario.
4. La riconciliazione della sessione live legge lo stato obsoleto della sessione.
5. Il retry viene riportato al vecchio modello prima che inizi il tentativo di fallback.

​

Osservabilità e riepiloghi dei guasti

• provider/modello tentato
• motivo (rate_limit, overloaded, billing, auth, model_not_found e motivi di failover simili)
• stato/codice facoltativo
• riepilogo dell’errore leggibile da umani

• i rate limit limitati a un modello ma non correlati vengono ignorati per la catena provider/modello tentata
• se il blocco rimanente è un rate limit limitato a un modello corrispondente, OpenClaw segnala l’ultima scadenza corrispondente che continua a bloccare quel modello

​

Configurazione correlata

• 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