它到底是什么

--model 是 CLI 启动 flag，用来为当前会话指定模型。官方 CLI reference 对它的描述是：用 model alias（如 sonnet、opus、haiku、fable）或模型全名设置当前会话的模型，并且覆盖 model 设置和 ANTHROPIC_MODEL。

接受的值：

alias 的解析结果取决于 provider（官方表格）：

不传 --model 时的默认值取决于账户类型：

• Max、Team Premium、Enterprise、Anthropic API:Opus 5
• Claude Platform on AWS、Amazon Bedrock、Google Cloud's Agent Platform:Opus 5
• Pro、Team Standard:Sonnet 5
• Microsoft Foundry:Sonnet 4.5

fable alias 在未设置 ANTHROPIC_DEFAULT_FABLE_MODEL 时解析为 Fable 5.1。在 Claude apps gateway 会话中，fable 和 best 解析为 Fable 5。要指定 Fable 5.1，可用 /model claude-fable-5-1。

用法

# 用 alias
claude --model opus
claude --model sonnet

# 用模型全名(官方 CLI reference 的示例)
claude --model claude-sonnet-5

# 1M context 变体
claude --model opus[1m]

# 混合模式:plan 用 opus,执行用 sonnet
claude --model opusplan

官方文档中的等价设置方式：

• 会话内：/model <alias|name>，或不带参数运行 /model 打开选择器
• 环境变量：ANTHROPIC_MODEL=<alias|name>
• 设置文件：model 字段
• 新会话默认值：ANTHROPIC_DEFAULT_MODEL=<alias|name>

与其他 flag 的组合 / 互斥

effort 级别与模型的对应（官方 model-config）：

• Fable 5.1、Fable 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 --model opus --effort high --fallback-model sonnet,haiku

在 settings.json / env 的等价配置

alias 指向的具体模型可以用环境变量固定：

运行约束 / 限制

经典使用场景

• 单次会话临时换模型：claude --model opus，不改动任何持久化设置。
• 固定到具体版本：传模型全名，如 claude --model claude-sonnet-5。alias 会随 provider 和版本更新而指向不同模型，全名不会。
• 长会话需要 1M context:claude --model opus[1m];plan 和执行两个阶段都要 1M 时用 opusplan[1m]。
• 主模型不可用时自动降级：配合 --fallback-model。

常见坑

1. /model 和 --model 的作用不同。 官方优先级列表中，会话内 /model 排在第一，--model 第二，ANTHROPIC_MODEL 第三，settings 的 model 字段第四，ANTHROPIC_DEFAULT_MODEL 最后。启动后在会话里执行 /model，会替换掉 --model 选的模型。
2. /model <name> 会保存为默认。 直接输入 /model <name> 的行为等同于在选择器里按 Enter，即切换并保存为默认。只想在本会话切换时，要先用 /model 打开选择器，再在目标模型行按 s。
3. alias 不等于固定模型。 同一个 sonnet 在 Anthropic API 上是 Sonnet 5，在 Bedrock 上是 Sonnet 4.5。需要一致性时传全名，或用 ANTHROPIC_DEFAULT_*_MODEL 固定。第三方平台的模型 ID 格式也不同，官方示例中 Bedrock 用 us.anthropic.claude-opus-4-8,Google Cloud's Agent Platform 和 Microsoft Foundry 用 claude-opus-4-8。
4. 被组织限制时不会报错退出。 会话会改用允许的模型启动，只显示一条提示。CI 里如果依赖特定模型，要检查实际生效的模型，不要只看你传了什么。
5. --model 优先于组织默认模型。 官方说明组织默认模型只是起点，不是限制，--model 和 ANTHROPIC_MODEL 优先于它。真正的限制要靠 availableModels 或组织的模型限制。

来源

• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 会 301 重定向到此地址）
• Model configuration - Claude Code Docs