模型接口 401、404、超时怎么判断
模型接入失败时，最容易出现的一种混乱是：
只要调不通就统称为“模型报错”但 401、404、timeout 这三类问题，其实根本不是同一层。
如果你分不清，排查就会越来越乱。
前置教程：国内模型配置排障总表
如果你还没有建立 API Key、Base URL、model、额度、网络这条基本排查顺序，先完成前置教程。
依据来源：OpenAI Codex 官方手册中关于 custom model providers、authentication、environment variables、network access、timeout 配置、troubleshooting 的说明，以及各类 OpenAI 兼容模型服务的常见错误分层。
学完后，你应该能做到：
- 一眼区分
401、404、timeout分别优先查什么。 - 不再把认证错误和网络错误混在一起。
- 知道什么时候该查 API Key。
- 知道什么时候该查 Base URL 或 model。
- 知道什么时候该查网络、代理和服务商状态。
先记住这个最重要的对照表
Section titled “先记住这个最重要的对照表”401 -> 优先看认证404 -> 优先看地址或模型标识timeout -> 优先看网络、代理、超时配置或服务商响应你只要先把这条记住，排障方向就不会一开始就跑偏。
一、401 是什么问题
Section titled “一、401 是什么问题”401 最常见的意思是：
你访问到了服务但服务不认你的身份所以 401 不是“连不上”，而是“连上了，但认证没通过”。
401 优先排查什么
Section titled “401 优先排查什么”优先查下面几项：
- API Key 是否正确。
- API Key 是否已经失效、删除或过期。
- 是否把别的 token 当成 API Key。
- 环境变量名是否写错。
- provider 配置读到的认证方式是否和你预期一致。
如果你用的是自定义 provider，官方手册里也明确写了，认证方式可能来自：
requires_openai_auth = trueenv_key = "..."- 或 provider 的自定义认证配置
所以 401 时要先确认“Codex 到底在用哪种认证方式”。
401 不要优先查什么
Section titled “401 不要优先查什么”下面这些不是第一优先级：
- 换模型
- 重装 Codex
- 重建项目
- 修改大量配置
因为 401 的核心不是“模型不对”，而是“身份没过”。
二、404 是什么问题
Section titled “二、404 是什么问题”404 最常见的意思是：
你请求的地址或目标资源不存在在模型配置里，最常见的两类 404 是：
Base URL写错了model写错了
404 最常见的错误写法
Section titled “404 最常见的错误写法”1. 把完整接口路径写进 Base URL
Section titled “1. 把完整接口路径写进 Base URL”例如本来应该填：
https://api.example.com/v1结果写成了：
https://api.example.com/v1/chat/completions这样很多工具层会再自己拼接路径，最后就变成错误地址。
2. model 名写错
Section titled “2. model 名写错”例如：
- 用了过期模型名
- 少了前缀
- 服务商需要接入点 ID，但你填成了产品名
- 把教程里的示例模型名原样拿来用，但当前账号根本没有
404 优先排查什么
Section titled “404 优先排查什么”- Base URL 是否只写到 provider 基础路径。
- 是否多写了
/chat/completions之类的完整接口路径。 - model 是否来自当前服务商官方控制台或官方文档。
- 当前账号是否真的有这个模型或接入点。
三、timeout 是什么问题
Section titled “三、timeout 是什么问题”timeout 通常不是认证问题，也不优先代表 model 名错误。
它更像是：
请求发出去了但在预期时间内没有拿到正常响应所以 timeout 更应该先查：
- 当前网络是否稳定。
- 是否存在代理、公司网络、TLS 证书问题。
- 服务商是否暂时响应慢。
- 当前超时配置是否太短。
官方手册里也提到，Codex 的 provider 或相关工具配置里存在 timeout / timeout_ms 一类超时参数。
所以 timeout 不一定是服务商挂了，也可能是你本地等待时间太短。
timeout 最常见的触发场景
Section titled “timeout 最常见的触发场景”1. 公司网络或代理环境
Section titled “1. 公司网络或代理环境”常见表现：
- 浏览器能开网页
- 但 CLI 请求不稳定
- 偶发超时
2. 国内外链路不稳定
Section titled “2. 国内外链路不稳定”尤其是跨地域或特定服务商节点时，更容易偶发超时。
3. 服务商本身响应慢
Section titled “3. 服务商本身响应慢”这类常见于：
- 高峰时段
- 大模型推理繁忙
- 某个地域节点不稳定
4. 超时设置太保守
Section titled “4. 超时设置太保守”如果等待时间设得很短，复杂请求也容易被判成超时。
一张最实用的判断表
Section titled “一张最实用的判断表”| 错误 | 第一优先级 | 第二优先级 | 不要先做什么 |
|---|---|---|---|
| 401 | API Key / 认证方式 | 环境变量 | 不要先换模型 |
| 404 | Base URL / model | 账号权限 | 不要先重装 |
| timeout | 网络 / 代理 / 超时设置 | 服务商状态 | 不要先改一堆认证配置 |
一段可直接发给 Codex 的排障提示词
Section titled “一段可直接发给 Codex 的排障提示词”我现在接模型时报错了，请帮我做只读排障。
错误现象：【把 401 / 404 / timeout 或相关报错粘过来，但不要贴真实密钥】
要求：1. 先判断这更像认证问题、地址/model 问题，还是网络/超时问题。2. 不要修改文件。3. 不要让我贴出真实 API Key。4. 请按优先级列出排查顺序。5. 如果怀疑是 Base URL 或 model，请明确告诉我该核对哪一项。6. 如果怀疑是网络或超时，请明确告诉我不要先去改认证配置。排障时最容易犯的错
Section titled “排障时最容易犯的错”1. 一看到 401 就去改 Base URL
Section titled “1. 一看到 401 就去改 Base URL”方向错了。
2. 一看到 404 就以为账号没余额
Section titled “2. 一看到 404 就以为账号没余额”不一定，很多时候就是地址或 model 写错。
3. 一看到 timeout 就去重新生成 API Key
Section titled “3. 一看到 timeout 就去重新生成 API Key”大概率不是第一优先级。
4. 三种错误混着试
Section titled “4. 三种错误混着试”比如同时改 Key、改 URL、改模型、换服务商，最后自己都不知道到底是哪一步解决的。
正确做法永远是：
一次只验证一个怀疑点如果是 OpenAI 兼容 provider，要特别注意什么
Section titled “如果是 OpenAI 兼容 provider，要特别注意什么”官方手册里提到，自定义 provider 的关键组成包括：
- base URL
- wire API
- authentication
- headers
所以你在排查时，不能只盯着 model。
尤其是你接国内模型服务商时，很多问题其实卡在：
- provider 配置结构
- env_key 指向的环境变量
- base_url 拼错
- 自定义 header 或认证方式不匹配
做到这里，如果你已经形成下面这些判断习惯，就说明本篇起作用了：
401先查认证。404先查地址或 model。timeout先查网络、代理、超时设置。- 不会再把这三类错误混成“模型不行”。
- 一次只验证一个怀疑点，不会同时乱改一堆配置。
这三篇排障主线写完后，下一波我建议继续补：
Codex 无法读取项目怎么判断端口被占用怎么处理中文路径和空格路径怎么排查