展开知识库目录
登录失败、401、429、超时：按错误类型一个个排除
报错先分类再处理：401 查凭证有没有配错，403 查权限够不够，404 查模型名和路径，429 查额度，超时查网络。每一步都改一个变量，验证一次，别一次改一堆。
先复现并记录完整报错文本
报错先分类再处理：401 查凭证有没有配错，403 查权限够不够，404 查模型名和路径，429 查额度，超时查网络。每一步只改一个变量，验证一次，别一次改一堆。
排查第一步是完整记录报错文本、时间和生效配置。只凭截图猜问题，或者反复重装客户端，都会把简单问题拖成半天；改一个测一个，才能定位问题。
这些情况适合用，另外几种先停一下
适合用
- 登录、连接或调用报错
- 401、403、404、429、超时等问题
- 配置改动后出现新错误
先别急着用
- 错误是临时的，重试就能过
- 报错涉及生产环境，先按应急流程处理
记录报错 → 按类型分层 → 一次只改一个变量
为什么这样安排
OpenAI 的错误处理指南按状态码分类排查；Claude Code 环境变量文档则说明配置来源不同会导致同一报错。
- 01
记录完整报错
错误文本、发生时间、请求地址和生效配置存下来，方便复现和对照。
- 02
按类型分层
401 查 Key，403 查权限，404 查模型和路径，429 查额度，超时查网络。
- 03
确认配置来源
环境变量、settings.json、config.toml 哪个生效，逐个确认。
- 04
一次改一个变量
改完验证一次，有效继续，无效回滚再试下一个，每步留记录，记录能对比。
复制前先替换 {占位}
排错提示词（复制后把报错贴进 {占位}）
我在使用{工具名}时遇到报错，请按下面的方式帮我排查：
环境：{操作系统 / 版本 / 工具版本}
报错原文：{完整报错，不要只贴关键词}
我做过什么：{已经尝试的步骤}
请按顺序：
1. 先按错误类型分类（401 凭证 / 403 权限 / 404 路径 / 429 限流 / 超时网络 / 其他）；
2. 给出最可能的 2 个原因，按可能性排序；
3. 每次只让我改一个变量，给出验证命令；
4. 如果都不行，给出拿日志的路径，便于继续查；
5. 不要让我重装、清缓存这类无差别操作。排错记录（示例）
下面是已经填过变量的示例。复制时请换成自己的文件名、数字和材料位置，别把示例数据原样交出去。
看清格式再改
排错记录（示例）
报错：401 unauthorized 时间：14:32，Windows 配置来源：.env 被加载 排查：Key 变量名写错 修复：改为正确变量名 验证：请求返回 200 复现：换环境重试同样报错，已定位 修复：变量名已改正，请求返回 200
先对症状，别一上来重写整段提示词
401 认证失败
- 常见原因
- Key 错误、未设置或认证方式不匹配
- 怎么修
- 检查 Key 是否被正确读取，重跑登录或重设环境变量。
429 限流或额度不足
- 常见原因
- 请求过多或余额用尽
- 怎么修
- 降低并发、检查额度，等待后重试。
超时但网络正常
- 常见原因
- 上游慢、代理或区域网络问题
- 怎么修
- 分别测试直连和代理，换时间重试。
最后五分钟，逐项打勾
这篇具体参考了什么
正文按公开教程和官方文档重新整理，并换成了可以直接操作的中文场景。产品能力、规则和投稿要求会更新，真正执行前请再打开原始页面核对一次。