固定模型与覆盖

模型 ID 与版本号以官方模型概览为准。

别名对应的环境变量

用这些环境变量控制别名映射到的模型名，每个值必须是完整模型名或你的 API 提供商的等价标识符：ANTHROPIC_DEFAULT_FABLE_MODEL（fable）、ANTHROPIC_DEFAULT_OPUS_MODEL（opus，或计划模式激活时的 opusplan）、ANTHROPIC_DEFAULT_SONNET_MODEL（sonnet，或计划模式未激活时的 opusplan）、ANTHROPIC_DEFAULT_HAIKU_MODEL（haiku，或后台功能使用的模型）、CLAUDE_CODE_SUBAGENT_MODEL（子智能体、智能体团队成员和工作流智能体在没有以其他方式分配模型时的默认）。ANTHROPIC_SMALL_FAST_MODEL 已弃用，改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。没设 ANTHROPIC_DEFAULT_FABLE_MODEL 时，fable 解析为 Fable 5.1（Claude apps gateway 会话里 fable 和 best 解析为 Fable 5）；未配置为提供 claude-fable-5-1 的网关会拒绝对该模型的请求，通过提供它的网关使用时用 /model claude-fable-5-1 选择。别名解析到较旧模型的地方，可以通过显式选完整模型名，或设置 ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL 使用更新的模型。

为第三方部署固定模型

通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 部署 Claude Code 时，在向用户推广之前先固定模型版本。不固定的话 Claude Code 使用 fable、opus、sonnet、haiku 这类别名，它们解析为每个提供商的内置默认模型 ID；那个默认值可能落后于 Anthropic 的最新发布，它指向的模型也可能还没在用户账号里启用。默认值不可用时，Bedrock 和 Google Cloud 的 Agent Platform 用户会看到通知，会话回退到该默认模型的较早版本（默认是 Opus 且没有 Opus 版本可用时回退到默认 Sonnet）；Foundry 没有等价的启动检查，用户直接看到错误。在 Bedrock 和 Agent Platform 上，用户以特定 Sonnet 或 Opus 版本启动会话（如用 --model、ANTHROPIC_MODEL 或 model 设置），就把该版本固定为对应别名的会话默认：启动检查跳过被替换的内置默认并且不显示回退通知（v2.1.211 之前，即使显式配置了会话模型，检查也会运行并可能显示通知）。

在初始设置时就把模型环境变量设为具体版本 ID，固定让你控制用户何时迁移到新模型。示例：

对 ANTHROPIC_DEFAULT_FABLE_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 套用同样的模式；要升级用户到新版本，更新这些变量并重新部署。想为固定的模型启用扩展上下文，在 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 或 ANTHROPIC_DEFAULT_FABLE_MODEL 的模型 ID 后追加 [1m]（如 'claude-opus-4-8[1m]'）。带 [1m] 后缀时，1M 窗口适用于固定别名的所有用法，包括 opusplan 的计划模式 Opus 阶段，以及 model 前置信息点名该别名的子智能体。Claude Code 在把模型 ID 发给提供商前剥掉后缀；只在底层模型支持 1M 上下文时才追加；后缀是按变量读取的而不是按模型：在 Bedrock、Google Cloud 的 Agent Platform 和 Foundry 上，一个变量里不带 [1m] 的模型 ID 用 200K 上下文，即使另一个变量以后缀设了同一模型；Sonnet 5 在这些提供商上总是 1M 窗口，从不需要该后缀。

设置了 ANTHROPIC_DEFAULT_*_MODEL 变量时，/model 选择器用一行代表该模型，取代该家族的内置行（含任何 1M 上下文行）；想在变量里不加后缀就到达 1M 窗口，用户运行 /model opus[1m]，Claude Code 把后缀应用到变量所指的模型，/model sonnet[1m] 同理。通过 MDM 或托管设置文件交付的 availableModels 白名单在第三方提供商上仍然适用（服务端托管设置不在那里交付）；过滤匹配别名（如 opus）、版本前缀（如 claude-opus-4-8）或完整的提供商形式模型 ID，不会剥掉 us.anthropic. 这类提供商特定前缀，所以要允许特定模型，列出它完整的提供商形式 ID，或通过 modelOverrides 映射；对固定的模型，该 ID 就是你在其 ANTHROPIC_DEFAULT_*_MODEL 变量里设的值；任何 [1m] 后缀在匹配前都会从白名单条目和所请求的模型两边剥掉。

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

在第三方提供商上固定模型时，它在 /model 选择器里那一行默认：Claude Code 认识固定的 ID 就显示模型名，否则显示原始 ID。「认识」指你固定的是 Claude Code 知道的某个模型的确切 ID（Anthropic API ID，或你的提供商或网关的形式，带或不带 [1m] 后缀）——固定 us.anthropic.claude-sonnet-4-5-20250929-v1:0 时该行显示 Sonnet 4.5；「不认识」指任何其他 ID（如应用推理配置文件 ARN，或 Claude Code 不知道的模型版本），除非 modelOverrides 有条目把某个模型映射到那个确切字符串；在 Foundry 上部署名由用户定义，所以 Claude Code 从不识别固定的 ID（无论是否映射），该行默认显示部署名。该行显示模型名时，默认描述里包含固定的 ID，让你仍能看到固定了哪个 ID。

