OpenClaw model failover

When a model call fails, OpenClaw does not simply try the next model. The docs describe two stages: auth-profile rotation within the current provider, then model fallback to the next entry in the configured fallbacks list, and before either a bounded same-model recovery for temporary rate limits and provider failures that continues the existing transcript and keeps completed work. Here is the runtime flow, the difference between a configured default and a model you picked in chat, why the fallback never changes your selection, and the two stops that look like failures and are not.

Fallback execution is turn-local.

The runtime flow

• Resolve the session’s model and auth-profile preference, then build the candidate chain from the current selection and the fallback policy for its source: configured defaults, cron primaries and auto-selected fallbacks may use the configured fallbacks; an explicit user selection is strict.
• Try the current provider with its rotation and cooldown rules, applying bounded recovery to eligible transient failures first; a retry status shows the wait and attempt count, and cancellation stays available.
• On a failover-worthy error with the provider exhausted, advance to the next model candidate and run it for this turn without changing the session’s selected provider or model.
• If every candidate fails, surface the terminal failure with per-attempt details and the soonest cooldown expiry when one is known.

Strict versus configured

A model you select in chat is strict: if that provider or model becomes unavailable, the reply fails visibly instead of sliding to a fallback, which is the behaviour you want when you asked for a specific model on purpose. Configured defaults and scheduled runs use the chain. The reply runner persists only a fallback notice, so the status command and transition notices can tell the selected model from the model that answered, and the next turn starts from your selection again. Thinking-level recovery applies only when the provider names a reasoning parameter; account restrictions and unsupported options keep their original classification and are not retried with thinking off.

Stops that are not failures

• When a run reaches its final timeout, or the idle-timeout cost-runaway breaker returns a terminal error, the fallback chain stops and the decision log records why; these are terminal stops, not requests to try another model, and the run deadline and cost limits still apply.
• A locked model selection reaches the runner as an empty fallback list, and every policy honours that the same way.
• The docs also describe a narrow automatic escalation for one structured provider refusal category on a specific route; it is turn-local, off for strict selections, and never sends ordinary failures to another model.

OpenClaw models and providers explains references and the aliases the chain is built from, and OpenClaw request timed out the errors that trigger recovery in the first place.

Why it matters for the bill

A fallback chain is a cost decision as much as a reliability one: the model that answers a turn may not be the one you priced. What OpenClaw costs is where the monthly number lives.

On Diali

On Diali the chain is configured for you across the managed catalog, so a provider outage becomes a fallback notice rather than a silent assistant, and the model you chose stays the one the next turn starts from. Hosted OpenClaw on Diali is the assistant.

• Rotate profiles first, then fall back to the next model.
• A chat-selected model is strict; configured defaults use the chain.
• Fallback answers one turn and never rewrites your selection.