Model-failover

OpenClaw verwerkt fouten in twee fasen:

1. Rotatie van authenticatieprofielen binnen de huidige provider.
2. Modelterugval naar het volgende model in agents.defaults.model.fallbacks.

Runtimeverloop

De uitvoering van terugval is beurtlokaal. De antwoordrunner slaat alleen de status van terugvalmeldingen persistent op, zodat /status en overgangsmeldingen onderscheid kunnen maken tussen het geselecteerde model en het model dat antwoordde; de terugval wordt niet opgeslagen als de modelselectie voor de volgende beurt.

Beleid voor selectiebronnen

De selectiebron bepaalt of de terugvalketen is toegestaan:

• Geconfigureerde standaardwaarde: agents.defaults.model.primary gebruikt agents.defaults.model.fallbacks.
• Primair model van agent: agents.entries.*.model is strikt, tenzij het modelobject van die agent een eigen fallbacks bevat. Gebruik fallbacks: [] om het strikte gedrag expliciet te maken, of een niet-lege lijst om modelterugval voor die agent in te schakelen.
• Runtimeterugval: de terugvalkandidaat geldt alleen voor de huidige beurt. De volgende beurt begint opnieuw met het geselecteerde primaire model. OpenClaw herkent nog steeds eerder opgeslagen modelOverrideSource: "auto"-vermeldingen, controleert elke 5 minuten hun geconfigureerde oorsprong en wist ze zodra de oorsprong is hersteld. /new, /reset en sessions.reset wissen deze vermeldingen eveneens.
• Gebruikersoverschrijving voor sessie: /model, de modelkiezer, session_status(model=...) en sessions.patch schrijven modelOverrideSource: "user". Dit is een exacte sessieselectie. Als de geselecteerde provider of het geselecteerde model mislukt voordat er een antwoord is geproduceerd, meldt OpenClaw de fout in plaats van te antwoorden met een niet-gerelateerde geconfigureerde terugvaloptie.
• Verouderde sessieoverschrijving: oudere sessievermeldingen kunnen modelOverride zonder modelOverrideSource bevatten. OpenClaw behandelt deze als gebruikersoverschrijvingen, zodat een expliciete oude selectie niet stilzwijgend wordt omgezet in terugvalgedrag.
• Model in Cron-payload: een Cron-taak met payload.model / --model is een primair taakmodel, geen gebruikersoverschrijving voor een sessie. Het gebruikt geconfigureerde terugvalopties, tenzij de taak payload.fallbacks opgeeft; payload.fallbacks: [] maakt de Cron-uitvoering strikt.

OpenClaw stuurt een zichtbare melding wanneer een beurt overschakelt op terugval en nog een melding wanneer een latere beurt slaagt met het geselecteerde primaire model. De persistent opgeslagen meldingsstatus voorkomt herhaalde meldingen wanneer opeenvolgende beurten hetzelfde geselecteerde/actieve paar gebruiken, terwijl de modelselectie zelf ongewijzigd blijft.

Cache voor het overslaan van authenticatiefouten

Standaard behoudt elke nieuwe beurt het bestaande gedrag voor nieuwe terugvalpogingen: OpenClaw probeert elke geconfigureerde terugvalkandidaat opnieuw, inclusief niet-primaire kandidaten die onlangs zijn mislukt met auth of auth_permanent.

Schakel het onderdrukken van herhaalde authenticatiefouten in met:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Wanneer dit is ingeschakeld, registreert OpenClaw na een fout uit de authenticatieklasse een sessiegebonden oversla-marker in het geheugen voor een niet-primaire terugvalkandidaat, met sessie-id, provider en model als sleutel. Primaire kandidaten worden nooit overgeslagen, zodat bij een expliciete gebruikersselectie van een model nog steeds de werkelijke authenticatiefout wordt weergegeven. De cache is proceslokaal en wordt gewist wanneer de Gateway opnieuw wordt gestart.

De waarde is een TTL in milliseconden. 0 of niet ingesteld schakelt de cache uit. Positieve waarden worden begrensd tussen 1 seconde en 10 minuten.

Voor de gebruiker zichtbare terugvalmeldingen

Wanneer een sessie overschakelt op een automatisch geselecteerde terugvaloptie, stuurt OpenClaw een statusmelding via hetzelfde antwoordoppervlak:

↪️ Modelterugval: <fallback> (geselecteerd: <primary>; <reason>)

Wanneer een latere controle slaagt en de sessie terugkeert naar het geselecteerde primaire model, stuurt OpenClaw:

↪️ Modelterugval opgeheven: <primary> (was <fallback>)

