51 · 常见问题排查完整指南

安装、登录、网络、权限、MCP、IDE、模型和性能等常见故障的定位顺序与解决方法，遇到问题时按现象快速查找。

出问题是常态，会排查才不慌。这一篇把最常见的几类问题，按「现象 → 定位 → 解决」整理。

「安装」：最常见是网络不通或权限不足。先确认网络能连官方源，再确认安装位置有写权限。

「登录」：多半是网络问题或授权流程没走完。确认浏览器能打开授权页、确认回执能回来。

「网络」：贯穿所有问题的元凶之一。很多「奇怪报错」追到底都是网络不通或不稳。

「权限」：它「不干活」常常不是坏了，而是被权限卡住、或某个操作等你审批。先查权限/审批，再怀疑别的。

「MCP」：外部工具连不上，先查配置对不对、凭证对不对、服务起没起。

「IDE」：集成出问题，先确认插件装对、登录状态正常、版本兼容。

「模型」：切了模型后异常，先确认模型名写对、接口兼容。

「性能」：跑得慢，先查上下文是不是太臃肿、模型是不是选重了。

「定位顺序」总原则：先看「环境问题」（网络、权限、配置），再看「用法问题」。绝大多数问题，追到最后都是这两类之一。

最后建议：报错原文要保存好。报错信息里往往就写着原因和提示，比盲目搜索靠谱得多。

动手试一下：比起看十遍，不如立刻打开 Codex 跑一个小任务验证你理解的概念。比如这一篇讲的概念，你可以找一个一分钟能完成的小需求，让它跑一遍，看实际行为是不是和你理解的一致。

五分钟练习：① 找一个一分钟能完成的代码任务 ② 用这一篇的方法描述给 Codex ③ 看它执行时有没有触发你刚学的那个机制 ④ 验证结果是否符合预期。这一轮做下来，你对这一篇的理解会深 3 倍。

延伸阅读：学完这一篇，你可以看本组里的下一篇，把相邻的概念连起来读；也可以跳到更后面的组学 MCP、子代理、Skills 这些更深的能力。知识是网状的，多跳几篇会理解更深。

一页速览：如果只能记三件事，① {一}。② {二}。③ {三}。其他细节以后需要再翻这一篇查。