排查报错，一半时间浪费在方向错了

AI 编程工具的报错有个共同的麻烦：报错文本描述的常常是症状，不是成因。

客户端报「连接关闭」，真因可能是服务端进程压根没起来；报「流式中断」， 真因可能是账号权限没开通；报「健康检查超时」，真因可能是操作系统拦住了进程启动。 按报错的字面意思去查，很容易一路查到岔路上。

这个页面做的事很简单：按报错文本里的特征把它归到一类，然后告诉你 先往哪个方向查、该看哪里、别做什么。

为什么「别做什么」和「往哪查」一样重要

排查时最贵的不是找不到答案，是在错误的方向上花了很久。

几个高频的例子：

• 证书报错时关掉校验——那不是修，是把门拆了，而且会影响这台机器上所有同类程序
• 命令找不到时反复重装——如果是 PATH 问题，装一百次也是同样的结果
• 解析崩溃时反复改配置——那是程序内部拿到了没预料到的数据后崩了，跟你的配置无关
• 被限流时疯狂重试——重试也算请求，只会让限流窗口一直是满的
• 服务端过载时去换网络、改凭证——那几样跟过载都没关系，改了只会让之后更难判断

所以每一类都单独列了一条「别做什么」。它省下的时间常常比「往哪查」还多。

分清「重试有用」和「重试没用」

这是本工具里另一个实用的标记。故障大致分两类：

偶发的——服务端过载、流式中断、客户端解析崩溃。这些跟服务端状态、网络、时机有关， 重试有可能就过去了。

确定的——路径找不到、认证失败、文本匹配不上、端口被占。 同样的输入一百次都是同样的结果，重试纯属浪费时间，应该直接去改条件。

很多人在确定性故障上反复重试，是因为没意识到这个区别。

一条不依赖任何工具的通用线索

报错前它让你等了多久。

• 立刻报错（一两秒内） → 本地就判断出来了：配置错、认证没通过、参数不合法。没有走到网络那一层
• 等了十几秒 → 可能是单次请求超时
• 等了一两分钟甚至更久 → 里面几乎一定有重试机制。真实的失败次数是你看到的好几倍，那不是网络抖了一下，是持续性的问题

这条线索不需要你开日志、不需要懂内部实现，就是看一眼时间—— 但它能把「偶发抖动」和「持续故障」这两种完全不同的情况分开。

嵌套报错从右往左读

一个操作内部调了别的东西，里面出错了，外层包一层自己的描述再抛出来。 你看到的是外层的描述，真因在里层。

比如形如 外层描述: 中层描述: 内层原因 的三段式报错， 越靠右越接近真因。这是读嵌套报错的通用技巧，也是本工具在命中多类时给出的建议顺序。

这个工具的边界

它不能替代官方文档，也不保证给出的方向一定对——它只是把常见特征和排查方向做了个映射， 帮你少走弯路。分诊规则核对日 2026-08-08。

另外提醒一句：往公开渠道贴日志或诊断文件之前，先确认里面没有你的凭证和代码内容。 调试输出通常包含请求体，而请求体里可能有你项目里的源码片段和 API 密钥。