只要一直用 Claude Code，就一定会卡住。这一章不是一本报错词典，而是让你掌握从症状往下追到原因的排查顺序。
只要手里有这个顺序，哪怕是头一回见到的报错，你也判断得出「这属于哪一类」。至于针对具体问题的文章，之后再看就够了。
拿报错去搜索之前，先做这件事
卡住的时候，很多人会直接把报错原文拿去搜。这么做也有用，但绝大多数情况下，先确认这三件事更快。
如果刚才还好，原因就不在环境，而在紧接着发生的那点变化：变长的对话、新加的配置、换过的网络。
每次都这样就是配置或环境的问题。偶尔出现多半是拥堵或线路，很多时候根本不在你这一侧。
是启动时、发出指令的那一刻，还是回答到一半。停下的位置基本就决定了它属于哪一类。
CHECK 3 最管用。只要知道它停在第 1 章那个收集 → 执行 → 验证循环的哪一环，候选范围一下子就收窄了。
先归到五大类里
Claude Code 的报错，按原因所在的位置分成五类。先判断它属于哪一类。
启动得起来吗？
否 → 应用本身的问题（见后面的附带一提）
是
↓
指令发得出去吗？
否，被拒绝 → ① 认证类
是
↓
有回应吗？
否，到不了／中途断掉 → ② 连接类
提示「已达上限」 → ③ 用量上限类
提示「太长了」 → ④ 上下文类
是
↓
用到外部工具的环节失败 → ⑤ 工具与扩展类
用这个分支先定个大方向，再翻到下面对应的小节。各类的处理套路不一样，混着试只会白白耗掉时间。
① 认证类 —— 身份验证过不去
症状是被告知「尚未登录」，或者因为凭据无效而被拒。特征是在指令送出去之前就停住了。
会话过期／登录的是另一个账号／把 API 密钥和订阅搞混了／公司网络挡住了认证的通信
重新登录 → 确认现在登录的是哪个账号 → 换一条线路试试（比如手机热点）。如果第三步就好了，那其实是第 ② 类连接问题
这一类重新登录就好的概率很高，于是没好的时候人就容易一路死磕下去。试两次还不行，就该怀疑第 ② 类了。认证的通信一样要走网络。
② 连接类 —— 请求到不了，或者中途断掉
这是最容易被误判的一类。未必是你的配置有问题。
症状分成三种。
代理、TLS、企业网络的拦截。属于环境侧的问题，换一条线路就能分辨出来。
服务那一侧正忙。等一等才是正解，去改配置只会留下副作用。
长回答途中连接掉线的类型。把输出切短一些，有时就不再复现。
这三种分别在 连接、代理与 TLS 报错的处理、529 Overloaded / 500 报错、Connection closed mid-response 里单独讲。
不要拿配置去治拥堵。 为了复现「偶尔会失败」而把配置改了十个地方，最后你会分不清到底是修好了，还是时间把它带过去了。请先隔一段时间再试一次，确认它是不是每次都发生。
③ 用量上限类 —— 额度用完了
就是那句「已达到上限」。它不是故障，而是既定规则，所以要调整的不是配置，而是用法。
这里要抓住的一点是：额度不止一种。周期短的额度和周期更长的额度是分开存在的。一边恢复了，另一边还没恢复，那就还是停着。「刚才明明恢复了，怎么又停了」，真相多半就是这个。
详细内容整理在 usage limit reached 的处理，以及用实测验证周额度的 周上限提前重置的真相 里。怎么减少消耗本身，放在第 7 章讲。
④ 上下文类 —— 输入太长
就是被回绝说「太长了」的那一类。可以把它理解成第 1 章讲的上下文窗口，直接以症状的形式冒出来了。
把历史折叠掉，或者收个尾重开一轮。在工作的段落处折叠是基本做法。
不要把超大的文件或日志整份贴进去。只给相关的那一段，或者让它自己去找。
针对症状的处理见 Prompt is too long 报错的成因与处理，什么时候该折叠的判断见 /compact 该不该手动执行。
另外还有一种情况是，输出因为违反方针而被拦下。那不是长度问题，请不要混为一谈。它属于另一种类型。
⑤ 工具与扩展类 —— 接上去的东西跑不起来
这是加了 MCP 服务器或外部工具之后才出现的一类。排查很简单：看看拔掉之后是不是就好了。
把扩展全部拔掉
→ 好了 ：原因就在扩展。一个一个装回去，找出是哪个
→ 还是不行：跟扩展无关。回到 ①～④
确定是扩展的问题之后，去看 MCP 连接报错的成因与处理。绝大多数情况就是配置的写法、启动命令的路径、权限这三样里的一样。
这时不要去怀疑 Claude 本身够不够聪明。扩展没接上，Claude 就会当那个工具根本不存在。「我明明说了它却不做」，原因是连接没通，这种情况很常见。
附带一提 —— 应用本身启动不了
如果你用的不是终端版而是桌面应用，有可能还没走到 Claude Code 这一步就停住了。它不属于上面五类中的任何一类，所以没放进排查表里。
Windows 上需要修复的那种情况见 「无法打开此应用」的修复步骤，画面渲染相关卡死的那种见 GPU process gone 卡死的成因与处理。
还是出不来时的五招
判断不出属于哪一类，或者判断出来了也修不好的时候，请从上往下依次试。它们是按代价从低到高排的。
上下文引起的毛病，这一下就没了。代价最低的一招。
拥堵和上限，光靠这一条就能解决。别去动配置。
换了就好，那就可以确定原因在环境侧的网络上。
第 ⑤ 类的排查法。装回去要一个一个来，一起装回去就没意义了。
在一个空目录里做同样的事。复现不出来，原因就在项目这一侧。
一次只改一样。 卡住的时候人会着急，想一口气改好几处，可那样一来你就始终不知道到底是哪一下起了作用，下次同样的症状再出现，你还得从零开始。把起作用的那一招定位出来，长远看要划算得多。
如果想按具体报错原文来查，常见报错与解决方法汇总可以当索引用。
小结
- 拿报错去搜之前，先看「刚才还是好的吗」「是不是每次都这样」「停在哪一步」这三件事
- 原因分成认证、连接、用量上限、上下文、工具五类。不要混着试
- 拥堵和上限，等一等才是正解。去动配置只会留下副作用
- 额度不止一种。短周期和长周期是分开的，所以恢复了也可能再停
- 扩展类的问题，靠全部拔掉看好不好就能一次分辨清楚。装回去要一个一个来
- 出不来的时候按代价从低到高走这五招，并且一次只改一样
能走出卡壳之后，接下来该决定「放手到什么程度」了。请前往 第 5 章「权限与安全」。