【Bug已解决】Invalid Model / Opus not available — Claude Code 模型不可用解决方案1. 问题描述在 Claude Code 中切换到 Opus 模型或使用特定模型时终端弹出以下报错信息Invalid model: claude-opus-4-20250514 Available models: claude-sonnet-4-20250514, claude-haiku-3-5-20241022或者Opus is not available for your account tier. Please use /model to switch to an available model.有时报错为Error: model_not_found {type:error,error:{type:not_found_error,message:model claude-opus-4-20250514 not found}}这个问题在以下场景中特别常见Pro 订阅用户尝试使用 Opus 模型需要 Max 订阅API Key 账户 Tier 不够高无法使用 Opus模型版本号输入错误或已弃用第三方 API 路由不支持某些模型Anthropic 暂时下线某个模型进行维护使用了过时的模型 ID# 典型复现过程 $ claude /model opus Opus is not available for your account tier. /model claude-opus-4-20250514 Error: model_not_found2. 原因分析核心原理拆解用户请求使用特定模型 → Claude Code 向 API 发送请求 ↓ API 检查模型可用性账户权限、模型是否存在 ↓ 模型不可用/不存在/权限不足 ↓ 返回 model_not_found 或 not_available 错误原因分类表原因分类具体表现占比账户 Tier 不足Opus 需要更高 Tier 或 Max 订阅约 40%模型 ID 错误版本号或名称拼写错误约 25%模型已弃用旧模型 ID 被移除约 15%第三方路由不支持路由未配置某些模型约 10%模型临时维护Anthropic 暂时下线模型约 5%区域限制某些地区不支持特定模型约 5%深入说明Anthropic 的模型有严格的访问层级模型与订阅对应关系Haiku所有用户可用包括免费 TierSonnetPro 订阅及以上可用OpusMax 订阅或 Tier 4 API 用户可用模型 ID 命名规则claude-sonnet-4-20250514模型名-版本-日期claude-opus-4-20250514claude-haiku-3-5-20241022当模型版本更新时旧版本 ID 可能被弃用。例如claude-3-opus-20240229已被claude-opus-4-20250514替代。3. 解决方案方案一切换到可用模型最推荐如果 Opus 不可用切换到 Sonnet 是最直接的解决方案。# 步骤 1切换到 Sonnet /model sonnet # 步骤 2验证模型已切换 /model # 应该输出: Current model: sonnet # 步骤 3继续工作 分析这段代码方案二升级订阅或 API Tier如果需要 Opus 的能力升级到 Max 订阅或更高的 API Tier。# 步骤 1检查当前订阅 # 登录 https://console.anthropic.com/settings/usage # 查看当前订阅计划和 Tier # 步骤 2升级到 Max 订阅 # Max 订阅可以使用 Opus 模型 # 或升级 API Tier 到 Tier 4累计消费 $400 # 步骤 3升级后重新尝试 /model opus方案三使用正确的模型 ID确保使用的模型 ID 正确且未被弃用。# 步骤 1查看可用模型列表 /model # 会列出当前账户可用的所有模型 # 步骤 2使用完整正确的模型 ID # 当前有效的模型 ID: # claude-sonnet-4-20250514 # claude-opus-4-20250514 (需要权限) # claude-haiku-3-5-20241022 # 步骤 3通过环境变量设置 export ANTHROPIC_MODELclaude-sonnet-4-20250514方案四检查第三方 API 路由支持的模型使用第三方路由时确认其支持的模型列表。# 步骤 1查看第三方路由文档 # 确认路由支持哪些模型 # 步骤 2使用路由支持的模型 ID # 某些路由使用不同的模型名称 # 如: gpt-4o, deepseek-chat, qwen-max 等 # 步骤 3测试模型可用性 curl -H x-api-key: $ANTHROPIC_API_KEY \ -H content-type: application/json \ $ANTHROPIC_BASE_URL/v1/messages \ -d {model:模型名,max_tokens:10,messages:[{role:user,content:hi}]}方案五检查模型是否在维护中# 步骤 1查看 Anthropic 状态页面 # https://status.anthropic.com # 步骤 2查看是否有模型维护公告 # 如果 Opus 在维护中切换到 Sonnet 等待恢复 # 步骤 3关注 Anthropic 官方公告 # 新模型发布时旧模型可能被弃用方案六清理旧的模型配置# 步骤 1检查环境变量中是否有旧模型设置 echo $ANTHROPIC_MODEL # 如果是旧模型 ID更新或清除 # 步骤 2检查配置文件 cat ~/.claude/settings.json # 查看是否有旧的模型设置 # 步骤 3更新到最新模型 export ANTHROPIC_MODELclaude-sonnet-4-20250514 # 或清除让 Claude Code 使用默认模型 unset ANTHROPIC_MODEL4. 各方案对比总结方案适用场景推荐指数难度方案一切换 SonnetOpus 不可用⭐⭐⭐⭐⭐低方案二升级订阅需要 Opus 能力⭐⭐⭐⭐低方案三正确模型 IDID 错误⭐⭐⭐⭐⭐低方案四检查路由第三方路由⭐⭐⭐⭐中方案五检查维护模型维护中⭐⭐⭐低方案六清理旧配置旧模型残留⭐⭐⭐⭐低5. 常见问题 FAQ5.1 Pro 订阅能否使用 OpusPro 订阅默认不包含 Opus 使用权限。需要 Max 订阅才能使用 Opus 模型。Pro 订阅可以使用 Sonnet 和 Haiku。5.2 如何查看当前账户可用的模型# 在 Claude Code 中 /model # 会列出当前可用的所有模型 # 或在 Anthropic Console 中查看 # https://console.anthropic.com/settings/models5.3 旧模型 ID 是否还能使用Anthropic 通常在新模型发布后保留旧模型一段时间约 3-6 个月然后弃用。弃用后旧 ID 返回model_not_found。建议始终使用最新的模型 ID。5.4 第三方路由报 model_not_found第三方路由可能不支持所有 Anthropic 模型。查看路由文档确认支持的模型列表或切换到 Anthropic 官方 API。5.5 Opus 有使用量限制吗即使有 Max 订阅Opus 的使用量也有限制。Max 订阅的 Opus 配额比 Sonnet 少得多。频繁使用 Opus 可能很快耗尽配额。5.6 环境变量 ANTHROPIC_MODEL 和 /model 命令的优先级/model命令的设置优先于环境变量。如果/model设定了模型会覆盖ANTHROPIC_MODEL环境变量。5.7 CI/CD 中如何指定模型env: ANTHROPIC_MODEL: claude-sonnet-4-20250514 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}5.8 切换模型后会话上下文是否保留切换模型不会清空对话历史。上下文保留但不同模型的上下文窗口大小可能不同。如果从 200K 窗口模型切换到更小窗口的模型可能触发上下文超限。5.9 使用 1M Context 模型时报 model_not_found1M Context 需要单独的模型 ID 和额外权限/model sonnet-1m # 或 export ANTHROPIC_MODELclaude-sonnet-4-1m5.10 排查清单速查表□ 1. 运行 /model 查看当前可用模型 □ 2. 确认使用的模型 ID 正确且未弃用 □ 3. Pro 用户切换到 SonnetOpus 需要 Max □ 4. 检查 ANTHROPIC_MODEL 环境变量 □ 5. 检查 ANTHROPIC_BASE_URL 是否指向第三方路由 □ 6. 查看 Anthropic 状态页面确认模型未维护 □ 7. 清除 ~/.claude/settings.json 中旧模型配置 □ 8. 使用 curl 测试模型可用性 □ 9. 升级到 Max 订阅使用 Opus □ 10. CI/CD 中通过环境变量指定模型6. 总结根本原因模型不可用最常见原因是账户 Tier 不足40%和模型 ID 错误25%Opus 需要 Max 订阅或 Tier 4 API最佳实践遇到模型不可用时立即切换到 SonnetSonnet 在大部分编码场景下性能足够模型 ID始终使用最新的完整模型 ID如claude-sonnet-4-20250514避免使用已弃用的旧版本第三方路由使用第三方路由时确认其支持的模型列表路由可能不支持所有 Anthropic 模型最佳实践建议在~/.zshrc中设置ANTHROPIC_MODEL环境变量为默认模型避免每次手动切换定期检查 Anthropic 公告了解模型更新和弃用计划故障排查流程图flowchart TD A[出现 Invalid Model / Opus not available] -- B{是否使用 Opus?} B --|是| C[检查账户是否有 Opus 权限] B --|否| D[检查模型 ID 是否正确] C -- E{有 Max 订阅或 Tier 4?} E --|是| F[检查模型是否在维护] E --|否| G[切换到 Sonnet 或升级 Max] D -- H{ID 是否正确?} H --|是| I[检查第三方路由支持] H --|否| J[使用正确的模型 ID] F -- K{维护中?} K --|是| L[切换 Sonnet 等待恢复] K --|否| M[检查环境变量配置] I -- N{路由支持该模型?} N --|是| M N --|否| O[使用路由支持的模型] G -- P[✅ 问题解决] J -- P L -- P M -- P O -- P