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 5

• 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 5 and usage credits

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

​

Setting your model

1. During session: use /model <alias|name> to switch immediately, or run /model with no argument to open the picker. The picker asks for confirmation when the conversation has prior output, since the next response re-reads the full history without cached context
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

• Enter: switch model and save as your default
• s: switch model for this session only

• 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"
}

​

Restrict model selection

• Main session model: /model, the --model flag, the ANTHROPIC_MODEL environment variable, the model setting, 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
• Subagent or teammate override: Claude Code falls back to the subagent’s inherited model or the lead’s model for a teammate rather than failing the request. 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 Fable 5. 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 fall back to the managed settings file in the runner image when your organization delivers no server-managed settings; when both exist, the server-managed payload takes precedence, with the per-key env merge exception described in settings precedence. 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, is not a Claude Code surface and does not receive server-managed settings by design. 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 organization login or a directly configured API 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 Default option and the sonnet, opus, haiku, and fable aliases resolve to

{
  "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.

​

Organization default model

• the --model flag and the ANTHROPIC_MODEL environment variable
• a model value in managed settings or supplied through --settings
• a model value in your user, project, or local settings, including a model you save with /model

• availableModels on its own never constrains the Default option, so an organization default outside the allowlist still applies. When enforceAvailableModels is also set, an organization default outside the allowlist is remapped to the first allowlist entry, like any other Default
• an organization default that organization model restrictions deny for your account is replaced by the newest allowed model in its family, or a lower-cost family when every version of it is restricted
• an organization default that isn’t available to your account at all, such as Fable 5 under zero data retention, is skipped, and the Default option resolves to the account-type default

​

Organization effort limits

​

Special model behavior

​

default model setting

• Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API: defaults to Opus 5
• Claude Platform on AWS, Amazon Bedrock, and Google Cloud’s Agent Platform: defaults to Opus 5
• Pro, Team Standard, and Enterprise subscription seats: defaults to Sonnet 5
• Microsoft Foundry: defaults to Sonnet 4.5

​

opusplan model setting

• In plan mode: uses opus for complex reasoning and architecture decisions
• In execution mode: automatically switches to sonnet for code generation and implementation

​

Fallback model chains

claude --fallback-model sonnet,haiku

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

• Outside the allowlist: Claude Code drops any entry not permitted by availableModels when it reads the chain.
• Smaller context window during compaction: the chain also covers compaction, but Claude Code won’t fall back to a model with a smaller context window than the primary’s, since summarizing there would cut off part of the conversation first. If every fallback is smaller, compaction shows the original error and you can retry.

​

Automatic model fallback

• Fable 5: biology-flagged requests re-run on Opus 5, and cybersecurity-flagged requests re-run on Opus 4.8.
• Opus 5: cybersecurity-flagged requests re-run on Opus 4.8. Biology-flagged requests end with a refusal instead, because Opus 5 runs its own biology classifiers with no fallback model.

​

Check what triggered fallback

​

Ask before switching

• When the flagged category has no fallback model, such as a biology flag on Opus 5, Claude Code doesn’t show the prompt and the request ends with the refusal.
• If both models flag the same request, you can edit the prompt and retry, or start a new session.
• On mobile Claude Code on the web sessions, editing and retrying is not supported. Switch models, or continue the session from a desktop browser or the desktop app.
• In non-interactive mode and SDK integrations that can’t show the prompt, a flagged request ends the turn with a refusal instead.
• When the fallback target is blocked by availableModels, Claude Code doesn’t show the prompt. The flagged request ends with the refusal, the same as automatic fallback when the target is blocked.

​

Enable fallback on Bedrock, Agent Platform, and Foundry

• Claude Code must recognize the current model as a fallback source. Fable 5 is recognized when the model ID contains claude-fable-5, matches the value of ANTHROPIC_DEFAULT_FABLE_MODEL, or is mapped with modelOverrides. Opus 5 is recognized by its provider model ID or a modelOverrides mapping.
• The fallback model must resolve in your deployment. If you set ANTHROPIC_DEFAULT_OPUS_MODEL, flagged requests re-run on that model for every category that has a fallback; a biology flag on Opus 5 still ends with a refusal. If you don’t set it, cybersecurity-flagged requests re-run on an Opus 4.8 entry in the provider’s model list, and biology-flagged requests from Fable 5 on an Opus 5 entry.

​