OpenClaw Provider Setup: Pick Model Backends Without Lock-In

Model provider setup is one of those OpenClaw chores that looks boring until it breaks production. Then it becomes the whole day. A token expires, a provider changes behavior, a cheaper model fails on tools, or an operator assumes “we added OpenAI” means the agent has actually switched to OpenAI. It usually has not.

The OpenClaw docs make a useful distinction: model providers are LLM backends, not chat channels. Slack, Discord, WhatsApp, Matrix, and friends are places the agent can talk. Providers are where the agent’s thinking comes from. If you blur those layers, you end up debugging the wrong thing.

This guide is the setup pattern I would use for a real operator box: authenticate providers intentionally, use explicit provider/model refs, keep the default model boring, add fallbacks for resilience, and verify what OpenClaw sees before trusting the agent with recurring work.

If you are already debugging provider outages, pair this with my OpenClaw model failover guide. This post is earlier in the lifecycle: choosing and wiring backends so failover has somewhere sane to go.

The first rule: use explicit model refs

OpenClaw model refs use the shape provider/model. The docs use examples like anthropic/claude-opus-4-6, openai/gpt-5.5, and OpenRouter-style refs such as openrouter/moonshotai/kimi-k2. The slash matters because OpenClaw parses refs by splitting on the first /. If the model ID itself contains a slash, keep the provider prefix.

I would avoid relying on aliases while you are doing initial setup. Aliases are useful later for humans, but explicit refs make the first configuration auditable. When a cron job, session, or fallback says provider/model, you can reason about exactly which backend the agent is trying to use.

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

openclaw models status is the command I care about most after setup. The docs say it shows the resolved default and fallbacks plus an auth overview. Add --json when you need automation-friendly output, and use --check when a script should fail on missing or expired auth.

Authenticate first, switch second

The provider directory keeps the quick start deliberately simple: authenticate with the provider, usually through openclaw onboard, then set the default model as provider/model. That order is important. Adding auth does not automatically mean every agent should start using that provider.

The online provider docs are explicit about this: adding or reauthing a provider preserves an existing agents.defaults.model.primary. Provider plugins may recommend a default in their setup patch, but OpenClaw treats that as “make this model available” when a primary model already exists, not “replace the current production brain.”

That is the right bias. Provider setup should not silently rewrite your operating model. If you intentionally want to switch, use openclaw models set <provider/model> or the provider auth login flow with --set-default where the provider supports it.

openclaw onboard
openclaw models status
openclaw models set openai/gpt-5.5

For provider-specific auth, the docs list examples like OpenAI API key auth through OPENAI_API_KEY, OpenAI Codex OAuth through openclaw models auth login --provider openai-codex, Anthropic through API key or CLI/token flows, Google Gemini through GEMINI_API_KEY, and local or hosted providers such as Ollama, OpenRouter, Vercel AI Gateway, Mistral, Groq, Together, and others.

The exact provider you choose matters less than the discipline: prove auth exists, prove the model is selectable, and only then make it your default.

Do not confuse catalogs with readiness

openclaw models list can show configured models, local providers, provider-filtered catalogs, and broader catalog rows. The docs note that this view is read-only and may include provider-owned static catalog rows even when you have not authenticated with that provider yet. In other words: a model appearing in a catalog is not the same thing as a working runtime path.

That distinction saves a lot of wasted debugging. If a model appears but auth is missing, the problem is not “OpenClaw forgot the model.” The problem is that the provider route is not ready for inference.

For production checks, I would separate questions like this:

• Can OpenClaw see the model? Use openclaw models list.
• What model will this agent actually use? Use openclaw models status.
• Is provider auth missing, expired, or warning? Use openclaw models status --check or inspect the JSON output.
• Do I want to spend tokens probing live providers? Only then consider --probe, because the docs warn probes are real requests.

The default model should be boring

OpenClaw can use many providers, but your default model should not be a science experiment. The models concept page recommends setting the primary to the strongest latest-generation model available to you, using fallbacks for cost or latency-sensitive tasks and lower-stakes chat, and avoiding older or weaker model tiers for tool-enabled agents or untrusted inputs.

