AI 客户端与中转 API 通用排错手册¶
[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看 教程配套 API。
这份手册适用于大多数 OpenAI 兼容客户端、Anthropic 兼容工具和自部署 AI 平台。排错原则只有一句：先确认请求有没有到达，再按认证、路径、模型、协议、额度、网络的顺序缩小范围。
1. 先收集六项信息¶
在修改配置前记录：
- 工具名称与版本；
- 操作系统或 Docker 镜像版本；
- 选择的供应商类型；
- Base URL 的结构（截图时隐藏私有域名和参数）；
- 模型 ID；
- HTTP 状态码与经过脱敏的错误摘要。
不要公开 API Key、认证请求头、完整配置文件或未经处理的服务端原始错误。
2. 五分钟快速排查¶
按顺序执行，某一步失败就先解决该步：
- 控制台中 Key 仍有效，余额或免费额度可用；
- 模型状态可用，模型 ID 是复制而非手输；
- 工具选择的协议与服务支持的端点一致；
- Base URL 没有重复
/v1，也没有误填完整端点； - 新建空白对话测试，避免旧上下文过长；
- 暂时关闭代理、插件、知识库和自定义请求头；
- 关闭流式输出再试一次；
- 换一个基础文本模型交叉验证；
- 查看工具日志中的最终 URL 和状态码。
3. 按状态码处理¶
400 Bad Request¶
含义：请求到达了服务，但请求体、参数或模型能力不符合要求。
常见原因：
- 模型 ID 不存在；
- 把图片发给纯文本模型；
max_tokens、温度或上下文长度越界；- 工具发送了服务不支持的字段；
- Function Calling / JSON Schema 格式不兼容；
- 对话角色或消息内容结构不被接受。
处理：新建空白对话，只发纯文本；关闭工具调用、联网、图片和结构化输出；恢复默认参数后再试。
401 Unauthorized¶
含义：认证缺失或认证信息无效。
检查：
- Key 是否复制完整、首尾是否有空格；
- 输入框是否只需要 Key，而你误加了
Bearer； - Key 是否已删除、过期或被重置；
- 环境变量是否在启动工具的同一终端生效；
- Docker 容器内是否真的拿到了环境变量。
403 Forbidden¶
含义：身份已识别，但没有当前资源权限，或请求被安全策略拒绝。
检查 Key 的模型权限、账户状态、IP/地区限制和工具所选模型。不要反复重试；先去控制台确认权限。
404 Not Found¶
含义：路径或资源不存在，也可能是模型 ID 不存在。
重点查看最终 URL：
错误示例：https://your-api.example.com/v1/v1/chat/completions
错误示例：https://your-api.example.com/v1/chat/completions/chat/completions
如果 URL 正确，再确认服务是否实现了 /responses、/messages 或所需的其他端点。
408 / 请求超时¶
原因可能是网络、模型排队、超长上下文、客户端超时过短或代理链路不稳定。
处理：发送更短的问题；新建会话；提高客户端超时时间；暂时关闭代理；改用非流式请求确定服务能否最终返回。
409 Conflict¶
某些异步任务、文件或会话状态冲突时可能出现。刷新资源状态，避免重复提交同一个任务；若工具有任务 ID，保留它以便排查。
413 Payload Too Large¶
上传文件、图片、知识库片段或完整对话超过网关限制。删除大附件，缩短上下文，降低图片大小或分批导入知识库。
422 Unprocessable Entity¶
JSON 可解析但字段语义不合法。通常与参数类型、必填字段、工具定义或消息结构有关。恢复默认模型参数并关闭扩展功能。
429 Too Many Requests¶
可能是频率、并发、Token 速率或额度限制，而不只是“余额不足”。
处理：降低并发；指数退避；减少一次请求的上下文；检查控制台额度。不要在失败循环中立即无限重试。
推荐退避节奏：
500 / 502 / 503 / 504¶
这类错误通常发生在服务端、网关或模型暂时不可用。先用同协议的另一个模型交叉验证，保存时间、请求 ID 和状态码，稍后重试。不要把服务端原始错误完整发布到公开 Issue。
4. 没有状态码时怎么查¶
一直转圈，没有任何文字¶
- 关闭流式输出；
- 检查浏览器开发者工具或客户端日志；
- 排除 SSE 被代理缓存或截断；
- 新建会话，避免上下文过大；
- 确认系统时间准确，证书校验正常。
流式输出到一半断开¶
- 网络或代理中断了长连接；
- 客户端不认识某种 SSE 事件；
- 模型达到长度或内容限制；
- 反向代理读取超时过短。
先测试 stream: false。非流式正常而流式失败，范围基本可锁定在 SSE、代理缓冲或客户端解析。
返回空白内容¶
查看响应是否把内容放在客户端不认识的字段里，尤其是 Responses 与 Chat Completions 混用时。另检查模型是否只返回了工具调用、推理字段或被客户端隐藏的内容块。
中文乱码¶
确保请求与响应使用 UTF-8，Content-Type 包含正确字符集；终端字体和 locale 也要支持中文。不要用错误编码二次转义 JSON。
5. 协议不匹配的典型症状¶
| 症状 | 可能原因 |
|---|---|
/chat/completions 正常，编程代理仍失败 |
代理需要 Responses 或 Messages |
| 普通聊天正常，工具调用失败 | Function Calling 字段或流事件不兼容 |
| 文本正常，图片失败 | 模型或服务未实现多模态内容块 |
| 客户端测试连接成功，正式对话 404 | 测试只请求了 /models，对话端点不同 |
| 能列出模型但不能请求 | 模型列表可见不等于 Key 有调用权限 |
接入编程工具时，必须专门测试工具调用；接入知识库平台时，还要分别测试聊天模型与 Embedding 模型。
6. Docker 与自部署平台专项¶
容器里访问不了宿主机¶
容器内的 localhost 指向容器自己，不是宿主机。使用适合当前操作系统和 Docker 环境的宿主机地址，或把服务放进同一个 Docker 网络并用服务名访问。
修改环境变量不生效¶
容器启动时读取的环境变量通常不会因编辑 .env 自动刷新。先查看平台官方说明，再重新创建对应服务。生产环境操作前务必备份配置，不要盲目删除数据卷。
浏览器报 CORS，但命令行正常¶
说明浏览器跨域策略阻止了直接请求。优先让应用后端代发请求，不要为省事把允许来源设成任意值并暴露管理接口。
反向代理导致 SSE 卡顿¶
检查代理是否缓冲响应、是否压缩事件流、读取超时是否太短。不同代理配置语法不同，应按其官方文档调整。
7. 编程代理专项¶
能对话但不会编辑文件¶
确认当前模式允许 Agent/工具调用，工作区已被信任，文件权限可写；同时验证服务支持工具调用协议。
命令执行反复失败¶
先让代理执行只读命令；检查 Shell、工作目录和审批策略。不要为了绕过失败直接关闭全部审批或给予不必要的系统权限。
上下文很快爆满¶
减少一次加载的目录；忽略构建产物与依赖目录；新开会话；把任务拆小；使用工具官方的上下文压缩功能。
8. 知识库 / RAG 专项¶
知识库通常至少涉及两条独立链路：
- Embedding 模型把文档转为向量；
- 聊天模型根据检索结果生成答案。
导入失败不一定是聊天模型问题。分别检查 Embedding Base URL、模型 ID、向量维度、分段大小和文件解析。更换 Embedding 模型后，旧知识库可能需要重新索引。
9. 安全地提供排错信息¶
向维护者求助时可以提供：
工具和版本：
系统：
配置类型：OpenAI Compatible / Anthropic Compatible
协议端点：Chat Completions / Responses / Messages
模型 ID：
时间（含时区）：
HTTP 状态码：
脱敏错误摘要：
是否流式：
最小请求能否复现：
必须删除或替换：
- 完整 API Key；
- Authorization、Cookie 等请求头；
- 私有域名、用户 ID、订单号；
- 文件正文、对话隐私和未经脱敏的日志；
- 任何内部路由或渠道信息。
10. 什么时候应该停止重试¶
- 401：先修复 Key，不要重试；
- 403：先确认权限，不要重试；
- 404：先修复路径或模型 ID，不要重试；
- 400/422：先修改请求参数，不要重试；
- 429：等待退避时间后有限重试；
- 5xx：保存请求 ID，间隔重试或切换已确认可用的模型。
11. 官方参考¶
仍然没有解决？回到教程总目录，按那篇教程的“日志与排错”章节检查工具特有配置。