Passaggio automatico al modello di riserva

OpenClaw gestisce gli errori in due fasi:

1. Rotazione del profilo di autenticazione all'interno del fornitore corrente.
2. Passaggio a un modello alternativo 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:

Questo è intenzionalmente più mirato di "salva e ripristina l'intera sessione". L'esecutore della risposta persiste solo i campi di selezione del modello che possiede per l'alternativa:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Questo impedisce a un nuovo tentativo alternativo non riuscito di sovrascrivere modifiche 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.

# Politica dell'origine della selezione

OpenClaw separa il fornitore/modello selezionato dal motivo per cui è stato selezionato. Tale origine controlla se la catena alternativa è consentita:

• Predefinito configurato: agents.defaults.model.primary usa agents.defaults.model.fallbacks.
• Modello primario dell'agente: agents.list[].model è rigoroso, a meno che l'oggetto modello di quell'agente includa le proprie fallbacks. Usa fallbacks: [] per rendere esplicito il comportamento rigoroso, oppure fornisci un elenco non vuoto per abilitare quel modello dell'agente al passaggio a modelli alternativi.
• Sostituzione alternativa automatica: un'alternativa di runtime scrive providerOverride, modelOverride e modelOverrideSource: "auto" prima di riprovare. Tale sostituzione automatica può continuare a percorrere la catena alternativa configurata e viene cancellata da /new, /reset e sessions.reset.
• Sostituzione della sessione utente: /model, il selettore di modelli, session_status(model=...) e sessions.patch scrivono modelOverrideSource: "user". Questa è una selezione esatta della sessione. Se il fornitore/modello selezionato fallisce prima di produrre una risposta, OpenClaw segnala l'errore invece di rispondere usando un'alternativa configurata non correlata.
• Sostituzione di sessione legacy: le voci di sessione più vecchie possono avere modelOverride senza modelOverrideSource. OpenClaw le tratta come sostituzioni utente, così una vecchia selezione esplicita non viene convertita silenziosamente in comportamento alternativo.
• Modello del payload Cron: un payload.model / --model di un processo cron è un modello primario del processo, non una sostituzione della sessione utente. Usa le alternative configurate a meno che il processo non fornisca payload.fallbacks; payload.fallbacks: [] rende rigorosa l'esecuzione Cron.

# Archiviazione dell'autenticazione (chiavi + OAuth)

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

• I segreti risiedono in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (legacy: ~/.openclaw/agent/auth-profiles.json).
• Lo stato di instradamento dell'autenticazione di runtime risiede in ~/.openclaw/agents/<agentId>/agent/auth-state.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 uso).

Maggiori dettagli: OAuth

Tipi di credenziali:

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

# ID dei profili

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

• Predefinito: provider:default quando non è disponibile alcuna email.
• OAuth con email: provider:<email> (ad esempio google-antigravity:[email protected]).

I profili risiedono in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json sotto profiles.

# Ordine di rotazione

Quando un fornitore ha più profili, OpenClaw sceglie un ordine in questo modo:

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

