Modeluitwijk

OpenClaw verwerkt fouten in twee fasen:

1. Auth-profielrotatie binnen de huidige provider.
2. Model-fallback naar het volgende model in agents.defaults.model.fallbacks.

Dit document legt de runtimeregels uit en de gegevens waarop ze zijn gebaseerd.

# Runtimeflow

Voor een normale tekstuitvoering evalueert OpenClaw kandidaten in deze volgorde:

Dit is bewust beperkter dan "de hele sessie opslaan en herstellen". De reply runner bewaart alleen de modelselectievelden die hij beheert voor fallback:

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

Dat voorkomt dat een mislukte fallbackpoging nieuwere, niet-gerelateerde sessiemutaties overschrijft, zoals handmatige /model-wijzigingen of sessierotatie-updates die plaatsvonden terwijl de poging werd uitgevoerd.

# Beleid voor selectiebron

OpenClaw scheidt de geselecteerde provider/het geselecteerde model van de reden waarom deze is geselecteerd. Die bron bepaalt of de fallbackketen is toegestaan:

• Geconfigureerde standaard: agents.defaults.model.primary gebruikt agents.defaults.model.fallbacks.
• Primair agentmodel: agents.list[].model is strikt, tenzij dat agentmodelobject eigen fallbacks bevat. Gebruik fallbacks: [] om het strikte gedrag expliciet te maken, of geef een niet-lege lijst op om model-fallback voor die agent in te schakelen.
• Automatische fallback-override: een runtimefallback schrijft providerOverride, modelOverride en modelOverrideSource: "auto" voordat opnieuw wordt geprobeerd. Die automatische override kan de geconfigureerde fallbackketen blijven doorlopen en wordt gewist door /new, /reset en sessions.reset.
• Gebruikerssessie-override: /model, de modelkiezer, session_status(model=...) en sessions.patch schrijven modelOverrideSource: "user". Dat is een exacte sessieselectie. Als de geselecteerde provider/het geselecteerde model mislukt voordat er een antwoord is geproduceerd, rapporteert OpenClaw de fout in plaats van te antwoorden via een niet-gerelateerde geconfigureerde fallback.
• Verouderde sessie-override: oudere sessie-items kunnen modelOverride hebben zonder modelOverrideSource. OpenClaw behandelt die als gebruikersoverrides, zodat een expliciete oude selectie niet stilzwijgend wordt omgezet naar fallbackgedrag.
• Cron-payloadmodel: een cron-job payload.model / --model is een primair jobmodel, geen gebruikerssessie-override. Het gebruikt geconfigureerde fallbacks, tenzij de job payload.fallbacks opgeeft; payload.fallbacks: [] maakt de Cron-run strikt.

# Auth-opslag (sleutels + OAuth)

OpenClaw gebruikt auth-profielen voor zowel API-sleutels als OAuth-tokens.

• Geheimen staan in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (verouderd: ~/.openclaw/agent/auth-profiles.json).
• Runtime-auth-routeringsstatus staat in ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Configuratie auth.profiles / auth.order is alleen metadata + routering (geen geheimen).
• Verouderd OAuth-bestand alleen voor import: ~/.openclaw/credentials/oauth.json (wordt bij eerste gebruik geïmporteerd in auth-profiles.json).

Meer details: OAuth

Credentialtypen:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl voor sommige providers)

# Profiel-ID's

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

• Standaard: provider:default wanneer er geen e-mail beschikbaar is.
• OAuth met e-mail: provider:<email> (bijvoorbeeld google-antigravity:[email protected]).

Profielen staan in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json onder profiles.

# Rotatievolgorde

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

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

• Primaire sleutel: profieltype (OAuth vóór API-sleutels).
• Secundaire sleutel: usageStats.lastUsed (oudste eerst, binnen elk type).
• Profielen in cooldown/uitgeschakelde profielen worden naar het einde verplaatst, gesorteerd op eerstvolgende verloopdatum.

# Sessiekleefkracht (cachevriendelijk)

OpenClaw pint het gekozen auth-profiel per sessie om providercaches warm te houden. Het roteert niet bij elke aanvraag. Het gepinde profiel wordt opnieuw gebruikt totdat:

• de sessie wordt gereset (/new / /reset)
• een Compaction is voltooid (Compaction-teller wordt verhoogd)
• het profiel in cooldown/uitgeschakeld is

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

# Waarom OAuth "verloren kan lijken"

Als je zowel een OAuth-profiel als een API-sleutelprofiel voor dezelfde provider hebt, kan round-robin tussen berichten wisselen, tenzij het profiel is gepind. Om één profiel af te dwingen:

• Pin met auth.order[provider] = ["provider:profileId"], of
• Gebruik een override per sessie via /model … met een profieloverride (wanneer ondersteund door je UI/chatoppervlak).

# Cooldowns

Wanneer een profiel mislukt door auth-/ratelimitfouten (of een time-out die op ratelimiting lijkt), markeert OpenClaw het als in cooldown en gaat naar het volgende profiel.

Cooldowns gebruiken exponentiële back-off:

• 1 minuut
• 5 minuten
• 25 minuten
• 1 uur (cap)

Status wordt opgeslagen in auth-state.json onder usageStats:

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

# Factureringsuitschakelingen

Facturerings-/kredietfouten (bijvoorbeeld "onvoldoende credits" / "creditsaldo te laag") worden behandeld als failoverwaardig, maar zijn meestal niet tijdelijk. In plaats van een korte cooldown markeert OpenClaw het profiel als uitgeschakeld (met een langere back-off) en roteert naar het volgende profiel/de volgende provider.

Status wordt opgeslagen in auth-state.json:

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

Standaarden:

• Factureringsback-off begint bij 5 uur, verdubbelt per factureringsfout en heeft een cap van 24 uur.
• Back-offtellers worden gereset als het profiel 24 uur niet is mislukt (configureerbaar).
• Overbelaste nieuwe pogingen staan 1 profielrotatie bij dezelfde provider toe vóór model-fallback.
• Overbelaste nieuwe pogingen gebruiken standaard 0 ms back-off.

# Model-fallback

Als alle profielen voor een provider mislukken, gaat OpenClaw naar het volgende model in agents.defaults.model.fallbacks. Dit geldt voor auth-fouten, ratelimits en time-outs waarbij profielrotatie is uitgeput (andere fouten zetten fallback niet voort). Providerfouten die niet genoeg details blootleggen, krijgen nog steeds een precies label in fallbackstatus: empty_response betekent dat de provider geen bruikbaar bericht of bruikbare status retourneerde, no_error_details betekent dat de provider expliciet Unknown error (no error details in response) retourneerde, en unclassified betekent dat OpenClaw de ruwe preview heeft behouden, maar dat er nog geen classifier op paste.

Overbelastings- en rate-limitfouten worden agressiever afgehandeld dan factureringscooldowns. Standaard staat OpenClaw één retry met hetzelfde provider-auth-profiel toe en schakelt daarna zonder wachten over naar de volgende geconfigureerde modelterugval. Provider-bezetsignalen zoals ModelNotReadyException komen in die overbelastingscategorie terecht. Stem dit af met auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs en auth.cooldowns.rateLimitedProfileRotations.

Wanneer een run start vanaf de geconfigureerde standaardprimaire keuze, een primaire keuze van een cronjob, een agent-primaire keuze met expliciete terugvalopties, of een automatisch geselecteerde terugvaloverride, kan OpenClaw de bijpassende geconfigureerde terugvalketen doorlopen. Agent-primaire keuzes zonder expliciete terugvalopties en expliciete gebruikersselecties (bijvoorbeeld /model ollama/qwen3.5:27b, de modelkiezer, sessions.patch of eenmalige CLI-provider-/modeloverrides) zijn strikt: als die provider/dat model onbereikbaar is of faalt voordat er een antwoord wordt geproduceerd, meldt OpenClaw de fout in plaats van te antwoorden via een niet-gerelateerde terugvaloptie.

# Regels voor de kandidatenketen

OpenClaw bouwt de kandidatenlijst op vanuit de momenteel aangevraagde provider/model plus geconfigureerde terugvalopties.

