Model configuration

​

Available models

• A model alias
• A model name
  • Anthropic API: a full model name
  • Amazon Bedrock: an inference profile ARN
  • Microsoft Foundry: a deployment name
  • Google Cloud’s Agent Platform: a version name

​

Model aliases

​

Work with Fable

• Fable 5.1: run /model fable, or launch with claude --model fable. In Claude apps gateway sessions, where the alias resolves to Fable 5, run /model claude-fable-5-1 instead.
• Fable 5: select it by model ID. On the Anthropic API, run /model claude-fable-5 or launch with claude --model claude-fable-5. On other providers, use your provider’s Fable 5 model ID or pin it with ANTHROPIC_DEFAULT_FABLE_MODEL.

• Describe the outcome, not the steps: hand it the result you want and let it plan the path. To keep it working toward that outcome, set a goal.
• Hand it ambiguous problems: root-cause investigations, outage debugging, and architecture decisions are where the extra investigation and verification pay off.
• Skip the verification reminders: it verifies its own work with less prompting, so reminders to test or check are usually unnecessary.
• Size up larger tasks: give it work you would normally break into pieces. It holds long sessions without losing the thread.

​

Fable and usage credits

• In the /model picker, you keep your current model.
• Mid-session, Claude Code continues the turn on your default model.

• With Remote Control connected or in a teammate’s session, press any key at the terminal to cancel the deadline, and Claude Code waits for your answer.
• In a background session, answer before the deadline.
• If you send a new message from the remote client before anyone has typed at the terminal, Claude Code ends the turn the same way, and your new message starts the next turn. After someone types at the terminal, Claude Code keeps waiting for the answer and queues your new message behind it.

​

Setting your model

1. During session: use /model <alias|name> to switch immediately, or run /model with no argument to open the picker. See when Claude Code asks you to confirm the switch
2. At startup: launch with claude --model <alias|name>
3. Environment variable: set ANTHROPIC_MODEL=<alias|name>
4. Settings: configure permanently in your settings file using the model field
5. Default for new sessions: set ANTHROPIC_DEFAULT_MODEL=<alias|name>

• Enter: switch model and save as your default
• s: switch model for this session only and leave your default unchanged. To use a different key, rebind modelPicker:thisSessionOnly

• a model alias
• an entry from the /model picker
• any name that starts with claude-
• a value you configured yourself as a custom model option or in modelOverrides

claude --model opus

/model sonnet

{
    "permissions": {
        "allow": ["Bash(npm run lint)"]
    },
    "model": "opus"
}

​

Set a default model for new sessions

• The --model flag
• ANTHROPIC_MODEL
• A model value in any settings file, including the choice you save with /model
• An organization default model

• You set it to default, inherit, opusplan, or haiku
• enforceAvailableModels is on
• availableModels or organization model restrictions exclude the model
• The model isn’t available to your account

​

A new session starts on a different model than you picked

• You chose it for one session. Pressing s in the picker, launching with --model, and running /model in non-interactive mode all apply to the current session and leave your saved default alone.
• Something with higher priority sets the model. A model value in project or managed settings, ANTHROPIC_MODEL in your shell, or an organization default your admin set to override user choices applies again at every launch. Your /model choice is still saved; it’s outranked. When project or managed settings set the model, the startup header names the file.
• Claude Code couldn’t save your choice. /model writes model to ~/.claude/settings.json. If you can’t write to that file, for example because another tool generates it or links it to a read-only copy, the model you chose lasts for the session and the next launch reads the old value. Set model in the tool that generates the file, or make the file writable. See A change you made in Claude Code is lost in new sessions.
• You resumed a session. A session you resume with claude --resume or --continue usually keeps the model it was using rather than your current default.

​

Restrict model selection

• Main session model: /model, the --model flag, the ANTHROPIC_MODEL environment variable, the model setting, ANTHROPIC_DEFAULT_MODEL, and the model restored when resuming a session
• Alias resolution: the ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, and ANTHROPIC_DEFAULT_FABLE_MODEL environment variables cannot redirect an allowed alias to a model outside the list
• Fast mode: /fast refuses to toggle when it would implicitly switch to an Opus model outside the list, with the message “is not in your organization’s allowed models”
• Subagent and teammate models: the model field in subagent frontmatter, the Agent tool’s model parameter, agent team teammate models, CLAUDE_CODE_SUBAGENT_MODEL, and, on v2.1.197 and earlier, the model picker in the /agents wizard
• Skill and command models: the model frontmatter in skills and commands
• Advisor model: the configured advisorModel setting and the --advisor flag
• Background agent model: the model selected in the dispatch picker

