Use this file to discover all available pages before exploring further.

Model failover

OpenClaw handles failures in two stages:

Auth profile rotation within the current provider.
Model fallback to the next model in
text
agents.defaults.model.fallbacks
.

This doc explains the runtime rules and the data that backs them.

Runtime flow

For a normal text run, OpenClaw evaluates candidates in this order:

Resolve session state

Resolve the active session model and auth-profile preference.

Build candidate chain

Build the model candidate chain from the current model selection and the fallback policy for that selection source. Configured defaults, cron job primaries, and auto-selected fallback models can use configured fallbacks; explicit user session selections are strict.

Try the current provider

Try the current provider with auth-profile rotation/cooldown rules.

Advance on failover-worthy errors

If that provider is exhausted with a failover-worthy error, move to the next model candidate.

Persist fallback override

Persist the selected fallback override before the retry starts so other session readers see the same provider/model the runner is about to use. The persisted model override is marked `modelOverrideSource: "auto"`.

Roll back narrowly on failure

If the fallback candidate fails, roll back only the fallback-owned session override fields when they still match that failed candidate.

Throw FallbackSummaryError if exhausted

If every candidate fails, throw a `FallbackSummaryError` with per-attempt detail and the soonest cooldown expiry when one is known.

This is intentionally narrower than "save and restore the whole session". The reply runner only persists the model-selection fields it owns for fallback:

text
providerOverride
text
modelOverride
text
modelOverrideSource
text
authProfileOverride
text
authProfileOverrideSource
text
authProfileOverrideCompactionCount

That prevents a failed fallback retry from overwriting newer unrelated session mutations such as manual

text

/model

changes or session rotation updates that happened while the attempt was running.

Selection source policy

OpenClaw separates the selected provider/model from why it was selected. That source controls whether the fallback chain is allowed:

Configured default:
text
agents.defaults.model.primary
uses
text
agents.defaults.model.fallbacks
.
Agent primary:
text
agents.list[].model
is strict unless that agent model object includes its own
text
fallbacks
. Use
text
fallbacks: []
to make the strict behavior explicit, or provide a non-empty list to opt that agent into model fallback.
Auto fallback override: a runtime fallback writes
text
providerOverride
,
text
modelOverride
, and
text
modelOverrideSource: "auto"
before retrying. That auto override can keep walking the configured fallback chain and is cleared by
text
/new
,
text
/reset
, and
text
sessions.reset
.
User session override:
text
/model
, the model picker,
text
session_status(model=...)
, and
text
sessions.patch
write
text
modelOverrideSource: "user"
. That is an exact session selection. If the selected provider/model fails before producing a reply, OpenClaw reports the failure instead of answering from an unrelated configured fallback.
Legacy session override: older session entries may have
text
modelOverride
without
text
modelOverrideSource
. OpenClaw treats those as user overrides so an explicit old selection is not silently converted into fallback behavior.
Cron payload model: a cron job
text
payload.model
/
text
--model
is a job primary, not a user session override. It uses configured fallbacks unless the job provides
text
payload.fallbacks
;
text
payload.fallbacks: []
makes the cron run strict.

Auth storage (keys + OAuth)

OpenClaw uses auth profiles for both API keys and OAuth tokens.

Secrets live in
text
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
(legacy:
text
~/.openclaw/agent/auth-profiles.json
).
Runtime auth-routing state lives in
text
~/.openclaw/agents/<agentId>/agent/auth-state.json
.
Config
text
auth.profiles
/
text
auth.order
are metadata + routing only (no secrets).
Legacy import-only OAuth file:
text
~/.openclaw/credentials/oauth.json
(imported into
text
auth-profiles.json
on first use).

More detail: OAuth

Credential types:

text
type: "api_key"
→
text
{ provider, key }
text
type: "oauth"
→
text
{ provider, access, refresh, expires, email? }
(+
text
projectId
/
text
enterpriseUrl
for some providers)

Profile IDs

OAuth logins create distinct profiles so multiple accounts can coexist.

Default:
text
provider:default
when no email is available.
OAuth with email:
text
provider:<email>
(for example
text
google-antigravity:user@gmail.com
).

Profiles live in

text

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

under

text

profiles

Rotation order

When a provider has multiple profiles, OpenClaw chooses an order like this:

Explicit config

`auth.order[provider]` (if set).

Configured profiles

`auth.profiles` filtered by provider.

Stored profiles

Entries in `auth-profiles.json` for the provider.

If no explicit order is configured, OpenClaw uses a round‑robin order:

Primary key: profile type (OAuth before API keys).
Secondary key:
text
usageStats.lastUsed
(oldest first, within each type).
Cooldown/disabled profiles are moved to the end, ordered by soonest expiry.