Claude Code 也可能不认识固定模型支持哪些功能（努力等级、扩展思考等是靠把模型 ID 与已知模式匹配来启用的，Bedrock ARN 或自定义部署名通常匹配不上，导致本应支持的功能被禁用）。可以为每个固定模型用配套环境变量自己设置显示名和描述并声明能力。这些变量在 Bedrock、Google Cloud 的 Agent Platform、Foundry 这类第三方提供商上生效；_NAME 和 _DESCRIPTION 在 ANTHROPIC_BASE_URL 指向 LLM 网关时也生效；直连 api.anthropic.com 时无效。

• ANTHROPIC_DEFAULT_OPUS_MODEL_NAME：固定的 Opus 模型在选择器里的显示名（未设置时显示模型名，若认得固定的 ID，否则显示固定的 ID）。
• ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION：显示描述（未设置时是以 Custom Opus model 开头的默认描述）。
• ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES：该固定模型支持的能力，逗号分隔。

同样的 _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 固定到 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'

添加自定义模型选项

用 ANTHROPIC_CUSTOM_MODEL_OPTION 向 /model 选择器添加一个自定义条目，而不替换内置别名，适合测试 Claude Code 默认不列出的模型 ID。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；省略描述时用 Custom model (<model-id>)。自定义条目列在内置条目之后。Claude Code 不校验该变量里的模型 ID，所以可以用你的 API 端点接受的任何字符串；设置了 availableModels 时，也要把自定义模型 ID 放进白名单，否则选择器会过滤掉这个条目。

按版本覆盖模型 ID（modelOverrides）

上面的家族级环境变量为每个家族别名配置一个模型 ID。需要把同一家族里的多个版本映射到不同的提供商 ID 时，改用 modelOverrides 设置：它把单个 Anthropic 模型 ID 映射到 Claude Code 发给提供商 API 的提供商特定字符串，用户在 /model 选择器里选了被映射的模型时，Claude Code 用你配置的值而不是内置默认，让企业管理员能把每个模型版本路由到特定的 Bedrock 推理配置文件 ARN、Google Cloud 的 Agent Platform 版本名或 Foundry 部署名，用于治理、成本分摊或区域路由。嵌入 Claude Code 并设置 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 的平台上，宿主的模型配置优先于托管模型设置。

{
  "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 要完整包含日期后缀，未知的键被忽略。想让网关别名这类 ID 不再出现 [claude-code:unrecognized_model] 诊断行，添加一个以该 ID 为值的条目。覆盖替换支撑 /model 选择器每个条目的内置模型 ID；在 Bedrock 上，modelOverrides 条目优先于 Claude Code 在启动时自动发现的任何推理配置文件；已经是提供商原生形式的值（Bedrock 推理配置文件 ARN、Foundry 部署名）原样传给提供商。覆盖也适用于你通过 --model、ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_*_MODEL 环境变量直接传入 Anthropic 模型 ID 的情况：在 Bedrock、Google Cloud 的 Agent Platform 和 Mantle 上，没有 modelOverrides 条目的 Anthropic 模型 ID 在提供商支持该版本时解析为与该版本的 /model 选择器行相同的提供商特定 ID；Mantle 只支持部分版本，对该子集之外的 Anthropic 模型 ID，除非有 modelOverrides 条目覆盖，否则 Claude Code 把原始 ID 不加映射地发给 Mantle（v2.1.200 之前，--model 和环境变量的值不经覆盖映射直接到达提供商）。

modelOverrides 与 availableModels 协同：白名单针对 Anthropic 模型 ID 求值，而不是覆盖值，所以即使 Opus 各版本被映射为 ARN，availableModels 里的 "opus" 条目仍然匹配。托管设置里设了 enforceAvailableModels 时，强制后的 Default 只通过托管设置里的 modelOverrides 解析：管理员的映射（如把某版本固定到推理配置文件 ARN）在强制后的 Default 里被遵循，用户或项目设置里的覆盖不影响它。托管设置里设了 availableModels 时，对通过 --model 或上述环境变量直接传入的 Anthropic 模型 ID，只有托管设置里的 modelOverrides 适用：Claude Code 忽略用户或项目设置里对这些 ID 的覆盖，也从不通过任何设置来源的 modelOverrides 解析托管列表排除的 ID（该托管来源限制需要 v2.1.200+）。

提示缓存配置

Claude Code 自动使用提示缓存来优化性能和降低成本，可以全局或对特定模型层级禁用：DISABLE_PROMPT_CACHING=1 对所有模型禁用（优先于按模型的设置）；DISABLE_PROMPT_CACHING_HAIKU、DISABLE_PROMPT_CACHING_SONNET、DISABLE_PROMPT_CACHING_OPUS 分别对对应的默认模型禁用；DISABLE_PROMPT_CACHING_FABLE 只对 Fable 模型禁用。分别为主对话和子智能体选择缓存 TTL，以及什么会触发缓存未命中，见提示缓存文档。

版本历史

下表列出各模型别名改变其所解析模型的 Claude Code 版本，最新在前：