Table of contents
Why Use Failover?
Failover provides:
- Reliability: Automatic switch on outages
- Cost control: Fallback to cheaper models
- Rate limit handling: Continue work during limits
How It Works
When the primary model fails:
- OpenClaw detects the error (HTTP 429/5xx, auth failure, etc.)
- It retries with the next model in the list
- Once the primary recovers, it switches back
Configure Failover
Edit ~/.openclaw/openclaw.json:
{
"agent": {
"model": "anthropic/claude-opus-4-6",
"modelFailover": [
"openai/gpt-4o",
"local/llama3-70b"
]
}
}You can also set per-provider failover:
{
"models": {
"anthropic": {
"model": "claude-opus-4-6",
"failover": ["openai/gpt-4o"]
},
"openai": {
"model": "gpt-4o",
"failover": ["local/llama3-70b"]
}
}
}Testing Failover
To test:
- Temporarily break the primary (e.g., revoke API key)
- Run an agent command
- Observe logs for “Falling back to…”
- Restore the primary and verify switchback
Next Steps
FAQ
Q: Does failover work with local models?
A: Yes. You can failover from cloud to local, or between local models.
Q: Can I weight models?
A: Not directly. Use failover and custom routing logic in a skill if needed.
Q: What if all models fail?
A: OpenClaw will log the error and stop. Configure monitoring to alert.
Q: How do I know which model was used?
A: Check the dashboard session logs or CLI output.