Claude Code支持通过模型别名（opus/sonnet/haiku）和opusplan混合模式灵活切换底层模型，可按会话、启动参数、环境变量或配置文件设置。本文包含别名对照表、四种切换方式及优先级、opusplan计划/执行分阶段切换机制、推理力度调节（low到max）、100万token扩展上下文支持情况，以及企业通过availableModels限制模型选择、第三方部署版本固定的方法。

Claude Code 模型配置：别名、切换、推理力度与扩展上下文 #

可用模型 #

在Claude Code的model配置中，可以填写两类值：

• 模型别名：简短名称，始终指向当前推荐版本
• 模型全名：具体版本号
  • Anthropic API：完整model name
  • Bedrock：inference profile ARN
  • Foundry：deployment name
  • Vertex：version name

ANTHROPIC_BASE_URL 更改的是请求发送的目标地址，不是回答问题的模型。要通过LLM网关路由Claude，见 LLM网关配置。

模型别名对照表 #

在Anthropic API和Claude Platform on AWS上，opus解析为Opus 4.7，sonnet解析为Sonnet 4.6。在Bedrock、Vertex和Foundry上，opus解析为Opus 4.6，sonnet解析为Sonnet 4.5；在这些提供商上使用新版模型需要选择完整model name或设置ANTHROPIC_DEFAULT_OPUS_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL。

别名指向当前推荐版本并会随时间更新。要锁定特定版本，用完整model name（如claude-opus-4-7）或设置对应的环境变量（如ANTHROPIC_DEFAULT_OPUS_MODEL）。

Opus 4.7需要Claude Code v2.1.111或更新版本。运行claude update升级。

切换模型的四种方式 #

按优先级从高到低：

1. 会话内切换 — 使用/model <别名|名称>立刻切换，或者运行/model不接参数打开选择器。选择器在对话已有历史输出时会询问确认，因为下次响应需要重新读取完整历史且不保留缓存上下文
2. 启动时指定 — claude --model <别名|名称>
3. 环境变量 — 设置ANTHROPIC_MODEL=<别名|名称>
4. 配置文件 — 在settings文件中用model字段持久配置

v2.1.144开始，/model仅应用于当前会话，不会写入settings。要让选择持久化为新会话的默认值，在选择器中高亮某行时按d键，会将model字段写入用户settings。managed settings优先级更高并在下次启动时覆盖。

--model参数和ANTHROPIC_MODEL环境变量也只对启动的当前会话生效。想在不同终端同时运行不同模型，给每个终端配各自的--model参数，不要用/model切换。

用claude --resume、--continue或/resume选择器恢复的会话，会保留保存时的模型设置，不受当前model配置影响。如果该模型已退役，则会按正常优先级回退。这避免了一个会话的/model选择影响到恢复时的模型。

启动时如果模型来自project settings或managed settings而非用户自身选择，启动头会显示哪个文件设定的。运行/model可以覆盖当前会话。

使用示例：

# 使用Opus启动
claude --model opus

# 会话内切换到Sonnet
/model sonnet

settings文件示例：

{
    "permissions": {
        ...
    },
    "model": "opus"
}

企业管理员：限制可用模型 #

企业管理员可在managed或policy settings中使用availableModels限制用户可选模型。

设置后，用户无法通过/model、--model参数或ANTHROPIC_MODEL环境变量切换到列表外的模型。

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

default选项的行为 #

模型选择器中的Default选项不受availableModels影响。它始终可用，代表系统运行时根据用户订阅级别决定的默认模型。

即使设置availableModels: []，用户仍可用Default模型正常使用Claude Code。

完整控制用户使用的模型 #

model设置只决定初始选择，不是强制限制。它设定会话开始时用的模型，但用户仍可以打开/model选择并选Default，而Default会解析为订阅级别的系统默认模型，不受model设置影响。

要完全控制模型体验，组合三个设置：

• availableModels：限制用户可以切换到哪些命名模型
• model：设置会话启动时的初始模型
• ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL：控制Default选项以及sonnet、opus、haiku别名解析到哪个具体模型

以下示例让用户以Sonnet 4.5启动，限制只能在Sonnet和Haiku之间选，并将Default固定为Sonnet 4.5（而不是最新版）：

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

不加env块，用户在选择器中选Default时会得到最新Sonnet版本，绕过model和availableModels里的版本固定。

多层配置合并规则 #

多个settings层都设置了availableModels时，数组会合并去重。要执行严格白名单，在managed或policy settings（最高优先级）中设置。

