OpenClaw Provider Routing: Use Multiple Models Without Turning Ops Into Guesswork

Model routing looks simple when you only have one API key and one default model. It gets messy the moment production work starts needing different strengths: one model for careful coding, another for fast routine replies, another for image-heavy prompts, and a backup when the first provider hits auth, quota, or latency trouble.

OpenClaw's docs give the right mental model: a model reference is written as provider/model, providers are authenticated separately, and the runner can use configured fallbacks when the selected provider is exhausted. The hard part is not memorizing provider names. The hard part is keeping that routing boring enough that an operator can debug it at 2 AM.

This is the provider-routing checklist I would use before trusting an OpenClaw workspace with revenue work, customer messages, or long coding tasks.

Start with provider/model, not brand names

The docs are explicit that OpenClaw model refs use the provider/model shape. That small rule prevents a lot of confusion. anthropic/claude-opus-4-6, openai/gpt-5.5, and google/gemini-3.1-pro-preview are not just labels. The provider prefix tells OpenClaw which auth, catalog, runtime policy, and fallback lane it is working with.

That matters because provider setup is not the same thing as channel setup. Slack, Telegram, browser tools, and webhooks are ways humans or systems reach the agent. Model providers are where the agent sends the thinking work. Mixing those concepts leads to bad runbooks like “Slack is broken” when the real issue is an expired model credential.

The safer operator habit is to describe incidents with the full ref: “the default model is failing,” “the fallback provider is being used,” or “this session was manually switched with /model.” It makes the next check obvious.

Use the CLI as the control surface

The docs list the basic control commands directly:

openclaw onboard
openclaw models status
openclaw models list
openclaw models set <provider/model>

openclaw onboard is the safest entry point when you are setting up a machine because it can configure common provider auth and model choices. openclaw models status shows the resolved primary model, fallbacks, and auth overview. openclaw models list shows what is configured and available. openclaw models set <provider/model> intentionally changes the default.

I like that split because it gives operators a clean ladder: inspect first, list options second, change only when you mean to. Do not hand-edit model config because you vaguely remember a model name from another machine. Use the control surface that knows the local catalog and auth state.

Adding auth should not surprise-switch production

The current official provider docs call out an important behavior: adding or reauthenticating a provider should not automatically replace an existing primary model. Provider plugins can make models available, and auth flows can be run with --set-default when you explicitly want a switch, but the safe default is preservation.

openclaw models auth login --provider openai-codex --set-default
openclaw models auth login --provider anthropic --method cli --set-default
openclaw models auth add

That is exactly what you want in production. A new provider key should expand your options, not silently move every customer conversation or cron job to a different model family. If you want the switch, make it visible in the command or run openclaw models set afterward.

The operational rule is simple: auth is permission; routing is policy. Keep them separate in your head and in your change logs.

Primary and fallbacks are a chain, not a vibe

OpenClaw selects a primary model first, then configured fallbacks, while provider auth failover happens inside the provider before moving to the next model. The failover docs describe two stages: auth profile rotation within the current provider, then model fallback to the next configured model.

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.5", "google/gemini-3.1-pro-preview"]
      }
    }
  }
}

This is not a recommendation to copy those exact models. It is the shape that matters: one primary model, then a deliberate fallback list. Your real list should reflect budget, latency, capability, and trust. A coding-heavy agent may put the strongest model first. A lightweight support agent may use a faster default and reserve the expensive model for manual overrides or high-stakes tasks.

The mistake is treating fallback as “anything that works.” A fallback model still needs the right auth, tool behavior, context capacity, and quality for the job. If the fallback cannot safely complete the task, it should not be in the chain.

Provider routing is where agent ops turns from demo to production. Want the complete operating checklist? Get ClawKit — $9.99.

Auth profiles are part of routing

The model failover docs explain that OpenClaw stores provider credentials as auth profiles for both API keys and OAuth tokens. Those profiles can be ordered explicitly, discovered from configured profiles, or read from stored provider profiles. When multiple profiles exist for a provider, OpenClaw can rotate through them instead of immediately giving up.

