Failover

Failover is about resilience: define a primary model, then one or more fallbacks that OpenClaw can try when the primary fails (rate limits, timeouts, transient provider issues).

See also:

• Costs and tokens
• Model selection
• Model providers

Recommended pattern

1. Pick a strong primary model.
2. Add 1–2 fallbacks that are likely to succeed when the primary fails:
   • different provider
   • different region / gateway
   • different rate-limit profile
3. Keep fallbacks simple until your baseline is stable.

Minimal config example

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.1-codex", "ollama/llama3.3"]
      }
    }
  }
}

Notes:

• If you use agents.defaults.models as an allowlist, include your fallback model ids there as well.
• Local fallbacks are a good “always works” option, but may be slower and weaker on hard tasks.

How to verify

Before relying on failover, confirm all referenced models exist and can be selected:

openclaw models list
openclaw models status

If your fallbacks never trigger when you expect, you may be seeing a “hard failure” (misconfiguration/auth) rather than a retryable provider error.