排错不是不停重试，也不是看到一个错误就重装全部软件。先判断问题发生在哪一层，再只改变一个变量，才能知道修复是否有效。

先定位五个层次

登录问题

应用打不开登录页

先确认系统时间、应用版本和网络。换网络之前记录错误文字；如果每次都改变多个条件，你很难知道真正原因。

登录后又回到登录页

关闭客户端后重新打开，检查浏览器授权是否完成。不要把账号密码交给所谓的“登录修复工具”。如果页面提示账号受限，走官方帮助流程。

API 问题

401 Unauthorized

重点检查 API Key 是否完整、是否复制了前后空格、是否已经被撤销，以及当前渠道是否真的使用了这把 Key。不要先修改模型名。

403 Forbidden

检查账号权限、服务地区、余额和该模型是否对当前 Key 开放。保留完整错误文本，不要在公开反馈中贴出 Key 或完整请求头。

404 Not Found

通常先检查 Base URL 和协议。不要把 /chat/completions、/responses 等路径凭感觉拼到地址后面。按服务商官方文档确认工具所需接口是否被支持。

请求一直转圈

先看 CC Switch 或客户端日志，再分别测试网络、Key 和模型。重启只能解决进程状态问题，不能解决地址、权限或协议错误。

项目问题

AI 修改了错误目录

先停止任务，查看当前工作目录和 git status。如果还没有确认修改范围，不要继续让 AI“修复刚才的错误”。先恢复不需要的变化，再重新给出目录和范围。

AI 说完成但没有结果

查看 diff 和命令输出。确认它是否只给了建议、是否等待确认、是否修改了另一个同名文件。结果必须通过文件内容、页面行为或测试命令验证。

AI 改动太多

把任务拆小，明确“只允许修改哪些文件”和“不要格式化无关代码”。下一次先要求计划，再逐项接受。

一个安全的排错顺序

1. 记录现象、时间和脱敏后的错误；
2. 确认当前工具、版本和工作目录；
3. 只检查一个最可能的配置项；
4. 重试一个最小任务；
5. 对比结果，确认问题是否真的变化；
6. 仍失败时查看官方文档或提交包含必要上下文的反馈。

不要这样排错

• 不要把真实 API Key 粘到公共聊天；
• 不要为了一个 404 随意升级所有依赖；
• 不要删除整个配置目录来“碰碰运气”；
• 不要同时更换客户端、模型、网络和渠道；
• 不要在没有备份和确认范围时覆盖工作区。

完成检查

• 我能把问题归入账号、Key、渠道、项目或任务层；
• 我记录了错误原文，但已去掉敏感信息；
• 我一次只修改一个变量；
• 我用最小任务验证了修复；
• 我知道什么时候应该停止并查官方文档。

主线完成后

如果你需要另一种终端工作流，可以阅读Claude Code 入门。如果你想连接外部文件或工具，再阅读MCP 入门。