• Chiave primaria: tipo di profilo (OAuth prima delle chiavi API).
• Chiave secondaria: usageStats.lastUsed (prima il meno recente, all'interno di ciascun tipo).
• I profili in sospensione temporanea/disabilitati vengono spostati alla fine, ordinati per scadenza più vicina.

# Persistenza di sessione (favorevole alla cache)

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

• la sessione viene reimpostata (/new / /reset)
• una Compaction viene completata (il conteggio delle Compaction aumenta)
• il profilo è in sospensione temporanea/disabilitato

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

# Perché OAuth può "sembrare perso"

Se hai sia un profilo OAuth sia un profilo con chiave API per lo stesso fornitore, la rotazione può passare dall'uno all'altro tra i messaggi a meno che non siano fissati. Per forzare un singolo profilo:

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

# Sospensioni temporanee

Quando un profilo fallisce a causa di errori di autenticazione/limite di frequenza (o di una scadenza del tempo di attesa che sembra un limite di frequenza), OpenClaw lo contrassegna in sospensione temporanea e passa al profilo successivo.

Le sospensioni temporanee usano un backoff esponenziale:

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

Lo stato è archiviato in auth-state.json sotto usageStats:

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

# Disabilitazioni per fatturazione

Gli errori di fatturazione/credito (ad esempio "insufficient credits" / "credit balance too low") sono trattati come idonei al passaggio di emergenza, ma di solito non sono transitori. Invece di una breve sospensione temporanea, OpenClaw contrassegna il profilo come disabilitato (con un backoff più lungo) e ruota al profilo/fornitore successivo.

Lo stato è archiviato in auth-state.json:

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

Impostazioni predefinite:

• Il backoff di fatturazione parte da 5 ore, raddoppia per ogni errore di fatturazione e ha un limite di 24 ore.
• I contatori di backoff vengono reimpostati se il profilo non ha generato errori per 24 ore (configurabile).
• I nuovi tentativi per sovraccarico consentono 1 rotazione del profilo dello stesso fornitore prima del passaggio a un modello alternativo.
• I nuovi tentativi per sovraccarico usano 0 ms di backoff per impostazione predefinita.

# Modello alternativo

Se tutti i profili per un fornitore falliscono, OpenClaw passa al modello successivo in agents.defaults.model.fallbacks. Questo si applica agli errori di autenticazione, ai limiti di frequenza e alle scadenze del tempo di attesa che hanno esaurito la rotazione dei profili (altri errori non avanzano all'alternativa). Gli errori del fornitore che non espongono dettagli sufficienti sono comunque etichettati con precisione nello stato dell'alternativa: empty_response significa che il fornitore non ha restituito alcun messaggio o stato utilizzabile, no_error_details significa che il fornitore 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 vengono gestiti in modo più aggressivo rispetto ai cooldown di fatturazione. Per impostazione predefinita, OpenClaw consente un tentativo con lo stesso profilo di autenticazione dello stesso provider, quindi passa al fallback del modello configurato successivo senza attendere. I segnali di provider occupato come ModelNotReadyException rientrano in questa categoria 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 processo cron, da un primario di agente con fallback espliciti o da una sostituzione fallback selezionata automaticamente, OpenClaw può percorrere la catena di fallback configurata corrispondente. I primari di agente senza fallback espliciti e le selezioni utente esplicite (per esempio /model ollama/qwen3.5:27b, il selettore dei modelli, sessions.patch o sostituzioni una tantum di provider/modello tramite CLI) sono rigidi: 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.

# Quali errori fanno avanzare il fallback

# Comportamento di salto cooldown rispetto a 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:

# Sostituzioni 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 ritentativi fallback devono coordinarsi con il cambio modello live:

• Solo le modifiche al modello guidate esplicitamente dall'utente segnano un cambio live in sospeso. Questo include /model, session_status(model=...) e sessions.patch.
• Le modifiche al modello guidate dal sistema, come rotazione fallback, sostituzioni heartbeat o compaction, non segnano mai da sole un cambio live in sospeso.
• Le sostituzioni del modello guidate dall'utente sono trattate come selezioni esatte per la policy di fallback, quindi un provider selezionato non raggiungibile emerge come errore invece di essere mascherato da agents.defaults.model.fallbacks.
• Prima che inizi un ritentativo fallback, il runner di risposta persiste i campi di sostituzione fallback selezionati nella voce di sessione.
• Le sostituzioni fallback automatiche rimangono selezionate nei turni successivi così OpenClaw non sonda un primario già noto come problematico a ogni messaggio. /new, /reset e sessions.reset cancellano le sostituzioni di origine automatica e riportano la sessione al valore predefinito configurato.
• /status mostra il modello selezionato e, quando lo stato fallback differisce, il modello fallback attivo e il motivo.
• La riconciliazione della sessione live preferisce le sostituzioni di sessione persistite rispetto ai campi del modello runtime obsoleti.
• Se un errore di cambio live punta a un candidato successivo nella catena fallback attiva, OpenClaw salta direttamente a quel modello selezionato invece di percorrere prima candidati non correlati.
• Se il tentativo fallback fallisce, il runner ripristina solo i campi di sostituzione che ha scritto, e solo se corrispondono ancora a quel candidato fallito.

Questo evita la classica race:

La sostituzione fallback persistita chiude quella finestra, e il rollback ristretto mantiene intatte le modifiche di sessione manuali o runtime più recenti.

# Osservabilità e riepiloghi degli errori

runWithModelFallback(...) registra dettagli per tentativo che alimentano i log e la messaggistica cooldown rivolta 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 da una persona

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 del primario anche quando anche il fallback terminale fallisce.

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 cooldown più vicina quando è nota.

Quel riepilogo cooldown è consapevole del modello:

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

# Configurazione correlata

Vedi Configurazione 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

Vedi Modelli per la panoramica più ampia su selezione dei modelli e fallback.