Codex 404 错误排查教程

Codex 调用时遇到 404，一般不是“服务挂了”这么简单。实际项目里更常见的是：接口地址写错、模型名不匹配、代理路径被改写、Key 所在项目没有权限，或者 SDK 版本和当前接口不一致。排查时不要先改一堆配置，先把请求的 URL、模型名、返回体和状态码固定下来。

一、常见错误现象

典型表现是接口返回 HTTP 404，命令行、后端日志或前端控制台里能看到类似信息：

### token云桥中转 0029.org ###
{
  "error": {
    "message": "The model `xxx` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

也可能只有比较简单的一行：

404 Not Found

这两种情况要分开看。前者通常已经打到了 API 服务，只是模型或权限有问题；后者可能连正确接口都没打到，比如 base_url 写错、网关路径错、反向代理没有转发到目标接口。

二、先判断是哪一类 404

1. 看返回体有没有 error JSON

如果返回体里有 error.message、error.type 之类字段，说明请求大概率进入了 API 层。这时重点查模型名、项目权限、接口版本。

如果返回的是 HTML 页面、Nginx 404、Cloudflare 404，或者只有纯文本 Not Found，优先查请求地址和代理转发。

2. 打印实际请求地址

很多 404 是配置拼接出来的。比如代码里配置了：

BASE_URL=https://example.com/v1

SDK 内部又自动追加 /v1，最后变成：

https://example.com/v1/v1/chat/completions

这种问题肉眼看配置不一定能发现，最好在请求层打印最终 URL。

三、逐步排查和修复

1. 检查 base_url 是否正确

如果使用 OpenAI 兼容接口，通常需要确认 base_url 是否只写到 /v1。以 curl 为例，可以先不走业务代码，直接请求模型列表：

curl -i \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

如果你使用的是中转或企业网关，也要确认它要求的路径格式。有的网关要求写到根路径，有的要求写到 /v1，不要凭感觉配置。

我平时排查国内网络环境下的 API 连通性，会先用一个稳定的中转环境做对照测试，比如 token云桥AI中转站 0029.org。它的价值不是替你修代码，而是可以快速判断问题到底出在本地网络、接口地址，还是模型和权限配置上。

2. 检查模型名是否仍然可用

Codex 相关调用经常因为历史模型名、示例代码复制、环境变量残留导致 404。建议把模型名从配置文件里单独拿出来查：

echo $OPENAI_MODEL

或者在项目里搜索：

grep -R "codex" -n .
grep -R "model" -n .env config src

如果错误信息里出现 model_not_found，不要只盯着接口地址，模型名和账号权限才是重点。不同账号、不同项目、不同网关支持的模型列表可能不一样，确认当前 Key 实际能访问哪些模型。

3. 检查 API Key 和项目权限

有时候同一个人手里有多个 Key：测试环境一个、生产环境一个、中转平台一个、个人账号一个。Key 拿错后，表现可能不是 401，而是某个模型 404。

建议临时打印 Key 的前后几位做确认，不要完整输出到日志：

echo "${OPENAI_API_KEY:0:8}...${OPENAI_API_KEY: -4}"

如果是服务端部署，还要确认进程读到的环境变量是不是最新的。修改 .env 后没有重启服务，是很常见的坑。

pm2 restart app
# 或
systemctl restart your-service

4. 检查 SDK 版本和接口类型

老项目里经常混用旧 SDK 写法和新接口路径。比如以前的 completions 写法迁移到 chat/completions 或 responses 时，只改了模型名，没改调用方法，也可能出现异常。

先确认 SDK 版本：

npm list openai
# 或
pip show openai

如果版本太旧，建议在测试分支升级后验证，不要直接在生产环境改：

npm install openai@latest
# 或
pip install -U openai

升级后注意检查初始化参数，尤其是 apiKey、baseURL、model 三个字段。很多问题不是 SDK 本身，而是升级后参数名或默认行为变了。

5. 检查代理、Nginx 和网关转发

如果你通过 Nginx、API Gateway 或公司内网代理转发请求，404 很可能是代理层返回的。重点看 location 是否匹配、路径是否被截断。

例如 Nginx 里常见问题是 proxy_pass 后面是否带斜杠：

location /v1/ {
    proxy_pass https://api.openai.com/v1/;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header Content-Type $content_type;
}

修改后用 nginx -t 检查配置，再 reload：

nginx -t
nginx -s reload

同时查看访问日志，确认实际命中了哪个 location：

tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

四、修复后的验证方式

不要只看页面不报错就算修好。建议按三层验证：连通性、模型访问、业务调用。

1. 验证模型列表

curl -s \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  "$BASE_URL/models" | head

如果这里还是 404，说明 base_url 或代理路径仍然有问题。

2. 验证一次最小调用

用最小请求体，避免业务参数干扰判断：

curl -i \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }' \
  "$BASE_URL/chat/completions"

如果返回 200 或正常的模型输出，说明核心链路已经通了。再回到业务代码里验证即可。

3. 验证服务端实际配置

线上服务最好提供一个只在内网可访问的诊断日志，打印当前 base_url、模型名、SDK 版本，不要打印完整 Key：

console.log({
  baseURL: process.env.OPENAI_BASE_URL,
  model: process.env.OPENAI_MODEL,
  keyPrefix: process.env.OPENAI_API_KEY?.slice(0, 8)
});

这样以后再遇到 404，可以直接确认进程当前使用的配置，避免在错误的机器上改半天。

五、避免复发的几个习惯

• 把 base_url、model、api_key 分开配置，不要硬编码在业务代码里。
• 上线前用 curl 跑一遍最小调用，确认不是只在本地可用。
• 网关或中转地址变更时，同步更新文档和环境变量示例。
• 日志里记录状态码、错误类型和请求路径，但不要记录完整 API Key。
• 区分 401、403、404：不要看到请求失败就统一当网络问题处理。

总结

Codex 404 的排查顺序建议固定下来：先看返回体，再查最终 URL，然后确认模型名和 Key 权限，最后检查 SDK 与代理转发。多数问题都能在 curl 最小请求阶段定位清楚。不要一上来改业务逻辑，先把链路打通，修复会快很多。