Model Fallback Guide

Set up automatic model switching so your agent never goes dark when a provider hits its limit.

Last updated: March 23, 2026

The Problem (and Why It Happens)
How Fallback Actually Works
Full Walkthrough: Claude Subscription + API Key + Kimi
Verify Everything Works
Per-Agent Fallback Chains
Common Mistakes That Break Fallback
Reading Fallback Events in Logs

1. The Problem (and Why It Happens)

You set up three models: Claude via OAuth (subscription), Claude Sonnet via API key ($200 credit), and Kimi 128K as a backup. Your primary Claude hits the rate limit. The agent stops. It never tries Sonnet or Kimi.

Why? Because having multiple models configured as providers tells OpenClaw those models exist. It does not tell OpenClaw to try them in order when one fails. That requires a separate config: the fallback chain.

The Mental Model

Providers = "these models are available and here's how to authenticate."

Fallbacks = "when the primary fails, try these in this order."

Without the fallback chain, each provider is an island. The agent uses the primary and has nowhere to go when it fails.

2. How Fallback Actually Works

When your primary model returns a rate limit (429), timeout, or connection error, OpenClaw does this:

Detects the error is retryable (not a bad request or auth failure).
Moves to the next model in the fallbacks array.
Sends the same request to the fallback model.
If that also fails with a retryable error, tries the next fallback.
If all fallbacks fail, the request errors out.

Important: Per-Request, Not Permanent

Fallback is per-request. Each new message starts from the primary model again. Once your primary's rate limit resets, it goes back to using it. The agent doesn't permanently switch.

What counts as retryable: Rate limits (429), server errors (5xx), connection timeouts, network errors.

What does NOT trigger fallback: Invalid API key (401/403), bad request format (400), billing/quota hard stops. These are config problems, not temporary failures. Fix them, don't fall back from them.

3. Full Walkthrough: Claude Subscription + API Key + Kimi

This is the exact setup for the most common scenario: Claude subscription as primary, paid API as first backup, different provider as last resort.

Step 1: Set Up Your Providers

You need three working auth paths. Each one must be independently configured and tested.

Provider 1: Anthropic (Subscription / OAuth)

If you already use Claude via subscription, this is already set up. It was configured during onboarding. You can verify:

openclaw models status --probe --probe-provider anthropic

You should see a profile like anthropic:default with mode token or oauth showing as valid.

Provider 2: Anthropic (API Key)

This is a separate auth profile for the same provider. The critical point: it uses a different credential with a different rate limit pool.

# Add the API key as a new auth profile
openclaw models auth paste-token --provider anthropic --profile-id anthropic:api-backup

Or if you have the key as an environment variable:

# In your openclaw.json env block:
{
  "env": {
    "ANTHROPIC_API_KEY_BACKUP": "sk-ant-api03-..."
  }
}

Same Provider, Different Credentials

OpenClaw supports multiple auth profiles for the same provider. Your subscription token and your API key are separate profiles under the anthropic provider. They have separate rate limits because they use different billing accounts.

If both credentials are on the same Anthropic account, they may share the same rate limit pool, which defeats the purpose.

Provider 3: Kimi (Moonshot)

This is a completely separate provider with its own API key and endpoint.

# Via onboarding wizard:
openclaw onboard --auth-choice moonshot-api-key

# Or manual config in openclaw.json:
{
  "env": {
    "MOONSHOT_API_KEY": "sk-..."
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.ai/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Step 2: Configure the Fallback Chain

Option A: CLI (easiest)

# Add fallbacks in order (first added = first tried)
openclaw models fallbacks add anthropic/claude-sonnet-4
openclaw models fallbacks add moonshot/kimi-k2.5

# Verify the chain
openclaw models fallbacks list

Option B: Config file

# In openclaw.json:
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4",
        "fallbacks": [
          "anthropic/claude-sonnet-4",
          "moonshot/kimi-k2.5"
        ]
      }
    }
  }
}

Wait, Why Is Sonnet Both Primary and Fallback #1?

Because they use different auth profiles. The primary uses your subscription token. When it hits the subscription rate limit, the fallback tries the same model but OpenClaw rotates to the next auth profile (your API key). Different billing, different rate limit.