Session stickiness (cache-friendly)

OpenClaw pins the chosen auth profile per session to keep provider caches warm. It does not rotate on every request. The pinned profile is reused until:

the session is reset (
text
/new
/
text
/reset
)
a compaction completes (compaction count increments)
the profile is in cooldown/disabled

Manual selection via

text

/model …@<profileId>

sets a user override for that session and is not auto-rotated until a new session starts.

note

Auto-pinned profiles (selected by the session router) are treated as a **preference**: they are tried first, but OpenClaw may rotate to another profile on rate limits/timeouts. User-pinned profiles stay locked to that profile; if it fails and model fallbacks are configured, OpenClaw moves to the next model instead of switching profiles.

Why OAuth can "look lost"

If you have both an OAuth profile and an API key profile for the same provider, round‑robin can switch between them across messages unless pinned. To force a single profile:

Pin with
text
auth.order[provider] = ["provider:profileId"]
, or
Use a per-session override via
text
/model …
with a profile override (when supported by your UI/chat surface).

Cooldowns

When a profile fails due to auth/rate-limit errors (or a timeout that looks like rate limiting), OpenClaw marks it in cooldown and moves to the next profile.

Cooldowns use exponential backoff:

1 minute
5 minutes
25 minutes
1 hour (cap)

State is stored in

text

auth-state.json

under

text

usageStats


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

Billing disables

Billing/credit failures (for example "insufficient credits" / "credit balance too low") are treated as failover-worthy, but they're usually not transient. Instead of a short cooldown, OpenClaw marks the profile as disabled (with a longer backoff) and rotates to the next profile/provider.

note

Not every billing-shaped response is `402`, and not every HTTP `402` lands here. OpenClaw keeps explicit billing text in the billing lane even when a provider returns `401` or `403` instead, but provider-specific matchers stay scoped to the provider that owns them (for example OpenRouter `403 Key limit exceeded`).

Meanwhile temporary

text

402

usage-window and organization/workspace spend-limit errors are classified as

text

rate_limit

when the message looks retryable (for example

text

weekly usage limit exhausted

text

daily limit reached, resets tomorrow

, or

text

organization spending limit exceeded

). Those stay on the short cooldown/failover path instead of the long billing-disable path.

State is stored in

text

auth-state.json


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

Defaults:

Billing backoff starts at 5 hours, doubles per billing failure, and caps at 24 hours.
Backoff counters reset if the profile hasn't failed for 24 hours (configurable).
Overloaded retries allow 1 same-provider profile rotation before model fallback.
Overloaded retries use 0 ms backoff by default.

Model fallback

If all profiles for a provider fail, OpenClaw moves to the next model in

text

agents.defaults.model.fallbacks

. This applies to auth failures, rate limits, and timeouts that exhausted profile rotation (other errors do not advance fallback). Provider errors that do not expose enough detail are still labeled precisely in fallback state:

text

empty_response

means the provider returned no usable message or status,

text

no_error_details

means the provider explicitly returned

text

Unknown error (no error details in response)

, and

text

unclassified

means OpenClaw preserved the raw preview but no classifier matched it yet.

Overloaded and rate-limit errors are handled more aggressively than billing cooldowns. By default, OpenClaw allows one same-provider auth-profile retry, then switches to the next configured model fallback without waiting. Provider-busy signals such as

text

ModelNotReadyException

land in that overloaded bucket. Tune this with

text

auth.cooldowns.overloadedProfileRotations

text

auth.cooldowns.overloadedBackoffMs

, and

text

auth.cooldowns.rateLimitedProfileRotations

When a run starts from the configured default primary, a cron job primary, an agent primary with explicit fallbacks, or an auto-selected fallback override, OpenClaw can walk the matching configured fallback chain. Agent primaries without explicit fallbacks and explicit user selections (for example

text

/model ollama/qwen3.5:27b

, the model picker,

text

sessions.patch

, or one-off CLI provider/model overrides) are strict: if that provider/model is unreachable or fails before producing a reply, OpenClaw reports the failure instead of answering from an unrelated fallback.

Candidate chain rules

OpenClaw builds the candidate list from the currently requested

text

provider/model

plus configured fallbacks.

Which errors advance fallback

* auth failures * rate limits and cooldown exhaustion * overloaded/provider-busy errors * timeout-shaped failover errors * billing disables * `LiveSessionModelSwitchError`, which is normalized into a failover path so a stale persisted model does not create an outer retry loop * other unrecognized errors when there are still remaining candidates * explicit aborts that are not timeout/failover-shaped * context overflow errors that should stay inside compaction/retry logic (for example `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model`, or `ollama error: context length exceeded`) * a final unknown error when there are no candidates left