Mantle model ID #

启用Bedrock Mantle端点后，availableModels中以anthropic.开头的条目会作为自定义选项加入/model选择器，并路由到Mantle端点。这是第三方部署模型版本固定中别名匹配规则的一个例外。但选择器仍然只显示列表中的条目，所以设置时需要同时包含标准别名和Mantle ID。

特殊模型行为 #

各账户类型的默认模型 #

default别名根据账户类型行为不同：

• Max和Team Premium：默认Opus 4.7
• Pro、Team Standard、Enterprise和Anthropic API：默认Sonnet 4.6
• Bedrock、Vertex和Foundry：默认Sonnet 4.5

如果Opus用量超过阈值，Claude Code会自动降级到Sonnet。

2026年4月23日起，Enterprise按量付费和Anthropic API用户的默认模型将改为Opus 4.7。要保持其他默认模型，设置ANTHROPIC_MODEL或在server-managed settings中设置model字段。

Haiku 默认用于哪些场景 #

haiku 别名是最快最轻量的模型，Claude Code 不会在主会话里自动切到 Haiku，但它是后台功能的默认模型，具体包括：

• 自动生成提交信息（git commit 时的 AI 摘要）
• 会话后台的摘要和压缩任务
• --bg 后台代理任务

如果你使用 Bedrock/Vertex/Foundry 并且 Haiku 4.5 还未发布，Claude Code 会回退到 Haiku 3.5。要手动指定后台使用的 Haiku 版本：

export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001

主会话里要切换到 Haiku：

/model haiku

或启动时指定：

claude --model haiku

opusplan混合模式 #

opusplan别名提供全自动的智能折中方案：

• 计划阶段 — 使用opus处理复杂推理和架构决策
• 执行阶段 — 自动切换到sonnet进行代码生成和实现

架构设计时用Opus的深度思考，写代码时用Sonnet的效率——两全其美。

计划阶段的Opus使用标准200K上下文窗口。扩展上下文中描述的自动1M升级适用于opus模型设置，不扩展到opusplan。

查看当前使用的模型 #

1. 状态行中显示（如果配置了）
2. /status命令，也会显示账户信息

调整推理力度（Effort Level） #

推理力度控制自适应推理能力，让模型根据任务复杂度自主决定每个步骤的思考深度。力度越低响应越快成本越低，力度越高推理越深入。

推理力度支持Opus 4.7、Opus 4.6和Sonnet 4.6。可用级别取决于模型：

如果设置的级别当前模型不支持，Claude Code会降级到最接近的较低级别。例如，xhigh在Opus 4.6上会作为high运行。

v2.1.117开始，默认推理力度：Opus 4.7为xhigh，Opus 4.6和Sonnet 4.6为high。

首次运行Opus 4.7时，Claude Code会应用xhigh，即使之前为Opus 4.6或Sonnet 4.6设置了不同级别。切换后运行/effort选择不同级别。

low、medium、high和xhigh会跨会话持久化。max提供最深推理，对token消耗没有限制，仅应用于当前会话，除非通过CLAUDE_CODE_EFFORT_LEVEL环境变量设置。

各级别使用场景 #

每个力度级别都是token消耗和推理能力的折中。默认级别适合大多数编码任务。

推理力度按模型分别校准，同一个级别名称在不同模型上代表不同的底层计算量。

一次性深度推理：使用ultrathink #

在提示词中任何位置包含ultrathink，Claude Code会识别这个关键词，在该轮请求中请求更深层推理，不改变会话的推理力度设置。Claude Code会增加一条上下文指令，但发送给API的力度级别不变。其他短语如"think"、“think hard”、"think more"会作为普通提示词传递，不会被识别为关键词。

设置推理力度 #

可以通过以下方式：

• /effort：不接参数运行打开交互式滑块，/effort后接级别名称直接设置，/effort auto重置为模型默认值
• /model中：选择模型时用左右方向键调整力度滑块
• --effort参数：启动Claude Code时传入级别名称，作用于单个会话
• 环境变量：设置CLAUDE_CODE_EFFORT_LEVEL为级别名称或auto
• 配置文件：在settings文件中将effortLevel设为low、medium、high或xhigh。max是会话级别的，不能在配置文件里写
• Skill和Subagent frontmatter：在技能或子代理的markdown文件中设置effort覆盖该技能或子代理运行时的推理力度

