How to Configure the Model in Claude Code: /model, Flags, Env Vars and settings.json (2026)

To configure the model in Claude Code you have four controls, from most temporary to most permanent: the /model command inside a session, the --model flag at launch, the ANTHROPIC_MODEL environment variable, and the model key in settings.json. A more specific layer wins over a more general one. This guide shows each, the alias system, and how to confirm which model is actually answering.

The four places to configure the model in Claude Code

When more than one is set, the narrower one takes precedence: a session command overrides the launch flag, the flag overrides the environment variable, and the environment variable overrides the settings file. The practical consequence is that a stale export in your shell profile can silently beat the project default you just committed. If a change seems to do nothing, look one layer up.

Aliases versus full model IDs

Claude Code accepts short aliases such as sonnet, opus and haiku, and also full model IDs such as claude-sonnet-5-5. The two behave differently over time:

• An alias follows whatever Claude Code currently maps that name to. When a new release lands, the alias moves with it. This is convenient for interactive work and risky for anything that needs reproducible output.
• A full ID pins one specific model. Pipelines, evaluations and anything you compare across weeks should use the full ID.

Searches like "set model to opus 4.x" are common because the version suffix changes often. Rather than memorising suffixes, run /model with no argument to see the choices your installation offers, or check the current model list in the official documentation before pinning.

Setting the model for one session

Inside an interactive session:

/model sonnet

or with a full ID:

/model claude-opus-5-5

The change applies from the next message onward and is forgotten when the session ends. /model with no argument opens a picker and shows what is currently selected, which makes it the fastest way to check state.

Setting the model at launch

claude --model opus

claude --model claude-haiku-5-5 -p "summarise the diff in this branch"

The flag is the right tool for scripts and for comparing two models on the same prompt: run the command twice with different values and diff the output.

Setting the model with an environment variable

export ANTHROPIC_MODEL=claude-sonnet-5-5
claude

Put the export in the environment of the thing that launches Claude Code: a CI job definition, a Dockerfile, a systemd unit, or a shell profile. Two related variables are worth knowing about:

• ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL change what the aliases resolve to. They let a team keep typing sonnet while an administrator decides which exact model that means.
• CLAUDE_CODE_SUBAGENT_MODEL sets the model used by subagents spawned from a session, independently of the main model.

If you use a gateway or relay through ANTHROPIC_BASE_URL, the model name must be one the gateway recognises. Some gateways accept Anthropic IDs unchanged, others expose their own names. A 404 or 400 complaining about an unknown model right after switching endpoints is almost always this mismatch, not a Claude Code bug. Running Claude Code with Alternative Models covers what else changes when the endpoint moves.

Setting the model in settings.json

For a default that survives restarts, add a model key to the appropriate settings file:

{
  "model": "claude-sonnet-5-5"
}

• ~/.claude/settings.json applies to you on every project.
• .claude/settings.json inside a repository applies to everyone who clones it (commit it).
• .claude/settings.local.json applies only to you, only in that repository (keep it out of version control).

Settings files merge per key, with the project-local file taking precedence over the project file, and both over the user file. Claude Code Configuration: Layers and Merge Rules walks through the merge order in detail if a value is not landing where you expect.

Verifying which model is actually in use

Configuring is not the same as confirming. Three checks, cheapest first:

1. Type /model with no argument. The picker highlights the active model.
2. Run /status. The status output includes the model alongside the account and endpoint, which also catches the case where the model is right but the endpoint is wrong.
3. Ask the model a question that a different model would answer differently, such as the size of its context window, and compare with the documented value for the model you intended. This is a sanity check, not a proof, because models can be mistaken about themselves.

If the active model differs from what you set, work down the precedence table: check for a session override, then the launch command, then env | grep ANTHROPIC, then each settings file.

Choosing a model for the work

Model choice is a cost and latency decision as much as a capability one. A reasonable split for coding work:

• A smaller, faster model for repetitive edits, test runs and commit messages.
• A mid-tier model as the daily default.
• The largest model for architecture decisions, difficult debugging and anything where a wrong answer costs more than the tokens.

Whichever you pick, the mechanism above is the same. The only thing that changes between the official endpoint and a relay such as ROIBest AI is the set of model names the endpoint will accept, so confirm the list on the provider's side before committing a default to settings.json.

FAQ

How do I change the model in Claude Code for just one session?

Type /model <alias or ID> inside the session. It applies from the next message and resets when you exit.

Where do I set a permanent default model for Claude Code?

Add "model": "<name>" to ~/.claude/settings.json for yourself, or to .claude/settings.json in the repository for the whole team.

Why does my settings.json model keep getting ignored?

Something more specific is set: a --model flag, an ANTHROPIC_MODEL export in your shell profile, or a /model override in the current session. Narrower layers win.

Can I use a model alias with a third-party endpoint?

Only if the endpoint maps that alias. Many relays expect full model IDs or their own names. Check the provider's model list and use the exact string it publishes.