Skip to content

Model configuration

Pick the model Claude Code runs on, tune effort and thinking, control the 1M context window and auto-compaction, and lock models down for a team.

Claude Code lets you choose which Claude model answers each request, how hard it thinks, and how much context it keeps before compacting. This page covers all of that, from the everyday /model switch through to the managed settings an administrator uses to pin versions across a fleet.

If you only need the short version: run /model to pick a model, run /effort to pick how much reasoning it does, and leave the rest at the defaults until something pushes you to change it.

What you can put in the model setting

Anywhere Claude Code asks for a model (the /model command, the --model flag, the model settings key, environment variables), you can give it one of two things:

  • An alias such as opus or sonnet, which Claude Code resolves to a specific version for you.
  • A concrete model identifier. What that looks like depends on where your requests go:
ProviderForm of the identifier
Anthropic APIA full model name, for example claude-opus-5-5
Amazon BedrockAn inference profile ARN
Microsoft FoundryA deployment name
Google Cloud's Agent PlatformA version name

Note: Setting ANTHROPIC_BASE_URL only changes where requests travel. It does not choose the model. For routing through a proxy, see LLM gateways.

Aliases

AliasWhat it gives you
defaultNot really an alias: it clears any override so you land on your account's runtime default (see the default model)
bestWhatever fable resolves to, if Fable is available to you; otherwise the same as opus
fableThe Fable model for your provider, aimed at the longest and hardest jobs
opusThe latest Opus, for heavy reasoning
sonnetThe latest Sonnet, the everyday coding workhorse
haikuHaiku, the fast and cheap option for simple jobs
opus[1m]Opus with the 1 million token context window
sonnet[1m]Sonnet with the 1M window. Does nothing extra when sonnet already resolves to Sonnet 5.5 or Sonnet 5, which have 1M natively
opusplanOpus while you are in plan mode, Sonnet once you start executing

The family aliases do not resolve to the same version everywhere. On the Anthropic API they track the newest release; other providers can lag:

Provideropussonnethaiku
Anthropic APIOpus 5.5Sonnet 5.5Haiku 5.5
Claude Platform on AWSOpus 5.5Sonnet 4.6Haiku 4.5
Amazon Bedrock, Google Cloud's Agent PlatformOpus 5.5Sonnet 4.5Haiku 4.5
Microsoft FoundryOpus 4.6Sonnet 4.5Haiku 4.5

fable resolves to Fable 5.1 unless you set ANTHROPIC_DEFAULT_FABLE_MODEL. The exception is a Claude apps gateway session, where fable and best both resolve to Fable 5; in that case run /model claude-fable-5-1 to get 5.1, provided the gateway serves it.

Aliases move forward as Claude Code updates. If you need stability, use a full model name (claude-opus-5-5) or pin the alias with an ANTHROPIC_DEFAULT_*_MODEL variable. On providers where an alias still points at an older release, those same two techniques get you the newer one.

Note: Minimum versions matter. Opus 5.5 needs v2.1.280, Sonnet 5.5 needs v2.1.284, Haiku 5.5 needs v2.1.293 and Fable 5.1 needs v2.1.257. Run claude update if a request fails because your client is too old.

When an alias changed

Claude Code versionWhat moved
v2.1.293haiku becomes Haiku 5.5 on the Anthropic API
v2.1.284sonnet becomes Sonnet 5.5 on the Anthropic API
v2.1.280opus becomes Opus 5.5 on the Anthropic API, Claude Platform on AWS, Bedrock and Agent Platform
v2.1.257fable becomes Fable 5.1 (not in Claude apps gateway sessions)
v2.1.219opus becomes Opus 5 on the Anthropic API, Claude Platform on AWS, Bedrock and Agent Platform
v2.1.207opus becomes Opus 4.8 on Claude Platform on AWS, Bedrock and Agent Platform
v2.1.197sonnet becomes Sonnet 5 on the Anthropic API
v2.1.154opus becomes Opus 4.8 on the Anthropic API

Before those, opus meant Opus 4.7 on Claude Platform on AWS and Opus 4.6 on Bedrock and Agent Platform, fable meant Fable 5, and haiku meant Haiku 4.5 everywhere.

Working with Fable