# Welke fouten terugval voortzetten

# Cooldown overslaan versus probeergedrag

Wanneer elk auth-profiel voor een provider al in cooldown staat, slaat OpenClaw die provider niet automatisch voorgoed over. Het neemt per kandidaat een beslissing:

# Sessieoverrides en live modelwisselingen

Sessiemodelwijzigingen zijn gedeelde staat. De actieve runner, de opdracht /model, compaction-/sessie-updates en live-sessiereconciliatie lezen of schrijven allemaal delen van dezelfde sessie-entry.

Dat betekent dat terugvalretries moeten coördineren met live modelwisselingen:

• Alleen expliciete door de gebruiker gestuurde modelwijzigingen markeren een wachtende livewisseling. Dat omvat /model, session_status(model=...) en sessions.patch.
• Door het systeem gestuurde modelwijzigingen, zoals terugvalrotatie, Heartbeat-overrides of Compaction, markeren nooit zelfstandig een wachtende livewisseling.
• Door de gebruiker gestuurde modeloverrides worden voor terugvalbeleid behandeld als exacte selecties, zodat een onbereikbare geselecteerde provider als fout zichtbaar wordt in plaats van te worden gemaskeerd door agents.defaults.model.fallbacks.
• Voordat een terugvalretry start, bewaart de reply-runner de geselecteerde terugvaloverridevelden in de sessie-entry.
• Automatische terugvaloverrides blijven geselecteerd bij volgende beurten, zodat OpenClaw niet bij elk bericht een bekende slechte primaire keuze probeert. /new, /reset en sessions.reset wissen automatisch afkomstige overrides en zetten de sessie terug naar de geconfigureerde standaard.
• /status toont het geselecteerde model en, wanneer de terugvalstatus verschilt, het actieve terugvalmodel en de reden.
• Live-sessiereconciliatie geeft de voorkeur aan persistente sessieoverrides boven verouderde runtime-modelvelden.
• Als een livewisselfout naar een latere kandidaat in de actieve terugvalketen wijst, springt OpenClaw direct naar dat geselecteerde model in plaats van eerst niet-gerelateerde kandidaten te doorlopen.
• Als de terugvalpoging mislukt, draait de runner alleen de overridevelden terug die hij heeft geschreven, en alleen als ze nog steeds overeenkomen met die mislukte kandidaat.

Dit voorkomt de klassieke race:

De persistente terugvaloverride sluit dat venster, en de smalle rollback houdt nieuwere handmatige of runtime-sessiewijzigingen intact.

# Observatie en foutensamenvattingen

runWithModelFallback(...) registreert details per poging die logs en gebruikersgerichte cooldownberichten voeden:

• geprobeerd(e) provider/model
• reden (rate_limit, overloaded, billing, auth, model_not_found en vergelijkbare failoverredenen)
• optionele status/code
• voor mensen leesbare foutensamenvatting

Gestructureerde model_fallback_decision-logs bevatten ook platte fallbackStep*-velden wanneer een kandidaat faalt, wordt overgeslagen of een latere terugval slaagt. Deze velden maken de geprobeerde overgang expliciet (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), zodat log- en diagnose-exporters de primaire fout kunnen reconstrueren, zelfs wanneer de uiteindelijke terugval ook faalt.

Wanneer elke kandidaat faalt, gooit OpenClaw FallbackSummaryError. De buitenste reply-runner kan dat gebruiken om een specifieker bericht te bouwen, zoals "alle modellen zijn tijdelijk rate-limited", en de vroegste cooldownvervaldatum opnemen wanneer die bekend is.

Die cooldownsamenvatting is modelbewust:

• niet-gerelateerde modelspecifieke rate limits worden genegeerd voor de geprobeerde provider-/modelketen
• als de resterende blokkade een overeenkomende modelspecifieke rate limit is, meldt OpenClaw de laatste overeenkomende vervaldatum die dat model nog steeds blokkeert

# Gerelateerde configuratie

Zie Gateway-configuratie voor:

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

Zie Modellen voor het bredere overzicht van modelselectie en terugval.