直接答案：Claude Code 报错先判断发生在启动、认证、模型请求还是工具执行阶段，再按原始状态码处理。401/403 检查密钥与权限，429 检查额度和并发，529 或连接异常再检查线路和有限重试。
1. Claude Code 快速排查顺序
- 保存终端最后一屏日志，不要只记录“启动失败”。
- 确认客户端版本和配置文件路径。
- 确认环境变量或配置模板中的 API Key 已生效。
- 确认 Base URL、模型代号和密钥分组匹配。
- 用短提示词发送最小请求，再逐步恢复完整任务。
一次只改一个变量同时更换客户端、模型和 Base URL，会让问题无法定位。
2. 启动失败、登录失败和快速退出
| 现象 | 排查顺序 |
|---|---|
| 命令不存在 | 检查安装目录、PATH、终端是否重启和当前用户权限 |
| 无法登录 | 确认使用的是 API 配置还是交互式登录流程，检查配置目录和网络 |
| 启动后很快退出 | 查看终端日志，检查版本、配置文件格式、环境变量和认证状态 |
| 配置读取不到 | 确认变量名、引号、换行、当前 Shell 和配置文件位置 |
Windows 用户建议重新打开 PowerShell 后再验证；macOS 和 Linux 用户检查当前 Shell 是否加载了对应的导出变量。
3. 401、403、429、529 状态码
| 状态码 | 常见原因 | 处理方式 |
|---|---|---|
| 401 | 密钥无效、OAuth 刷新失败或凭据路径冲突 | 查看Claude Code 401 与 OAuth 排查 |
| 403 | 密钥分组或项目没有目标模型权限 | 在 API 密钥页面确认分组和模型访问范围 |
| 429 | 额度不足、并发过高或请求频率受限 | 查余额和倍率，降并发并按退避策略重试 |
| 529 | 上游繁忙或暂时不可用 | 有限次数重试，持续失败时暂停并保留请求 ID |
| MCP initialize 超时 | OAuth 完成但 MCP 握手没有返回 | 查看MCP OAuth 超时排查 |
| 扩展 60000ms 超时 | VS Code 子进程或配置探针未确认 | 查看扩展初始化超时排查 |
| 5xx | 网关、线路或上游响应异常 | 用最小请求复现，参阅稳定性指南 |
4. 模型不存在与权限问题
模型卡片名称、API 调用代号和密钥分组可能不是同一个文本。出现模型不存在时：
- 从模型广场复制当前代号。
- 在 API 密钥页面确认分组包含该模型。
- 确认当前客户端协议支持该模型的输入和输出能力。
- 用短文本请求验证，再恢复长上下文或工具调用。
5. Claude Code 响应缓慢怎么办
- 区分首字慢、完整响应慢和本地工具执行慢。
- 缩小文件范围和上下文，减少重复历史。
- 为复杂任务选择能力匹配的模型，不要让轻量模型反复纠错。
- 批量任务使用队列和并发上限，避免 429 后无限重试。
- 记录 P50/P95 延迟、模型代号和请求时间，比较优化前后差异。
如果同时出现 Reconnecting、ECONNRESET 或 IDE 连接失败，参阅Claude Code 代理与网络排查文章。工作流、权限和上下文方法见Claude Code 工作流与 MCP 专题。
6. 日志与客服求助信息
提交问题时提供以下脱敏信息：
- 发生时间、客户端版本和操作系统。
- 模型代号、接口类型和状态码。
- 响应正文、请求 ID 和复现步骤。
- 是否只读请求成功、是否涉及工具或多模态输入。
不要提交完整 API Key、Cookie、用户隐私或未脱敏项目文件。客服微信：GPT774。
7. 常见问题
Claude Code 返回 401 怎么办？
检查 API Key、环境变量、Base URL 和客户端实际读取的配置，重新用最小请求验证。
Claude Code 启动后很快退出怎么办？
记录终端日志，依次检查客户端版本、配置文件、环境变量、认证状态、模型代号和网络请求。
Claude Code 返回 529 可以一直重试吗？
不应无限重试。使用有限次数指数退避，降低并发，持续失败时暂停请求并保留请求 ID。