Fable 5.1 and Fable 5 are the most capable models Claude Code offers. They are built for work that runs longer than one sitting: they investigate before changing things and check their own output more than the smaller models do. Neither is the default on any plan, so you opt in:

  • Fable 5.1: /model fable or claude --model fable.
  • Fable 5: select it by ID, for example claude --model claude-fable-5 on the Anthropic API, or pin your provider's ID with ANTHROPIC_DEFAULT_FABLE_MODEL.

My habit with Fable is to describe the end state rather than the steps, hand it the messy problems (outage root causes, architecture calls) and stop adding "remember to run the tests" to prompts, because it does that unprompted. Pair it with a goal for multi-hour jobs.

A few behaviours worth knowing:

  • From v2.1.257, if your user settings saved claude-fable-5 or claude-fable-5[1m] and you talk to the Anthropic API directly, Claude Code rewrites it once to fable or fable[1m] and marks the startup line (auto-updated). Project, local and managed values are left alone.
  • If your organisation cannot use Fable at all (zero data retention, for instance), the picker row stays visible but greyed out with a reason.
  • Requests a Fable classifier flags, mostly in security and biology, trigger automatic fallback.

Fable billed to usage credits

On some plans and seat tiers Fable draws on usage credits rather than your included allowance. The picker labels such rows "Requires usage credits".

In an interactive session you are asked to consent before the first credit-billed Fable request. Enterprise members on organisation billing skip this prompt. If you dismiss it, a /model selection leaves you on your current model, and a mid-session prompt finishes the turn on your default model. Once you accept, you are not asked again.

When nobody may be at the keyboard (Remote Control connected, a background session, or an agent team teammate), the mid-session prompt waits until the dialogExpiry deadline, five minutes by default. If it expires, the turn ends without sending the request and a notice lands in the transcript. Pressing any key at the terminal cancels the deadline in Remote Control and teammate sessions. In -p mode, and in SDK hosts that never show the prompt, Claude Code bills credits without asking.

Choosing a model

Claude Code takes the first of these that applies, highest priority first:

  1. /model <alias|name> during a session, or /model alone for the picker.
  2. claude --model <alias|name> at launch.
  3. The ANTHROPIC_MODEL environment variable.
  4. The model key in a settings file.
  5. ANTHROPIC_DEFAULT_MODEL, a fallback for new sessions.

Here is a typical flow: start a session on Sonnet for a refactor, then step up to Opus when it hits a gnarly bit.

claude --model sonnet
/model opus

And a project settings file that keeps the whole team on Sonnet unless they choose otherwise:

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(pnpm test:*)"]
  }
}

How /model saves your choice

/model writes your pick to the model field in ~/.claude/settings.json, so it becomes the default for later sessions. Inside the picker:

KeyEffect
EnterSwitch and save as default
sSwitch for this session only (rebindable as modelPicker:thisSessionOnly, see keybindings)

Typing /model sonnet directly behaves like Enter. In -p mode, /model (v2.1.205 and later) applies to that run only. Between v2.1.144 and v2.1.152 the behaviour was reversed: /model was session-only and d saved a default.

--model and ANTHROPIC_MODEL only affect the session they launch. If you want two terminals on two models at once, give each its own --model rather than flipping one with /model.

On an Enterprise plan with a claude.ai login (v2.1.280 or later), saving a default with /model also records it on your account. If no organisation default is set, the picker's Default row can then resolve to that recorded model, as long as it is allowed and available. Choosing Default or opusplan does not change what is recorded.

A few other details:

  • Subagents follow along. Subagents that inherit the main model resolve it when they start, so switching to Opus before Claude delegates means the delegated work runs on Opus too. Set model in a subagent's definition to keep it on something smaller. See subagents.
  • Prices in the picker appear only when you talk to the Anthropic API (directly or via a gateway that proxies it). Third-party providers and the Claude apps gateway show no price.
  • Resumed sessions (--resume, --continue, /resume) keep the model they were saved with, unless it has been retired or is blocked by availableModels. On Bedrock, Agent Platform and Foundry the saved model is never restored. If your model setting is haiku, a resumed Haiku session moves to whatever haiku resolves to today. --model, ANTHROPIC_MODEL and (from v2.1.195) an ANTHROPIC_DEFAULT_*_MODEL variable still win over the restored model.
  • Startup header. When project or managed settings chose the model, the header names the file responsible. Platforms that set CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST get to override managed model settings, though a managed availableModels list still applies unless the host supplies one.
  • Hooks can veto. PreModelSwitch hooks run before a switch and can block it or ask you to confirm. If Claude Code cannot tell which hooks your managed plugins provide, it refuses the switch. See hooks reference.
  • Validation. Switches from the Agent SDK setModel() or an app such as Desktop (v2.1.268+) are checked with your provider the first time; Remote Control switches are checked locally. Values from --model, ANTHROPIC_MODEL or the model setting are not checked up front, so a typo surfaces as an error on the first request.
  • Retirement warnings. If the model you asked for is scheduled for retirement or is remapped, you get a startup notice. From v2.1.182 the warning also goes to stderr in -p text mode, but not with --output-format json or stream-json, where you should read modelUsage in the result instead.

