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

Dit is bewust beperkter dan „de hele sessie opslaan en herstellen”. De antwoorduitvoerder slaat alleen de modelselectievelden op waarvan deze voor terugval eigenaar is: providerOverride, modelOverride, modelOverrideSource, authProfileOverride, authProfileOverrideSource, authProfileOverrideCompactionCount. Zo wordt voorkomen dat een mislukte nieuwe terugvalpoging nieuwere, niet-gerelateerde sessiewijzigingen overschrijft, zoals een handmatige wijziging via /model of een update van de sessierotatie die plaatsvond terwijl de poging werd uitgevoerd.

Beleid voor selectiebronnen

De selectiebron bepaalt of de terugvalketen is toegestaan:

• Geconfigureerde standaardwaarde: agents.defaults.model.primary gebruikt agents.defaults.model.fallbacks.
• Primair agentmodel: agents.list[].model is strikt, tenzij het modelobject van die agent 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.
• Automatische terugvaloverschrijving: een runtime-terugval schrijft vóór een nieuwe poging providerOverride, modelOverride, modelOverrideSource: "auto" en het geselecteerde oorspronkelijke model. Met deze overschrijving wordt de geconfigureerde terugvalketen verder doorlopen zonder bij elk bericht het primaire model te testen, maar OpenClaw test de geconfigureerde oorsprong elke 5 minuten (niet configureerbaar) en wist de overschrijving zodra deze is hersteld. /new, /reset en sessions.reset wissen ook automatisch aangemaakte overschrijvingen. Heartbeat-uitvoeringen zonder expliciet heartbeat.model wissen directe automatische overschrijvingen wanneer hun oorsprong niet meer overeenkomt met de huidige geconfigureerde standaardwaarde.
• Gebruikersoverschrijving voor sessies: /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-gerelateerd geconfigureerd terugvalmodel.
• 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: payload.model / --model van een Cron-taak is een primair taakmodel, geen gebruikersoverschrijving voor een sessie. Het gebruikt geconfigureerde terugvalmodellen, tenzij de taak payload.fallbacks opgeeft; payload.fallbacks: [] maakt de Cron-uitvoering strikt.

OpenClaw onthoudt recente tests van primaire modellen per sessie en per primair model, zodat een falend primair model niet bij elke beurt opnieuw wordt geprobeerd. Het stuurt een zichtbare melding wanneer een sessie naar een terugvalmodel overschakelt en nog een melding wanneer deze terugkeert naar het geselecteerde primaire model; de melding wordt niet bij elke beurt met een aangehouden terugvalmodel herhaald.

Cache voor het overslaan van authenticatiefouten

Standaard behoudt elke nieuwe beurt het bestaande gedrag voor nieuwe terugvalpogingen: OpenClaw probeert elk geconfigureerd kandidaat-terugvalmodel opnieuw, inclusief niet-primaire kandidaatmodellen 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 authenticatiecategorie een sessiegebonden oversla-markering in het geheugen voor een niet-primair kandidaat-terugvalmodel, met sessie-id, provider en model als sleutel. Primaire kandidaatmodellen worden nooit overgeslagen, zodat een expliciete modelselectie door de gebruiker nog steeds de werkelijke authenticatiefout toont. De cache is lokaal voor het proces en wordt gewist wanneer de Gateway opnieuw wordt gestart.

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

Voor gebruikers zichtbare terugvalmeldingen

Wanneer een sessie overschakelt naar een automatisch geselecteerd terugvalmodel, stuurt OpenClaw een statusmelding via hetzelfde antwoordoppervlak:

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

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

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

Deze meldingen zijn operationele berichten, geen inhoud van de assistent. Ze worden eenmaal per statuswijziging afgeleverd, waar mogelijk ook bij beurten met uitsluitend neveneffecten, maar worden niet herhaald bij beurten met een aangehouden terugvalmodel. De aflevering omzeilt de normale onderdrukking van antwoorden op de bron, neemt bij kanalen met threads niet de eerste antwoordpositie van de assistent in en wordt uitgesloten van tekst-naar-spraak en de extractie van toezeggingen.

Opslag van authenticatie (sleutels + OAuth)

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

• Geheimen en de runtimestatus voor authenticatieroutering bevinden zich in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• De configuratie auth.profiles / auth.order bevat alleen metagegevens + routering (geen geheimen).
• Verouderd OAuth-bestand uitsluitend voor import: ~/.openclaw/credentials/oauth.json (bij het eerste gebruik geïmporteerd in de authenticatieopslag per agent).
• Verouderde bestanden auth-profiles.json, auth-state.json en 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 vervaldatum; OpenClaw vernieuwt dit niet (gebruikt voor aws-sdk en andere authenticatiemodi met een aanmeldgegevensketen)