Cooldown skip vs probe behavior

When every auth profile for a provider is already in cooldown, OpenClaw does not automatically skip that provider forever. It makes a per-candidate decision:

Session overrides and live model switching

Session model changes are shared state. The active runner,

text

/model

command, compaction/session updates, and live-session reconciliation all read or write parts of the same session entry.

That means fallback retries have to coordinate with live model switching:

Only explicit user-driven model changes mark a pending live switch. That includes
text
/model
,
text
session_status(model=...)
, and
text
sessions.patch
.
System-driven model changes such as fallback rotation, heartbeat overrides, or compaction never mark a pending live switch on their own.
User-driven model overrides are treated as exact selections for fallback policy, so an unreachable selected provider surfaces as a failure instead of being masked by
text
agents.defaults.model.fallbacks
.
Before a fallback retry starts, the reply runner persists the selected fallback override fields to the session entry.
Auto fallback overrides remain selected on subsequent turns so OpenClaw does not probe a known-bad primary on every message.
text
/new
,
text
/reset
, and
text
sessions.reset
clear auto-sourced overrides and return the session to the configured default.
text
/status
shows the selected model and, when fallback state differs, the active fallback model and reason.
Live-session reconciliation prefers persisted session overrides over stale runtime model fields.
If a live-switch error points at a later candidate in the active fallback chain, OpenClaw jumps directly to that selected model instead of walking unrelated candidates first.
If the fallback attempt fails, the runner rolls back only the override fields it wrote, and only if they still match that failed candidate.

This prevents the classic race:

Primary fails

The selected primary model fails.

Fallback chosen in memory

Fallback candidate is chosen in memory.

Session store still says old primary

Session store still reflects the old primary.

Live reconciliation reads stale state

Live-session reconciliation reads the stale session state.

Retry snapped back

The retry gets snapped back to the old model before the fallback attempt starts.

The persisted fallback override closes that window, and the narrow rollback keeps newer manual or runtime session changes intact.

Observability and failure summaries

text

runWithModelFallback(...)

records per-attempt details that feed logs and user-facing cooldown messaging:

provider/model attempted
reason (
text
rate_limit
,
text
overloaded
,
text
billing
,
text
auth
,
text
model_not_found
, and similar failover reasons)
optional status/code
human-readable error summary

Structured

text

model_fallback_decision

logs also include flat

text

fallbackStep*

fields when a candidate fails, is skipped, or a later fallback succeeds. These fields make the attempted transition explicit (

text

fallbackStepFromModel

text

fallbackStepToModel

text

fallbackStepFromFailureReason

text

fallbackStepFromFailureDetail

text

fallbackStepFinalOutcome

) so log and diagnostic exporters can reconstruct the primary failure even when the terminal fallback also fails.

When every candidate fails, OpenClaw throws

text

FallbackSummaryError

. The outer reply runner can use that to build a more specific message such as "all models are temporarily rate-limited" and include the soonest cooldown expiry when one is known.

That cooldown summary is model-aware:

unrelated model-scoped rate limits are ignored for the attempted provider/model chain
if the remaining block is a matching model-scoped rate limit, OpenClaw reports the last matching expiry that still blocks that model

Related config

See Gateway configuration for:

text
auth.profiles
/
text
auth.order
text
auth.cooldowns.billingBackoffHours
/
text
auth.cooldowns.billingBackoffHoursByProvider
text
auth.cooldowns.billingMaxHours
/
text
auth.cooldowns.failureWindowHours
text
auth.cooldowns.overloadedProfileRotations
/
text
auth.cooldowns.overloadedBackoffMs
text
auth.cooldowns.rateLimitedProfileRotations
text
agents.defaults.model.primary
/
text
agents.defaults.model.fallbacks
text
agents.defaults.imageModel
routing

See Models for the broader model selection and fallback overview.

OpenClaw Docs

Model failover

Runtime flow

Resolve session state

Build candidate chain

Try the current provider

Advance on failover-worthy errors

Persist fallback override

Roll back narrowly on failure

Throw FallbackSummaryError if exhausted

Selection source policy

Auth storage (keys + OAuth)

Profile IDs

Rotation order

Explicit config

Configured profiles

Stored profiles

Session stickiness (cache-friendly)

note

Why OAuth can "look lost"

Cooldowns

Billing disables

note

Model fallback

Candidate chain rules

Which errors advance fallback

Cooldown skip vs probe behavior

Session overrides and live model switching

Primary fails

Fallback chosen in memory

Session store still says old primary

Live reconciliation reads stale state

Retry snapped back

Observability and failure summaries

Related config