文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

模型配置

了解 Claude Code 的模型配置，包括 opusplan 等模型别名

可用模型

对于 Claude Code 中的 model 设置，你可以配置：

• 模型别名
• 模型名称
  • Anthropic API：完整的 模型名称
  • Bedrock：推理配置文件 ARN
  • Foundry：部署名称
  • Vertex：版本名称

模型别名

模型别名提供了一种便捷的方式来选择模型设置，无需记住确切的版本号：

在 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；在这些提供商上，通过显式选择完整模型名称或设置 ANTHROPIC_DEFAULT_OPUS_MODEL 或 ANTHROPIC_DEFAULT_SONNET_MODEL 可以使用更新的模型。

别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，使用完整的模型名称（例如 claude-opus-4-7）或设置相应的环境变量如 ANTHROPIC_DEFAULT_OPUS_MODEL。

设置你的模型

你可以通过多种方式配置模型，按优先级列出：

1. 会话期间 - 使用 /model <alias|name> 立即切换，或运行不带参数的 /model 打开选择器。当对话有先前输出时，选择器会要求确认，因为下一个响应会在没有缓存上下文的情况下重新读取完整历史
2. 启动时 - 使用 claude --model <alias|name> 启动
3. 环境变量 - 设置 ANTHROPIC_MODEL=<alias|name>
4. 设置 - 在设置文件中使用 model 字段永久配置。

从 v2.1.144 起，/model 仅适用于当前会话，不会写入设置。要将你的选择保存为新会话的默认值，在选择器中高亮行上按 d，这会将 model 字段写入你的用户设置。托管设置优先并在下次启动时重新应用。

--model 标志和 ANTHROPIC_MODEL 环境变量也仅适用于你使用它们启动的会话。要在不同终端同时运行不同的模型，为每个终端使用自己的 --model 标志启动，而不是用 /model 切换。

使用 claude --resume、--continue 或 /resume 选择器恢复的会话保持转录保存时使用的模型，无论当前的 model 设置如何。如果该模型已停用，会话会回退到正常的优先级顺序。这可以防止另一个会话的 /model 选择在恢复时更改模型。

当启动时的活动模型来自项目或托管设置而不是你自己的选择时，启动标题会显示哪个设置文件设置了它。运行 /model 为当前会话覆盖。

示例用法：

# 使用 Opus 启动
claude --model opus

# 会话期间切换到 Sonnet
/model sonnet

示例设置文件：

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

限制模型选择

企业管理员可以在托管或策略设置中使用 availableModels 来限制用户可以选择的模型。

设置 availableModels 后，用户无法通过 /model、--model 标志或 ANTHROPIC_MODEL 环境变量切换到不在列表中的模型。

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

默认模型行为

模型选择器中的默认选项不受 availableModels 影响。它始终可用，代表系统运行时默认值基于用户的订阅层级。

即使设置 availableModels: []，用户仍可以使用其层级的默认模型使用 Claude Code。

控制用户运行的模型

model 设置是初始选择，而非强制执行。它设置会话启动时哪个模型是活动的，但用户仍然可以打开 /model 并选择默认值，无论 model 设置如何，默认值都会解析为其层级的系统默认值。

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

• availableModels：限制用户可以切换到的命名模型
• model：设置会话启动时的初始模型选择
• ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL：控制默认选项和 sonnet、opus 和 haiku 别名解析为什么

此示例让用户从 Sonnet 4.5 开始，将选择器限制为 Sonnet 和 Haiku，并将默认值固定为解析为 Sonnet 4.5 而不是最新版本：

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

没有 env 块时，在选择器中选择默认值的用户会获得最新的 Sonnet 版本，绕过 model 和 availableModels 中的版本固定。

合并行为

当 availableModels 在多个级别设置时（如用户设置和项目设置），数组会被合并和去重。要强制执行严格的白名单，在托管或策略设置中设置 availableModels，它们具有最高优先级。

Mantle 模型 ID

当启用 Bedrock Mantle 端点时，availableModels 中以 anthropic. 开头的条目作为自定义选项添加到 /model 选择器并路由到 Mantle 端点。这是为第三方部署固定模型中描述的仅别名匹配的例外。该设置仍将选择器限制为列出的条目，因此请在任何 Mantle ID 旁边包含标准别名。

特殊模型行为

default 模型设置

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。

opusplan 模型设置

opusplan 模型别名提供自动混合方法：

• 在计划模式中 - 使用 opus 进行复杂推理和架构决策
• 在执行模式中 - 自动切换到 sonnet 进行代码生成和实施

这让你兼得两者之长：Opus 的卓越推理用于规划，Sonnet 的高效用于执行。

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

调整努力级别

努力级别控制自适应推理，让模型根据任务复杂性决定是否以及在每一步思考多少。较低的努力对于简单任务更快更便宜，而较高的努力为复杂问题提供更深入的推理。

努力支持 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 时，即使你之前为 Opus 4.6 或 Sonnet 4.6 设置了不同的努力级别，Claude Code 也会应用 xhigh。切换后再次运行 /effort 选择不同的级别。

low、medium、high 和 xhigh 跨会话持久化。max 提供最深入的推理，没有 token 支出限制，仅适用于当前会话，通过 CLAUDE_CODE_EFFORT_LEVEL 环境变量设置时除外。

选择努力级别

每个级别在 token 支出和能力之间进行权衡。默认值适合大多数编程任务；当你想要不同的平衡时进行调整。

努力级别按模型校准，因此相同的级别名称不代表跨模型的相同底层值。

使用 ultrathink 进行一次性深度推理

