Failover del modello

OpenClaw gestisce gli errori in due fasi:

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 esecuzione

Questo comportamento è intenzionalmente più circoscritto rispetto a «salvare e ripristinare l'intera sessione». L'esecutore delle risposte salva soltanto i campi di selezione del modello che gestisce per il fallback: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Ciò impedisce che un tentativo di fallback non riuscito sovrascriva modifiche della sessione più recenti e non correlate, come una modifica manuale tramite /model o un aggiornamento della rotazione della sessione avvenuto durante il tentativo.

Criteri relativi all'origine della selezione

L'origine della selezione determina se la catena di fallback è consentita:

• Impostazione predefinita configurata: agents.defaults.model.primary usa agents.defaults.model.fallbacks.
• Modello primario dell'agente: agents.list[].model è rigido, a meno che l'oggetto del modello dell'agente non includa i propri fallbacks. Usa fallbacks: [] per rendere esplicito il comportamento rigido oppure un elenco non vuoto per abilitare il fallback del modello per tale agente.
• Override di fallback automatico: prima di riprovare, un fallback in fase di esecuzione scrive providerOverride, modelOverride, modelOverrideSource: "auto" e il modello di origine selezionato. Questo override continua a percorrere la catena di fallback configurata senza verificare il modello primario a ogni messaggio, ma OpenClaw verifica l'origine configurata ogni 5 minuti (intervallo non configurabile) e rimuove l'override quando questa torna disponibile. Anche /new, /reset e sessions.reset rimuovono gli override di origine automatica. Le esecuzioni Heartbeat prive di un heartbeat.model esplicito rimuovono gli override automatici diretti quando la loro origine non corrisponde più all'impostazione predefinita configurata corrente.
• Override della sessione utente: /model, il selettore del modello, session_status(model=...) e sessions.patch scrivono modelOverrideSource: "user". Si tratta di una selezione esatta per la sessione. Se il provider o il modello selezionato non riesce prima di produrre una risposta, OpenClaw segnala l'errore anziché rispondere usando un fallback configurato non correlato.
• Override di sessione precedente: le voci di sessione meno recenti possono contenere modelOverride senza modelOverrideSource. OpenClaw le considera override utente, affinché una vecchia selezione esplicita non venga convertita silenziosamente in un comportamento di fallback.
• Modello del payload Cron: il payload.model / --model di un processo Cron è il modello primario del processo, non un override della sessione utente. Usa i fallback configurati, a meno che il processo non fornisca payload.fallbacks; payload.fallbacks: [] rende rigida l'esecuzione Cron.

OpenClaw memorizza per ogni sessione e modello primario le verifiche recenti del modello primario, in modo che un modello primario non funzionante non venga riprovato a ogni interazione. Invia un avviso visibile quando una sessione passa al fallback e un altro avviso quando torna al modello primario selezionato; non ripete l'avviso a ogni interazione che continua a usare lo stesso fallback.

Cache per ignorare gli errori di autenticazione

Per impostazione predefinita, ogni nuova interazione mantiene il comportamento esistente per i nuovi tentativi di fallback: OpenClaw riprova ogni candidato di fallback configurato, inclusi i candidati non primari che recentemente hanno restituito un errore auth o auth_permanent.

Per evitare la ripetizione degli errori di autenticazione, abilita:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Quando questa opzione è abilitata, dopo un errore di autenticazione OpenClaw registra in memoria un indicatore di esclusione limitato alla sessione per il candidato di fallback non primario, identificato dall'ID della sessione, dal provider e dal modello. I candidati primari non vengono mai ignorati, quindi una selezione esplicita del modello da parte dell'utente continua a mostrare il reale errore di autenticazione. La cache è locale al processo e viene svuotata al riavvio del Gateway.

Il valore è un TTL espresso in millisecondi. 0 o l'assenza del valore disabilitano la cache. I valori positivi vengono limitati a un intervallo compreso 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:

↪️ Fallback del modello: <fallback> (selezionato <primary>; <reason>)

Quando una verifica successiva riesce e la sessione torna al modello primario selezionato, OpenClaw invia:

↪️ Fallback del modello rimosso: <primary> (in precedenza <fallback>)

Questi avvisi sono messaggi operativi, non contenuti dell'assistente. Vengono inviati una volta per ogni cambiamento di stato, incluse, quando possibile, le interazioni che producono soltanto effetti collaterali, ma non vengono ripetuti nelle interazioni che continuano a usare lo stesso fallback. L'invio aggira la normale soppressione delle risposte all'origine, non occupa il primo spazio di risposta dell'assistente per i canali con conversazioni in 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 instradamento dell'autenticazione in fase di esecuzione risiedono in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Le configurazioni auth.profiles / auth.order contengono soltanto metadati e instradamento (nessun segreto).
• File OAuth precedente usato soltanto per l'importazione: ~/.openclaw/credentials/oauth.json (importato nell'archivio di autenticazione del singolo agente al primo utilizzo).
• I precedenti file auth-profiles.json, auth-state.json e i file auth.json dei singoli agenti vengono importati da openclaw doctor --fix.

Ulteriori dettagli: OAuth

Tipi di credenziali:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl per alcuni provider)
• type: "token" → token statico di tipo bearer, facoltativamente con scadenza; OpenClaw non lo rinnova (usato per aws-sdk e altre modalità di autenticazione basate su una catena di credenziali)

ID dei profili

Gli accessi OAuth creano profili distinti, in modo che possano coesistere più account.

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

I profili risiedono nell'archivio dei profili di autenticazione openclaw-agent.sqlite del singolo agente.

Ordine di rotazione

Quando un provider dispone di più profili, OpenClaw sceglie l'ordine nel modo seguente:

Se non è configurato alcun ordine esplicito, OpenClaw usa un ordine circolare:

• Chiave primaria: tipo di profilo (OAuth, quindi token statico, quindi chiave API).
• Chiave secondaria: usageStats.lastUsed (prima il meno recente, all'interno di ciascun tipo).
• I profili sospesi temporaneamente o disabilitati vengono spostati in fondo, ordinati in base alla scadenza più prossima.

Persistenza nella sessione (favorevole alla cache)

OpenClaw fissa il profilo di autenticazione scelto per ogni sessione per mantenere attive le cache del provider. Non effettua la rotazione a ogni richiesta. Il profilo fissato viene riutilizzato finché:

• la sessione non viene reimpostata (/new / /reset)
• non viene completata una Compaction (il conteggio delle Compaction aumenta)
• il profilo non viene sospeso temporaneamente o disabilitato

La selezione manuale tramite /model …@<profileId> imposta un override utente per tale sessione e non viene sottoposta a rotazione automatica fino all'avvio di una nuova sessione.

Abbonamento OpenAI Codex con chiave API di riserva

Per i modelli agente OpenAI, l'autenticazione e l'ambiente di esecuzione sono separati. openai/gpt-* rimane nell'infrastruttura Codex, mentre l'autenticazione può alternarsi tra un profilo di abbonamento Codex e una chiave API OpenAI di riserva.

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

{  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 di Codex, OpenClaw registra l'ora esatta di reimpostazione, se Codex la fornisce, prova il profilo di autenticazione successivo nell'ordine e mantiene l'esecuzione all'interno dell'infrastruttura Codex. Una volta trascorsa l'ora di reimpostazione, il profilo dell'abbonamento torna idoneo e la selezione automatica successiva può tornare a usarlo.

Usa un profilo fissato dall'utente soltanto quando vuoi imporre l'uso di uno specifico account o di una specifica chiave per tale sessione. I profili fissati dall'utente sono intenzionalmente rigidi e non passano silenziosamente a un altro profilo.

Sospensioni temporanee

Quando un profilo non riesce a causa di errori di autenticazione o di limite di frequenza (oppure per un timeout che sembra causato da un limite di frequenza), OpenClaw lo sospende temporaneamente e passa al profilo successivo.

I cooldown normali (non dovuti alla fatturazione o ad autenticazione permanentemente non valida) aumentano in base al numero di errori recenti del profilo:

• 1° errore: 30 secondi
• 2° errore: 1 minuto
• Dal 3° errore in poi: 5 minuti (limite massimo)

I contatori vengono reimpostati una volta trascorsa la finestra degli errori del profilo (auth.cooldowns.failureWindowHours, valore predefinito 24).

Lo stato viene archiviato nello stato di autenticazione SQLite specifico dell'agente, sotto usageStats:

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

Disabilitazioni per fatturazione

Gli errori di fatturazione/credito (ad esempio "crediti insufficienti" / "saldo del credito troppo basso") vengono considerati idonei al failover, ma in genere 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.

Gli errori permanenti di autenticazione con un elevato grado di certezza (chiavi revocate/disattivate, aree di lavoro disattivate) seguono un percorso di disabilitazione simile, ma vengono ripristinati molto prima rispetto agli errori di fatturazione, poiché durante gli incidenti alcuni provider possono restituire temporaneamente payload che sembrano errori di autenticazione.

Lo stato viene archiviato nello stato di autenticazione SQLite specifico dell'agente:

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

Valori predefiniti (auth.cooldowns.*):

Gli errori di sovraccarico e di limite di frequenza vengono gestiti in modo più aggressivo rispetto ai cooldown di fatturazione: per impostazione predefinita, OpenClaw consente un tentativo con un altro profilo di autenticazione dello stesso provider, quindi passa al fallback del modello configurato successivo senza attendere.

Fallback del modello

Se tutti i profili di un provider non riescono, OpenClaw passa al modello successivo in agents.defaults.model.fallbacks. Ciò si applica agli errori di autenticazione, ai limiti di frequenza e ai timeout che hanno esaurito la rotazione dei profili (gli altri errori non fanno avanzare il fallback). Gli errori del provider che non forniscono dettagli sufficienti vengono comunque etichettati con precisione nello stato del fallback: empty_response indica che il provider non ha restituito alcun messaggio o stato utilizzabile, no_error_details indica che il provider ha restituito esplicitamente Unknown error (no error details in response) e unclassified indica che OpenClaw ha conservato l'anteprima non elaborata, ma nessun classificatore ha ancora trovato una corrispondenza.

I segnali di provider occupato, come ModelNotReadyException, vengono inseriti nella categoria di sovraccarico e seguono la stessa politica di una rotazione seguita dal fallback applicata ai limiti di frequenza (consulta la tabella dei valori predefiniti precedente).

Quando un'esecuzione parte dal modello primario predefinito configurato, dal modello primario di un processo Cron, dal modello primario di un agente con fallback espliciti o da un override di fallback selezionato automaticamente, OpenClaw può percorrere la catena di fallback configurata corrispondente. I modelli primari degli agenti senza fallback espliciti e le selezioni esplicite dell'utente (ad esempio /model ollama/qwen3.5:27b, il selettore del modello, sessions.patch o gli override una tantum di provider/modello della CLI) sono rigorosi: se tale provider/modello non è raggiungibile o non riesce prima di produrre una risposta, OpenClaw segnala l'errore anziché rispondere usando un fallback non correlato.

Regole della catena dei candidati

OpenClaw crea l'elenco dei candidati a partire dal provider/model attualmente richiesto e dai fallback configurati.

Quali errori fanno avanzare il fallback

Differenza tra esclusione per cooldown e comportamento di verifica

Quando tutti i profili di autenticazione di un provider sono già in cooldown, OpenClaw non esclude automaticamente quel provider per sempre. Prende una decisione per ogni candidato:

Override di sessione e cambio del modello in tempo reale

Le modifiche al modello della sessione costituiscono uno stato condiviso. Il gestore attivo, il comando /model, gli aggiornamenti di Compaction/sessione e la riconciliazione della sessione in tempo reale leggono o scrivono tutti parti della stessa voce di sessione.

Ciò significa che i nuovi tentativi di fallback devono coordinarsi con il cambio del modello in tempo reale:

• Solo le modifiche esplicite del modello avviate dall'utente contrassegnano un cambio in tempo reale come in sospeso. Sono inclusi /model, session_status(model=...) e sessions.patch.
• Le modifiche del modello avviate dal sistema, come la rotazione del fallback, gli override di Heartbeat o la Compaction, non contrassegnano mai autonomamente un cambio in tempo reale come in sospeso.
• Gli override del modello avviati dall'utente vengono considerati selezioni esatte ai fini della politica di fallback, quindi un provider selezionato ma non raggiungibile viene segnalato come errore anziché essere mascherato da agents.defaults.model.fallbacks.
• Prima dell'avvio di un nuovo tentativo di fallback, il gestore delle risposte salva nella voce di sessione i campi di override del fallback selezionato.
• Gli override automatici del fallback rimangono selezionati nei turni successivi, affinché OpenClaw non verifichi un modello primario noto come non funzionante a ogni messaggio. OpenClaw verifica nuovamente e periodicamente l'origine configurata e cancella l'override automatico quando questa si ripristina; /new, /reset e sessions.reset cancellano immediatamente gli override di origine automatica.
• Le risposte all'utente segnalano le transizioni del fallback e il ripristino con cancellazione del fallback una volta per ogni modifica dello stato. I turni con fallback persistente non ripetono l'avviso.
• /status mostra il modello selezionato e, quando lo stato del fallback è diverso, il modello di fallback attivo e il motivo.
• La riconciliazione della sessione in tempo reale preferisce gli override persistenti della sessione rispetto ai campi obsoleti del modello di runtime.
• Se un errore di cambio in tempo reale indica un candidato successivo nella catena di fallback attiva, OpenClaw passa direttamente al modello selezionato anziché percorrere prima candidati non correlati.
• Se il tentativo di fallback non riesce, il gestore ripristina solo i campi di override che ha scritto e soltanto se corrispondono ancora al candidato non riuscito.

Ciò impedisce la classica condizione di competizione:

L'override persistente del fallback elimina questa finestra e il ripristino circoscritto mantiene intatte le modifiche manuali o di runtime più recenti della sessione.

Osservabilità e riepiloghi degli errori

runWithModelFallback(...) registra i dettagli di ogni 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 facoltativo
• riepilogo dell'errore leggibile dall'utente

I log strutturati model_fallback_decision includono anche campi fallbackStep* non annidati quando un candidato non riesce, viene ignorato o un fallback successivo riesce. Questi campi rendono esplicita la transizione tentata (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), affinché gli esportatori di log e diagnostica possano ricostruire l'errore primario anche quando non riesce anche il fallback finale.

Quando tutti i candidati non riescono, OpenClaw genera FallbackSummaryError. Il gestore esterno delle risposte può usarlo per creare un messaggio più specifico, ad esempio "tutti i modelli sono temporaneamente soggetti a limiti di frequenza", e includere la scadenza più prossima del periodo di attesa, se nota.

Il riepilogo del periodo di attesa tiene conto del modello:

• i limiti di frequenza con ambito di modello non correlati vengono ignorati per la catena provider/modello tentata
• se il blocco residuo è un limite di frequenza con ambito di modello corrispondente, OpenClaw segnala l'ultima scadenza corrispondente che continua a bloccare tale modello

Configurazione correlata

Consulta Configurazione del Gateway per:

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

Consulta Modelli per una panoramica più ampia sulla selezione dei modelli e sul fallback.