排错中心
Claude Code 常见问题
Claude Code 出错时先保留完整错误，再区分命令环境、认证、地址路由、模型、目录权限和网络连接。
提示：先确认当前使用的客户端、配置来源和权限范围，再按本文步骤操作。Claude Code 常见问题完成后仍要用最小任务验证。
01.
先确定问题现象
排查命令、环境变量、权限、模型和连接问题。
Claude Code 出错时先保留完整错误，再区分命令环境、认证、地址路由、模型、目录权限和网络连接。
记录准确现象
保存执行命令、错误原文、发生时间和当前目录，避免只留下“不能用”。
确认配置来源
检查当前终端环境变量、配置文件和旧进程，确认 Claude Code 实际读取哪一份。
按状态码定位
401/403 看认证权限，404 看地址与模型，429 看频率和额度，超时看网络与上游。
这一节的目标：先确认要解决的问题、当前客户端和配置来源，再开始修改。
02.
复现前保留证据
开始前把环境、材料和权限边界列清楚，可以避免把安装问题、配置问题和服务端问题混在一起。
- 保留错误原文、时间与执行动作
- 记录客户端、配置来源和当前目录
- 先用最小请求复现，暂时移除复杂变量
03.
四步定位故障层
- 1
记录准确现象
保存执行命令、错误原文、发生时间和当前目录，避免只留下“不能用”。
- 2
确认配置来源
检查当前终端环境变量、配置文件和旧进程，确认 Claude Code 实际读取哪一份。
- 3
按状态码定位
401/403 看认证权限，404 看地址与模型，429 看频率和额度，超时看网络与上游。
- 4
回到最小请求
暂时移除长上下文和复杂工具，使用短输入验证基础链路，再逐项恢复。
04.
怎样确认问题已解决
不要把“已经保存”或“没有弹窗”当成成功。至少确认下面三项都有可观察结果。
- 错误原文与时间已保存
- 实际配置来源已确认
- 能够在最小请求中复现或排除问题
验证原则：先做只读、最小、可重复的检查，再把同一配置用于真实任务。
05.
常见误判与边界
重装能解决所有问题吗？
不能。认证、路由、模型和网络问题通常不会因为重装自动消失，先确定故障层。
同一 Key 在其他工具可用，为什么这里失败？
不同客户端可能使用不同地址、请求格式、模型字段或权限作用域，需要检查实际请求路径。
06.
恢复真实任务前的检查
把当前方法压缩成四个动作，完成后再进入相邻教程，不必一次改动所有配置。
- 1记录准确现象保存执行命令、错误原文、发生时间和当前目录，避免只留下“不能用”。
- 2确认配置来源检查当前终端环境变量、配置文件和旧进程，确认 Claude Code 实际读取哪一份。
- 3按状态码定位401/403 看认证权限，404 看地址与模型，429 看频率和额度，超时看网络与上游。
- 4回到最小请求暂时移除长上下文和复杂工具，使用短输入验证基础链路，再逐项恢复。