Modelfailover

1. Rotatie van auth-profielen binnen de huidige provider.
2. Model fallback naar het volgende model in agents.defaults.model.fallbacks.

​

Runtime-flow

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

​

Beleid voor selectiebron

• Geconfigureerde standaardwaarde: agents.defaults.model.primary gebruikt agents.defaults.model.fallbacks.
• Primaire agent: agents.list[].model is strikt tenzij dat agentmodelobject zijn eigen fallbacks bevat. Gebruik fallbacks: [] om het strikte gedrag expliciet te maken, of geef een niet-lege lijst op om die agent model fallback te laten gebruiken.
• Automatische fallback-override: een runtime-fallback schrijft providerOverride, modelOverride, modelOverrideSource: "auto" en het geselecteerde oorsprongsmodel voordat opnieuw wordt geprobeerd. Die automatische override kan de geconfigureerde fallback-keten blijven doorlopen zonder bij elk bericht de primaire te testen, maar OpenClaw test periodiek opnieuw de geconfigureerde oorsprong en wist de automatische override wanneer die herstelt. /new, /reset en sessions.reset wissen ook automatisch afkomstige overrides. Heartbeat-runs zonder expliciete heartbeat.model wissen directe automatische overrides wanneer hun oorsprong niet langer overeenkomt met de huidige geconfigureerde standaardwaarde.
• 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 faalt voordat er een antwoord wordt geproduceerd, meldt OpenClaw de fout in plaats van te antwoorden vanuit 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 in fallback-gedrag.
• Cron-payloadmodel: een cronjob payload.model / --model is een primaire job, geen gebruikerssessie-override. Het gebruikt geconfigureerde fallbacks tenzij de job payload.fallbacks levert; payload.fallbacks: [] maakt de cron-run strikt.

​

Skipcache voor auth-fouten

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

Gebruikerszichtbare fallback-meldingen

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

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

​

Auth-opslag (sleutels + OAuth)

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

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

​

Profiel-id’s

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

​

Rotatievolgorde

• Primaire sleutel: profieltype (OAuth vóór API-sleutels).
• Secundaire sleutel: usageStats.lastUsed (oudste eerst, binnen elk type).
• Cooldown-/uitgeschakelde profielen worden naar het einde verplaatst, geordend op de eerstvolgende vervaltijd.

​

Sessiestickiness (cachevriendelijk)

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

​

OpenAI Codex-abonnement plus API-sleutelback-up

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

​

Cooldowns

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

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

​

Facturering schakelt uit

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

• Backoff voor facturering begint bij 5 uur, verdubbelt per factureringsfout en kapt af op 24 uur.
• Backoff-tellers worden gereset als het profiel 24 uur niet is mislukt (configureerbaar).
• Overbelaste retries staan 1 profielrotatie bij dezelfde provider toe vóór modelfallback.
• Overbelaste retries gebruiken standaard 0 ms backoff.

​

Modelfallback

​

Regels voor kandidaatketen

​

Welke fouten fallback laten doorgaan

​

Cooldown overslaan versus probe-gedrag

​

Sessie-overrides en live modelschakeling

• Alleen expliciete door de gebruiker gestuurde modelwijzigingen markeren een pending live switch. Dat omvat /model, session_status(model=...) en sessions.patch.
• Door het systeem gestuurde modelwijzigingen zoals fallback-rotatie, heartbeat-overrides of compaction markeren nooit uit zichzelf een pending live switch.
• Door de gebruiker gestuurde modeloverrides worden behandeld als exacte selecties voor fallbackbeleid, zodat een onbereikbare geselecteerde provider als fout verschijnt in plaats van te worden gemaskeerd door agents.defaults.model.fallbacks.
• Voordat een fallback-retry start, slaat de reply-runner de geselecteerde fallback-overridevelden op in de sessie-entry.
• Automatische fallback-overrides blijven geselecteerd tijdens volgende beurten, zodat OpenClaw niet bij elk bericht een bekende slechte primaire waarde probeit. OpenClaw probeit periodiek opnieuw de geconfigureerde oorsprong en wist de automatische override wanneer die herstelt; /new, /reset en sessions.reset wissen automatisch afkomstige overrides direct.
• Gebruikersantwoorden kondigen fallback-overgangen en herstel waarbij fallback is gewist één keer per statuswijziging aan. Sticky fallback-beurten herhalen de melding niet.
• /status toont het geselecteerde model en, wanneer fallbackstatus verschilt, het actieve fallbackmodel en de reden.
• Live-sessiereconciliatie geeft de voorkeur aan opgeslagen sessie-overrides boven verouderde runtimemodelvelden.
• Als een live-switch-fout wijst naar een latere kandidaat in de actieve fallback-keten, springt OpenClaw direct naar dat geselecteerde model in plaats van eerst niet-gerelateerde kandidaten te doorlopen.
• Als de fallbackpoging mislukt, rolt de runner alleen de overridevelden terug die hij schreef, en alleen als ze nog steeds overeenkomen met die mislukte kandidaat.

​

Observeerbaarheid en foutoverzichten

• provider/model geprobeerd
• reden (rate_limit, overloaded, billing, auth, model_not_found en vergelijkbare failover-redenen)
• optionele status/code
• menselijk leesbare foutsamenvatting

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

​

Gerelateerde configuratie

• 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