模型配置

在 Claude Code 的 model 设置里，你可以配置模型别名，或模型名：Anthropic API 上是完整的模型名，Amazon Bedrock 上是推理配置文件 ARN，Microsoft Foundry 上是部署名，Google Cloud 的 Agent Platform 上是版本名。

ANTHROPIC_BASE_URL 改变请求发往哪里，而不是哪个模型来回答。要通过 LLM 网关路由 Claude，见自定义模型：LLM 网关与兼容接口。

模型别名

用别名选择模型设置，不必记住确切的版本号：

opus 和 sonnet 别名解析到哪个版本取决于提供商。在 Anthropic API 上，opus 是 Opus 5.5、sonnet 是 Sonnet 5.5；在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上，opus 是 Opus 5.5、sonnet 是 Sonnet 4.5；在 Microsoft Foundry 上，opus 是 Opus 4.6、sonnet 是 Sonnet 4.5。别名指向你的提供商的推荐版本并随时间更新。想固定到特定版本，使用完整模型名（如 claude-opus-5-5），或设置对应的环境变量，如 ANTHROPIC_DEFAULT_OPUS_MODEL。

Sonnet 5.5 需要 Claude Code v2.1.284 或更新版本，Opus 5.5 需要 v2.1.280 或更新版本。运行 claude update 升级。

设置你的模型

按优先级从高到低：

1. 会话中：用 /model <alias|name> 立即切换，或不带参数运行 /model 打开选择器
2. 启动时：claude --model <alias|name>
3. 环境变量：设置 ANTHROPIC_MODEL=<alias|name>
4. 设置：在设置文件里用 model 字段永久配置
5. 新会话的默认值：设置 ANTHROPIC_DEFAULT_MODEL=<alias|name>（需要 v2.1.236 或更新版本）

/model 会把你的选择作为新会话的默认值保存，写入用户设置里的 model 字段。在选择器里：Enter 切换模型并保存为默认；s 只在本会话切换模型，不改变你的默认值。

--model 标志和 ANTHROPIC_MODEL 环境变量只对你用它们启动的那个会话生效。想在不同终端同时运行不同的模型，为每个都用自己的 --model 标志启动，而不是用 /model 切换。用 claude --resume、--continue 或 /resume 恢复的会话，会保持转录保存时所用的模型，不管当前 model 设置如何。

如果你用 --model 标志、ANTHROPIC_MODEL 环境变量或 model 设置设定模型，Claude Code 不会预先检查，拼写错误的值会在第一次请求时报错「There's an issue with the selected model」。

例如，用 Opus 启动会话，然后在会话里切换：

claude --model opus

/model sonnet

设置文件示例：

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

新会话没有以你选的模型开始，常见原因：你为一个会话选的（在选择器里按了 s、用 --model 启动，或在非交互模式里运行 /model，这些都只作用于当前会话，不改变你保存的默认值）；有更高优先级的东西设置了模型（项目或托管设置里的 model 值、你 shell 里的 ANTHROPIC_MODEL，或管理员设定要覆盖用户选择的组织默认值）；Claude Code 无法保存你的选择（/model 把 model 写入 ~/.claude/settings.json，如果你无法写这个文件，选择只在本会话有效）；你恢复了一个会话。

特殊的模型行为

default：default 的行为取决于账号类型：Pro、Max、Team、Enterprise 和 Anthropic API 默认是 Opus 5.5；Claude Platform on AWS、Amazon Bedrock 和 Google Cloud 的 Agent Platform 默认也是 Opus 5.5；Microsoft Foundry 默认是 Sonnet 4.5。管理员设置了组织默认模型时，default 解析为那个模型。

opusplan：自动的混合方式——计划模式下用 opus 做复杂推理和架构决策，执行模式下自动切到 sonnet 做代码生成和实现，把 Opus 的推理用在规划、Sonnet 的效率用在执行上。

调整努力等级

努力等级控制自适应推理，让模型在每一步根据任务复杂度决定是否思考以及思考多少。对简单任务，较低的努力更快更省，较高的努力则为复杂问题提供更深的推理。可用的等级取决于模型：Fable 5.1 / 5、Opus 5.5 / Sonnet 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。设置了活动模型不支持的等级时，Claude Code 会回退到不高于所设等级的最高受支持等级（例如 xhigh 在 Opus 4.6 上按 high 运行）。

选择等级：

设置方式：/effort（不带参数打开交互式滑块，或 /effort <level> 直接设置，/effort auto 清除为活动模型保存的等级）；在 /model 里选模型时用左右箭头调整努力滑块；--effort 标志（对单个会话设置）；环境变量 CLAUDE_CODE_EFFORT_LEVEL；设置里的 modelSettings 按模型设置，或 effortLevel 作为没有按模型设置的模型的默认值（不接受 max）；Skill 和子智能体前置信息里的 effort，覆盖该 Skill 或子智能体运行时的努力等级。在提示里任意位置写上 ultrathink 可以让这一回合更深入地推理，而不改变你的会话努力设置。

扩展思考

扩展思考是 Claude 在回答之前发出的推理。在支持自适应推理的模型上，努力等级是控制思考多少的主要手段；下面的设置控制思考的开关和显示：按 Option+T（macOS）或 Alt+T（Windows 和 Linux）切换当前会话；运行 /config 切换思考模式设置全局默认值（保存为 ~/.claude/settings.json 里的 alwaysThinkingEnabled）；设置环境变量 MAX_THINKING_TOKENS=0 可禁用。在 Opus 5.5、Sonnet 5.5 和 Fable 模型上无法关闭思考。Claude Code 默认折叠思考输出，按 Ctrl+O 切换详细模式，以灰色斜体文字显示推理。

扩展上下文