I agree with that. Your primary model is the agent’s normal operating brain. It touches tools, interprets standing orders, handles channel context, and decides when to ask for approval. Saving a little money on the model can become expensive if it causes bad tool calls, confused handoffs, or broken customer replies.

A clean default config shape is simple:

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.5",
        fallbacks: [
          "anthropic/claude-opus-4-6",
          "openrouter/moonshotai/kimi-k2"
        ]
      }
    }
  }
}

Those model names are examples from the docs, not a universal recommendation. The real rule is to pick a primary you trust, then add fallbacks that are actually authenticated and acceptable for the kinds of work your agent does.

If you want the operator version of this, model routing, memory, approvals, cron discipline, and production guardrails in one place, get ClawKit here.

Understand the two failover layers before you add five providers

OpenClaw failover happens in two stages. First, it rotates auth profiles within the current provider. Second, when that provider is exhausted, it moves to the next model in agents.defaults.model.fallbacks.

That means provider setup is not just a list of logos. It is a recovery graph. Multiple auth profiles for one provider can absorb token or account-specific failures. Fallback models can absorb provider-level failures. You want both layers to be deliberate.

The model failover docs also explain session stickiness. OpenClaw pins the chosen auth profile per session to keep provider caches warm. It does not rotate on every message just because multiple credentials exist. A pinned profile stays until a reset, compaction, cooldown, or disabled state changes the route.

That is good operator ergonomics. Constant random rotation would make failures harder to reproduce. Sticky sessions make the system predictable until a real failover signal appears.

Use allowlists carefully

agents.defaults.models is powerful because it becomes the allowlist for /model and session overrides. It can keep operators from selecting random backends you do not support. It can also confuse everyone if the allowlist is stale.

The docs are clear about the failure mode. If a user selects a model outside the allowlist, OpenClaw returns:

Model "provider/model" is not allowed. Use /model to list available models.

That happens before a normal reply is generated, so it can look like the agent simply failed to answer. The fix is not to restart the whole box. Add the model to agents.defaults.models, clear the allowlist, or choose a listed model from /model list.

My bias: use allowlists when you have a real operating reason, such as limiting a team to tested models. Do not use them as a dumping ground for every model you have ever tried. Every extra entry becomes another path someone can accidentally pick.

Provider plugins own more behavior than most operators realize

The provider docs describe a useful architecture boundary: provider plugins own provider-specific behavior while OpenClaw keeps the generic inference loop. Plugins can own onboarding flows, catalogs, auth env-var mappings, transport normalization, OAuth refresh, usage reporting, model capability metadata, runtime auth preparation, and provider-specific request handling.

That matters because providers are not interchangeable at the implementation level. One provider may need OAuth refresh. Another may need API-key rotation. Another may expose a catalog through a plugin. Another may support a local runtime. OpenClaw gives you one operator surface, but it does not pretend every backend is identical behind the curtain.

This is also why I prefer using documented provider flows over hand-editing random config. The provider plugin usually knows the auth shape, model catalog, and runtime quirks better than a tired operator at midnight.

A practical setup checklist

Here is the checklist I would use before letting a provider-backed agent run unattended:

1. Pick the primary model ref explicitly as provider/model.
2. Authenticate the provider through openclaw onboard or the documented openclaw models auth flow.
3. Run openclaw models status and confirm the primary and fallbacks resolve as expected.
4. Add one or two realistic fallbacks, not a giant panic list.
5. Use agents.defaults.models only if you want a real allowlist.
6. Avoid live probes in automated checks unless you are comfortable with token usage and rate-limit risk.
7. Document which provider is used for high-stakes crons so future you does not guess.

If something still feels wrong after setup, start with openclaw models status. Then look at auth health, allowlists, and fallback configuration. Most “provider problems” I see are really one of those three things.

The short version

OpenClaw provider setup is about control, not collecting backends. Use explicit model refs. Authenticate before switching. Treat model catalogs as visibility, not proof of readiness. Keep the primary strong and boring. Add fallbacks that are actually usable. Check status before you trust the setup.

Do that, and model providers become replaceable infrastructure instead of a hidden single point of failure.

Want the complete guide? Get ClawKit — $9.99