排障：模型配置失败

模型配置失败不要乱改一堆参数。先分清 API Key、Base URL、Model、额度、网络、配置语法分别有没有问题。

排查模板

模型配置失败时，不要同时改 Key、Base URL、Model、网络和代理。一次只验证一个变量，不然很难知道到底哪里修好了。

Claude Code 模型配置失败了。

请按类别帮我排查：
1. API Key 是否缺失、过期或没有权限。
2. Base URL 是否填写错误。
3. Model 名称是否来自官方控制台。
4. 服务商额度或套餐是否可用。
5. 当前网络是否能访问服务。
6. 配置文件语法是否可能错误。

请不要让我暴露真实 API Key。
如果需要检查密钥，只说检查方式，不要要求我粘贴密钥。

先确认你用哪条路线

• 官方 Claude：重点看账号权限、网络和套餐。
• cc switch 国内网关：重点看当前切到哪个配置档。
• 团队 LLM Gateway：重点看网关地址、认证方式、模型路由。
• 企业云：重点看云权限、区域、模型可用性。

请先判断我当前模型配置属于哪条路线。

已知信息：
1. 我是否使用 cc switch：【是 / 否 / 不确定】
2. 服务商或网关名称：【填写】
3. Base URL 是否已配置：【是 / 否 / 不确定】
4. 模型名：【填写或不确定】
5. 错误信息：【粘贴错误，不要粘贴密钥】

请不要要求我暴露真实 API Key。

常见判断

• 401 / unauthorized：优先看 API Key。
• 404 / model not found：优先看模型名和账号权限。
• timeout / network error：优先看网络和 Base URL。
• 配置后表现混乱：优先做只读项目分析验证。

用 cc switch 时怎么排查

我使用 cc switch 切换模型后失败。

请指导我检查：
1. 当前选中的配置档是不是目标配置。
2. Base URL 是否是 Claude Code 应该请求的地址。
3. 模型名是否来自服务商控制台。
4. API Key 是否只保存在本机或切换器里。
5. 切换后是否需要重启 Claude Code。
6. 如何做只读验证。

不要要求我把 API Key 发给你。

切换配置后的验证顺序

cc switch 切换成功不代表模型可用于真实任务。按顺序验证：

1. 能否正常对话。
2. 能否只读读取项目目录。
3. 能否总结 README 和技术栈。
4. 能否区分文件事实和推测。
5. 能否解释一个小 diff 或小任务计划。

任何一步不稳定，都先切回已知可用配置。

错误码怎么读

• 401：Key 错、Key 过期、认证字段不对、账号无权限。
• 403：账号被限制、模型无权限、区域或组织策略限制。
• 404：Base URL 错、模型名错、网关路由不存在。
• 429：额度、限流、并发超限。
• 500/502/503：服务商或网关故障，先不要乱改本地配置。
• timeout：网络、代理、DNS、网关不可达。

不要同时改多个变量

模型排障一次只动一个变量：

否则就算恢复了，也不知道是哪一步修好的。

配置成功但不好用

能回复不代表适合写代码。要做只读项目验证。

请做模型能力验证，不要修改文件。

要求：
1. 读取项目根目录和 README。
2. 总结项目技术栈。
3. 指出入口文件和关键脚本。
4. 明确哪些结论来自文件。
5. 不要编造不存在的文件。
6. 如果上下文、工具调用或代码理解明显不稳定，请提示我换模型或网关。

不要把这些写进项目

• API Key。
• 真实 token。
• 私有网关账号。
• 个人代理地址和密码。
• 公司内部服务地址。

最小恢复方案

模型配置已经乱了，请帮我恢复到可验证状态。

要求：
1. 不要修改项目文件。
2. 先确认当前配置路线。
3. 建议我切回一个已知可用配置。
4. 用只读任务验证。
5. 验证通过前不要继续开发任务。

模型问题和代码问题要分开

如果模型经常读错文件、编造结论、丢上下文，不要让它继续修代码：

请先判断这是模型配置问题还是项目代码问题。

要求：
1. 不修改项目文件。
2. 用只读任务验证模型是否能正确读取文件。
3. 如果模型理解不稳定，请建议切换配置。
4. 不要通过改项目代码来掩盖模型问题。

验收结果

• 能完成一次只读项目分析。
• 不会要求暴露真实密钥。
• 能区分配置问题和模型能力问题。
• 知道 cc switch 切换后也要做只读验证。