That is useful, but it is also where messy workspaces become hard to reason about. If one provider has a work OAuth login, a personal OAuth login, and a fallback API key, you need to know which profile is expected to handle production traffic. Otherwise a “model problem” may actually be a profile selection problem.

The docs also note session stickiness. OpenClaw pins the chosen auth profile per session to keep caches warm, and it does not rotate on every request. The pin can change when the session resets, compaction completes, or the profile is disabled or cooling down. That means one session may keep using a profile while another new session chooses differently.

For operators, the fix is not panic. Inspect the status, understand the profile order, and only then adjust policy.

Cooldowns are a safety feature, not a failure

When a profile fails due to auth errors, rate limits, or timeout-like failures, the docs say OpenClaw can put it into cooldown and move to another profile. Billing or credit failures are treated differently: they are marked as longer-lived disabled states because they are usually not transient.

That behavior is good. It keeps a stuck key from burning the whole run, and it avoids hammering an account that is already rejecting requests. The operator job is to read the signal correctly. A cooldown is not proof that the model is bad. It may be proof that one credential, quota window, or billing state is unhealthy.

Use models status before changing defaults. If the issue is auth, fix auth. If the issue is a provider outage or quota window, let fallbacks carry the work. If the issue is a low-quality fallback answer, change the fallback policy after the incident.

Manual session switches are different from defaults

The concepts docs distinguish configured defaults, auto fallback selections, and user session selections. That difference is easy to miss. A configured default can use configured fallbacks. A runtime fallback can persist an automatic override so later turns do not keep probing a known-bad primary every time. A user-selected session model is exact.

That is the right behavior. If a human deliberately switches a live session with /model, they are asking for that model, not a fuzzy “similar enough” route. If a cron or default run hits provider trouble, it can use the configured fallback chain because that is part of the operator policy.

In a team setting, write this into your runbook: defaults are fleet policy; /model is session policy. Do not debug a one-off session override as if the entire workspace changed.

Keep image, PDF, and generation routes separate

The model concepts docs call out separate routing surfaces beyond the text model: agents.defaults.imageModel for image-capable understanding when the primary model cannot accept images, agents.defaults.pdfModel for the PDF tool, and agents.defaults.imageGenerationModel for image generation. The docs also describe music and video generation model defaults.

That separation prevents a common mistake: assuming the main chat model controls every media task. It does not have to. A workspace can use one model for normal agent reasoning, another for image understanding, and another provider-backed route for generation.

The business reason is cost control. Media tasks can be expensive or provider-specific. If you leave them implicit, you may not know why one task is fast and cheap while another waits on a provider you did not expect.

Use probes carefully

The CLI docs say models status --probe runs live auth probes and that probes are real requests. That makes probes valuable, but not free. Use them when you need proof that a credential can execute. Do not run them in tight loops or make every status check a live provider call.

openclaw models status --json
openclaw models status --probe --probe-provider openai-codex
openclaw models list --all --provider openai --plain

My rule: regular status checks are safe for dashboards and quick triage; probes are for setup, incident recovery, or preflight before important automation. If you need to probe, narrow it with provider or profile flags instead of blasting every configured provider.

A practical provider-routing runbook

1. Inspect: run openclaw models status and confirm the resolved primary, fallbacks, and auth overview.
2. List: run openclaw models list before choosing a new model. If you need a broader catalog view, use documented provider filters.
3. Authenticate: add or refresh provider auth, but do not assume that should change the primary model.
4. Set policy: change the default with openclaw models set <provider/model> or a deliberate config change.
5. Define fallbacks: keep fallback models strong enough for the actual job. Remove weak “just in case” models from production chains.
6. Verify: use JSON status or a targeted probe when you need execution proof.
7. Record: log the reason for routing changes, especially when they affect cron jobs, customer channels, or production agents.

The boring version wins. OpenClaw gives you multiple providers, auth profiles, fallbacks, and media-specific routing surfaces. Your job is to turn those into a small policy that people can inspect and trust.

Want the complete guide? Get ClawKit — $9.99