​

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 è iniziata da una sostituzione.

1. Risolvere il modello di sessione attivo e la preferenza del profilo di autenticazione.
2. Costruire la catena dei candidati modello.
3. Provare 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, passare al candidato modello successivo.
5. Rendere persistente la sostituzione di fallback selezionata prima che inizi il nuovo tentativo, in modo che gli altri lettori della sessione vedano lo stesso provider/modello che il runner sta per usare.
6. Se il candidato di fallback fallisce, ripristinare solo i campi di sostituzione della sessione di proprietà del fallback quando corrispondono ancora a quel candidato fallito.
7. Se ogni candidato fallisce, generare un FallbackSummaryError con i dettagli per tentativo e la scadenza del cooldown più vicina quando è nota.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Archiviazione dell’autenticazione (chiavi + OAuth)

• I secret si trovano in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legacy: ~/.openclaw/agent/auth-profiles.json).
• Lo stato di instradamento dell’autenticazione a runtime si trova in ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• La config auth.profiles / auth.order contiene solo metadati + instradamento (nessun secret).
• 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. Config esplicita: auth.order[provider] (se impostato).
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 ogni tipo).
• I profili in cooldown/disabilitati vengono spostati alla fine, ordinati per scadenza più vicina.

​

Affinità di sessione (favorevole alla cache)

• la sessione non viene reimpostata (/new / /reset)
• viene completata una compattazione (il conteggio della compattazione aumenta)
• il profilo è in cooldown/disabilitato

​

Perché OAuth può “sembrare perso”

• Blocca con auth.order[provider] = ["provider:profileId"], oppure
• Usa una sostituzione per sessione tramite /model … con una sostituzione di profilo (quando supportata dalla tua UI/superficie chat).

​

Cooldown

• OpenClaw registra cooldownModel per gli errori di limite di frequenza quando il modello che ha fallito è noto.
• Un modello correlato sullo stesso provider può comunque essere provato quando il cooldown è limitato a un modello diverso.
• Le finestre di fatturazione/disabilitazione continuano comunque a bloccare l’intero profilo su tutti i modelli.

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

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

​

Disabilitazioni per fatturazione

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

• Il backoff per fatturazione parte da 5 ore, raddoppia a ogni errore di fatturazione e ha un massimo di 24 ore.
• I contatori di backoff si azzerano se il profilo non ha fallito per 24 ore (configurabile).
• I retry per stato overloaded consentono 1 rotazione dello stesso provider tra profili prima del fallback del modello.
• I retry per stato overloaded 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 configurati espliciti vengono deduplicati ma non filtrati in base alla allowlist dei modelli. Sono trattati come intenzione esplicita 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 config e quel modello corrente non fa già parte della catena di fallback configurata, OpenClaw non aggiunge fallback configurati non correlati di un altro provider.
• Quando l’esecuzione è iniziata da una sostituzione, il modello 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
• limiti di frequenza ed esaurimento del cooldown
• errori overloaded/provider occupato
• errori di failover con forma di timeout
• disabilitazioni per fatturazione
• LiveSessionModelSwitchError, che viene normalizzato in un percorso di failover in modo che un modello persistente non aggiornato 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 all’interno della 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 più candidati

​

Comportamento di salto per cooldown rispetto al sondaggio

• Gli errori di autenticazione persistenti saltano immediatamente l’intero provider.
• Le disabilitazioni per fatturazione di solito saltano, ma il candidato primario può comunque essere sondato con limitazione, così da consentire il recupero senza riavviare.
• Il candidato primario può essere sondato vicino alla scadenza del cooldown, con una limitazione per provider.
• I modelli correlati di fallback sullo stesso provider possono essere provati nonostante il cooldown quando il fallimento sembra transitorio (rate_limit, overloaded o sconosciuto). Questo è particolarmente rilevante quando un limite di frequenza è limitato al modello e un modello correlato può ancora recuperare immediatamente.
• I sondaggi di cooldown transitori sono limitati a uno per provider per esecuzione di fallback, così un singolo provider non blocca il fallback tra provider.

​

Sostituzioni di sessione e cambio modello live

• Solo le modifiche di modello esplicite guidate dall’utente contrassegnano un cambio live in sospeso. Questo include /model, session_status(model=...) e sessions.patch.
• Le modifiche di modello guidate dal sistema come rotazione di fallback, sostituzioni heartbeat o compattazione non contrassegnano mai da sole un cambio live in sospeso.
• Prima che inizi un retry di fallback, il runner della risposta rende persistenti i campi di sostituzione del fallback selezionato nella voce di sessione.
• La riconciliazione della sessione live privilegia le sostituzioni persistenti della sessione rispetto a campi di modello runtime non aggiornati.
• Se il tentativo di fallback fallisce, il runner ripristina solo i campi di sostituzione 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 indica ancora il vecchio primario.
4. La riconciliazione della sessione live legge lo stato obsoleto della sessione.
5. Il retry torna al vecchio modello prima che inizi il tentativo di fallback.

​

Osservabilità e riepiloghi degli errori

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

• i limiti di frequenza limitati a modelli non correlati vengono ignorati per la catena provider/modello tentata
• se il blocco rimanente è un limite di frequenza limitato al modello corrispondente, OpenClaw riporta l’ultima scadenza corrispondente che blocca ancora quel modello

​

Config 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
• instradamento di agents.defaults.imageModel