Fallback models
Set up a fallback model so your agent keeps working when the primary model hits rate limits or goes down.
What fallback models do
AI providers impose rate limits on how many requests you can make per minute or per day. When your primary model hits a rate limit, your agent stops responding until the limit resets. A fallback model gives the agent an alternative to switch to automatically.
How it works
When you configure a fallback model, the OpenClaw gateway does the following:
- Sends the request to the primary model.
- If the primary returns a rate limit error (429) or is unavailable (5xx), retries with the fallback model.
- If the fallback also fails, returns an error to the chat.
The switch is automatic. Once the primary model's rate limit resets, the agent goes back to using it.
When fallbacks help
Rate limits are common, especially on lower-tier API plans. A busy agent can exhaust them quickly during tasks like code generation or long research sessions.
Providers also have occasional outages. A fallback on a different provider means your agent keeps working through them.
You can also use fallbacks for cost control: run a powerful primary model for complex work, and fall back to a cheaper one when rate-limited. The agent still responds, just with a less capable model temporarily.
Setting up fallbacks
During desktop creation
- Click New Desktop.
- Configure your primary provider and model.
- In the fallback section, select a fallback provider and model.
- Create the desktop.
On an existing desktop
- Open your desktop's settings.
- Add or update the fallback model configuration.
- Restart the desktop.
Recommended combinations
| Primary model | Recommended fallback | Reason |
|---|---|---|
| Claude (Anthropic) | GPT-4o (OpenAI) | Different provider, no shared rate limits |
| GPT-4o (OpenAI) | Claude Sonnet (Anthropic) | Different provider, good at code |
| Any premium model | A smaller model on OpenRouter | Cheap fallback |
The main thing: use a different provider for your fallback. If both primary and fallback are on the same provider, a provider outage takes out both.
Checking fallback activity
If you notice the agent responding with a different model than expected, fallback may have been triggered. You can check the chat panel for any fallback notifications. If fallbacks are happening frequently, consider upgrading your API plan or switching to a provider with higher rate limits.
Tips
- Configure a fallback if your agent runs unattended or on long tasks.
- OpenRouter works well as a fallback provider since one key covers hundreds of models.
- To test your fallback setup, temporarily use an invalid primary key. The agent should switch to the fallback without interruption.
- The fallback model does not need to match the primary in capability. A smaller model is better than no response.