环境变量优先级高于所有其他方式，然后是配置文件中的设置，最后是模型默认值。Frontmatter中的effort在该技能或子代理激活时覆盖会话设置，但不能覆盖环境变量。

/model中选中支持推理力度的模型时会出现力度滑块。当前推理力度也会显示在Logo和spinner旁边，比如"with low effort"，方便确认设置状态。

自适应推理与固定思考预算 #

自适应推理让Claude在每一步上可选的进行思考，对常规提示快速响应，只在需要深度思考的步骤上投入更多计算。如果希望Claude比当前力度级别思考更多或更少，可以直接在提示词或CLAUDE.md中说明；模型会在其力度设置内响应你的指导。

Opus 4.7始终使用自适应推理。固定思考预算模式和CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING对它不生效。

在Opus 4.6和Sonnet 4.6上，可以设置CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1回退到旧的固定思考预算，由MAX_THINKING_TOKENS控制。见环境变量。

扩展上下文：100万Token #

Opus 4.7、Opus 4.6和Sonnet 4.6支持100万token上下文窗口，适合超大型代码库的长时间会话。

可用性因模型和计划而异。Max、Team和Enterprise计划中Opus自动升级到1M上下文，无需额外配置。这同时适用于Team Standard和Team Premium席位。Sonnet的1M上下文不属于自动升级，在所有订阅计划（包括Max）上都需要使用额度。

要完全禁用1M上下文，设置CLAUDE_CODE_DISABLE_1M_CONTEXT=1。这会将1M模型变体从模型选择器中移除。见环境变量。

1M上下文使用标准模型定价，200K以上无需额外费用。订阅计划内包含扩展上下文的，用量仍在订阅范围内。通过使用额度访问扩展上下文的，token用量从使用额度中扣除。

如果账户支持1M上下文，选项会出现在最新版Claude Code的/model选择器中。如果看不到，尝试重启会话。

也可以使用[1m]后缀加到模型别名或完整model name上：

# 使用opus[1m]或sonnet[1m]别名
/model opus[1m]
/model sonnet[1m]

# 或者将[1m]附加到完整model name
/model claude-opus-4-7[1m]

添加自定义模型选项 #

使用ANTHROPIC_CUSTOM_MODEL_OPTION在/model选择器中添加一个自定义条目，不替换内置别名。适合测试Claude Code默认未列出的模型ID。对于LLM网关部署，当CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1时，Claude Code可以从网关的/v1/models端点自动填充选择器，所以这个变量只在发现功能禁用或未返回所需模型时需要。见LLM网关模型选择。

以下示例设置三个变量创建一个可选择的网关路由Opus部署：

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-7"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="通过内部LLM网关路由的自定义部署"

自定义条目出现在/model选择器底部。ANTHROPIC_CUSTOM_MODEL_OPTION_NAME和ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION是可选的。不设置时，模型ID用作名称，描述默认为Custom model (<model-id>)。

Claude Code会跳过对ANTHROPIC_CUSTOM_MODEL_OPTION中设置的模型ID的验证，可以使用API端点接受的任意字符串。

模型相关环境变量 #

以下环境变量使用完整model name（或API提供商的等价格式）来控制别名映射到的模型。

ANTHROPIC_SMALL_FAST_MODEL已弃用，请改用ANTHROPIC_DEFAULT_HAIKU_MODEL。

第三方部署锁定模型版本 #

通过Bedrock、Vertex AI、Foundry或Claude Platform on AWS部署时，在推送给用户前锁定模型版本。

不锁定时，Claude Code使用模型别名（sonnet、opus、haiku）指向最新版本。当Anthropic发布新模型但用户账户尚未启用时，Bedrock和Vertex AI用户会看到提示并降级到旧版本，而Foundry用户会看到错误（Foundry没有等效的启动检查）。

在初始设置时就把三个模型环境变量都设置为特定版本ID。锁定版本让你能控制用户何时迁移到新模型。

使用以下环境变量，值为提供商特定的版本ID：

对ANTHROPIC_DEFAULT_SONNET_MODEL和ANTHROPIC_DEFAULT_HAIKU_MODEL应用相同模式。当前和历史模型ID见Models overview。升级用户到新模型版本时，更新这些环境变量并重新部署。

为锁定的模型启用扩展上下文，在ANTHROPIC_DEFAULT_OPUS_MODEL或ANTHROPIC_DEFAULT_SONNET_MODEL的模型ID后附加[1m]：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7[1m]'

[1m]后缀会让该别名的所有使用都应用1M上下文窗口，包括opusplan。

