Configure OpenClaw Model and Auth Failover Strategies

We’ve all been there: you’re running a complex automation and suddenly the API key hits a rate limit. Or maybe you forgot to top up your credits and the whole process crashes. It’s frustrating to handle these interruptions manually when you just want your code to work.

OpenClaw handles these failures automatically in two stages. First, it tries auth profile rotation within your current provider. If that doesn’t work, it moves to model fallback using the next model you’ve set in agents.defaults.model.fallbacks. Here is how the runtime rules and data work.

Auth storage (keys + OAuth)

OpenClaw uses auth profiles for both API keys and OAuth tokens.

Secrets live in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (or the legacy path: ~/.openclaw/agent/auth-profiles.json). Your config files for auth.profiles and auth.order only handle metadata and routing, so no secrets are stored there. If you have a legacy OAuth file at ~/.openclaw/credentials/oauth.json, it gets imported into auth-profiles.json the first time you use it.

You can find more detail here: /concepts/oauth

Credential types look like this:

type: "api_key" → { provider, key }

type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl for some providers)

Profile IDs

OAuth logins create distinct profiles so you can use multiple accounts at the same time.

• Default: provider:default when no email is available.
• OAuth with email: provider:<email> (for example google-antigravity:user@gmail.com).

These profiles are stored in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json under the profiles key.

Rotation order

When a provider has multiple profiles, OpenClaw picks an order based on these priorities:

1. Explicit config and configured profiles: It checks auth.order[provider] first, then auth.profiles filtered by provider.
2. Stored profiles: It looks at entries in auth-profiles.json for that provider.

If you don’t set an explicit order, OpenClaw uses a round‑robin system. It uses the profile type as the primary key (OAuth comes before API keys) and usageStats.lastUsed as the secondary key (oldest first). Any profiles in cooldown or disabled states move to the end, ordered by which one expires soonest.

Session stickiness (cache-friendly)

OpenClaw pins the chosen auth profile per session to keep provider caches warm. It does not rotate on every request. The pinned profile stays active until:

• You reset the session (/new or /reset).
• A compaction completes.
• The profile enters cooldown or becomes disabled.
• A new session starts.

If you manually select a model via /model …@<profileId>, you create a user override. This stays locked for that session and won’t auto-rotate. Auto-pinned profiles chosen by the router are just a preference. OpenClaw tries them first but can rotate if it hits rate limits. User-pinned profiles are different; if they fail and you have fallbacks, OpenClaw moves to the next model instead of switching profiles.

Why OAuth can “look lost”

If you have an OAuth profile and an API key for the same provider, round‑robin might switch between them. To keep things consistent, you should:

• Pin it with auth.order[provider] = ["provider:profileId"].
• Use a per-session override via /model … with a profile override.

Cooldowns

When a profile fails because of auth errors, rate limits, or certain timeouts, OpenClaw puts it in cooldown and tries the next one. This also applies to format errors, like Cloud Code Assist tool call failures. OpenAI-compatible errors like Unhandled stop reason: error, stop reason: error, and reason: error also trigger this.

Cooldowns use exponential backoff:

• 1 minute
• 5 minutes
• 25 minutes
• 1 hour (cap)

The state is tracked in auth-profiles.json:

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

Billing disables

Billing or credit failures are usually not temporary. Instead of a short cooldown, OpenClaw marks the profile as disabled and moves to the next profile or provider.

This state is also in auth-profiles.json:

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

Here are the defaults:

• Billing backoff starts at 5 hours, doubles each time, and caps at 24 hours.
• Backoff counters reset if there are no failures for 24 hours.
• Overloaded retries allow 1 same-provider profile rotation before switching models.
• Overloaded retries use a 0 ms backoff by default.

Model fallback

If every profile for a provider fails, OpenClaw switches to the next model in agents.defaults.model.fallbacks. This happens for auth failures, rate limits, timeouts, or exhausted rotations.

OpenClaw handles overloaded and rate-limit errors aggressively. It usually allows one retry within the same provider before switching to the next model fallback. You can tune this behavior using auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, and auth.cooldowns.rateLimitedProfileRotations.

If you start a run with a model override, fallbacks will still eventually end at agents.defaults.model.primary.

Related config

Check the Gateway configuration for these settings:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel routing

For a broader look at how models are selected, see Models.

Next Steps

• Gateway configuration
• Models
• OAuth Concepts

AI Setup Assistant