OpenClaw Multi-Model

The Three Layers of Routing

1. Primary — the model used by default for every chat
2. Fallbacks — tried in order if primary fails (paid plans only)
3. Per-channel override — pin a specific model to a single channel

Setting the Primary Model

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6"
      }
    }
  }
}

Model IDs use the format provider/model. OpenRouter IDs nest one level deeper: openrouter/provider/model. The gateway hot-reloads on save — no restart.

Fallbacks (Paid Only)

On Lite and Pro plans, you can list fallback models. If primary returns an error (rate limit, provider outage, model removed), OpenClaw tries the next entry:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6",
        "fallbacks": [
          "openrouter/openai/gpt-5.5",
          "openrouter/google/gemini-2.5-pro"
        ]
      }
    }
  }
}

Trial users get no fallbacks — only the primary. Upgrade to a paid plan to unlock fallback routing.

Per-Channel Overrides

Want Telegram on Claude and Discord on GPT? Override per channel:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "modelOverride": { "primary": "openrouter/anthropic/claude-sonnet-4.6" }
    },
    "discord": {
      "enabled": true,
      "modelOverride": { "primary": "openrouter/openai/gpt-5.5" }
    }
  }
}

Per-Skill Model Pinning

Some skills work better on specific models — e.g. tool-use heavy skills prefer Claude, image generation prefers Gemini. Pin a model inside the skill manifest:

// skill.json
{
  "name": "web-search",
  "modelPreference": "openrouter/anthropic/claude-sonnet-4.6"
}

BYOK Gate Affects All Routes

If you enable BYOK for any provider, OpenClaw treats the entire agent as fully BYOK and refuses to silently fall back to a shared sub-key. Make sure every model in your fallback chain points to a provider you have BYOK'd, or chats will fail when the chain hits an un-keyed provider.

Hot-Reload Behavior

• Hot-apply: agents.defaults.model.*, channels.*.modelOverride.*, models.*
• Restart required: none for model routing — all changes hot-reload

Picking the Right Primary

• Quality default: openrouter/anthropic/claude-sonnet-4.6 — strong tool use, low hallucination
• Cheap default: openrouter/deepseek/deepseek-chat or google/gemini-2.5-flash
• Long context: google/gemini-2.5-pro — 1M token window
• Reasoning-heavy: deepseek/deepseek-reasoner or Claude with thinking enabled

Verifying the Active Model

# Send a quick probe
openclaw chat send "Reply with the model ID you are running on."

# Or inspect the gateway log
openclaw logs --since 30s | grep "model="

Skip the JSON Editing