• Claude Code在将模型ID发送给提供商前会去掉后缀。
• 仅当底层模型支持1M上下文时才附加[1m]。
• 后缀按变量读取，不是按模型。在Bedrock、Vertex和Foundry上，一个变量中不带[1m]的模型ID会使用200K上下文，即使另一个变量中同样的模型ID带了后缀。

使用第三方提供商时settings.availableModels白名单仍然生效。过滤匹配的是模型别名（opus、sonnet、haiku），不是提供商特定的模型ID。

自定义锁定的模型显示与能力声明 #

在第三方提供商上锁定模型时，提供商特定的ID会原样显示在/model选择器中，Claude Code可能无法识别该模型支持哪些功能。可以通过每个锁定模型的配套环境变量覆盖显示名称和声明能力。

这些变量在Bedrock、Vertex AI和Foundry等第三方提供商上生效。_NAME和_DESCRIPTION变量在ANTHROPIC_BASE_URL指向LLM网关时也生效。直接连接api.anthropic.com时不生效。

_NAME、_DESCRIPTION和_SUPPORTED_CAPABILITIES后缀同样适用于ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL和ANTHROPIC_CUSTOM_MODEL_OPTION。

Claude Code通过匹配模型ID与已知模式来启用功能，如推理力度和扩展思考。提供商特定的ID（如Bedrock ARN或自定义部署名称）通常不匹配这些模式，导致支持的功能被禁用。设置_SUPPORTED_CAPABILITIES告诉Claude Code该模型实际支持哪些功能：

设置_SUPPORTED_CAPABILITIES后，列表中的能力被启用，未列出的能力被禁用。变量未设置时，Claude Code基于模型ID进行内置检测。

以下示例将Opus锁定到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='通过Bedrock自定义端点的Opus 4.7'
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

modelOverrides：按版本映射模型ID #

如果需要将同一模型族内多个版本映射到不同的提供商特定ID，使用modelOverrides设置。

modelOverrides将各个Anthropic模型ID映射到Claude Code发送给提供商API的提供商特定字符串。用户在/model选择器中选择映射的模型时，Claude Code使用你配置的值而不是内置默认值。

这使企业管理员可以将每个模型版本路由到特定的Bedrock inference profile ARN、Vertex AI版本名或Foundry部署名，用于治理、成本分配或区域路由。

在settings文件中设置modelOverrides：

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

键必须是Models overview中列出的Anthropic模型ID。带日期的模型ID需要完全匹配日期后缀。无法识别的键会被忽略。

覆盖替换了/model选择器中每个条目的内置模型ID。在Bedrock上，覆盖的优先级高于Claude Code启动时自动发现的任何inference profile。通过ANTHROPIC_MODEL、--model或ANTHROPIC_DEFAULT_*_MODEL环境变量直接设置的值会原样发送给提供商，不会被modelOverrides转换。

modelOverrides与availableModels协同工作。白名单基于Anthropic模型ID判断，而不是覆盖值，所以availableModels中的"opus"条目即使Opus版本映射为ARN也仍然匹配。

提示缓存配置 #

Claude Code自动使用提示缓存优化性能和降低成本。可以通过环境变量全局或按模型禁用提示缓存：

要修改缓存TTL或了解什么会触发缓存未命中，见Claude Code如何使用提示缓存。

常见问题 #

企业部署怎么彻底防止用户选最便宜的模型？ #

单独用availableModels不够，因为用户还能选Default选项得到订阅级别的默认模型。正确做法是组合三个设置：availableModels（限制可选列表）、model（设置初始选择）、ANTHROPIC_DEFAULT_*_MODEL环境变量（控制Default选项解析到哪个版本）。参见完整控制用户使用的模型部分的配置示例。

第三方部署（Bedrock/Vertex）的模型版本怎么固定？ #

设置ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL和ANTHROPIC_DEFAULT_HAIKU_MODEL三个环境变量，值用提供商特定的模型ID（Bedrock用inference profile ARN，Vertex用version name）。不锁定时新模型发布会导致用户降级或报错。第三方部署锁定模型版本部分有各提供商的具体写法。

1M上下文在我的计划上怎么收费？ #

Max、Team和Enterprise计划的Opus 1M上下文订阅内含；Pro计划的Opus 1M上下文和使用额度的Sonnet 1M上下文需要Extra Usage Credits。API和按量付费账户完整访问但不免费，使用标准模型定价，200K以上无额外费用。详见扩展上下文的计划支持表格。