Deze meldingen zijn operationele berichten, geen inhoud van de assistent. Ze worden eenmaal per statuswijziging afgeleverd, indien haalbaar ook bij beurten met alleen neveneffecten, maar herhaalde beurtlokale terugvalovergangen zorgen niet voor herhaling. De aflevering omzeilt de normale onderdrukking van bronantwoorden, neemt bij kanalen met threads niet de positie van het eerste assistentantwoord in en wordt uitgesloten van tekst-naar-spraak en extractie van toezeggingen.

Opslag van authenticatie (sleutels + OAuth)

OpenClaw gebruikt authenticatieprofielen voor zowel API-sleutels als OAuth-tokens.

• Geheimen en de runtime-status voor authenticatieroutering bevinden zich in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• Configuratie auth.profiles / auth.order bevat alleen metadata en routering (geen geheimen).
• Verouderd OAuth-bestand dat alleen voor import wordt gebruikt: ~/.openclaw/credentials/oauth.json (bij het eerste gebruik geïmporteerd in de authenticatieopslag per agent).
• Verouderde bestanden auth-profiles.json, auth-state.json en bestanden auth.json per agent worden geïmporteerd door openclaw doctor --fix.

Meer informatie: OAuth

Typen aanmeldgegevens:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl voor sommige providers)
• type: "token" → statisch token van het bearer-type, eventueel met een vervaldatum; OpenClaw vernieuwt dit niet (gebruikt voor aws-sdk en andere authenticatiemodi met een keten van aanmeldgegevens)

Profiel-ID's

OAuth-aanmeldingen maken afzonderlijke profielen, zodat meerdere accounts naast elkaar kunnen bestaan.

• Standaard: provider:default wanneer geen e-mailadres beschikbaar is.
• OAuth met e-mailadres: provider:<email> (bijvoorbeeld google-antigravity:user@gmail.com).

Profielen bevinden zich in de opslag voor authenticatieprofielen openclaw-agent.sqlite per agent.

Rotatievolgorde

Wanneer een provider meerdere profielen heeft, kiest OpenClaw als volgt een volgorde:

Als er geen expliciete volgorde is geconfigureerd, gebruikt OpenClaw een round-robinvolgorde:

• Primaire sleutel: profieltype (eerst OAuth, dan statisch token, dan API-sleutel).
• Secundaire sleutel voor OAuth: profielen met een momenteel bruikbaar toegangstoken vóór profielen waarvan het toegangstoken is verlopen. Verlopen OAuth-profielen blijven in aanmerking komen, zodat de runtime ze kan vernieuwen wanneer er geen bruikbaar alternatief beschikbaar is.
• Volgende sleutel: usageStats.lastUsed (oudste eerst, binnen elke type-/statuscategorie).
• Profielen in een afkoelperiode of uitgeschakelde profielen worden naar het einde verplaatst, gerangschikt op het eerstvolgende einde.

Sessiegebondenheid (cachevriendelijk)

OpenClaw zet het gekozen authenticatieprofiel per sessie vast om providercaches warm te houden. Het roteert niet bij elke aanvraag. Het vastgezette profiel wordt hergebruikt totdat:

• de sessie wordt gereset (/new / /reset)
• een Compaction is voltooid (het aantal compacties wordt verhoogd)
• het profiel in een afkoelperiode staat of is uitgeschakeld

Handmatige selectie via /model …@<profileId> stelt een gebruikersoverschrijving voor die sessie in en wordt niet automatisch geroteerd totdat een nieuwe sessie begint.

OpenAI Codex-abonnement met API-sleutel als reserveoptie

Voor OpenAI-agentmodellen staan authenticatie en runtime los van elkaar. openai/gpt-* blijft op de Codex-harness, terwijl de authenticatie kan roteren tussen een Codex-abonnementsprofiel en een OpenAI API-sleutel als reserveoptie.

Gebruik auth.order.openai voor de volgorde die aan de gebruiker wordt getoond:

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

Gebruik openai:* voor zowel ChatGPT/Codex OAuth-profielen als OpenAI API-sleutelprofielen. Wanneer het abonnement een Codex-gebruikslimiet bereikt, registreert OpenClaw het exacte resettijdstip als Codex dit verstrekt, probeert het volgende geordende authenticatieprofiel en houdt de uitvoering binnen de Codex-harness. Zodra het resettijdstip is verstreken, komt het abonnementsprofiel weer in aanmerking en kan de volgende automatische selectie ernaar terugkeren.

Gebruik alleen een door de gebruiker vastgezet profiel wanneer je voor die sessie één account/sleutel wilt afdwingen. Door de gebruiker vastgezette profielen zijn bewust strikt en schakelen niet stilzwijgend over naar een ander profiel.

Afkoelperioden

