Switching and configuring models in Claude Code

Who this is for

People who want to change models, cut costs, or let Claude think harder on difficult problems. After reading, you can switch models with an alias or a full model name, know which setting wins when several are set, and adjust effort levels and extended thinking.

What it is

The model Claude Code uses is set by the model setting. That setting accepts an alias or a full model name. On the Anthropic API a full model name is the model ID. On Amazon Bedrock the value is an inference profile ARN, on Microsoft Foundry it is a deployment name, and on Google Cloud's Agent Platform it is a version name.^[1]

Aliases

Aliases let you skip version numbers. The common ones are:^[1]

• sonnet uses the latest Sonnet model for daily coding tasks.^[1]
• opus uses the latest Opus model for complex reasoning tasks.^[1]
• haiku uses the fast and efficient Haiku model for simple tasks.^[1]
• fable uses the Fable model for your provider and suits the hardest, longest-running work.^[1]
• opusplan uses opus in plan mode and switches to sonnet for execution.^[1]
• sonnet[1m] uses Sonnet with a 1 million token context window for long sessions.^[1]

Aliases move to newer versions over time. On the Anthropic API, opus, sonnet and haiku resolve to Opus 5.5, Sonnet 5.5 and Haiku 5.5. On Microsoft Foundry they resolve to Opus 4.6, Sonnet 4.5 and Haiku 4.5. To pin a version, use the full model name, such as claude-opus-5-5, or set the matching variable, such as ANTHROPIC_DEFAULT_OPUS_MODEL.^[1]

Three ways to switch

1. Choose at launch. This command starts a session on Opus:^[1]

claude --model opus

1. Switch inside a session. Type /model sonnet, or run /model alone to open the picker. In the picker, Enter switches and saves the choice as your default, and s applies it to this session only.^[1]
2. Set it in a settings file or an environment variable. The model field in settings and the ANTHROPIC_MODEL variable both work.^[1]

The --model flag and ANTHROPIC_MODEL apply only to the session you launch with them. To run different models in two terminals at once, give each one its own --model flag instead of switching with /model.^[1]

Which setting wins

From highest to lowest priority: /model during a session, --model at launch, the ANTHROPIC_MODEL variable, the model field in settings, and finally ANTHROPIC_DEFAULT_MODEL, which picks the model for new sessions.^[1] A choice saved with /model goes into the model field of your user settings, so later new sessions use it.^[1] ANTHROPIC_DEFAULT_MODEL requires Claude Code v2.1.236 or later.^[1]

Subagents that inherit the main conversation's model follow your /model switch. If you switch to Opus before delegating work, that work runs on Opus too. To keep a custom subagent on a smaller model, set model in its definition.^[1]

Effort levels

Effort controls how much the model thinks. The levels are low, medium, high, xhigh and max, and each model supports a different subset. Fable models, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8 and Opus 4.7 support all five. Opus 4.6 and Sonnet 4.6 do not offer xhigh.^[1] If you request a level the model does not support, Claude Code uses the highest supported level at or below it. For example, xhigh runs as high on Opus 4.6.^[1]

The effort level comes from these sources, in order: the CLAUDE_CODE_EFFORT_LEVEL variable, a level picked in the session, the --effort flag, your saved settings, and the model's default.^[1] The default is medium on Fable 5.2, Opus 5.5, Sonnet 5.5 and Haiku 5.5, xhigh on Opus 4.7, and high on the other models in the table.^[1]

In a session, /effort opens a slider. /effort followed by a level name sets it directly, and /effort auto clears your saved level for the active model. The --effort flag applies to one session only.^[1] max is the deepest level. Unless it is set through CLAUDE_CODE_EFFORT_LEVEL, Claude Code applies it to the current session only.^[1]

Extended thinking

Option+T on macOS or Alt+T on Windows and Linux toggles extended thinking for the current session. /config sets the global default, which is saved as alwaysThinkingEnabled in ~/.claude/settings.json.^[1]

You cannot turn thinking off on Opus 5.5, Sonnet 5.5, Haiku 5.5 or the Fable models, because they always use extended thinking. To reduce thinking on those models, lower the effort level. Setting MAX_THINKING_TOKENS=0 as an environment variable disables extended thinking on models where it can be turned off.^[1]

Fallback models

When the primary model is overloaded, unavailable, or returns another non-retryable server error, Claude Code can switch to a fallback model. The switch lasts only for the current turn, so your next message tries the primary model first.^[1] Use --fallback-model sonnet,haiku to set a chain for one session. To keep a chain, set fallbackModel as an array in settings. Claude Code caps a chain at three models.^[1]

Common questions

A model name is mistyped. A value passed with --model, ANTHROPIC_MODEL or the model setting is not rejected at launch. The session starts, but the first request reports an error. On the Anthropic API, Claude Code may suggest the closest valid name.^[1]

A resumed session uses a different model. A session resumed with --resume, --continue or the /resume picker keeps the model it used when it was saved, unless that model has been retired or excluded by your settings.^[1]

You want a custom entry in the picker. ANTHROPIC_CUSTOM_MODEL_OPTION adds one entry without replacing the built-in aliases. Claude Code does not validate that model ID, so it must be one your endpoint accepts.^[1]

Next steps

For the full effort table, fallback details and provider-specific settings, use the official model configuration documentation.^[1]