Claude Code 模型配置完全指南：从别名到代理，一文讲透

详解 Claude Code 中 model 参数的所有配置方式、别名解析机制、优先级规则和环境变量，附代理商自定义模型实战示例。

一、为什么需要了解模型配置

Claude Code 默认会根据你的订阅等级自动选择模型，大多数场景下开箱即用。但以下场景你需要手动配置：

使用第三方代理（如 Bedrock、Vertex AI、自建网关）时，模型名称与官方不同
团队协作时，需要统一模型版本避免行为差异
控制成本，日常用 Sonnet，关键任务切 Opus
子代理使用便宜模型，主对话保持高质量

二、`/model` 命令：最快的切换方式

在 Claude Code 会话中输入 /model，会弹出模型选择器：

别名	解析为	适用场景
`default`	恢复账户类型默认模型	重置覆盖
`best`	当前等同 `opus`	最高能力
`opus`	`claude-opus-4-6`	复杂推理、架构决策
`sonnet`	`claude-sonnet-4-6`	日常编码（性价比最优）
`haiku`	`claude-haiku-4-5`	简单任务、后台操作
`opusplan`	规划用 opus，执行用 sonnet	混合模式
`sonnet[1m]`	Sonnet + 100 万 token 上下文	超长会话
`opus[1m]`	Opus + 100 万 token 上下文	超长会话

也可以直接输入完整模型 ID：

/model claude-opus-4-6
/model claude-sonnet-4-5-20241022

附加功能

努力级别调整：选择模型后，用左/右箭头调节推理努力（low / medium / high / max）
扩展上下文：[1m] 后缀启用 100 万 token 上下文窗口

三、配置文件中的 `model` 参数

3.1 可以写在哪里

model 参数可以出现在以下位置，按优先级从高到低排列：

优先级	配置位置	文件路径	说明
1（最高）	Managed settings	macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` Linux: `/etc/claude-code/managed-settings.json`	组织级强制配置，无法被覆盖
2	CLI 标志	`claude --model <value>`	仅当次会话生效
3	本地项目设置	`.claude/settings.local.json`	个人项目覆盖，不提交 git
4	共享项目设置	`.claude/settings.json`	团队共享，提交 git
5	用户全局设置	`~/.claude/settings.json`	个人所有项目的默认值
6（最低）	环境变量	`ANTHROPIC_MODEL`	适合 CI/CD 和脚本

优先级规则：高优先级的配置会覆盖低优先级。例如 CLI 标志 --model opus 会覆盖 settings.json 中的 "model": "sonnet"。

3.2 有效值

model 字段接受两种写法：

别名写法（推荐，自动跟随最新版本）：

{ "model": "sonnet" }
{ "model": "opus" }
{ "model": "haiku" }
{ "model": "opusplan" }

完整模型 ID（固定版本，不会自动升级）：

{ "model": "claude-opus-4-6" }
{ "model": "claude-sonnet-4-6" }
{ "model": "claude-haiku-4-5" }
{ "model": "claude-sonnet-4-5-20241022" }

3.3 默认模型（按订阅等级）

如果不设置 model，系统按账户类型选择：

订阅等级	默认模型
Max / Team Premium	Opus 4.6
Pro / Team Standard	Sonnet 4.6
Enterprise	Opus 4.6 可用但非默认

四、别名解析机制

这是理解模型配置的关键。当你写 "model": "sonnet" 时，Claude Code 并不是直接把 "sonnet" 发给 API，而是经历一套解析流程：

用户输入: "sonnet"
    │
    ▼
是否为已知别名？ ── 否 ──▶ 直接作为模型 ID 使用
    │
    是
    ▼
检查环境变量 ANTHROPIC_DEFAULT_SONNET_MODEL
    │
    ├─ 已设置 ──▶ 使用环境变量的值（如 "claude-sonnet-4.6"）
    │
    └─ 未设置 ──▶ 使用内置默认值 "claude-sonnet-4-6"
    │
    ▼
检查 modelOverrides 映射（Bedrock/Vertex 场景）
    │
    ▼
最终模型 ID 发送给 API

每个别名对应一个环境变量：

别名	环境变量	内置默认值
`opus`	`ANTHROPIC_DEFAULT_OPUS_MODEL`	`claude-opus-4-6`
`sonnet`	`ANTHROPIC_DEFAULT_SONNET_MODEL`	`claude-sonnet-4-6`
`haiku`	`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`claude-haiku-4-5`

opusplan 的特殊解析：规划阶段走 ANTHROPIC_DEFAULT_OPUS_MODEL，执行阶段走 ANTHROPIC_DEFAULT_SONNET_MODEL。

五、环境变量完整参考

5.1 模型选择

变量	作用	示例值
`ANTHROPIC_MODEL`	全局模型选择，与 `model` 设置同级	`opus` / `claude-opus-4-6`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	覆盖 `opus` 别名的解析目标	`claude-opus-4.6`
`ANTHROPIC_DEFAULT_SONNET_MODEL`	覆盖 `sonnet` 别名的解析目标	`claude-sonnet-4.6`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	覆盖 `haiku` 别名的解析目标	`claude-haiku-4.5`
`CLAUDE_CODE_SUBAGENT_MODEL`	子代理使用的模型	`claude-haiku-4.5`
`ANTHROPIC_CUSTOM_MODEL_OPTION`	添加自定义模型到 `/model` 选择器	`my-gateway/claude-opus-4-6`