Wanneer een profiel mislukt door authenticatie- of frequentielimietfouten (of een time-out die op frequentiebeperking lijkt), plaatst OpenClaw het in een afkoelperiode en gaat het door naar het volgende profiel.

Reguliere cooldowns (niet voor facturering en niet voor permanente authenticatiefouten) schalen met het recente aantal fouten van het profiel:

• 1e fout: 30 seconden
• 2e fout: 1 minuut
• 3e en volgende fouten: 5 minuten (maximum)

Tellers worden opnieuw ingesteld zodra het ingebouwde foutvenster van het profiel is verstreken.

De status wordt opgeslagen in de SQLite-authenticatiestatus per agent onder usageStats:

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

Uitschakeling wegens facturering

Fouten met facturering/tegoed (bijvoorbeeld "onvoldoende tegoed" / "tegoedsaldo te laag") worden beschouwd als reden voor failover, maar zijn meestal niet tijdelijk. In plaats van een korte cooldown markeert OpenClaw het profiel als uitgeschakeld (met een langere wachttijd) en schakelt het door naar het volgende profiel/de volgende provider.

Permanente authenticatiefouten met hoge zekerheid (ingetrokken/gedeactiveerde sleutels, gedeactiveerde werkruimten) krijgen een vergelijkbaar uitschakelingstraject, maar herstellen veel sneller dan bij facturering, omdat sommige providers tijdens incidenten tijdelijk payloads tonen die op authenticatiefouten lijken.

De status wordt opgeslagen in de SQLite-authenticatiestatus per agent:

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

Overbelastings- en snelheidslimietfouten worden agressiever afgehandeld dan cooldowns voor facturering: standaard staat OpenClaw één nieuwe poging met een authenticatieprofiel van dezelfde provider toe en schakelt het daarna zonder te wachten over naar de volgende geconfigureerde modelfallback.

Modelfallback

Als alle profielen voor een provider mislukken, gaat OpenClaw naar het volgende model in agents.defaults.model.fallbacks. Dit geldt voor authenticatiefouten, snelheidslimieten en time-outs waarbij profielrotatie is uitgeput (andere fouten gaan niet door naar de fallback). Providerfouten die onvoldoende details beschikbaar stellen, worden nog steeds nauwkeurig gelabeld in de fallbackstatus: empty_response betekent dat de provider geen bruikbaar bericht of status retourneerde, no_error_details betekent dat de provider expliciet Unknown error (no error details in response) retourneerde en unclassified betekent dat OpenClaw het onbewerkte voorbeeld heeft behouden, maar dat nog geen classificator ermee overeenkwam.

Signalen dat de provider bezet is, zoals ModelNotReadyException, komen in de categorie overbelasting terecht en volgen hetzelfde beleid van één rotatie en daarna fallback als snelheidslimieten (zie de tabel met standaardwaarden hierboven).

Als de volledige keten met kandidaten uitsluitend door overbelastingsfouten is uitgeput, probeert de uitvoerder van antwoorden de keten in dezelfde beurt maximaal 10 keer opnieuw. Opnieuw proberen van de volledige beurt is alleen toegestaan voordat de uitvoering van tools of de uitvoer van de assistent begint, om dubbele mutaties of berichten te voorkomen als overbelasting optreedt nadat waarneembaar werk is uitgevoerd. De wachttijd begint bij 2.5 seconden en verdubbelt tot een maximum van 30 seconden. Zodra de beurt 30 seconden heeft gewacht, verstuurt OpenClaw één tijdelijke statusmelding: The AI service is temporarily overloaded. I’m still retrying; this may take a few minutes. De nieuwe poging en een eventuele winnende fallback blijven beperkt tot de beurt; reguliere tijdelijke serverfouten behouden hun afzonderlijke beleid van één nieuwe poging.

Wanneer een uitvoering begint met de geconfigureerde standaard-primaire optie, de primaire optie van een Cron-taak, de primaire optie van een agent met expliciete fallbacks of een automatisch geselecteerde fallbackoverschrijving, kan OpenClaw de bijbehorende geconfigureerde fallbackketen doorlopen. Primaire opties van agents zonder expliciete fallbacks en expliciete gebruikersselecties (bijvoorbeeld /model ollama/qwen3.5:27b, de modelkiezer, sessions.patch of eenmalige CLI-overschrijvingen van provider/model) zijn strikt: als die provider/dat model onbereikbaar is of faalt voordat een antwoord wordt geproduceerd, meldt OpenClaw de fout in plaats van te antwoorden via een niet-gerelateerde fallback.

Regels voor de kandidatenketen

OpenClaw stelt de kandidatenlijst samen uit de momenteel aangevraagde provider/model en de geconfigureerde fallbacks.