If you only have one auth profile for Anthropic, the fallback to the same model does nothing useful. In that case, skip straight to a different provider:

"fallbacks": ["moonshot/kimi-k2.5"]

Step 3: Set Auth Profile Order (If Using Same-Provider Fallback)

If your primary and first fallback are both Anthropic (subscription then API key), you need to tell OpenClaw which credential to try first:

# Set the auth order: subscription first, API key second
openclaw models auth order set --provider anthropic anthropic:default anthropic:api-backup

# Verify
openclaw models auth order get --provider anthropic

This ensures the subscription token is used for the primary attempt, and the API key is available when the fallback kicks in.

Step 4: Restart

openclaw gateway restart

4. Verify Everything Works

Don't trust it until you've tested it. Check each layer:

# 1. Are fallbacks configured?
openclaw models fallbacks list

# 2. Does each model respond?
openclaw models status --probe

# 3. Are auth profiles healthy?
openclaw models status --probe --probe-provider anthropic
openclaw models status --probe --probe-provider moonshot

The --probe flag sends a live check to each provider. If any profile shows expired, invalid, or unreachable, fix it before relying on it as a fallback.

A Broken Fallback Is Worse Than No Fallback

An expired API key or empty credit balance doesn't fail fast. It can hang, timeout, or return confusing errors. Test each fallback model independently. If it doesn't work on its own, it won't work as a fallback either.

5. Per-Agent Fallback Chains

The default fallback chain (under agents.defaults) applies to all agents. But you can override it per agent. Why would you?

Main assistant: Expensive fallback is fine (you're in a conversation).
Background cron agents: Cheap fallback preferred (no one's waiting).
Code review agent: Needs a strong model as fallback (can't use a small model).

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4",
        "fallbacks": ["moonshot/kimi-k2.5"]
      }
    },
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "anthropic/claude-opus-4-6",
          "fallbacks": [
            "anthropic/claude-sonnet-4",
            "moonshot/kimi-k2.5"
          ]
        }
      },
      {
        "id": "cron-worker",
        "model": {
          "primary": "moonshot/kimi-k2.5",
          "fallbacks": ["ollama/llama3"]
        }
      }
    ]
  }
}

Agent-level model config overrides the default. If an agent doesn't specify its own model/fallbacks, it inherits from agents.defaults.

6. Common Mistakes That Break Fallback

Mistake	What Happens	Fix
No `fallbacks` array	Agent has nowhere to go when primary fails	Add at least one fallback model
Fallback uses same auth as primary	Same rate limit hits both; fallback fails too	Use a different credential or different provider
Expired API key in fallback	Fallback attempted but fails silently	Test with `openclaw models status --probe`
Same model, one auth profile	Fallback retries the same credential	Add a second auth profile or use a different model
Fallback model too weak	Agent responds but quality drops dramatically	Pick a fallback that can handle your workload
No gateway restart after config change	Old config still running	`openclaw gateway restart`

7. Reading Fallback Events in Logs

When a fallback happens, the gateway logs it. Check the logs to confirm your chain is actually working:

# View recent gateway logs
journalctl --user -u openclaw -n 50 --no-pager

# Filter for model/fallback events
journalctl --user -u openclaw --no-pager | grep -i "fallback\|retry\|rate.limit\|429"

What to look for:

Fallback triggered: You'll see the primary model fail and the next model attempt start.
All fallbacks exhausted: If every model in the chain failed, you'll see the final error.
Auth profile rotation: When using multiple profiles for the same provider, look for profile ID changes between attempts.

Quick Reference: CLI Commands

Command	What It Does
`openclaw models fallbacks list`	Show current fallback chain
`openclaw models fallbacks add <model>`	Add a fallback (order matters)
`openclaw models fallbacks remove <model>`	Remove a fallback
`openclaw models fallbacks clear`	Remove all fallbacks
`openclaw models status --probe`	Live-check all provider auth
`openclaw models auth order set --provider <p> <ids...>`	Set credential priority
`openclaw models auth order get --provider <p>`	Show credential priority

True Webmaster — March 23, 2026
Verified against OpenClaw 2026.3.22

This content is protected