Profiel-ID's

OAuth-aanmeldingen maken afzonderlijke profielen aan, 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 in 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 (OAuth, vervolgens statisch token, vervolgens API-sleutel).
• Secundaire sleutel: usageStats.lastUsed (oudste eerst, binnen elk type).
• Profielen in afkoeling of uitgeschakelde profielen worden naar het einde verplaatst, geordend op het eerstvolgende verloopmoment.

Sessiebinding (cachevriendelijk)

OpenClaw koppelt het gekozen authenticatieprofiel aan de sessie om de providercaches warm te houden. Het roteert niet bij elke aanvraag. Het gekoppelde profiel wordt hergebruikt totdat:

• de sessie opnieuw wordt ingesteld (/new / /reset)
• een Compaction is voltooid (de Compaction-teller wordt verhoogd)
• het profiel in afkoeling staat of is uitgeschakeld

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

OpenAI Codex-abonnement met API-sleutel als reserve

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

Gebruik auth.order.openai voor de aan de gebruiker getoonde volgorde:

{  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 hersteltijdstip als Codex dat verstrekt, probeert het het volgende authenticatieprofiel in de ingestelde volgorde en houdt het de uitvoering binnen het Codex-harnas. Nadat het hersteltijdstip is verstreken, komt het abonnementsprofiel weer in aanmerking en kan de volgende automatische selectie ernaar terugkeren.

Gebruik een door de gebruiker gekoppeld profiel alleen wanneer u voor die sessie één account of sleutel wilt afdwingen. Door de gebruiker gekoppelde profielen zijn bewust strikt en springen niet stilzwijgend naar een ander profiel.

Afkoelperioden

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

Reguliere afkoelperiodes (niet voor facturering en niet voor permanente authenticatiefouten) worden geschaald op basis van het recente aantal fouten van het profiel:

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

De tellers worden opnieuw ingesteld zodra het foutvenster van het profiel is verstreken (auth.cooldowns.failureWindowHours, standaard 24).

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

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

Uitschakeling vanwege facturering

Facturerings- en tegoedfouten (bijvoorbeeld "onvoldoende tegoed" / "te laag tegoedsaldo") worden beschouwd als redenen voor failover, maar zijn meestal niet tijdelijk. In plaats van een korte afkoelperiode markeert OpenClaw het profiel als uitgeschakeld (met een langere wachttijd) en schakelt het over naar het volgende profiel of de volgende provider.

Permanente authenticatiefouten met hoge zekerheid (ingetrokken of gedeactiveerde sleutels, gedeactiveerde werkruimten) krijgen een vergelijkbaar uitschakelpad, maar herstellen veel sneller dan factureringsfouten, omdat sommige providers tijdens incidenten tijdelijk reacties retourneren die op authenticatiefouten lijken.

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

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

Standaardwaarden (auth.cooldowns.*):

Fouten vanwege overbelasting en frequentielimieten worden agressiever afgehandeld dan afkoelperiodes vanwege facturering: standaard staat OpenClaw één nieuwe poging met een authenticatieprofiel van dezelfde provider toe en schakelt het daarna zonder te wachten over naar het volgende geconfigureerde terugvalmodel.

Modelterugval

Als alle profielen voor een provider mislukken, gaat OpenClaw naar het volgende model in agents.defaults.model.fallbacks. Dit geldt voor authenticatiefouten, frequentielimieten en time-outs waarbij profielwisseling is uitgeput (andere fouten activeren geen terugval). Providerfouten die onvoldoende details bevatten, krijgen nog steeds een nauwkeurig label in de terugvalstatus: 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 het onbewerkte voorbeeld heeft behouden, maar dat nog geen classificatiemechanisme ermee overeenkwam.

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

Wanneer een uitvoering begint met de geconfigureerde standaardwaarde voor het primaire model, het primaire model van een Cron-taak, het primaire model van een agent met expliciete terugvalmodellen of een automatisch geselecteerde terugvaloverschrijving, kan OpenClaw de bijbehorende geconfigureerde terugvalketen doorlopen. Primaire modellen van agents zonder expliciete terugvalmodellen en expliciete gebruikersselecties (bijvoorbeeld /model ollama/qwen3.5:27b, de modelkiezer, sessions.patch of eenmalige CLI-overschrijvingen voor provider/model) zijn strikt: als die provider of dat model onbereikbaar is of mislukt voordat er een antwoord wordt geproduceerd, meldt OpenClaw de fout in plaats van een antwoord van een niet-gerelateerd terugvalmodel te geven.

Regels voor de kandidatenketen

OpenClaw stelt de kandidatenlijst samen uit het momenteel aangevraagde provider/model plus de geconfigureerde terugvalmodellen.

Welke fouten terugval activeren

Gedrag bij overslaan van afkoeling versus testen

Wanneer elk authenticatieprofiel voor een provider al in een afkoelperiode zit, slaat OpenClaw die provider niet automatisch voorgoed over. Het neemt per kandidaat een beslissing:

Sessieoverschrijvingen en live wisselen van model

Wijzigingen van het sessiemodel zijn gedeelde status. De actieve runner, de opdracht /model, updates voor Compaction en sessies en afstemming van live sessies lezen of schrijven allemaal delen van dezelfde sessievermelding.

Dat betekent dat nieuwe terugvalpogingen moeten worden gecoördineerd met het live wisselen van model:

• Alleen expliciete, door de gebruiker gestuurde modelwijzigingen markeren een wachtende live wissel. Dit omvat /model, session_status(model=...) en sessions.patch.
• Door het systeem gestuurde modelwijzigingen, zoals terugvalwisseling, Heartbeat-overschrijvingen of Compaction, markeren zelf nooit een wachtende live wissel.
• Door de gebruiker gestuurde modeloverschrijvingen worden voor het terugvalbeleid behandeld als exacte selecties, zodat een onbereikbare geselecteerde provider als fout wordt weergegeven in plaats van te worden gemaskeerd door agents.defaults.model.fallbacks.
• Voordat een nieuwe terugvalpoging begint, slaat de antwoordrunner de geselecteerde velden voor de terugvaloverschrijving op in de sessievermelding.
• Automatische terugvaloverschrijvingen blijven tijdens volgende beurten geselecteerd, zodat OpenClaw niet bij elk bericht een primair model test waarvan bekend is dat het niet werkt. OpenClaw test periodiek opnieuw de geconfigureerde oorsprong en wist de automatische overschrijving wanneer deze herstelt; /new, /reset en sessions.reset wissen automatisch ingestelde overschrijvingen onmiddellijk.
• Antwoorden aan gebruikers kondigen terugvalovergangen en herstel na het wissen van de terugval eenmaal per statuswijziging aan. Beurten met blijvende terugval herhalen de melding niet.
• /status toont het geselecteerde model en, wanneer de terugvalstatus afwijkt, het actieve terugvalmodel en de reden.
• Afstemming van live sessies geeft voorrang aan opgeslagen sessieoverschrijvingen boven verouderde modelvelden tijdens runtime.
• Als een fout bij live wisselen naar een latere kandidaat in de actieve terugvalketen verwijst, 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 overschrijvingsvelden terug die deze zelf heeft geschreven, en alleen wanneer ze nog steeds overeenkomen met die mislukte kandidaat.

Dit voorkomt de klassieke racevoorwaarde:

De opgeslagen terugvaloverschrijving sluit dat venster, en de beperkte terugdraaiing laat nieuwere handmatige of tijdens runtime aangebrachte sessiewijzigingen intact.

Observeerbaarheid en foutoverzichten

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

• geprobeerde provider/model
• reden (rate_limit, overloaded, billing, auth, model_not_found en vergelijkbare redenen voor failover)
• optionele status/code
• voor mensen leesbare samenvatting van de fout

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

Wanneer elke kandidaat mislukt, genereert OpenClaw een FallbackSummaryError. De bovenliggende antwoordrunner kan die gebruiken om een specifiekere melding op te stellen, zoals "voor alle modellen geldt tijdelijk een snelheidslimiet", en het eerstvolgende tijdstip waarop de afkoelperiode afloopt opnemen wanneer dat bekend is.

Die samenvatting van de afkoelperiode houdt rekening met het model:

• niet-gerelateerde, modelgebonden snelheidslimieten worden genegeerd voor de geprobeerde provider/model-keten
• als de resterende blokkering een overeenkomende modelgebonden snelheidslimiet is, rapporteert OpenClaw het laatste overeenkomende verlooptijdstip dat dat model nog 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.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• routering van agents.defaults.imageModel

Zie Modellen voor het bredere overzicht van modelselectie en fallback.