Welke fouten doorgaan naar de fallback

Gedrag voor cooldown overslaan versus testen

Wanneer elk authenticatieprofiel voor een provider al een cooldown heeft, slaat OpenClaw die provider niet automatisch voor altijd over. Het neemt een beslissing per kandidaat:

Sessieoverschrijvingen en live van model wisselen

Wijzigingen van het sessiemodel zijn gedeelde status. De actieve uitvoerder, de opdracht /model, Compaction-/sessie-updates en reconciliatie van livesessies lezen of schrijven allemaal delen van dezelfde sessievermelding. De uitvoering van fallbacks schrijft geen modelselectievelden en kan daarom tijdens het opnieuw proberen geen recentere handmatige selectie vervangen.

Live van model wisselen volgt deze regels:

• Alleen expliciete, door de gebruiker aangestuurde modelwijzigingen markeren een wachtende livewissel. Dit omvat /model, session_status(model=...) en sessions.patch.
• Door het systeem aangestuurde modelwijzigingen zoals fallbackrotatie, Heartbeat-overschrijvingen of Compaction markeren nooit uit zichzelf een wachtende livewissel.
• Door gebruikers aangestuurde modeloverschrijvingen worden voor het fallbackbeleid behandeld als exacte selecties, zodat een onbereikbare geselecteerde provider als fout wordt weergegeven in plaats van te worden gemaskeerd door agents.defaults.model.fallbacks.
• Fallbackkandidaten tijdens runtime blijven beperkt tot de beurt. De volgende beurt begint met het momenteel geselecteerde model, inclusief een handmatige selectie die tijdens de vorige uitvoering is binnengekomen.
• Eerder opgeslagen automatische fallbackoverschrijvingen blijven ondersteund: OpenClaw test periodiek hun geconfigureerde oorsprong en wist de overschrijving wanneer die is hersteld; /new, /reset en sessions.reset wissen automatisch aangemaakte overschrijvingen onmiddellijk.
• Antwoorden aan gebruikers kondigen fallbackovergangen en herstel na het wissen van een fallback eenmaal per statuswijziging aan. Opeenvolgende beurten met hetzelfde geselecteerde/actieve paar herhalen de melding niet.
• /status toont het geselecteerde model en, wanneer de fallbackstatus afwijkt, het actieve fallbackmodel en de reden.
• Bij reconciliatie van livesessies krijgen permanent opgeslagen sessieoverschrijvingen voorrang boven verouderde modelvelden tijdens runtime.
• Als een fout bij live wisselen verwijst naar een latere kandidaat in de actieve fallbackketen, springt OpenClaw rechtstreeks naar dat geselecteerde model in plaats van eerst niet-gerelateerde kandidaten te doorlopen.

De actieve uitvoering draagt de gekozen kandidaat rechtstreeks mee. Live reconciliatie wijzigt die kandidaat alleen bij een expliciete wachtende gebruikerswissel, zodat geen tijdelijke fallbackoverschrijving of terugdraaiing nodig is.

Observeerbaarheid en foutoverzichten

runWithModelFallback(...) registreert details per poging die worden gebruikt voor logboeken en gebruikersgerichte cooldownmeldingen:

• geprobeerde provider/model
• reden (rate_limit, overloaded, billing, auth, model_not_found en vergelijkbare failoverredenen)
• optionele status/code
• voor mensen leesbaar foutoverzicht

Gestructureerde model_fallback_decision-logboeken bevatten ook platte fallbackStep*-velden wanneer een kandidaat faalt, wordt overgeslagen of een latere fallback slaagt. Deze velden maken de geprobeerde overgang expliciet (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), zodat exporteurs van logboeken en diagnostische gegevens de primaire fout kunnen reconstrueren, zelfs wanneer de uiteindelijke fallback ook faalt.

Wanneer elke kandidaat mislukt, genereert OpenClaw FallbackSummaryError. De buitenste antwoordrunner kan dit gebruiken om een specifiekere melding op te stellen, zoals "voor alle modellen geldt tijdelijk een frequentielimiet", en de eerstvolgende vervaldatum van de afkoelperiode vermelden wanneer die bekend is.

Dat overzicht van de afkoelperiode houdt rekening met het model:

• niet-gerelateerde modelspecifieke frequentielimieten worden genegeerd voor de gebruikte provider-/modelketen
• als de resterende blokkering een overeenkomende modelspecifieke frequentielimiet is, rapporteert OpenClaw de laatste overeenkomende vervaldatum die dat model nog blokkeert

Gerelateerde configuratie

Zie Gateway-configuratie voor:

• auth.profiles / auth.order
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel-routering

Zie Modellen voor het bredere overzicht van modelselectie en fallback.