Concepts and configuration

Failover del modello

OpenClaw gestisce gli errori in due fasi:

Rotazione dei profili di autenticazione all'interno del provider corrente.
Fallback del modello al modello successivo in agents.defaults.model.fallbacks.

Questo documento spiega le regole di runtime e i dati che le supportano.

Flusso di runtime

Per una normale esecuzione di testo, OpenClaw valuta i candidati in questo ordine:

Resolve session state

Risolve il modello della sessione attiva e la preferenza del profilo di autenticazione.

Build candidate chain

Costruisce la catena dei modelli candidati dalla selezione del modello corrente e dalla policy di fallback per quella fonte di selezione. I default configurati, i primari dei processi cron e i modelli di fallback selezionati automaticamente possono usare i fallback configurati; le selezioni esplicite della sessione utente sono rigide.

Try the current provider

Prova il provider corrente con le regole di rotazione/cooldown dei profili di autenticazione.

Advance on failover-worthy errors

Se quel provider è esaurito con un errore che giustifica il failover, passa al modello candidato successivo.

Persist fallback override

Persiste l'override di fallback selezionato prima dell'inizio del nuovo tentativo, così gli altri lettori della sessione vedono lo stesso provider/modello che il runner sta per usare. L'override del modello persistito è contrassegnato con modelOverrideSource: "auto".

Roll back narrowly on failure

Se il candidato di fallback fallisce, ripristina solo i campi di override della sessione di proprietà del fallback quando corrispondono ancora a quel candidato fallito.

Throw FallbackSummaryError if exhausted

Se tutti i candidati falliscono, genera un FallbackSummaryError con il dettaglio per tentativo e la scadenza di cooldown più vicina quando è nota.

Questo è intenzionalmente più ristretto di "salvare e ripristinare l'intera sessione". Il reply runner persiste solo i campi di selezione del modello che possiede per il fallback:

providerOverride
modelOverride
modelOverrideSource
authProfileOverride
authProfileOverrideSource
authProfileOverrideCompactionCount

Questo impedisce a un nuovo tentativo di fallback fallito di sovrascrivere mutazioni di sessione più recenti e non correlate, come modifiche manuali con /model o aggiornamenti della rotazione della sessione avvenuti mentre il tentativo era in esecuzione.

Policy della fonte di selezione

OpenClaw separa il provider/modello selezionato dal motivo per cui è stato selezionato. Quella fonte controlla se la catena di fallback è consentita:

Default configurato: agents.defaults.model.primary usa agents.defaults.model.fallbacks.
Primario dell'agente: agents.list[].model è rigido a meno che l'oggetto modello di quell'agente includa i propri fallbacks. Usa fallbacks: [] per rendere esplicito il comportamento rigido, oppure fornisci un elenco non vuoto per abilitare il fallback del modello per quell'agente.
Override di fallback automatico: un fallback di runtime scrive providerOverride, modelOverride, modelOverrideSource: "auto" e il modello di origine selezionato prima di riprovare. Quell'override automatico può continuare a percorrere la catena di fallback configurata senza sondare il primario a ogni messaggio, ma OpenClaw sonda periodicamente di nuovo l'origine configurata e cancella l'override automatico quando si ripristina. Anche /new, /reset e sessions.reset cancellano gli override provenienti da auto. Le esecuzioni Heartbeat senza un heartbeat.model esplicito cancellano gli override automatici diretti quando la loro origine non corrisponde più al default configurato corrente.
Override della sessione utente: /model, il selettore del modello, session_status(model=...) e sessions.patch scrivono modelOverrideSource: "user". Questa è una selezione esatta della sessione. Se il provider/modello selezionato fallisce prima di produrre una risposta, OpenClaw segnala l'errore invece di rispondere da un fallback configurato non correlato.
Override della sessione legacy: le voci di sessione più vecchie possono avere modelOverride senza modelOverrideSource. OpenClaw le tratta come override utente, così una vecchia selezione esplicita non viene convertita silenziosamente in comportamento di fallback.
Modello del payload Cron: un payload.model / --model di un processo cron è un primario del job, non un override della sessione utente. Usa i fallback configurati a meno che il job fornisca payload.fallbacks; payload.fallbacks: [] rende rigida l'esecuzione cron.