• /model: Claude Code rejects the switch with an error
• --model flag, ANTHROPIC_MODEL, or the model setting: Claude Code replaces the value at startup with a warning naming both the requested and substituted models, and the session starts on the default model
• ANTHROPIC_DEFAULT_MODEL: Claude Code ignores the variable
• Subagent or teammate override: Claude Code runs the subagent or teammate on a fallback model rather than failing the request. See Choose a model for the subagent fallback and Specify teammates and models for the teammate fallback. In interactive sessions, Claude Code warns you when it substitutes a subagent’s model, by this fallback or by the newest-permitted-version substitution above, naming the requested and substituted models; it doesn’t report a teammate’s fallback. Where the newest-permitted-version substitution above operates, a blocked family alias follows it instead. Before v2.1.222, an alias fell back like any other blocked value on every provider
• Skill or command override: Claude Code ignores the override, including a blocked family alias, and the skill or command runs on the session model. A skill or command that runs in a subagent follows the subagent behavior above instead
• advisorModel setting: the advisor is disabled for the session
• --advisor flag: Claude Code exits with an error at launch. In a background session, it starts the session without the advisor instead of exiting

• Fallback model chains: entries outside the allowlist are dropped
• Plan-mode upgrades: on the Anthropic API and Claude Platform on AWS, an upgrade such as opusplan to an excluded model uses the newest permitted version of the upgrade family. On providers with provider-specific model IDs, and when no version is permitted, the upgrade is skipped and planning continues on the session’s model
• Automatic model fallback: a fallback whose target is excluded does not run, so the flagged request ends with a refusal instead
• Auto mode classifier: the classifier’s Claude Sonnet 5 default applies only when the allowlist permits Sonnet 5. When it’s excluded, the classifier runs on the session’s model, which the allowlist already governs, or on an Opus model when the session runs on a Fable model. On providers other than the Anthropic API, that Opus fallback runs on the provider’s default Opus model without consulting the allowlist. Requires Claude Code v2.1.210 or later
• Fast mode: enabling fast mode is refused when the model the session would run on afterward is outside the allowlist

{
  "availableModels": ["sonnet", "haiku"]
}

​

Surface coverage

• Cloud sessions, on Claude Code on the web or in the Desktop app, run on Anthropic-managed VMs by default: settings deployed to your device do not reach them, so deliver the allowlist through server-managed settings. Sessions your organization routes to a self-hosted environment run on your own compute and also read the managed settings file in the runner image. How Claude Code combines managed sources says when that file applies. A mid-session model switch in a cloud session is rejected when the requested model is excluded by the allowlist. Server-side rejection at session creation applies to organization model restrictions, not the availableModels settings key.
• Cowork, the agentic-work tab in the Claude Desktop app, runs its sessions on Claude Code but, by design, does not receive server-managed settings from the claude.ai admin console. A managed settings file applies to Cowork sessions when it is present where the session runs; remote Cowork sessions run on Anthropic-managed VMs, where a device-deployed file is not present.
• Sessions on third-party providers such as Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and Claude Platform on AWS do not receive server-managed settings, so deliver the allowlist through MDM or managed settings files there.
• Server-managed delivery also requires the session to authenticate with an eligible login or key. Fleets that generate keys only through an apiKeyHelper script should deliver the allowlist through MDM or managed settings files.
• The Desktop Code tab also hosts SSH sessions, which read the managed settings file from the remote host they run on. See Desktop managed settings.
• The model pickers on claude.ai and in the Desktop app hide or grey out models excluded by your organization’s allowlist. The picker state is a convenience for users; enforcement happens in the session.

​

Default model behavior

​

Enforce the allowlist for the Default model

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

​

Control the model users run on

• availableModels: restricts which named models users can switch to
• enforceAvailableModels: extends the availableModels allowlist to the Default option, so Default cannot resolve to a model outside the list
• model: sets the initial model selection when a session starts
• ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL / ANTHROPIC_DEFAULT_FABLE_MODEL: control what the sonnet, opus, haiku, and fable aliases resolve to, and which version the account-type default uses

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "enforceAvailableModels": true,
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

​

Merge behavior

​

Mantle model IDs

​

Organization model restrictions

• Disabling a model at the organization level removes it for every member.
• Role-level access grants different models to different custom roles, and a member who holds several roles can use any model that one of their roles grants.
• Haiku models are always available and can’t be disabled, so every member keeps at least one usable model.
• An access change takes effect on new requests within about a minute; the /model picker reflects it the next time a session starts.

​