AI 工具链排错：装不上、连不上、跑一半断掉

一个独立开发者的排查顺序清单。写给正在被 AI 工具折腾的人，也写给未来的自己。

先说结论

AI 工具链的故障，九成落在四个位置：安装与权限、网络与代理、模型与凭据、工作流编排。按顺序查，比乱试快得多。

顺序很重要：上一层没通，下一层的报错基本都是噪音。所以不要跳步，也不要一上来就怀疑代码。

一、安装阶段

• 装不上：先确认系统版本与架构（x64 / arm64）、安装包是否完整（SHA256）、是否需要管理员权限
• 装完打不开：日志优先级是 应用日志 > 系统事件 > 启动器输出
• 两个常见坑：装进了用户目录而不是 Program Files；杀软静默拦截
• 判断标准：能不能用一个最小命令跑起来（--version），先别急着接业务

二、连接阶段

• 连不上：先分清是 DNS、TLS、代理还是服务端 4xx/5xx；一层一层往下排除
• 代理环境：检查分流规则是否覆盖目标域名、端口是否被占用、NO_PROXY 有没有写漏
• MCP：先单独测 server 能否启动，再接客户端；stdio 和 HTTP 的失败表现完全不同
• 阶段性验证：curl -v 拿到 TLS 握手结果，比在客户端里猜有效率得多

三、模型阶段

• 本地模型加载失败：显存不足、量化格式不匹配、驱动版本太旧
• API 报错：鉴权（key / 额度 / 区域）、路由（base_url 写错）、超时
• 一个容易忽略的点：同一个 key 在不同区域的可用模型不一样，报错信息往往只说 404

四、工作流阶段

• 跑一半断：先加日志，再做断点重跑；把长流程拆成幂等的小步骤
• 别一上来就重构，先复现；复现不了的问题不要「顺手优化」
• 记录改动：一次只改一个变量，否则下次出问题你分不清是谁的锅

什么情况我不接

账号买卖或共享、破解、绕过软件限制、爬隐私数据。这几条没有例外。

一句话版本

装得上 → 连得上 → 模型跑得动 → 流程断得住。四步全过，再谈优化。