Lesson 2. Choosing an AI Model#

Why you need this#

The AI model is the “brain” of your assistant. Different models vary in speed, response quality, and cost. OpenClaw lets you choose a model, switch between them, and set up automatic substitution if the primary model is unavailable.

It’s like choosing between different specialists: one is faster, another is more accurate, a third is cheaper. And you can switch between them at any time.

What models are available#

OpenClaw works with models from different providers (developer companies):

Model name format#

Models are written in the format provider/name:

anthropic/claude-sonnet-4-5
openai/gpt-5.2
google/gemini-2.0-flash

How to configure a model#

In the configuration file#

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",    // primary model
        fallbacks: ["openai/gpt-5.2"]              // backup models
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" }
      }
    }
  }
}

primary — the main model used by default.

fallbacks — a list of backup models. If the primary is unavailable, OpenClaw automatically switches to the next one.

alias — a short name for convenience (instead of the long name, you can just write “Sonnet”).

Via command line#

# Check current model and status
openclaw models status

# Set the primary model
openclaw models set anthropic/claude-sonnet-4-5

# View all available models
openclaw models list --all

# Add a backup model
openclaw models fallbacks add openai/gpt-5.2

Through the setup wizard#

openclaw onboard

The wizard will walk you through model selection and authorization setup.

Switching models in chat#

Right during a conversation with the assistant, you can switch models:

/model                        — show the list of available models
/model list                   — same thing
/model 3                      — select model number 3 from the list
/model openai/gpt-5.2         — select a specific model
/model status                 — detailed information about models and authorization

The model changes only for the current session (current conversation). A new session will use the default model.

Authorization: keys and subscriptions#

To use a model, you need to confirm access. There are two main ways:

API key (recommended)#

You get a key from the provider’s website and enter it in OpenClaw. It’s like a password that confirms your right to use the model.

OAuth subscription#

Some providers (OpenAI, Anthropic) let you use your paid subscription. This is convenient: no need to pay separately for the API.

For Anthropic (Claude Pro/Max):

claude setup-token
openclaw models auth setup-token --provider anthropic

For OpenAI (ChatGPT Plus):

openclaw onboard
# Select "openai-codex" in the authorization section

Checking authorization#

openclaw models status

This command shows which providers are connected, which keys are working, and which are about to expire.

Automatic substitution (Failover)#

Failover is automatic switching to a backup when something fails. It works in two stages:

Stage 1: Authorization profile rotation#

If you have multiple keys for one provider (for example, a work and personal OpenAI account), OpenClaw will first try another key from the same provider.

Stage 2: Switch to backup model#

If all keys for a provider failed, OpenClaw moves to the next model from the fallbacks list.

Cooldowns (pauses after errors)#

If a key gets an error (rate limit exceeded, insufficient funds), OpenClaw temporarily “freezes” it:

• First error → 1 minute pause
• Second → 5 minutes
• Third → 25 minutes
• Maximum → 1 hour

After a successful request, all pauses are reset.

Tip: Set up at least one backup model from a different provider. That way, if one provider has issues, your assistant keeps working.

Full configuration example#

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2", "google/gemini-2.0-flash"]
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "openai/gpt-5.2": { alias: "GPT" },
        "google/gemini-2.0-flash": { alias: "Gemini" }
      }
    }
  }
}

In this example:

• Primary model — Claude Sonnet
• If it’s unavailable — switches to GPT
• If GPT is also unavailable — switches to Gemini
• In chat, you can switch between all four models

Lesson summary#

• AI model is the “brain” of the assistant; different models suit different tasks
• Models are written in the format provider/name
• primary — the main model, fallbacks — backups
• You can switch between models right in chat with the /model command
• Access requires an API key or OAuth subscription
• Failover automatically switches to a backup model on failures
• It’s recommended to set up backup models from different providers

Next lesson: Memory and Context