【Bug已解决】Claude Code --model flag not working / Wrong model in use — Claude Code 模型切换失效解决方案

【Bug已解决】Claude Code --model flag not working / Wrong model in use — Claude Code 模型切换失效解决方案1. 问题描述使用--model参数或/model命令切换模型时Claude Code 仍然使用旧模型# --model 参数不生效 $ claude --model sonnet 你使用的是哪个模型 # 回答: 我使用的是 Opus而不是 Sonnet # 或 /model 命令后不切换 /model sonnet 你使用的是哪个模型 # 仍然使用旧模型 # 或环境变量不生效 $ ANTHROPIC_MODELclaude-sonnet-4-20250514 claude 你使用的是哪个模型 # 使用默认模型而非环境变量指定的 # 或切换后报错 /model haiku Error: Model not available这个问题在以下场景中特别常见环境变量和配置文件冲突模型名称拼写错误API Key 不支持目标模型settings.json 中的 model 覆盖了命令行参数项目级配置覆盖用户级/model 切换后未生效需要重启2. 原因分析核心原理拆解用户指定模型 → 多配置来源冲突 / 名称错误 / 权限不足 ↓ 实际使用的模型与预期不一致 ↓ 模型切换失效原因分类表原因分类具体表现占比配置覆盖settings.json 覆盖约 35%名称错误模型名称拼写不正确约 25%环境变量冲突ANTHROPIC_MODEL 覆盖约 20%权限不足Key 不支持该模型约 10%未重启/model 后需要重新加载约 5%版本问题旧版本不支持新模型约 5%3. 解决方案方案一检查配置优先级最推荐# 步骤 1了解配置优先级从高到低 # 1. 命令行参数 (--model) # 2. 环境变量 (ANTHROPIC_MODEL) # 3. 项目级 settings.json # 4. 用户级 settings.json # 步骤 2检查所有配置来源 env | grep ANTHROPIC_MODEL cat .claude/settings.json 2/dev/null | grep model cat ~/.claude/settings.json | grep model # 步骤 3清除冲突的配置 # 如果环境变量覆盖了命令行 unset ANTHROPIC_MODEL claude --model sonnet方案二使用正确的模型名称# 步骤 1查看可用模型 claude --list-models # 或查看文档 # 步骤 2正确的模型名称 # 简写: sonnet, opus, haiku # 全名: claude-sonnet-4-20250514, claude-opus-4-20250514 # 步骤 3使用简写 claude --model sonnet # 步骤 4或使用全名 claude --model claude-sonnet-4-20250514 # 步骤 5验证 你使用的是哪个模型方案三清理 settings.json 中的 model# 步骤 1如果 settings.json 中有 model 设置 cat ~/.claude/settings.json # {model: opus} ← 这会覆盖 --model # 步骤 2移除 settings.json 中的 model cat ~/.claude/settings.json EOF { streaming: true, autoUpdate: true } EOF # 不设置 model使用命令行或环境变量指定 # 步骤 3重启 claude --model sonnet方案四使用环境变量# 步骤 1设置环境变量 export ANTHROPIC_MODELclaude-sonnet-4-20250514 # 步骤 2确保 settings.json 中没有 model # 环境变量优先级高于 settings.json # 步骤 3启动 claude # 步骤 4验证 你使用的是哪个模型方案五处理权限不足# 步骤 1如果报 Model not available # 某些 API Key 可能不支持所有模型 # 步骤 2检查 API Key 的权限 # 在 Console 中查看 Key 的权限范围 # 步骤 3如果 Key 不支持 Opus # 切换到 Sonnet 或 Haiku /model sonnet # 步骤 4或升级 API 套餐获取所有模型方案六重启 Claude Code# 步骤 1/model 切换后可能需要重启 /model sonnet /exit # 步骤 2重新启动 claude --model sonnet # 步骤 3验证 你使用的是哪个模型 # 步骤 4使用 --debug 确认 claude --model sonnet --debug 21 | grep -i model4. 各方案对比总结方案适用场景推荐指数难度方案一检查优先级排查⭐⭐⭐⭐⭐低方案二正确名称名称错误⭐⭐⭐⭐⭐低方案三清理配置配置覆盖⭐⭐⭐⭐⭐低方案四环境变量持久设置⭐⭐⭐⭐低方案五检查权限权限不足⭐⭐⭐低方案六重启切换不生效⭐⭐⭐⭐低5. 常见问题 FAQ5.1 可用的模型有哪些Sonnet: claude-sonnet-4-20250514快速、性价比高Opus: claude-opus-4-20250514最强、最贵Haiku: claude-haiku-4-20250514最快、最便宜5.2 --model 和 /model 的区别--model命令行参数启动时指定/model交互式命令运行中切换5.3 为什么 settings.json 的 model 覆盖了 --model正常情况下--model优先级最高。但如果环境变量设置了ANTHROPIC_MODEL可能覆盖。检查所有配置来源。5.4 模型名称大小写敏感吗简写sonnet/opus/haiku通常不敏感。全名claude-sonnet-4-20250514需要正确拼写。5.5 如何确认当前使用的模型# 方法 1: 直接询问 你使用的是哪个模型 # 方法 2: /status /status # 方法 3: --debug claude --debug 21 | grep -i model5.6 切换模型后上下文会保留吗/model切换后上下文保留。/exitclaude --model重启后上下文丢失除非--continue。5.7 不同模型的上下文窗口一样吗Sonnet/Opus/Haiku 都是 200K tokens。但不同模型对上下文的利用效率不同。5.8 项目级 settings.json 覆盖了模型项目级.claude/settings.json中的model会覆盖用户级。删除项目级中的 model 或修改为期望的模型。5.9 CI/CD 中如何指定模型ANTHROPIC_MODELclaude-sonnet-4-20250514 \ claude --print task --max-turns 105.10 排查清单速查表□ 1. env | grep ANTHROPIC_MODEL 检查环境变量 □ 2. cat settings.json 检查配置文件中的 model □ 3. unset ANTHROPIC_MODEL 清除冲突 □ 4. 使用正确的模型简写: sonnet/opus/haiku □ 5. 从 settings.json 中移除 model 设置 □ 6. /model 后重启 Claude Code □ 7. claude --debug 确认加载的模型 □ 8. 检查 API Key 是否支持目标模型 □ 9. /status 查看当前状态 □ 10. 检查项目级和用户级配置冲突6. 总结根本原因模型切换失效最常见原因是配置覆盖35%settings.json 中的 model 覆盖命令行和名称错误25%最佳实践从 settings.json 中移除model设置通过--model参数或ANTHROPIC_MODEL环境变量指定配置优先级命令行参数 环境变量 项目级 settings.json 用户级 settings.json检查所有来源模型名称使用简写sonnet/opus/haiku或全名claude-sonnet-4-20250514确保拼写正确最佳实践建议使用ANTHROPIC_MODEL环境变量持久指定模型——在.zshrc中设置后所有终端统一使用避免每次手动指定故障排查流程图flowchart TD A[模型切换失效] -- B[检查所有配置来源] B -- C[env | grep ANTHROPIC_MODEL] B -- D[cat settings.json | grep model] C -- E{环境变量设置了?} D -- F{settings.json 有 model?} E --|是| G[unset ANTHROPIC_MODEL] F --|是| H[从 settings.json 移除 model] E --|否| I[检查模型名称] F --|否| I G -- J[claude --model sonnet] H -- J I -- K{名称正确?} K --|否| L[使用正确名称: sonnet/opus/haiku] K --|是| M[重启 Claude Code] L -- J M -- N[claude --model sonnet --debug] N -- O{debug 显示正确模型?} O --|是| P[✅ 问题解决] O --|否| Q[检查 API Key 权限] Q -- R{Key 支持该模型?} R --|是| S[使用 ANTHROPIC_MODEL 环境变量] R --|否| T[切换到支持的模型] S -- P T -- P