Setting a default for brand-new sessions

ANTHROPIC_DEFAULT_MODEL (v2.1.236+) chooses where a new session starts, but only if nothing else has spoken: no --model, no ANTHROPIC_MODEL, no model value in any settings file (including one /model saved) and no organisation default. Unlike ANTHROPIC_MODEL, a later /model save outranks it on subsequent launches.

It also feeds the Default option, which then shows "Set by ANTHROPIC_DEFAULT_MODEL". It is ignored when set to default, inherit, opusplan or haiku, when enforceAvailableModels is on, when model restrictions exclude it, or when the model is not available to you. When it does apply, resumed sessions start on it too instead of the transcript model.

Why did my session start on a different model?

Work through these in order:

  • You picked for one session only: s in the picker, --model, or /model in -p mode.
  • Something outranks you: a model in project or managed settings, ANTHROPIC_MODEL in your shell profile, or an organisation default set to override users.
  • The save failed: /model could not write ~/.claude/settings.json (perhaps a dotfiles tool owns it or it is a read-only symlink). See settings and debugging your configuration.
  • You resumed: resumed sessions usually keep their original model.

To confirm what you are running on, check /status or add the model to your status line.

The default model

When you choose Default, or set nothing at all, the model depends on how you sign in:

Account typeDefault
Pro, Max, Team, Enterprise, Anthropic APIOpus 5.5
Claude Platform on AWS, Amazon Bedrock, Google Cloud's Agent PlatformOpus 5.5
Microsoft FoundrySonnet 4.5

Before v2.1.280 these were Sonnet 5 for Pro and Team Standard and Opus 5 for the rest (from v2.1.219), and earlier still Opus 4.8 from v2.1.154 on the API and subscription tiers.

The Default option can also resolve to an organisation default, to ANTHROPIC_DEFAULT_MODEL, or to a model recorded on your account. When enforceAvailableModels is on and the account-type default is not allowed, Default lands on the enforced allowlist entry instead. Fable is never the account-type default, but picking it with /model saves it so later sessions start there.

opusplan: Opus to plan, Sonnet to build

opusplan switches models at the plan boundary. Planning happens on opus, and once you approve the plan, execution runs on sonnet. Each phase uses the context window of its own model, so with current Anthropic API models both get 1M. Where they do not, set opusplan[1m] (via /model from v2.1.265, or via --model/settings on older versions).

If the allowlist blocks the newest Opus but permits an older one, planning uses the newest permitted Opus; it only stays on Sonnet if no Opus is allowed. The same logic lifts a Haiku session to the newest permitted Sonnet in plan mode. That substitution works on the Anthropic API and Claude Platform on AWS. On Bedrock, Agent Platform, Foundry and Mantle, an excluded upgrade simply leaves plan mode on the session's model.

For a second model that chips in at decision points rather than at the plan boundary, look at the advisor tool.

Effort and thinking

Effort levels

Effort controls adaptive reasoning: how freely the model decides to think on each step. Lower effort is quicker and cheaper; higher effort digs further.

ModelsLevels available
Fable 5.1, Fable 5low, medium, high, xhigh, max
Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7low, medium, high, xhigh, max
Opus 4.6, Sonnet 4.6low, medium, high, max

Other models do not support effort. Ask for a level a model lacks and Claude Code drops to the highest supported level below it, so xhigh on Opus 4.6 runs as high.

The level is resolved from the first source that applies:

  1. An explicit choice: CLAUDE_CODE_EFFORT_LEVEL, --effort, or /effort in the session.
  2. Your settings: a per-model level saved under modelSettings, or an effortLevel key.
  3. The model's own default: high for most models, medium for Opus 5.5, Sonnet 5.5 and Haiku 5.5, xhigh for Opus 4.7, or a level your organisation attached to its default model.

