Configure OpenClaw Models: Switch Providers in Seconds

Ever feel like you’re stuck with one AI model even when it’s not the right fit for the task? Switching between a heavy-duty model for complex logic and a fast, cheap one for simple summaries shouldn’t feel like a chore.

In this guide, we’ll look at how to manage your models in OpenClaw so you always have the right tool for the job.

What is the “default model”?

OpenClaw’s default model is whatever you set as:

agents.defaults.model.primary

Models are referenced as provider/model (example: anthropic/claude-opus-4-5).

What model do you recommend?

Choosing a model depends on your budget and what you need to get done. Here are the top picks:

• Recommended default: anthropic/claude-opus-4-5
• Good alternative: anthropic/claude-sonnet-4-5
• Reliable (less character): openai/gpt-5.2
• Budget: zai/glm-4.7

A good rule of thumb is to use the best model you can afford for high-stakes work. Use a cheaper model for routine chat or summaries.

⚠️ Strong warning: weaker/over-quantized models are more vulnerable to prompt injection and unsafe behavior.

Can I use self-hosted models (llama.cpp, vLLM, Ollama)?

Yes. If your local server exposes an OpenAI-compatible API, you can point a custom provider at it. Ollama is supported directly and is the easiest path.

Security note: smaller or heavily quantized models are more vulnerable to prompt injection. We strongly recommend large models for any bot that can use tools.

How do I switch models without wiping my config?

You have several safe options to change your model without breaking your setup:

• /model in chat (quick, per-session)
• openclaw models set ... (updates just model config)
• openclaw configure --section models (interactive)
• edit agents.defaults.model in ~/.openclaw/openclaw.json

Avoid config.apply with a partial object unless you intend to replace the whole config.

How do I switch models on the fly (without restarting)?

Use the /model command as a standalone message:

/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash

You can list available models with /model, /model list, or /model status.

Select by number:

/model 3

You can also force a specific auth profile:

/model opus@anthropic:default
/model opus@anthropic:work

Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding?

Yes.

Option A: switch per session Set one as default and switch as needed:

/model gpt-5.2      # for daily tasks
/model gpt-5.2-codex  # for coding

Option B: sub-agents Route coding tasks to sub-agents with a different default model.

Why do I see “Model … is not allowed” and then no reply?

If agents.defaults.models is set, it becomes the allowlist for /model and any session overrides. Choosing a model that isn’t in that list returns an error.

Fix: add the model to agents.defaults.models, remove the allowlist, or pick a model from /model list.

Why do I see “Unknown model: minimax/MiniMax-M2.1”?

This means the provider isn’t configured (no MiniMax provider config or auth profile was found).

Fix checklist:

1. Make sure MiniMax is configured (wizard or JSON) and use the exact model id (case-sensitive): minimax/MiniMax-M2.1
2. Run openclaw models list and pick from the list

Are opus / sonnet / gpt built-in shortcuts?

Yes. OpenClaw ships a few default shorthands:

• opus → anthropic/claude-opus-4-5
• sonnet → anthropic/claude-sonnet-4-5
• gpt → openai/gpt-5.2
• gpt-mini → openai/gpt-5-mini
• gemini → google/gemini-3-pro-preview
• gemini-flash → google/gemini-3-flash-preview

If you set your own alias with the same name, your value wins.

How do I define/override model shortcuts (aliases)?

Aliases come from agents.defaults.models.<modelId>.alias:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-5" },
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" }
      }
    }
  }
}

How do I add models from other providers like OpenRouter or Z.AI?

OpenRouter:

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
      models: { "openrouter/anthropic/claude-sonnet-4-5": {} }
    }
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." }
}

Z.AI:

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} }
    }
  },
  env: { ZAI_API_KEY: "..." }
}

Next Steps

• Learn about Provider Configuration
• Explore Sub-agents and Routing

Need help getting your models running? Check out the AI Setup Assistant.