Model Fallback Guide

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 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.

2. How Fallback Actually Works

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

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

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-..."
  }
}

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 (in openclaw.json)

Fallbacks are a config-file concept, not a CLI command. Edit openclaw.json and set agents.defaults.model.primary plus a fallbacks array. Order matters: first entry is tried first.

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

After editing, reload the config so the gateway picks it up, then verify the chain:

# Reload / restart to apply config
openclaw gateway restart

# Inspect the current chain
openclaw models fallbacks list

"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), tell OpenClaw which credential to try first by editing the auth.order section of your config:

{
  "auth": {
    "order": {
      "anthropic": [
        "anthropic:default",
        "anthropic:api-backup"
      ]
    }
  }
}

Each provider key takes an ordered list of auth profile IDs. The first healthy profile wins; when its rate limit hits, OpenClaw rotates to the next profile in the list before moving on to the next model in the fallback chain.

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.

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-6",
        "fallbacks": ["moonshot/kimi-k2.5"]
      }
    },
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "anthropic/claude-opus-4-6",
          "fallbacks": [
            "anthropic/claude-sonnet-4-6",
            "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

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.

True Webmaster — March 23, 2026
Verified against OpenClaw 2026.4.12