One trap: a top-level effortLevel in your user settings is the legacy form, and it does not apply to Opus 5.5 or newer models. They start at their own default until you pick a level for them. A top-level effortLevel in project, local or managed settings, or passed with --settings, does apply to every model.

How long a level lasts depends on how you confirm it:

  • Enter in the /effort slider or the /model picker, or typing /effort high, saves it as the default for that model under modelSettings.
  • s in either applies it to this session only (v2.1.257+).
  • max is always session-only unless it comes from CLAUDE_CODE_EFFORT_LEVEL.
  • In -p runs and from Remote Control devices, a chosen level applies to that session only.

Picking a level

LevelWhere I reach for it
lowThrowaway questions, renames, quick sketches I will review anyway
mediumDefault on Opus 5.5, Sonnet 5.5 and Haiku 5.5. Well-scoped feature work
highBug fixing in existing code, anything with edge cases. Default on most other models
xhighDeeper reasoning at higher spend. Default on Opus 4.7
maxLong unattended hunts such as security reviews. Can overthink, so test before making it a habit

Levels are calibrated per model, so high on one model is not the same amount of thinking as high on another. When moving from Opus 5 to Opus 5.5, start at medium rather than carrying high across: Opus 5.5 at medium holds up against Opus 5 at high and thinks more per turn at any given level.

Ways to set effort

  • /effort opens a slider; /effort xhigh sets directly; /effort auto clears your saved level for the current model. It works mid-turn, applying from the next request after any cache warning.
  • Left and right arrows on the effort slider inside /model.
  • claude --effort high for one session.
  • CLAUDE_CODE_EFFORT_LEVEL set to a level or auto.
  • modelSettings per model, or effortLevel (low, medium, high or xhigh; max is not accepted in either key).
  • The effort control on a phone or browser over Remote Control (v2.1.234+), session-only.
  • An effort field in a skill or subagent's frontmatter, which overrides the session level while it runs but not the environment variable.

maxEffortLevel and organisation caps still clamp everything. An effortLevel in managed settings is only a starting point users can change; use maxEffortLevel to impose a ceiling. Run /effort status to see the level in force. The session header also shows it next to the model, for example "with low effort".

Ultracode

The /effort slider carries an Ultracode toggle. It is a Claude Code behaviour rather than an effort level: with it on, Claude plans a dynamic workflow for substantial tasks (see workflows) at whatever effort the session runs at.

  • /effort ultracode turns it on for the session; /effort ultracode off turns it off; Tab flips it in the slider.
  • claude --effort ultracode turns it on and sets effort to xhigh (v2.1.203+).
  • "ultracode": true in settings or via --settings. The SDK's effortLevel: "ultracode" also sets xhigh.
  • effortLevel and CLAUDE_CODE_EFFORT_LEVEL do not accept ultracode.

It is unavailable when workflows are turned off or the model lacks xhigh. Keeping it on at levels other than xhigh, and the off form, need v2.1.284.

ultrathink

Put the word ultrathink anywhere in a prompt to ask for deeper reasoning on that turn alone. Claude Code adds an in-context instruction; the effort level sent to the API stays the same. Phrases like "think hard" are just ordinary text.

Adaptive reasoning versus fixed budgets

Fable, Sonnet 5 and later, Haiku 5.5, and Opus 4.7 and later always reason adaptively. Only Opus 4.6 and Sonnet 4.6 can go back to a fixed budget: set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 and control the budget with MAX_THINKING_TOKENS. You can always nudge thinking frequency in plain language in your prompt or CLAUDE.md.

Extended thinking switches

What you wantHow
Toggle thinking for this sessionOption+T on macOS, Alt+T on Windows and Linux
Change the saved default/config, thinking mode (stored as alwaysThinkingEnabled)
Turn it off via environmentMAX_THINKING_TOKENS=0

Thinking cannot be turned off on Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable; the toggle shows "Thinking can't be turned off". On third-party providers MAX_THINKING_TOKENS=0 omits the thinking parameter, so adaptive models may still think. With thinking off on the Anthropic API, models that reject the combination (such as Opus 5) are sent effort high.

