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
opusorsonnet, which Claude Code resolves to a specific version for you. - A concrete model identifier. What that looks like depends on where your requests go:
| Provider | Form of the identifier |
|---|---|
| Anthropic API | A full model name, for example claude-opus-5-5 |
| Amazon Bedrock | An inference profile ARN |
| Microsoft Foundry | A deployment name |
| Google Cloud's Agent Platform | A version name |
Note: Setting
ANTHROPIC_BASE_URLonly changes where requests travel. It does not choose the model. For routing through a proxy, see LLM gateways.
Aliases
| Alias | What it gives you |
|---|---|
default | Not really an alias: it clears any override so you land on your account's runtime default (see the default model) |
best | Whatever fable resolves to, if Fable is available to you; otherwise the same as opus |
fable | The Fable model for your provider, aimed at the longest and hardest jobs |
opus | The latest Opus, for heavy reasoning |
sonnet | The latest Sonnet, the everyday coding workhorse |
haiku | Haiku, 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 |
opusplan | Opus 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:
| Provider | opus | sonnet | haiku |
|---|---|---|---|
| Anthropic API | Opus 5.5 | Sonnet 5.5 | Haiku 5.5 |
| Claude Platform on AWS | Opus 5.5 | Sonnet 4.6 | Haiku 4.5 |
| Amazon Bedrock, Google Cloud's Agent Platform | Opus 5.5 | Sonnet 4.5 | Haiku 4.5 |
| Microsoft Foundry | Opus 4.6 | Sonnet 4.5 | Haiku 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 updateif a request fails because your client is too old.
When an alias changed
| Claude Code version | What moved |
|---|---|
| v2.1.293 | haiku becomes Haiku 5.5 on the Anthropic API |
| v2.1.284 | sonnet becomes Sonnet 5.5 on the Anthropic API |
| v2.1.280 | opus becomes Opus 5.5 on the Anthropic API, Claude Platform on AWS, Bedrock and Agent Platform |
| v2.1.257 | fable becomes Fable 5.1 (not in Claude apps gateway sessions) |
| v2.1.219 | opus becomes Opus 5 on the Anthropic API, Claude Platform on AWS, Bedrock and Agent Platform |
| v2.1.207 | opus becomes Opus 4.8 on Claude Platform on AWS, Bedrock and Agent Platform |
| v2.1.197 | sonnet becomes Sonnet 5 on the Anthropic API |
| v2.1.154 | opus 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 fableorclaude --model fable. - Fable 5: select it by ID, for example
claude --model claude-fable-5on the Anthropic API, or pin your provider's ID withANTHROPIC_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-5orclaude-fable-5[1m]and you talk to the Anthropic API directly, Claude Code rewrites it once tofableorfable[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:
/model <alias|name>during a session, or/modelalone for the picker.claude --model <alias|name>at launch.- The
ANTHROPIC_MODELenvironment variable. - The
modelkey in a settings file. 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:
| Key | Effect |
|---|---|
Enter | Switch and save as default |
s | Switch 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
modelin 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 byavailableModels. On Bedrock, Agent Platform and Foundry the saved model is never restored. If yourmodelsetting ishaiku, a resumed Haiku session moves to whateverhaikuresolves to today.--model,ANTHROPIC_MODELand (from v2.1.195) anANTHROPIC_DEFAULT_*_MODELvariable 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_HOSTget to override managed model settings, though a managedavailableModelslist still applies unless the host supplies one. - Hooks can veto.
PreModelSwitchhooks 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_MODELor themodelsetting 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
-ptext mode, but not with--output-format jsonorstream-json, where you should readmodelUsagein 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:
sin the picker,--model, or/modelin-pmode. - Something outranks you: a
modelin project or managed settings,ANTHROPIC_MODELin your shell profile, or an organisation default set to override users. - The save failed:
/modelcould 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 type | Default |
|---|---|
| Pro, Max, Team, Enterprise, Anthropic API | Opus 5.5 |
| Claude Platform on AWS, Amazon Bedrock, Google Cloud's Agent Platform | Opus 5.5 |
| Microsoft Foundry | Sonnet 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.
| Models | Levels available |
|---|---|
| Fable 5.1, Fable 5 | low, medium, high, xhigh, max |
| Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7 | low, medium, high, xhigh, max |
| Opus 4.6, Sonnet 4.6 | low, 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:
- An explicit choice:
CLAUDE_CODE_EFFORT_LEVEL,--effort, or/effortin the session. - Your settings: a per-model level saved under
modelSettings, or aneffortLevelkey. - The model's own default:
highfor most models,mediumfor Opus 5.5, Sonnet 5.5 and Haiku 5.5,xhighfor 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:
Enterin the/effortslider or the/modelpicker, or typing/effort high, saves it as the default for that model undermodelSettings.sin either applies it to this session only (v2.1.257+).maxis always session-only unless it comes fromCLAUDE_CODE_EFFORT_LEVEL.- In
-pruns and from Remote Control devices, a chosen level applies to that session only.
Picking a level
| Level | Where I reach for it |
|---|---|
low | Throwaway questions, renames, quick sketches I will review anyway |
medium | Default on Opus 5.5, Sonnet 5.5 and Haiku 5.5. Well-scoped feature work |
high | Bug fixing in existing code, anything with edge cases. Default on most other models |
xhigh | Deeper reasoning at higher spend. Default on Opus 4.7 |
max | Long 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
/effortopens a slider;/effort xhighsets directly;/effort autoclears 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 highfor one session.CLAUDE_CODE_EFFORT_LEVELset to a level orauto.modelSettingsper model, oreffortLevel(low,medium,highorxhigh;maxis not accepted in either key).- The effort control on a phone or browser over Remote Control (v2.1.234+), session-only.
- An
effortfield 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 ultracodeturns it on for the session;/effort ultracode offturns it off;Tabflips it in the slider.claude --effort ultracodeturns it on and sets effort toxhigh(v2.1.203+)."ultracode": truein settings or via--settings. The SDK'seffortLevel: "ultracode"also setsxhigh.effortLevelandCLAUDE_CODE_EFFORT_LEVELdo not acceptultracode.
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 want | How |
|---|---|
| Toggle thinking for this session | Option+T on macOS, Alt+T on Windows and Linux |
| Change the saved default | /config, thinking mode (stored as alwaysThinkingEnabled) |
| Turn it off via environment | MAX_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:
| Plan | Opus 4.6 at 1M | Sonnet 4.6 at 1M |
|---|---|---|
| Max, Team (Standard and Premium), Enterprise | Included | Usage credits |
| Pro | Usage credits | Usage credits |
| API and pay-as-you-go | Full access | Full 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:
| Where | Scope |
|---|---|
/autocompact 400k | Current model, saved under modelSettings; /autocompact auto restores the tuned value |
autoCompactWindow in settings | Every model (a per-model value in the same file wins) |
--autocompact <size> | One launch; --autocompact auto forces the tuned window |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | Overrides 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 model | Cybersecurity flag | Biology flag |
|---|---|---|
| Fable 5.1, Fable 5, Opus 5.5 | Opus 4.8 | Opus 5 |
| Sonnet 5.5 | Sonnet 5 | Refusal |
| Opus 5 | Opus 4.8 | Refusal |
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 inavailableModelspermits 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'
| Variable | Controls |
|---|---|
ANTHROPIC_DEFAULT_FABLE_MODEL | fable, and what counts as Fable for flag fallback |
ANTHROPIC_DEFAULT_OPUS_MODEL | opus, and the plan phase of opusplan |
ANTHROPIC_DEFAULT_SONNET_MODEL | sonnet, and the execution phase of opusplan |
ANTHROPIC_DEFAULT_HAIKU_MODEL | haiku and background tasks (replaces the deprecated ANTHROPIC_SMALL_FAST_MODEL) |
CLAUDE_CODE_SUBAGENT_MODEL | Subagents, 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:
| Variable | Turns caching off for |
|---|---|
DISABLE_PROMPT_CACHING=1 | Every model (overrides the rest) |
DISABLE_PROMPT_CACHING_HAIKU=1 | The default Haiku model |
DISABLE_PROMPT_CACHING_SONNET=1 | The default Sonnet model |
DISABLE_PROMPT_CACHING_OPUS=1 | The default Opus model |
DISABLE_PROMPT_CACHING_FABLE=1 | Fable models |