Back to Knowledge Base
Reliability

What happens if one model fails?

OpenClaw is designed for resiliency. It automatically detects failures and rotates through keys or fallback models to keep your agents running.

When a model request fails (due to rate limits, outages, or auth errors), OpenClaw triggers a two-stage recovery process to ensure your message gets a response.

1

Auth Profile Rotation

First, it tries other API keys or profiles for the same provider. If Key A is rate-limited, it automatically switches to Key B.

2

Model Fallback

If all keys for the primary model fail, it moves to the next model in your fallbacks list (e.g., from Claude Opus to GPT-4).

Configuring Fallbacks

You can define a list of fallback models in your configuration. OpenClaw will try them in order until one succeeds.

Example Configuration

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: {
        // Primary model to try first
        primary: "anthropic/claude-opus-4-6",
        
        // List of models to try if primary fails
        fallbacks: [
          "anthropic/claude-sonnet-4-5",
          "openai/gpt-5.2",
          "zai/glm-4.7"
        ]
      }
    }
  }
}

What triggers a failover?

Failover is designed to catch infrastructure and quota issues, not user errors. It triggers on:

  • Rate Limits (429): When you've hit the TPM/RPM limit for a key.
  • Timeouts: If the model doesn't respond within the configured timeout window.
  • Auth Errors (401/403): If a key is expired or invalid.
  • Server Errors (5xx): If the provider API is down.

If all configured models and profiles fail, OpenClaw will finally report an error to the user ("All models failed"), but this is rare with a properly configured fallback chain.