Fable 5.1、Fable 5、Sonnet 5 及更新版本、Opus 4.6 及更新版本和 Sonnet 4.6 支持 100 万 token 上下文窗口，适合有大型代码库的长会话。在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更新版本、Opus 4.7 及更新版本在所有套餐（包括 Pro）上都以 1M 窗口运行，不需要选择 [1m] 变体。Opus 4.6 和 Sonnet 4.6 只能通过 [1m] 变体到达 1M，访问取决于你的套餐。

添加自定义模型选项

用 ANTHROPIC_CUSTOM_MODEL_OPTION 向 /model 选择器里添加一个自定义条目，而不替换内置别名，适合测试 Claude Code 默认不列出的模型 ID。下面的例子设置三个变量，让一个经网关路由的 Opus 部署可被选择。Claude Code 在启动时读取环境变量，所以要在启动 claude 之前运行这些 export，或重启已有会话让它们生效：

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-5-5"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

_NAME 和 _DESCRIPTION 是可选的：省略名称时，条目显示模型名（如果 Claude Code 认得这个 ID）或模型 ID；省略描述时，Claude Code 用 Custom model (<model-id>)。自定义条目列在内置条目之后。Claude Code 不校验 ANTHROPIC_CUSTOM_MODEL_OPTION 里设置的模型 ID，所以可以用你的 API 端点接受的任何字符串。设置了 availableModels 时，也要把自定义模型 ID 包含进白名单，否则选择器会过滤掉这个自定义条目。

环境变量

用下面的环境变量控制别名映射到的模型名。每个值必须是完整的模型名，或你的 API 提供商的等价标识符。

注：ANTHROPIC_SMALL_FAST_MODEL 已弃用，改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。

为第三方部署固定模型

通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 部署 Claude Code 时，在向用户推广之前先固定模型版本。不固定的话，Claude Code 使用 fable、opus、sonnet、haiku 这类别名，它们解析为每个提供商的内置默认模型 ID。那个默认值可能落后于 Anthropic 的最新发布，它指向的模型也可能还没在用户账号里启用。

对 ANTHROPIC_DEFAULT_FABLE_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 套用同样的模式。想为固定的模型启用扩展上下文，在 ANTHROPIC_DEFAULT_OPUS_MODEL 等变量里的模型 ID 后追加 [1m]，Claude Code 在把模型 ID 发给你的提供商之前会去掉这个后缀。

自定义固定模型的显示与能力

在第三方提供商上固定模型时，它在 /model 选择器里的那一行默认显示模型名（如果 Claude Code 认得固定的 ID），否则显示原始 ID。Claude Code 可能也不知道固定的模型支持哪些功能（努力等级、扩展思考等是靠把模型 ID 与已知模式匹配来启用的，Bedrock ARN 或自定义部署名通常匹配不上，导致本应支持的功能被禁用）。可以为每个固定模型设置配套的环境变量：

• ANTHROPIC_DEFAULT_OPUS_MODEL_NAME：在选择器里显示的名称
• ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION：在选择器里显示的描述
• ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES：该模型支持的能力，逗号分隔，可选值有 effort、xhigh_effort、max_effort、thinking、adaptive_thinking、interleaved_thinking

同样的 _NAME、_DESCRIPTION、_SUPPORTED_CAPABILITIES 后缀也适用于 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_FABLE_MODEL 和 ANTHROPIC_CUSTOM_MODEL_OPTION。设置了 _SUPPORTED_CAPABILITIES 时，Claude Code 启用所列的能力并禁用未列的；未设置时回退到基于模型 ID 的内置检测。下面的例子把 Opus 固定到一个 Amazon Bedrock 自定义模型 ARN，设置友好名称并声明能力：

export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'
export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.7 routed through a Bedrock custom endpoint'
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

按版本覆盖模型 ID

环境变量按家族别名配置一个模型 ID。如果你需要把同一家族里的多个版本映射到不同的提供商 ID，改用 modelOverrides 设置。它把单个 Anthropic 模型 ID 映射到 Claude Code 发给提供商 API 的提供商特定字符串，让企业管理员能把每个模型版本路由到特定的 Amazon Bedrock 推理配置文件 ARN、Google Cloud 的 Agent Platform 版本名或 Microsoft Foundry 部署名，用于治理、成本分摊或区域路由：

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  }
}

键必须是 Anthropic 的模型 ID（带日期后缀的模型 ID 要完整包含日期后缀），未知的键会被忽略。覆盖会替换支撑 /model 选择器每个条目的内置模型 ID，也适用于你通过 --model、ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_*_MODEL 环境变量直接传入 Anthropic 模型 ID 的情况。

提示缓存配置

Claude Code 自动使用提示缓存来优化性能和降低成本，可以全局或对特定模型层级禁用：DISABLE_PROMPT_CACHING=1 对所有模型禁用（优先于按模型的设置）；DISABLE_PROMPT_CACHING_HAIKU、DISABLE_PROMPT_CACHING_SONNET、DISABLE_PROMPT_CACHING_OPUS、DISABLE_PROMPT_CACHING_FABLE 分别对对应的默认模型禁用。

深入阅读

• 选择与设置模型：Fable、/model 的保存与作用范围、新会话默认模型、新会话没有以你选的模型开始的原因
• 限制模型选择：availableModels、enforceAvailableModels、deniedModels、各界面覆盖范围、组织限制与组织默认模型、努力上限
• 特殊模型行为：default、opusplan、后备模型链、自动模型降级
• 努力、思考与扩展上下文：努力等级与 ultracode、扩展思考、1M 上下文
• 上下文窗口与自动压缩：压缩窗口设置、默认阈值、网关与自定义模型 ID 的窗口修正
• 固定模型与覆盖：第三方部署固定模型、显示与能力变量、modelOverrides、提示缓存、版本历史