在提示中任意位置包含 ultrathink 以在该轮请求更深入的推理，而不更改你的会话努力设置。Claude Code 识别该关键字并添加上下文指令。发送到 API 的努力级别不变。其他短语如 "think"、"think hard" 和 "think more" 作为普通提示文本传递，不被识别为关键字。

设置努力级别

你可以通过以下任一方式更改努力：

• /effort：不带参数运行 /effort 打开交互式滑块，/effort 后跟级别名称直接设置，或 /effort auto 重置为模型默认值
• 在 /model 中：选择模型时使用左右箭头键调整努力滑块
• --effort 标志：启动 Claude Code 时传递级别名称为单个会话设置
• 环境变量：将 CLAUDE_CODE_EFFORT_LEVEL 设置为级别名称或 auto
• 设置：在设置文件中将 effortLevel 设置为 low、medium、high 或 xhigh。max 是仅会话的，不在此接受
• 技能和子智能体 frontmatter：在技能或子智能体 markdown 文件中设置 effort 以在该技能或子智能体运行时覆盖努力级别

环境变量优先于所有其他方法，然后是你配置的级别，然后是模型默认值。frontmatter 努力在该技能或子智能体活动时应用，覆盖会话级别但不覆盖环境变量。

努力滑块在选择支持的模型时出现在 /model 中。当前努力级别也显示在徽标和旋转器旁边，例如 "with low effort"，因此你可以确认哪个设置是活动的而无需打开 /model。

自适应推理和固定思考预算

自适应推理使思考在每一步都是可选的，因此 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 控制的先前固定思考预算。参见环境变量。

扩展思考

扩展思考是 Claude 在响应前发出的推理。在支持自适应推理的模型上，努力级别是控制思考量的主要手段；以下设置打开或关闭思考并控制其显示方式。

思考输出默认折叠。按 Ctrl+O 切换详细模式，以灰色斜体文本查看推理。Anthropic API 上的交互式会话默认接收编辑过的思考块，因此如果你想在展开时获得完整摘要，请在设置中设置 showThinkingSummaries: true。即使折叠或编辑，你也会被收取所有生成的思考 token 的费用。

扩展上下文

Opus 4.7、Opus 4.6 和 Sonnet 4.6 支持100 万 token 上下文窗口，用于具有大型代码库的长会话。

可用性因模型和计划而异。在 Max、Team 和 Enterprise 计划上，Opus 自动升级到 1M 上下文，无需额外配置。这适用于 Team Standard 和 Team Premium 席位。带 1M 上下文的 Sonnet 不是自动升级的一部分，需要在每个订阅计划（包括 Max）上使用使用额度。

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

1M 上下文窗口使用标准模型定价，超过 200K 的 token 没有溢价。对于扩展上下文随订阅包含的计划，使用量仍由你的订阅覆盖。对于通过使用额度访问扩展上下文的计划，token 计入使用额度。

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

你也可以将 [1m] 后缀与模型别名或完整模型名称一起使用：

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

# 或将 [1m] 附加到完整模型名称
/model claude-opus-4-7[1m]

检查当前模型

你可以通过多种方式查看当前使用的模型：

1. 在状态行中（如果已配置）
2. 在 /status 中，它还显示你的账户信息。

添加自定义模型选项

使用 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="Custom deployment routed through the internal LLM gateway"

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

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

环境变量

你可以使用以下环境变量（必须是完整的模型名称或你的 API 提供商的等效名称）来控制别名映射到的模型名称。

注意：ANTHROPIC_SMALL_FAST_MODEL 已弃用，改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。

为第三方部署固定模型

通过 Bedrock、Vertex AI、Foundry 或 Claude Platform on AWS 部署 Claude Code 时，在向用户推出之前固定模型版本。

不固定的话，Claude Code 使用模型别名（sonnet、opus、haiku）解析为最新版本。当 Anthropic 发布尚未在用户账户中启用的新模型时，Bedrock 和 Vertex AI 用户会看到通知并在该会话中回退到先前版本，而 Foundry 用户会看到错误，因为 Foundry 没有等效的启动检查。

使用以下环境变量为你的提供商设置特定版本的模型 ID：

对 ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参见模型概述。要将用户升级到新模型版本，更新这些环境变量并重新部署。

要为固定模型启用扩展上下文，在 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 原样出现在 /model 选择器中，Claude Code 可能无法识别模型支持哪些功能。你可以为每个固定模型使用伴随环境变量覆盖显示名称并声明功能。

这些变量在 Bedrock、Vertex AI 和 Foundry 等第三方提供商上生效。当 ANTHROPIC_BASE_URL 指向 LLM 网关时，_NAME 和 _DESCRIPTION 变量也会生效。当直接连接到 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='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 设置。

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

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

在你的设置文件中设置 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"
  }
}

键必须是模型概述中列出的 Anthropic model ID。对于带日期的模型 ID，完全按照其中出现的方式包含日期后缀。未知键被忽略。

覆盖替换 /model 选择器中每个条目支持的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。你通过 ANTHROPIC_MODEL、--model 或 ANTHROPIC_DEFAULT_*_MODEL 环境变量直接提供的值会原样传递给提供商，不受 modelOverrides 转换。

modelOverrides 与 availableModels 一起工作。白名单针对 Anthropic model ID 评估，而不是覆盖值，因此 availableModels 中的 "opus" 等条目在 Opus 版本映射到 ARN 时继续匹配。

提示缓存配置

Claude Code 自动使用提示缓存来优化性能和降低成本。你可以全局禁用提示缓存或针对特定模型层级禁用：

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