Thinking is collapsed by default; Ctrl+O toggles verbose mode to show it. Interactive Anthropic API sessions get redacted thinking unless you set showThinkingSummaries: true. You pay for every thinking token, shown or not.

Context window

The 1M window

Fable 5.1, Fable 5, Sonnet 5 and later, Haiku 5.5, Opus 4.6 and later, and Sonnet 4.6 support a 1 million token window. On the Anthropic API, all of those except Opus 4.6 and Sonnet 4.6 run at 1M on every plan, Pro included, with no [1m] suffix and no credits needed for the window itself.

Opus 4.6 and Sonnet 4.6 need their [1m] variant:

PlanOpus 4.6 at 1MSonnet 4.6 at 1M
Max, Team (Standard and Premium), EnterpriseIncludedUsage credits
ProUsage creditsUsage credits
API and pay-as-you-goFull accessFull access

These plan checks only run when Claude Code talks to the Anthropic API directly. Behind a gateway with your claude.ai login active, the [1m] options stay in the picker and the gateway decides.

1M pricing has no premium above 200K, except Haiku 5.5, which charges more for prompts beyond 100K tokens. Haiku 5.5's ID is claude-haiku-5-5.

Append [1m] to aliases or full names when you need it:

/model sonnet[1m]
/model claude-opus-4-6[1m]

To switch the 1M window off, set CLAUDE_CODE_DISABLE_1M_CONTEXT=1. The 1M rows disappear from the picker, and native-1M models are treated as 200K: they compact at 200K with auto-compaction on, or stop with a context-limit error with it off.

Behind an LLM gateway or any custom ANTHROPIC_BASE_URL, recognised models get the same window they have on the Anthropic API. Claude Code cannot see a lower limit the gateway enforces, so if it rejects anything over 200K, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000.

Auto-compaction

The auto-compact window is how full context may get before Claude Code summarises the conversation (see context window). You can set it in four places:

WhereScope
/autocompact 400kCurrent model, saved under modelSettings; /autocompact auto restores the tuned value
autoCompactWindow in settingsEvery model (a per-model value in the same file wins)
--autocompact <size>One launch; --autocompact auto forces the tuned window
CLAUDE_CODE_AUTO_COMPACT_WINDOWOverrides all of the above while set; plain token count only

The command and flag accept 100K to 1M as 250000, 250k, 1M or a bare 250 meaning thousands. The window is capped at the model's actual context size. If a higher settings scope sets its own value, /autocompact saves yours but tells you it is outranked.

Without a setting, compaction happens at the model's limit, except that native-1M models compact at roughly 967K, models running at 200K (including Opus 4.8 and later on Bedrock, Agent Platform and Foundry) compact at 200K, and cloud sessions compact as they approach the limit.

Unrecognised model IDs on gateways

If Claude Code assumes the wrong window for a gateway alias or custom ID, set CLAUDE_CODE_MAX_CONTEXT_TOKENS. It applies directly to IDs Claude Code cannot map to a known model (anything not starting with claude-, or carrying a stripped suffix like @20250929). If such an ID also contains [1m], add CLAUDE_CODE_DISABLE_1M_CONTEXT=1 so the variable takes effect, and expect a "200K limit isn't enforced" warning. For IDs that resolve to a known model, the variable only applies alongside DISABLE_COMPACT. Set CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 to compact only after the API rejects an over-long prompt.

Fallbacks

Fallback chains for outages

When the primary model is overloaded, unavailable or returns a non-retryable server error, Claude Code can try backups instead of failing. Auth, billing, rate-limit, request-size, transport and policy-denial errors never trigger it. A Bedrock or Agent Platform refusal for a model you cannot invoke counts as unavailable, so it does.

claude --fallback-model opus,sonnet
{
  "fallbackModel": ["sonnet", "default"]
}

The flag beats the setting. "default" expands to your default model. Chains are capped at three after deduplication, entries outside availableModels are dropped, and during compaction Claude Code will not fall back to a smaller-window model. The switch lasts for one turn. Subagents use the chain too (from v2.1.247). There is no startup confirmation and /status does not list it, so the first sign is the notice when it fires.

Automatic fallback on flagged requests

Fable, Opus 5.5, Sonnet 5.5 and Opus 5 run safety classifiers. When one flags a request in a category that has a fallback, the request reruns on another model and the session stays there until you /model back:

Refusing modelCybersecurity flagBiology flag
Fable 5.1, Fable 5, Opus 5.5Opus 4.8Opus 5
Sonnet 5.5Sonnet 5Refusal
Opus 5Opus 4.8Refusal

The effort level carries over to the fallback model until you change effort, pick a model or resume. If availableModels blocks the fallback target, you get the refusal instead.

The first request can trip this on its own, because it carries CLAUDE.md and git status. claude --safe-mode strips customisations so you can test whether your config is the trigger. To be asked instead of switched automatically, turn off Switch models when a message is flagged in /config or set switchModelsOnFlag: false.

On Bedrock, Agent Platform and Foundry, fallback only works when Claude Code can identify both models: set ANTHROPIC_DEFAULT_FABLE_MODEL for Fable sources, ANTHROPIC_DEFAULT_OPUS_MODEL (or keep an Opus 4.8 entry) to switch fallback on at all, and for Sonnet 5.5 also ANTHROPIC_DEFAULT_SONNET_MODEL or a Sonnet 5 entry.

Penetration testing, CTFs and biology codebases hit this routinely. That is expected routing, not an account flag.

Organisation defaults and limits

Restricting models with availableModels

Administrators put availableModels in managed settings (see managed settings) to limit what users can select. Entries can be a family (sonnet), a version prefix (claude-sonnet-4-5, which also matches longer IDs that extend it) or a full ID.

{
  "availableModels": ["sonnet", "haiku", "claude-opus-4-8"],
  "enforceAvailableModels": true
}

The list is enforced everywhere a model can be named: /model, --model, ANTHROPIC_MODEL, the model key, ANTHROPIC_DEFAULT_MODEL, resumed sessions, alias pins, /fast, subagent and teammate models, CLAUDE_CODE_SUBAGENT_MODEL, skill and command frontmatter, the advisor, and the background dispatch picker. Fallback chains, plan-mode upgrades, flag fallbacks and the auto mode classifier are checked too.

What happens to a blocked choice depends on where it came from: /model errors; --model, ANTHROPIC_MODEL and the model key are replaced at startup with a warning; ANTHROPIC_DEFAULT_MODEL is ignored; subagents fall back; skill overrides are ignored; a blocked advisorModel disables the advisor; and a blocked --advisor exits at launch (background sessions just drop the advisor). On the Anthropic API and Claude Platform on AWS a blocked family alias first tries the newest permitted version of that family.

Merge rules: a managed availableModels replaces lists from user, project and local settings. Without one, those lists concatenate. Naming a specific version in a family switches off that family's wildcard, so ["opus", "claude-opus-4-8"] allows only Opus 4.8. IDs starting with anthropic. (Mantle) appear as picker rows and count as specific entries.

availableModels alone does not touch the Default option. Add enforceAvailableModels: true (v2.1.175+) so Default resolves to the first allowed entry when the normal default is excluded. An empty list blocks every named selection.

Holding back specific versions

From v2.1.283, two managed-only keys let you hold a release back:

  • deniedModels: block listed models even if the allowlist permits them.
  • availableModelsMatch: "exact": each ID in availableModels permits only that version.
{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-sonnet-5-5"],
  "requiredMinimumVersion": "2.1.283"
}

Pair them with requiredMinimumVersion, because older clients ignore both keys. If Default would land on a blocked model, it steps down to the newest permitted version of the family, then Sonnet, then Haiku, then the first allowed entry; if none qualifies the session refuses to start.

Locking the experience down

model is a starting point, not enforcement. To fully control what people run, combine availableModels, enforceAvailableModels, deniedModels or availableModelsMatch, model, and an env block that pins ANTHROPIC_DEFAULT_SONNET_MODEL and friends to exact versions.

Delivery matters: server-managed settings reach CLI, Desktop, web and SDK sessions (not Claude Tag, and not third-party providers); MDM or managed settings files reach local sessions and self-hosted cloud runners. See server-managed settings.

Enterprise console controls

On Claude Enterprise (v2.1.187+), admins can disable models org-wide or per role in the claude.ai admin console. Haiku can never be disabled. Restricted models disappear from the picker; naming one with --model substitutes an allowed model with a notice, and /model rejects it. Changes apply to new requests within about a minute. These restrictions cover Anthropic API and LLM gateway sessions; elsewhere use availableModels.