L'intervallo di sondaggio del primario per il fallback automatico è di cinque minuti e non è configurabile. OpenClaw ricorda i sondaggi recenti per sessione e modello primario, così un primario in errore non viene riprovato a ogni turno. OpenClaw invia un avviso visibile quando una sessione passa al fallback e un altro avviso quando torna al primario selezionato; non ripete l'avviso a ogni turno di fallback persistente.

Cache di salto degli errori di autenticazione

Per impostazione predefinita, ogni nuovo turno mantiene il comportamento esistente di nuovo tentativo del fallback: OpenClaw proverà di nuovo ogni candidato di fallback configurato, inclusi i candidati non primari che di recente hanno fallito con auth o auth_permanent.

Gli operatori che preferiscono sopprimere questi errori di autenticazione ripetuti possono abilitarlo con:

bash

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Quando abilitato, OpenClaw registra un marcatore di salto in memoria, con ambito di sessione, per un candidato di fallback non primario dopo un errore di classe auth. Il marcatore è indicizzato per id sessione, provider e modello. I candidati primari non vengono mai saltati, quindi una selezione esplicita del modello utente mostra comunque il vero errore di autenticazione. La cache è locale al processo e viene cancellata al riavvio del Gateway.

Il valore è un TTL in millisecondi. 0 o un valore non impostato disabilita la cache. I valori positivi sono limitati tra 1 secondo e 10 minuti.

Avvisi di fallback visibili all'utente

Quando una sessione passa a un fallback selezionato automaticamente, OpenClaw invia un avviso di stato nella stessa superficie di risposta:

text

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

Quando un sondaggio successivo riesce e la sessione torna al primario selezionato, OpenClaw invia:

text

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

Questi avvisi sono messaggi operativi, non contenuto dell'assistente. Vengono consegnati una volta per cambio di stato, inclusi i turni con soli effetti collaterali quando possibile, ma i turni di fallback persistente non li ripetono. La consegna aggira la normale soppressione della risposta alla fonte, l'avviso non consuma il primo slot di risposta dell'assistente per i canali con thread ed è escluso dalla sintesi vocale e dall'estrazione degli impegni.

Archiviazione dell'autenticazione (chiavi + OAuth)

OpenClaw usa profili di autenticazione sia per le chiavi API sia per i token OAuth.

I segreti e lo stato di routing dell'autenticazione di runtime vivono in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
La configurazione auth.profiles / auth.order è solo metadati + routing (nessun segreto).
File OAuth legacy solo importazione: ~/.openclaw/credentials/oauth.json (importato nello store di autenticazione per agente al primo utilizzo).
I file legacy auth-profiles.json, auth-state.json e auth.json per agente vengono importati da openclaw doctor --fix.

Maggiori dettagli: OAuth

Tipi di credenziali:

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

ID dei profili

Gli accessi OAuth creano profili distinti, così più account possono coesistere.

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

I profili vivono nello store dei profili di autenticazione openclaw-agent.sqlite per agente.

Ordine di rotazione

Quando un provider ha più profili, OpenClaw sceglie un ordine come questo:

Explicit config

auth.order[provider] (se impostato).

Configured profiles

auth.profiles filtrati per provider.

Stored profiles

Voci dei profili di autenticazione SQLite per agente per il provider.

Se non è configurato alcun ordine esplicito, OpenClaw usa un ordine round-robin:

Chiave primaria: tipo di profilo (OAuth prima delle chiavi API).
Chiave secondaria: usageStats.lastUsed (prima il più vecchio, all'interno di ogni tipo).
Profili in cooldown/disabilitati vengono spostati alla fine, ordinati per scadenza più vicina.

Persistenza della sessione (compatibile con la cache)

OpenClaw blocca il profilo di autenticazione scelto per sessione per mantenere calde le cache del provider. Non ruota a ogni richiesta. Il profilo bloccato viene riutilizzato finché:

la sessione viene reimpostata (/new / /reset)
una compaction si completa (il conteggio della compaction aumenta)
il profilo è in cooldown/disabilitato

La selezione manuale tramite /model …@<profileId> imposta un override utente per quella sessione e non viene ruotata automaticamente finché non inizia una nuova sessione.

Abbonamento OpenAI Codex più backup con chiave API

Per i modelli agente OpenAI, autenticazione e runtime sono separati. openai/gpt-* resta sul harness Codex mentre l'autenticazione può ruotare tra un profilo di abbonamento Codex e un backup con chiave API OpenAI.

Usa auth.order.openai per l'ordine visibile all'utente:

json5

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

Usa openai:* sia per i profili OAuth ChatGPT/Codex sia per i profili con chiave API OpenAI. Quando l'abbonamento raggiunge un limite di utilizzo Codex, OpenClaw registra l'ora esatta di reset quando Codex ne fornisce una, prova il profilo di autenticazione ordinato successivo e mantiene l'esecuzione all'interno dell'harness Codex. Una volta superata l'ora di reset, il profilo di abbonamento torna idoneo e la selezione automatica successiva può tornare a esso.

Usa un profilo bloccato dall'utente solo quando vuoi forzare un account/una chiave per quella sessione. I profili bloccati dall'utente sono intenzionalmente rigidi e non passano silenziosamente a un altro profilo.

Cooldown

Quando un profilo fallisce a causa di errori di autenticazione/rate-limit (o di un timeout che sembra un rate limiting), OpenClaw lo contrassegna in cooldown e passa al profilo successivo.

What lands in the rate-limit / timeout bucket

Quel bucket rate-limit è più ampio di un semplice 429: include anche messaggi dei provider come Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, throttled, resource exhausted e limiti periodici della finestra di utilizzo come weekly/monthly limit reached.

Gli errori di formato/richiesta non valida sono di solito terminali perché riprovare lo stesso payload fallirebbe nello stesso modo, quindi OpenClaw li mostra invece di ruotare i profili di autenticazione. I percorsi noti di retry-repair possono abilitarlo esplicitamente: per esempio gli errori di convalida dell'ID di chiamata tool di Cloud Code Assist vengono sanificati e riprovati una volta tramite la policy allowFormatRetry. Gli errori di motivo di stop compatibili con OpenAI, come Unhandled stop reason: error, stop reason: error e reason: error, sono classificati come segnali di timeout/failover.

Anche testo server generico può finire in quel bucket di timeout quando la fonte corrisponde a un pattern transitorio noto. Per esempio, il messaggio nudo del wrapper di stream del runtime del modello An unknown error occurred è trattato come idoneo al failover per ogni provider perché il runtime del modello condiviso lo emette quando gli stream del provider terminano con stopReason: "aborted" o stopReason: "error" senza dettagli specifici. Anche i payload JSON api_error con testo server transitorio come internal server error, unknown error, 520, upstream error o backend error sono trattati come timeout idonei al failover.

Il testo upstream generico specifico di OpenRouter, come il semplice Provider returned error, è trattato come timeout solo quando il contesto del provider è effettivamente OpenRouter. Il testo di fallback interno generico, come LLM request failed with an unknown error., resta conservativo e da solo non attiva il failover.

Limiti retry-after dell'SDK

Alcuni SDK dei provider potrebbero altrimenti attendere per una lunga finestra Retry-After prima di restituire il controllo a OpenClaw. Per gli SDK basati su Stainless, come Anthropic e OpenAI, OpenClaw limita per impostazione predefinita a 60 secondi le attese interne all'SDK retry-after-ms / retry-after e rende immediatamente visibili le risposte riprovabili più lunghe, così questo percorso di failover può essere eseguito. Regola o disabilita il limite con OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS; vedi Comportamento dei tentativi.

Cooldown con ambito modello

I cooldown per limite di frequenza possono anche avere ambito modello:

OpenClaw registra cooldownModel per gli errori di limite di frequenza quando l'id del modello che fallisce è noto.
Un modello correlato dello stesso provider può ancora essere provato quando il cooldown è limitato a un modello diverso.
Le finestre di fatturazione/disabilitazione bloccano comunque l'intero profilo tra i modelli.

I cooldown usano backoff esponenziale:

1 minuto
5 minuti
25 minuti
1 ora (limite)

Lo stato è archiviato nello stato di autenticazione SQLite per agente sotto usageStats:

json

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

Disabilitazioni di fatturazione

Gli errori di fatturazione/credito (per esempio "insufficient credits" / "credit balance too low") sono trattati come idonei al failover, ma di solito non sono transitori. Invece di un breve cooldown, OpenClaw contrassegna il profilo come disabilitato (con un backoff più lungo) e passa al profilo/provider successivo.

Lo stato è archiviato nello stato di autenticazione SQLite per agente:

json

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

Impostazioni predefinite:

Il backoff di fatturazione parte da 5 ore, raddoppia a ogni errore di fatturazione e ha un limite di 24 ore.
I contatori di backoff si azzerano se il profilo non ha avuto errori per 24 ore (configurabile).
I tentativi per sovraccarico consentono 1 rotazione di profilo dello stesso provider prima del fallback del modello.
I tentativi per sovraccarico usano per impostazione predefinita un backoff di 0 ms.

Fallback del modello

Se tutti i profili di un provider falliscono, OpenClaw passa al modello successivo in agents.defaults.model.fallbacks. Questo si applica a errori di autenticazione, limiti di frequenza e timeout che hanno esaurito la rotazione dei profili (altri errori non fanno avanzare il fallback). Gli errori del provider che non espongono dettagli sufficienti sono comunque etichettati con precisione nello stato di fallback: empty_response significa che il provider non ha restituito alcun messaggio o stato utilizzabile, no_error_details significa che il provider ha restituito esplicitamente Unknown error (no error details in response), e unclassified significa che OpenClaw ha conservato l'anteprima grezza ma nessun classificatore l'ha ancora riconosciuta.

Gli errori di sovraccarico e limite di frequenza sono gestiti in modo più aggressivo rispetto ai cooldown di fatturazione. Per impostazione predefinita, OpenClaw consente un tentativo con profilo di autenticazione dello stesso provider, poi passa al fallback del modello configurato successivo senza attendere. I segnali di provider occupato, come ModelNotReadyException, finiscono in quel gruppo di sovraccarico. Regola questo comportamento con auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs e auth.cooldowns.rateLimitedProfileRotations.

Quando un'esecuzione parte dal primario predefinito configurato, da un primario di un job cron, da un primario dell'agente con fallback espliciti o da un override di fallback selezionato automaticamente, OpenClaw può percorrere la catena di fallback configurata corrispondente. I primari dell'agente senza fallback espliciti e le selezioni utente esplicite (per esempio /model ollama/qwen3.5:27b, il selettore di modello, sessions.patch o override provider/modello CLI una tantum) sono rigorosi: se quel provider/modello non è raggiungibile o fallisce prima di produrre una risposta, OpenClaw segnala l'errore invece di rispondere da un fallback non correlato.

Regole della catena dei candidati

OpenClaw costruisce l'elenco dei candidati dal provider/model attualmente richiesto più i fallback configurati.

Regole

Il modello richiesto è sempre il primo.
I fallback configurati espliciti vengono deduplicati ma non filtrati dalla allowlist dei modelli. Sono trattati come intento esplicito dell'operatore.
Se l'esecuzione corrente è già su un fallback configurato nella stessa famiglia di provider, OpenClaw continua a usare l'intera catena configurata.
Quando non viene fornito alcun override di fallback esplicito, i fallback configurati vengono provati prima del primario configurato anche se il modello richiesto usa un provider diverso.
Quando non viene fornito alcun override di fallback esplicito al runner di fallback, il primario configurato viene aggiunto alla fine, così la catena può tornare al valore predefinito normale una volta esauriti i candidati precedenti.
Quando un chiamante fornisce fallbacksOverride, il runner usa esattamente il modello richiesto più quell'elenco di override. Un elenco vuoto disabilita il fallback del modello e impedisce che il primario configurato venga aggiunto come destinazione di tentativo nascosta.

Quali errori fanno avanzare il fallback

Continua con

errori di autenticazione
limiti di frequenza ed esaurimento del cooldown
errori di sovraccarico/provider occupato
errori di failover con forma di timeout
disabilitazioni di fatturazione
LiveSessionModelSwitchError, che viene normalizzato in un percorso di failover così un modello persistito obsoleto non crea un ciclo di retry esterno
altri errori non riconosciuti quando ci sono ancora candidati rimanenti

Non continua con

interruzioni esplicite che non hanno forma di timeout/failover
errori di overflow del contesto che devono restare nella logica di compaction/retry (per 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 sconosciuto finale quando non restano candidati
rifiuti di sicurezza di Claude Fable 5; le richieste dirette con chiave API li gestiscono invece a livello di provider tramite il fallback lato server di Anthropic a claude-opus-4-8 (vedi Anthropic)

Salto del cooldown rispetto al comportamento di probe

Quando ogni profilo di autenticazione per un provider è già in cooldown, OpenClaw non salta automaticamente quel provider per sempre. Prende una decisione per ciascun candidato:

Decisioni per candidato

Gli errori di autenticazione persistenti saltano immediatamente l'intero provider.
Le disabilitazioni di fatturazione di solito saltano, ma il candidato primario può comunque essere sondato con throttling, così il recupero è possibile senza riavviare.
Il candidato primario può essere sondato vicino alla scadenza del cooldown, con throttling per provider.
I fallback correlati dello stesso provider possono essere tentati nonostante il cooldown quando l'errore sembra transitorio (rate_limit, overloaded o sconosciuto). Questo è particolarmente rilevante quando un limite di frequenza ha ambito modello e un modello correlato potrebbe comunque recuperare immediatamente.
I probe di cooldown transitorio sono limitati a uno per provider per esecuzione di fallback, così un singolo provider non blocca il fallback tra provider.

Override di sessione e cambio modello live

Le modifiche al modello di sessione sono stato condiviso. Il runner attivo, il comando /model, gli aggiornamenti di compaction/sessione e la riconciliazione della sessione live leggono o scrivono tutti parti della stessa voce di sessione.

Questo significa che i tentativi di fallback devono coordinarsi con il cambio modello live:

Solo le modifiche del modello esplicitamente guidate dall'utente contrassegnano un cambio live in sospeso. Questo include /model, session_status(model=...) e sessions.patch.
Le modifiche del modello guidate dal sistema, come la rotazione di fallback, gli override di heartbeat o la compaction, non contrassegnano mai da sole un cambio live in sospeso.
Gli override del modello guidati dall'utente sono trattati come selezioni esatte per la policy di fallback, quindi un provider selezionato non raggiungibile viene mostrato come errore invece di essere mascherato da agents.defaults.model.fallbacks.
Prima che inizi un tentativo di fallback, il runner di risposta persiste i campi di override di fallback selezionati nella voce di sessione.
Gli override di fallback automatici restano selezionati nei turni successivi, così OpenClaw non sonda un primario già noto come non funzionante a ogni messaggio. OpenClaw sonda periodicamente di nuovo l'origine configurata e cancella l'override automatico quando recupera; /new, /reset e sessions.reset cancellano immediatamente gli override di origine automatica.
Le risposte all'utente annunciano le transizioni di fallback e il recupero con fallback cancellato una volta per cambio di stato. I turni con fallback persistente non ripetono l'avviso.
/status mostra il modello selezionato e, quando lo stato di fallback differisce, il modello di fallback attivo e il motivo.
La riconciliazione della sessione live preferisce gli override di sessione persistiti rispetto ai campi modello runtime obsoleti.
Se un errore di cambio live punta a un candidato successivo nella catena di fallback attiva, OpenClaw salta direttamente a quel modello selezionato invece di percorrere prima candidati non correlati.
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.

Questo evita la classica condizione di race:

Il primario fallisce

Il modello primario selezionato fallisce.

Fallback scelto in memoria

Il candidato di fallback viene scelto in memoria.

L'archivio sessioni indica ancora il vecchio primario

L'archivio sessioni riflette ancora il vecchio primario.

La riconciliazione live legge uno stato obsoleto

La riconciliazione della sessione live legge lo stato di sessione obsoleto.

Il retry viene riportato indietro

Il retry viene riportato al vecchio modello prima che inizi il tentativo di fallback.

L'override di fallback persistito chiude quella finestra, e il rollback ristretto mantiene intatte le modifiche manuali o runtime più recenti alla sessione.

Osservabilità e riepiloghi degli errori

runWithModelFallback(...) registra dettagli per tentativo che alimentano i log e i messaggi di cooldown rivolti all'utente:

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

I log strutturati model_fallback_decision includono anche campi piatti fallbackStep* quando un candidato fallisce, viene saltato o un fallback successivo riesce. Questi campi rendono esplicita la transizione tentata (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), così gli esportatori di log e diagnostica possono ricostruire l'errore primario anche quando fallisce anche il fallback terminale.

Quando ogni candidato fallisce, OpenClaw genera FallbackSummaryError. Il runner di risposta esterno può usarlo per costruire un messaggio più specifico, come "tutti i modelli sono temporaneamente soggetti a limite di frequenza", e includere la scadenza del cooldown più vicina quando è nota.

Quel riepilogo del cooldown è consapevole del modello:

i limiti di frequenza con ambito modello non correlati vengono ignorati per la catena provider/modello tentata
se il blocco rimanente è un limite di frequenza con ambito modello corrispondente, OpenClaw segnala l'ultima scadenza corrispondente che blocca ancora quel modello

Configurazione correlata

Vedi Configurazione del Gateway per:

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
routing agents.defaults.imageModel

Consulta Modelli per la panoramica più ampia sulla selezione del modello e sui fallback.

Was this useful?