5.2 模型显示名称（第三方提供商场景）

当使用 Bedrock / Vertex AI 等提供商时，模型 ID 可能是 ARN 或部署名称，在 /model 选择器中不可读。可以用以下变量自定义显示：

变量	作用
`ANTHROPIC_DEFAULT_OPUS_MODEL_NAME`	Opus 在选择器中的显示名称
`ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION`	Opus 的描述文本
`ANTHROPIC_DEFAULT_SONNET_MODEL_NAME`	Sonnet 在选择器中的显示名称
`ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION`	Sonnet 的描述文本
`ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME`	Haiku 在选择器中的显示名称
`ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION`	Haiku 的描述文本
`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`	自定义模型的显示名称
`ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`	自定义模型的描述文本

5.3 能力声明

用于 *_SUPPORTED_CAPABILITIES 变量（如 ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES），逗号分隔：

值	启用功能
`effort`	努力级别调节和 `/effort` 命令
`max_effort`	`max` 努力级别
`thinking`	扩展思考模式
`adaptive_thinking`	自适应推理
`interleaved_thinking`	思考穿插工具调用

5.4 其他控制

变量	作用	值
`CLAUDE_CODE_EFFORT_LEVEL`	默认推理努力级别	`low` / `medium` / `high` / `max` / `auto`
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`	禁用自适应推理	`1`
`MAX_THINKING_TOKENS`	扩展思考最大 token 数	`10000`
`CLAUDE_CODE_DISABLE_1M_CONTEXT`	禁用 1M 上下文选项	`1`

六、实战示例

6.1 最简配置：直连 Anthropic API

{
  "model": "sonnet"
}

别名 sonnet 解析为内置默认值 claude-sonnet-4-6，直接发给 Anthropic API。

6.2 团队统一版本

{
  "model": "claude-sonnet-4-5-20241022"
}

写死完整模型 ID，确保团队所有人用同一版本，避免模型升级导致行为差异。放入 .claude/settings.json 提交 git。

6.3 通过第三方代理使用（以 Bedrock 代理为例）

这是最常见的进阶场景。假设你的代理服务（如 huancode.com）使用的模型名是 claude-sonnet-4.6（带点号），而非官方的 claude-sonnet-4-6（带连字符）：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4.5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4.5",
    "CLAUDE_CODE_USE_BEDROCK": "true",
    "ANTHROPIC_BEDROCK_BASE_URL": "https://api.huancode.com/bedrock",
    "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "true",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key"
  },
  "model": "sonnet"
}

解析过程：

"model": "sonnet"
    │
    ▼
识别为 sonnet 别名
    │
    ▼
检查 ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-4.6"
    │
    ▼
发送给 API 的模型名: "claude-sonnet-4.6" ✅（匹配代理服务的模型名）

关键点：ANTHROPIC_DEFAULT_*_MODEL 环境变量的作用就是把别名重定向到代理服务实际使用的模型名称。

6.4 省钱配置：子代理用便宜模型

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  },
  "model": "sonnet"
}

主对话用 Sonnet 保证质量，Agent 子任务用 Haiku 降低成本。

6.5 混合模式：规划用 Opus，执行用 Sonnet

{
  "model": "opusplan"
}

进入 Plan Mode 时自动切换 Opus 做深度分析，退出后自动回到 Sonnet 执行代码修改。兼顾推理深度和成本。

6.6 添加自定义模型到选择器

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="通过内部网关路由的 Opus 模型"

执行 /model 时会多出一个自定义选项。

6.7 CLI 临时切换

# 本次会话用 Opus
claude --model opus

# 本次会话用特定版本
claude --model claude-sonnet-4-5-20241022

# 本次会话用 1M 上下文
claude --model sonnet[1m]

不影响配置文件，会话结束后恢复原配置。

七、常见问题

Q: `"model": "sonnet"` 和 `"model": "claude-sonnet-4-6"` 有什么区别？

前者是别名，会随 Anthropic 更新自动指向最新版本（今天是 4-6，未来可能是 4-7）。后者是固定版本，永远指向 claude-sonnet-4-6。

建议：个人使用写别名跟随最新；团队协作或需要行为一致时写完整 ID。

Q: 为什么设置了 `model` 但没生效？

按优先级排查：

是否有 Managed settings 强制覆盖？
是否用了 --model CLI 标志？
.claude/settings.local.json 是否有覆盖？
确认修改的是正确的配置文件

Q: `ANTHROPIC_MODEL` 和 `"model"` 字段有什么区别？

功能相同，但优先级不同。"model" 在 settings.json 中的优先级高于 ANTHROPIC_MODEL 环境变量。

Q: 使用第三方代理时，别名还能用吗？

可以。只要通过 ANTHROPIC_DEFAULT_*_MODEL 环境变量把别名重定向到代理服务的模型名即可。如上面 6.3 的示例。

Q: 子代理的模型可以单独控制吗？

可以。设置 CLAUDE_CODE_SUBAGENT_MODEL 环境变量即可。它只影响 Agent 工具启动的子代理，不影响主对话。

Claude Code 模型配置完全指南：从别名到代理，一文讲透

On this page