How to Change Model in Claude Code: /model, --model, Aliases

Claude Code takes the model from five sources. Each one overrides the ones below it, so a switch can appear to do nothing when a higher-priority source is still set.

This guide covers every method, when each one wins, and how to make custom or gateway models appear in the picker at all.

Table of Contents

The five ways to set a model

From highest priority to lowest:

1. /model <name> during a session.
2. claude --model <name> at launch.
3. The ANTHROPIC_MODEL environment variable.
4. The model key in a settings file.
5. ANTHROPIC_DEFAULT_MODEL, which sets what new sessions start on.

A higher source always wins. If /status shows a model you did not expect, walk down this list.

Method 1: the /model command

Inside a running session, type:

/model

With no argument, this opens an interactive picker of available models. With an argument, it switches immediately:

/model sonnet
/model opus
/model claude-sonnet-4-6

In the interactive list:

• Press Enter to switch and save the choice as your default. Claude Code writes the model key to your user settings file.
• Press s to switch for this session only, without saving.

Typing /model <name> directly behaves like Enter: it switches and saves.

To stop overriding and return to the runtime default for your account, use the default alias:

/model default

default is a reset instruction, not a model.

In non-interactive -p mode, /model applies to the current session only and is not saved. That behavior requires v2.1.205 or later.

Method 2: the --model flag

Set the model for one launch:

claude --model sonnet
claude --model claude-opus-4-6

The flag overrides both the model setting and ANTHROPIC_MODEL for that session. It is the cleanest way to run a one-off task on a stronger or cheaper model without touching any config.

Method 3: ANTHROPIC_MODEL

ANTHROPIC_MODEL sets the model for any session launched with that variable present:

export ANTHROPIC_MODEL="sonnet"
claude

It accepts an alias or a full model name. Claude Code reads the variable first and falls back to the model setting only when the variable is unset.

Method 4: the model setting

Set a persistent default in a settings file:

{
  "model": "sonnet"
}

Put it in ~/.claude/settings.json for every project, or in a project settings file for one repo. If both ANTHROPIC_MODEL and this key are set, the environment variable wins.

Method 5: ANTHROPIC_DEFAULT_MODEL

This variable sets the model a new session starts on. It applies only when nothing else selects one, and it requires v2.1.236 or later. It is ignored if set to default, inherit, opusplan, or haiku.

export ANTHROPIC_DEFAULT_MODEL="sonnet"

Aliases explained

Aliases are short names that map to model versions. They are the stable way to refer to a model, because the underlying version changes over time.

opusplan is the built-in answer to "I want Opus-quality planning without paying Opus rates for every edit". Enable plan mode and Claude Code uses Opus to think, then switches to Sonnet to execute.

If you are on a custom provider or gateway, aliases still work, but only after you map them. See the next section.

Switching models on a custom provider

On a gateway or third-party endpoint, the alias tiers must point at model names the endpoint knows. Set them in the env block:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://provider.example/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "provider-strong-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "provider-balanced-model",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "provider-fast-model",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "provider-strong-model"
  }
}

After this, /model opus and /model sonnet switch between the mapped models. Without the mapping, /model opus sends a name the endpoint does not have and the request fails.

ANTHROPIC_SMALL_FAST_MODEL is the deprecated predecessor of ANTHROPIC_DEFAULT_HAIKU_MODEL. New setups should use the ANTHROPIC_DEFAULT_* family.

Making custom models appear in the picker

If /model lists only built-in Claude models, two options fix it.

Gateway model discovery fills the picker from an Anthropic-compatible gateway. Point ANTHROPIC_BASE_URL at one and enable it:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

For a single model, use ANTHROPIC_CUSTOM_MODEL_OPTION to add one entry that is not in the built-in list:

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/special-model"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Gateway Special"

Claude Code does not validate this ID, so any string the endpoint accepts works. The entry appears at the bottom of the picker.

For full control of the picker order and labels, use the modelPicker settings key in your user settings:

{
  "modelPicker": {
    "options": [
      { "model": "provider/strong", "label": "Strong" },
      { "model": "provider/fast", "label": "Fast" }
    ]
  }
}

Switching providers mid-session

/model changes the model, not the endpoint. The base URL and credential come from the environment and are read at startup, so you cannot move from Anthropic to OpenRouter with /model.

To change providers you have three options:

• Restart Claude Code with different environment variables set.
• Put provider profiles behind small shell functions and launch the one you want.
• Use a local router that exposes one endpoint and switches providers behind it, so /model selects a provider and model pair.

The router approach is the only one that changes providers without a restart. If that is what you need, the Claude Code router guide covers it.

Verify which model is active

Run /status to see the active model, base URL, and credential source in one place. If the model looks wrong, check the five sources in priority order.

claude --debug also prints model resolution details when a switch does not take effect.

Troubleshooting

Frequently asked questions

How do I change the model in Claude Code right now?

Type /model for the picker, or /model sonnet to switch immediately. Press Enter to save as default, s for this session only.

How do I make the model change permanent?

Press Enter in the /model picker, or set "model": "sonnet" in ~/.claude/settings.json. ANTHROPIC_MODEL also persists for any session launched with it.

How do I use a different model for one run?

claude --model opus overrides the settings file and ANTHROPIC_MODEL for that launch only.

How do I switch to a custom provider with /model?

You cannot. /model changes the model, not the endpoint. Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in a settings file, map ANTHROPIC_DEFAULT_*_MODEL, then restart.

How do I use Opus for planning and Sonnet for edits?

Use the opusplan alias with plan mode enabled. Claude Code uses Opus to plan, Sonnet to execute.

Sources: Claude Code model configuration · Environment variables

Related reading

• Claude Code Environment Variables Reference
• How to Add a Custom Model Provider to Claude Code
• Extending Claude Code with Multiple Models

Closing

Switch with /model, persist with the picker or the model key, and map the alias tiers the moment you point Claude Code at anything other than Anthropic.