AGI 未来之门

主题

AI 工具通用排错手册 ​

排错的核心不是“多试几个命令”，而是缩小问题属于哪一层。每次只改变一个变量，保存原始报错与复现步骤。

1. 先收集最小现场 ​

text
操作系统与版本：
工具名称与版本：
安装方式：
执行的完整命令或点击路径：
完整报错（隐藏令牌和个人路径）：
预期结果：
实际结果：
最后一次正常时间与之后的改动：

截图可能截断关键信息，优先复制文本。脱敏时保留错误码、域名类型、路径结构和时间。

2. 七层定位法 ​

2.1 第 1 层：系统与运行环境 ​

检查操作系统、CPU 架构、Node.js/Python/Git 版本是否满足官方要求：

bash
uname -a        # macOS / Linux
node --version
npm --version
python --version
git --version

Windows PowerShell 可运行：

powershell
[System.Environment]::OSVersion.Version
node --version
npm --version
git --version

2.2 第 2 层：安装与 PATH ​

bash
command -v TOOL_NAME   # macOS / Linux
which TOOL_NAME        # 部分环境可用
npm list -g --depth=0
powershell
Get-Command TOOL_NAME
npm list -g --depth=0

刚安装后找不到命令，先彻底关闭并重开终端。不要在不知道原因时反复混用 npm、Homebrew、WinGet 等多种安装方式。

2.3 第 3 层：认证与权限 ​

错误常见方向
401 / Unauthorized令牌错误、过期、环境变量未生效
403 / Forbidden账户、组织或模型权限不足
浏览器登录循环回调被拦截、账号不匹配、旧凭据缓存

只验证令牌是否存在，不要把令牌本身打印到共享日志：

bash
test -n "$API_KEY" && echo "API_KEY 已设置" || echo "API_KEY 未设置"

2.4 第 4 层：网络与 DNS ​

bash
curl -I https://SERVICE_HOST
nslookup SERVICE_HOST

区分 DNS 失败、TLS 证书失败、连接超时和服务返回错误。代理环境还要检查 HTTP_PROXY、HTTPS_PROXY、NO_PROXY，但不要把包含账号密码的代理地址贴到公开渠道。

2.5 第 5 层：API 与客户端配置 ​

逐项核对 API 地址、协议、模型名、令牌变量名和配置文件优先级。常见坑包括：

  • 地址多写或少写 /v1。
  • 客户端需要 OpenAI 兼容协议，服务却配置成另一种协议。
  • 模型显示名称和 API 实际模型 ID 不同。
  • 修改了配置文件，但环境变量覆盖了它。
  • Windows 与 WSL 各有一套独立配置。

2.6 第 6 层：额度、限速与服务容量 ​

429 可能代表余额不足、请求过快、并发过高或服务容量不足。依次查看控制台额度、模型可用性、状态页，再降低并发并做指数退避；不要无间隔循环重试。

2.7 第 7 层：项目与上下文 ​

工具能启动、简单问答正常，但在项目里失败，通常属于这一层：目录权限、依赖未安装、测试本来就失败、规则冲突、上下文过长或任务范围太大。

bash
git status
git diff
npm run typecheck   # 项目存在该脚本时
npm test            # 项目存在该脚本时
npm run build       # 项目存在该脚本时

先在没有 AI 改动的基线运行一次验证，才能区分旧问题和新问题。

3. 二分定位 ​

当配置很多时，建立最小对照组：

  1. 新建空目录，只发一句简单问答。
  2. 使用官方默认 API 地址与一个明确可用的模型。
  3. 暂时停用 MCP、插件、自定义规则和代理。
  4. 成功后每次只恢复一项配置，直到问题重现。

这比一次重装所有软件更容易找到根因。

4. 向 AI 求助的有效格式 ​

text
请按“已知事实 / 可能原因 / 下一项最小检查”分析，不要一次给出多种修改。
环境：[版本信息]
操作：[完整步骤]
预期：[结果]
实际：[完整错误]
已经验证：[排除项]
限制：不要删除配置，不要重装，不要输出任何秘密值。

执行建议前，要求它解释命令是只读检查还是会改变系统。

5. 什么时候停止尝试 ​

出现下面任一情况，先保存现场并回滚：

  • 建议开始删除未知目录、全局配置或系统证书。
  • 同一错误连续三次没有新增证据。
  • 修复一个问题后出现更多无关错误。
  • 当前改动无法用 git diff 或配置备份解释。
  • 涉及生产、付款、发布或真实客户数据。

回到最后一个可工作的状态，再用最小复现继续。专项问题可查看《Codex 模型繁忙处理》。

先找工作，再找工具。

AGI 未来之门