Admins can also set an organisation default model (v2.1.196+), org-wide or per role, shown as "Org default" in the picker. It is a starting point: your --model, ANTHROPIC_MODEL, managed model and saved /model choice beat it, unless the admin turns on override, in which case it returns at each launch. It is read once at startup.

Effort caps come from per-role limits in Enterprise (v2.1.195+) or the maxEffortLevel managed setting on any plan. The lower cap wins. Levels above the cap vanish from /effort and requests are clamped.

Third-party deployments

Pin every alias before rollout

On Bedrock, Agent Platform, Foundry and Claude Platform on AWS, pin versions up front so you control when users move. Without pins, a default that is not enabled in a user's account causes a fallback notice on Bedrock and Agent Platform, and outright errors on Foundry.

export ANTHROPIC_DEFAULT_OPUS_MODEL='eu.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='eu.anthropic.claude-sonnet-4-5-20250929-v1:0'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='eu.anthropic.claude-haiku-4-5-20251001-v1:0'
VariableControls
ANTHROPIC_DEFAULT_FABLE_MODELfable, and what counts as Fable for flag fallback
ANTHROPIC_DEFAULT_OPUS_MODELopus, and the plan phase of opusplan
ANTHROPIC_DEFAULT_SONNET_MODELsonnet, and the execution phase of opusplan
ANTHROPIC_DEFAULT_HAIKU_MODELhaiku and background tasks (replaces the deprecated ANTHROPIC_SMALL_FAST_MODEL)
CLAUDE_CODE_SUBAGENT_MODELSubagents, teammates and workflow agents without their own model

Append [1m] to a pinned ID to get the 1M window for every use of that alias; Claude Code strips it before calling the provider. The suffix is read per variable. When a family is pinned, the picker shows one row for it, and /model opus[1m] still applies the suffix.

For allowlists on these providers, list the full provider-form ID (prefixes like us.anthropic. are not stripped) or map it with modelOverrides.

Picker labels and capabilities

Unrecognised IDs (ARNs, Foundry deployment names) show raw in the picker and may lose features like effort. Each pinned variable, and ANTHROPIC_CUSTOM_MODEL_OPTION, accepts companion variables with these suffixes: _NAME, _DESCRIPTION and _SUPPORTED_CAPABILITIES. Capabilities are a comma list of effort, xhigh_effort, max_effort, thinking, adaptive_thinking and interleaved_thinking; once set, unlisted capabilities are disabled. _NAME and _DESCRIPTION also work behind an LLM gateway; none of them affect direct api.anthropic.com sessions.

modelOverrides for per-version routing

When one ID per family is not enough, modelOverrides maps individual Anthropic model IDs to provider strings:

{
  "modelOverrides": {
    "claude-opus-4-8": "arn:aws:bedrock:eu-west-2:111122223333:application-inference-profile/opus-finance",
    "claude-sonnet-4-5-20250929": "arn:aws:bedrock:eu-west-2:111122223333:application-inference-profile/sonnet-shared"
  }
}

Keys must be real Anthropic model IDs (with any date suffix exactly); unknown keys are ignored. Overrides beat Bedrock's auto-discovered profiles and also apply to IDs passed via --model or environment variables (from v2.1.200). The allowlist is evaluated against the Anthropic ID, not the mapped value. When availableModels is managed, only managed modelOverrides count. Mapping a gateway alias as a value also silences the [claude-code:unrecognized_model] diagnostic.

A custom picker entry

To add one extra row without replacing the built-ins:

export ANTHROPIC_CUSTOM_MODEL_OPTION="corp-proxy/claude-sonnet-5-5"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet (corp proxy)"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Routed through the shared platform team gateway"

The ID is not validated. Name and description are optional. If you use availableModels, add the custom ID to it. For several custom rows in your own order use the modelPicker setting (see settings reference), and for gateways that list models set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1.

Prompt caching switches

Caching is automatic (see prompt caching). To turn it off:

VariableTurns caching off for
DISABLE_PROMPT_CACHING=1Every model (overrides the rest)
DISABLE_PROMPT_CACHING_HAIKU=1The default Haiku model
DISABLE_PROMPT_CACHING_SONNET=1The default Sonnet model
DISABLE_PROMPT_CACHING_OPUS=1The default Opus model
DISABLE_PROMPT_CACHING_FABLE=1Fable models