从安装到断点重跑的 AI 工具排障清单

AI 工具装不上、服务连不上、任务跑到一半中断，常让人同时怀疑代理、模型和代码。作者给出的办法是固定排查顺序：安装与权限、网络与代理、模型与凭据、工作流编排，前一层通过后再查下一层。

这份清单的价值在于缩小问题范围。它没有提供性能测试或故障统计，却给了一个实用原则：先证明最小链路可用，再接入业务；先复现故障，再考虑优化。

装好和连通，要分别拿出证据

安装阶段先核对系统版本、CPU 架构（x64 / arm64）、安装包完整性（SHA256），以及是否需要管理员权限。判断安装是否成功，先看能否执行一个最小命令，例如 --version，别急着接业务。

如果装完打不开，作者建议按「应用日志 > 系统事件 > 启动器输出」的顺序查日志，并提醒检查安装目录和杀软静默拦截。这里的 Program Files 显然对应 Windows 环境；原文把装进用户目录列为常见坑，但没有交代具体软件，不能据此认定用户目录安装都有问题。

到了网络层，先区分 DNS、TLS、代理和服务端 4xx/5xx。它们对应的故障位置不同：域名解析失败、握手失败、代理转发异常，以及收到 HTTP 错误响应，需要分别处理。

代理环境还要核对三件事：分流规则是否覆盖目标域名、端口是否被占用、NO_PROXY 是否符合预期。原文只提醒它可能写漏，实际排查时还需要明确哪些请求应该直连。

作者推荐用 curl -v 查看 TLS 握手结果。它能把连接过程摊开，但一次成功请求只能证明这条测试路径可用，不能自动证明应用采用了相同的代理配置。

模型和 MCP 都要先单独跑通

MCP 的排查顺序很具体：先确认 server 能独立启动，再接客户端。同时分清 stdio 和 HTTP，两种传输方式的失败表现不同，不能都按远程接口连不上的思路处理。

模型问题则分两路：

• 本地模型加载失败，检查显存、量化格式和驱动版本。
• API 调用失败，检查鉴权信息，包括 key、额度、区域，再检查路由配置 base_url 和超时。

其中一个容易误判的现象是：同一个 key 在不同区域，可用模型可能不同，而报错只返回 404。看到 404 时，模型是否可用、区域是否匹配、base_url 是否正确，都应进入检查范围。

原文没有说明具体服务商，也没有提供请求样例。这个提醒适合帮助扩大排查范围，不能直接当作某个 API 的诊断结论。

跑到一半中断，重点是让失败可以恢复

前面几层解决的是「能不能开始」，工作流编排解决的是「失败后怎么办」。

作者建议先补日志，再做断点重跑，并把长流程拆成幂等的小步骤。幂等指的是，同一步重复执行，不会因为重复操作产生额外副作用。只有做到这一点，重试才不容易把一次中断变成另一种错误。

先复现，再修改；一次只改一个变量。

这两条约束很有用。如果同时换 key、改代理、调整超时，任务即使恢复，也无法确定哪个改动起了作用。下一次故障出现时，仍然只能重新猜。

原文还明确划出了边界：账号买卖或共享、破解、绕过软件限制、爬取隐私数据，都不应成为排错手段。

我的判断

我赞同这套顺序作为默认入口。它把笼统的「AI 工具坏了」拆成了几个可验证的问题，适合个人开发者整理检查清单，也方便团队交接故障信息。

但作者声称故障「九成」落在这四个位置，没有给出样本、统计口径或对照数据。这是经验之谈，不能当作经过验证的比例。

「上一层没通，下一层报错基本都是噪音」也有适用前提。初次安装、首次接入时，顺序排查很省心；如果工具之前一直正常，刚改完 base_url 就失败，应优先验证这次改动。清单应帮助缩小范围，而不是要求每次从头检查。

另外，--version 只能证明程序能启动，无法证明模型调用成功；日志也应结合读取成本和有效信息选择，原文给出的优先级并非所有工具都适用。

能拿来做什么

• 给日常 AI 编程工具留一份最小验证清单，分别记录启动命令、网络测试方式、模型调用方式和成功标志，升级或迁移后按顺序检查。
• 接入 MCP 时，先单独验证 server 启动，再连接客户端，并记录使用的是 stdio 还是 HTTP，避免把不同层的问题混在一起。
• 在 Node 长任务中，按可独立重跑的步骤记录输入、完成状态和错误信息；增加重试前，先确认重复执行是否会产生副作用。
• 排查 API 故障时，把区域、模型、base_url、超时和错误响应一起记录，每次只调整一个配置，让恢复过程留下可复用的证据。