OpenClaw model failover is the part of the Gateway that keeps an agent useful when one provider account, API key, or model route stops answering. That sounds like a simple retry loop. It is not.
The important bit is the order. OpenClaw first rotates auth profiles inside the current provider. If that provider is exhausted by a failover-worthy error, it can move to the next configured model in the fallback list. The fallback answer is for the current turn only. It does not quietly rewrite the session’s selected model for the next message.
That design is more careful than the usual “just fallback to another LLM” pitch. A self-hosted agent may hold credentials, run tools, answer through WhatsApp, work from cron, or operate under a standing order. If failover is too eager, it hides broken config. If it is too strict, a minor rate limit turns into a dead agent. OpenClaw tries to sit in the practical middle.
What OpenClaw model failover actually does
The official docs describe two stages:
- Auth profile rotation within the current provider.
- Model fallback to the next model in `agents.defaults.model.fallbacks`.
Read that twice because it prevents a lot of bad debugging. If your OpenAI account has a ChatGPT/Codex OAuth profile and an API-key backup, OpenClaw can rotate between those auth profiles before it gives up on the OpenAI model route. If every usable profile for that provider is out, disabled, rate-limited, or otherwise exhausted in a way OpenClaw trusts as failover-worthy, then model fallback can advance to the next candidate.
This is not load balancing in the vague dashboard sense. LiteLLM, Portkey, and other AI gateway tools talk about weighted routing, per-status fallback, retries, cooldowns, and tracing. Those are real patterns, and they matter. OpenClaw’s version is shaped by agent sessions. The Gateway needs to know whether the selected model came from config, a cron payload, a user picking `/model`, or a previous automatic fallback. Those sources are not equivalent.
The rule I like: configured automation can be resilient; explicit user selection should be honest.
The runtime flow in plain English
OpenClaw starts each run by resolving the session’s active model and auth preference. Then it builds a candidate chain from the current model plus the fallback policy allowed for that selection source.
After that, the runner tries the current provider with auth-profile rotation and cooldown rules. If a profile fails because of auth, billing, rate limits, timeouts, or other classified failures, OpenClaw can move to the next eligible profile. If the provider is exhausted and the error class allows model fallback, it tries the next model candidate.
If a fallback model wins, it answers the current turn. The session still starts the next turn from the selected primary model. OpenClaw stores enough fallback notice state for `/status` and user-facing transition messages, but it does not treat the fallback as a new permanent model choice.
That small distinction saves operators from mystery behavior. Without it, a provider outage at noon could move an agent to a backup model and leave it there for days. The agent might get slower, more expensive, or less capable, and nobody would know why. Turn-local fallback keeps recovery boring: survive the bad turn, then try the intended model again next time.
Why user model overrides stay strict
OpenClaw treats user model selection as exact intent. If someone uses `/model`, the model picker, `session_status(model=…)`, or `sessions.patch`, the session gets a user-sourced override. If that selected provider/model fails before producing a reply, OpenClaw reports the failure instead of answering from an unrelated configured fallback.
That may feel harsh the first time it happens. It is the right call.
When a user explicitly picks a model, they may be testing it, comparing output, forcing a cheaper route, using a local model for privacy, or checking provider behavior. Silent fallback would poison that test. The user asked for one model and received another.
Cron jobs work differently. A cron job `payload.model` or `–model` is a job primary, not a user session override. It can use configured fallbacks unless the job supplies `payload.fallbacks: []`. That is sensible because scheduled work usually wants completion unless the operator deliberately made it strict. A daily report should not fail just because the first provider had a short overload window, as long as the backup model is compatible with the task.
Auth profile rotation comes before model fallback
OpenClaw’s auth profile system is easy to underestimate. Profiles can represent API keys, OAuth tokens, or static bearer-style tokens. They live in the per-agent SQLite auth profile store, while `auth.profiles` and `auth.order` in config are metadata and routing, not secret storage.
When a provider has multiple profiles, OpenClaw chooses an order. Explicit `auth.order[provider]` wins when it exists. Then configured profiles, then stored profiles. Without an explicit order, it prefers OAuth before static token before API key, puts currently usable OAuth tokens ahead of expired ones, and accounts for last-used time, cooldowns, and disabled profiles.
There is session stickiness too. OpenClaw pins the automatically chosen auth profile per session to keep provider caches warm. It does not rotate keys on every request for sport. It may rotate or clear the automatic pin after a reset, compaction, cooldown, disabled profile, or profile mismatch.
This matters because not every provider failure means the model is bad. Maybe one API key hit a request limit. Maybe one OAuth profile expired. Maybe one backup key has billing disabled. Trying the next same-provider profile can preserve output quality and prompt compatibility better than jumping to a different model family.
Which errors should move the agent to another model
OpenClaw advances fallback for failures that are likely to be fixed by another profile, provider, or model. The docs call out auth failures, rate limits, billing and credit failures, timeouts, overloads, certain server errors, empty responses, malformed response classes, and provider-busy signals.
Vendor error docs back up why this classification matters. Anthropic documents 429 rate limits, 500 API errors, 504 timeouts, and 529 overloads. OpenAI documents 429 rate, credit, spend, and usage-limit errors, plus 500 and 503 server or overload cases. Those are exactly the kinds of events where a backup route can help.
But OpenClaw does not treat every error as a reason to run elsewhere. Format errors, invalid requests, context problems, and failures without enough signal may need to surface. Retrying the same broken payload against another model can make a real bug harder to find.
There is also a special overload path. If every candidate fails only because providers are overloaded, OpenClaw can retry the full turn-local chain up to 10 times with exponential backoff. That only happens before tool execution or assistant output begins. After 30 seconds, it sends one status notice so the user is not left staring at silence.
That guard is not cosmetic. Once a tool has run or a message has started, retrying the whole turn risks duplicate side effects. Good failover is not just “try harder.” It knows when trying again would make a mess.
How to configure a practical fallback chain
For the default agent model, the core shape lives under `agents.defaults.model`:
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: [
"openai/gpt-5.6-sol",
"google/gemini-3-pro"
]
}
}
}
}Use real model refs available in your OpenClaw install; the exact catalog depends on your provider plugins and account access. The broader provider docs use the `provider/model` format and point operators to `openclaw models list`, `openclaw models set
A good fallback chain is not just a list of famous models. It should preserve the job’s needs:
- Keep tool-call quality high for agents that use tools heavily.
- Keep context window large enough for your normal sessions.
- Avoid backup models that refuse your routine workload in different ways.
- Watch price and latency because a fallback turn may call more than one provider.
- Use `fallbacks: []` when strict behavior is the safer operational choice.
Agent entries deserve their own decision. An `agents.entries.*.model` value is strict unless that agent’s model object includes its own `fallbacks`. Use an empty array when you want to make the strict behavior explicit. Use a non-empty list when that agent owns work where continuity matters more than exact model identity.
Local models as a fallback, not a fantasy safety net
The OpenClaw local-model docs show a hybrid pattern: a hosted primary with a local LM Studio model as fallback, or the reverse for local-first setups with hosted backup. That is useful. It is not magic.
Local fallback makes sense when the backup model can actually do the job. The docs are blunt about hardware: small or heavily quantized models can truncate context and skip provider-side safety filters. A single 24 GB GPU is described as suitable for lighter prompts at higher latency, while a comfortable agent loop may need much heavier hardware.
So do not add a local fallback because it sounds independent. Add it because you have tested the exact agent workload on that local backend. Confirm it can handle the context, tool format, latency, and safety posture you need.
The local docs also recommend keeping `models.mode: “merge”` so hosted models remain available as fallbacks. That is the right mental model. Local hosting is a route in the chain, not a religion.
What operators see during fallback
Outside group and channel conversations, OpenClaw sends a visible notice when a turn moves onto an automatic fallback:
Model Fallback: <fallback> (selected <primary>; <reason>)When a later turn succeeds on the selected primary again, it sends a cleared notice:
Model Fallback cleared: <primary> (was <fallback>)Group and channel conversations keep the same lifecycle state without posting those visible notices. The point is to avoid clutter in shared channels while preserving the operational record.
The `/status` view can show the selected model and, when fallback state differs, the active fallback model and reason. When every candidate fails, OpenClaw throws a `FailoverError` with structured attempt records and can include the soonest cooldown expiry when one is known.
That observability is where OpenClaw’s design earns trust. A fallback that hides itself is a future incident report. A fallback that tells you what happened, once, gives the operator enough context without turning every transient hiccup into noise.
Common OpenClaw model failover mistakes
Putting weak models in the fallback list
A fallback model must be compatible with the work. If your agent depends on long context, reliable tool calls, image input, or a specific reasoning profile, test those before adding the model to production fallback.
Expecting manual `/model` picks to fallback
Manual selection is strict by design. If you picked the model, OpenClaw assumes you meant it. Use configured defaults, cron payload fallbacks, or agent-specific fallback objects when you want automatic recovery.
Treating auth failure and model failure as the same problem
They are separate. Rotate same-provider auth profiles first. Jumping across models because one key hit a limit can degrade quality for no reason.
Letting fallback hide billing problems
Billing and credit failures can be failover-worthy, but they are usually not transient. OpenClaw may disable the failing profile for a longer backoff. The operator still needs to fix the billing state.
Ignoring the cost of a chain
Fallback can mean more than one provider attempt in one user turn. Portkey’s docs make the same warning: fallback targets may differ in latency and pricing. Build the chain with that in mind.
FAQ about OpenClaw model failover
Does OpenClaw model failover permanently switch my session model?
No. Runtime fallback is turn-local. The next turn starts from the selected primary again, though OpenClaw keeps enough notice state for status and transition messages.
Where do I configure default model fallbacks?
Use `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`, or manage the default models through Settings -> Model Providers in the Control UI.
Can an agent have its own fallback list?
Yes. An agent primary is strict unless its model object includes `fallbacks`. Use `fallbacks: []` for explicit strict mode or a non-empty list to opt that agent into fallback.
Do cron jobs use model fallbacks?
Yes, a cron `payload.model` or `–model` is a job primary and can use configured fallbacks. A cron payload can also provide its own fallback list, and `payload.fallbacks: []` makes the run strict.
Should I put a local model in my fallback chain?
Only if you have tested it with the real agent workload. Local models can be useful backups, but small or heavily quantized models may struggle with context, tools, and safety-sensitive prompts.
What happens if every provider is overloaded?
If every candidate fails only from overload and no tool execution or assistant output has started, OpenClaw can retry the full chain up to 10 times with exponential backoff and send a status notice after 30 seconds.
Build the boring fallback path before the outage
Model failover is not where you want surprises. Pick a primary, add compatible fallbacks, test each candidate with the same tools and context your agent uses, and decide which sessions should stay strict.
For OpenClaw operators, the best setup is usually boring: rotate auth profiles first, fallback across models only for classified failures, keep manual user picks honest, and make recovery visible without spamming every channel.
If you run self-hosted agents, do this work before the provider outage, not during it. OpenClaw gives you the hooks. Your job is to choose backup models that can actually carry the run.
