OpenClaw Model Failover: Keep Your Agent Running When One Provider Breaks

Most agent outages are not glamorous. A token expires. A provider rate-limits you at the worst moment. A billing balance runs dry. A model starts timing out even though your prompts did nothing wrong. If your whole setup depends on one provider staying perfect forever, you do not have an agent system. You have a fragile demo.

OpenClaw is built around a more realistic assumption: providers fail, auth profiles get noisy, and operators still need work to continue. The docs describe a two-stage recovery path. First, OpenClaw rotates auth profiles inside the current provider. If that provider is exhausted, it falls back to the next model in agents.defaults.model.fallbacks.

That split matters. You do not want to jump providers too early when a second credential on the same provider would have solved the problem. You also do not want to stay stuck hammering a dead lane when the next configured model could keep the session moving.

If you are troubleshooting a flaky setup more broadly, read Why Your OpenClaw Agent Is Not Working after this. This post is narrower: how failover actually works, what to configure, and what mistakes I would avoid.

The core failover sequence

The OpenClaw docs define model selection in a simple order:

1. The primary model from agents.defaults.model.primary (or agents.defaults.model)
2. Fallbacks from agents.defaults.model.fallbacks, in order
3. Provider auth failover inside a provider before OpenClaw moves to the next model

That means the first recovery move is usually smaller than people expect. OpenClaw does not immediately abandon a provider after one bad response. It tries another auth profile for that provider first when rotation is possible. Only after provider-level options are exhausted does it move down the model fallback chain.

In practice, that gives you two resilience layers:

• Credential resilience, via auth profile rotation
• Provider or model resilience, via configured model fallbacks

What OpenClaw means by auth profiles

OpenClaw uses auth profiles for both API keys and OAuth tokens. The docs say secrets live in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json with a legacy path at ~/.openclaw/agent/auth-profiles.json. The routing config you write, auth.profiles and auth.order, is metadata and routing only, not the secret store itself.

That separation is healthy. It lets you control routing behavior without pretending config files should be your secret vault.

The docs also define the profile ID pattern clearly:

• provider:default when no email is available
• provider:<email> for OAuth logins that expose an email address

If you have multiple credentials for the same provider, failover is not random. OpenClaw chooses an order based on explicit configuration first, then configured profiles for that provider, then stored profiles. If you do not specify order manually, the default round-robin rules prefer OAuth before API keys and then sort by usageStats.lastUsed with the oldest-used profile first. Cooldown or disabled profiles are pushed to the end.

Why session stickiness matters more than constant rotation

One of the smartest parts of the docs is what they do not recommend. OpenClaw does not rotate credentials on every request just because it can. It pins the chosen auth profile per session to keep provider caches warm.

That pinned profile stays in place until one of a few things happens:

• you reset the session with /new or /reset
• a compaction completes
• the chosen profile is in cooldown or disabled

This is the difference between a failover system and a roulette wheel. Constant credential switching can make behavior noisier and harder to debug. Session stickiness gives you predictable performance until there is an actual reason to move.

There is also a useful distinction in the docs between auto-pinned and user-pinned profiles. If you manually select a profile with /model …@<profileId>, OpenClaw treats that as a user override for the session. When that locked profile fails and fallbacks are configured, OpenClaw moves to the next model instead of switching to a different profile on the same provider.

If you want the full operator playbook for model routing, approvals, memory, and production guardrails, get ClawKit here.

What failures actually trigger rotation or fallback

The docs call out a practical set of failover-worthy cases. OpenClaw puts profiles into cooldown for auth failures, rate-limit errors, and timeouts that look like rate limiting. The same failover path can also apply to invalid-request or format errors that OpenClaw classifies as failover-worthy, plus certain OpenAI-compatible stop-reason errors such as stop reason: error.

Cooldown backoff is exponential:

• 1 minute
• 5 minutes
• 25 minutes
• 1 hour maximum

The stored usage state includes values like lastUsed, cooldownUntil, and errorCount. In other words, OpenClaw remembers what has already failed instead of rediscovering the same pain on every retry.

Billing failures take a different path. The docs say messages like insufficient credits or low credit balance are treated as failover-worthy, but usually not as short-lived transient errors. Instead of a one-minute style cooldown, OpenClaw marks the profile disabled with a much longer backoff and rotates onward.

The default billing backoff starts at five hours, doubles per billing failure, and caps at twenty-four hours. If the profile stays clean for twenty-four hours, the backoff counters reset. That is exactly the kind of operator-friendly behavior I want: fast escape from broken billing, but without permanently poisoning the profile.

A practical config shape

If you want failover, you have to give OpenClaw somewhere to go. That means setting a primary model and an ordered fallback list.

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openai/gpt-5.2",
          "openrouter/moonshotai/kimi-k2"
        ]
      }
    }
  }
}

The exact provider choices are yours. The rule from the docs is the important part: OpenClaw tries the primary first, then the fallback chain in order, while handling auth-profile failover inside each provider before advancing.

The provider quickstart docs are deliberately simple here. First authenticate with the provider, usually through openclaw onboard. Then set the default model as provider/model. If you want a cleaner operational view after setup, openclaw models status shows the resolved primary model, fallbacks, image model, and the auth overview for configured providers.

openclaw onboard
openclaw models status

The allowlist trap that looks like a silent failure

One subtle point from the models docs is worth knowing because it confuses operators all the time. If you set agents.defaults.models, that becomes the allowlist for /model and session overrides. When a user picks a model that is not in that allowlist, OpenClaw returns:

Model "provider/model" is not allowed. Use /model to list available models.

That response happens before a normal reply is generated, which can make it feel like the agent simply stopped responding. It did not. It rejected the selection before the run started.

This matters for failover planning too. If you want clean operator ergonomics, keep your configured fallback models consistent with the models you actually intend to expose and manage. Otherwise you create your own mystery outages.

How to switch and inspect models without restarting everything

OpenClaw supports model switching in-session through /model. The docs show several useful forms:

/model
/model list
/model 3
/model openai/gpt-5.4
/model status

For CLI workflows, the docs also list commands for inspecting and editing model configuration:

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models fallbacks list
openclaw models fallbacks add <provider/model>

If you are running a production agent, that visibility matters. Good failover is not just about automated recovery. It is about operators being able to see the active model policy, confirm auth health, and change course quickly without turning the whole system into a manual firefight.

The setup pattern I would actually use

If I were configuring a serious OpenClaw operator box, I would keep it boring:

• Pick one strong primary model you trust for the best default quality.
• Add at least one fallback from a different provider family.
• Keep multiple auth profiles when a provider account setup justifies it.
• Use auth.order only when you need deterministic preference.
• Check openclaw models status instead of guessing what the runtime sees.

I would also avoid pretending every fallback chain needs five layers. More branches are not automatically more resilient. They are also more surface area, more cost variance, and more weirdness during debugging. Start with one great primary and one or two realistic fallbacks.

If you are building broader operator discipline around your agent, pair this with a clear authority model too. My standing orders guide is about behavioral guardrails, but the same philosophy applies here: decide the recovery lanes in advance so the system is calm when stress hits.

The short version

OpenClaw model failover is not a vague promise. The docs define a real operating path: auth profile rotation inside a provider, cooldowns and billing disables when profiles fail, and model fallback through agents.defaults.model.fallbacks when the provider is exhausted.

That means one broken token, one exhausted account, or one flaky provider does not have to take your agent down with it. But only if you configure the lanes ahead of time.

Do that once, verify it with the models tooling, and your agent stops depending on the fantasy that every provider will behave forever.

Want the complete guide? Get ClawKit — $9.99