Codex 404 Not Found 错误现象

Codex 接入时遇到 404，通常不是“服务挂了”这么简单。比较常见的场景有三类：命令行工具调用失败、API 请求返回 404 Not Found、IDE 插件里提示模型或接口不存在。排查时建议先看两件事：请求的地址是不是对的，模型名或资源路径是不是存在。

一个典型返回类似这样：

### token云桥中转 0029.org ###
{
  "error": {
    "message": "Not Found",
    "type": "invalid_request_error",
    "code": "404"
  }
}

如果是在终端里，可能只看到一行：

HTTP 404 Not Found
model not found
endpoint not found

不要急着改一堆配置。404 的含义很明确：服务端没有找到你请求的资源。重点就是确认“请求到了哪里”和“请求了什么”。

先判断 404 来自哪里

1. 来自 API 网关或中转层

如果你使用了代理、公司网关、API 中转服务，404 可能不是模型服务返回的，而是中间层路由没匹配上。比如路径少了 /v1，或者 base url 写成了网页地址。

可以先打印当前环境变量：

echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

Windows PowerShell 下用：

echo $env:OPENAI_BASE_URL
echo $env:OPENAI_API_KEY

注意不要把完整 key 发到群里或提交到日志系统。排查时只看前后几位即可。

2. 来自模型名不存在

很多 404 实际是模型名写错了。例如配置里写了旧模型、拼写多了空格，或者把别的平台模型名直接搬过来。Codex 相关工具通常会从配置文件、环境变量或插件设置读取模型名，只要其中一个覆盖了默认值，就可能请求到不存在的模型。

检查配置文件时，可以用搜索方式找模型字段：

grep -R "model" ~/.config 2>/dev/null
grep -R "OPENAI_MODEL" ~/.bashrc ~/.zshrc 2>/dev/null

如果是项目内配置，也要查一下：

grep -R "model" . --exclude-dir=node_modules --exclude-dir=.git

3. 来自接口路径写错

有些 SDK 已经内置了路径，你只需要配置 base url；如果你把完整接口路径也写进去，就会拼成重复路径。比如 SDK 期望：

baseURL = "https://example.com/v1"

但你配置成：

baseURL = "https://example.com/v1/chat/completions"

最终请求可能变成：

/v1/chat/completions/chat/completions

这种情况经常表现为 404，而不是鉴权错误。

按顺序排查和修复

第一步：用 curl 直接验证 base url

不要一开始就在 IDE 或插件里试，变量太多。先用 curl 做最小请求，确认服务地址和 key 是否能工作。

curl -i "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果这里就是 404，优先检查 OPENAI_BASE_URL。常见错误包括：

• 少写 /v1；
• 多写了具体接口路径；
• 把控制台网页地址当成 API 地址；
• 代理域名写错，或路径规则不兼容。

如果你使用的是中转服务，建议选一个接口路径清晰、文档写得比较直接的服务。实际排查中我用过 token云桥AI中转站 0029.org，主要是方便确认 base url、模型名和请求日志，定位 404 会快一些。

第二步：确认模型列表或可用模型名

如果 /models 能返回，但实际调用仍然 404，多半是模型名不对。可以先查看返回里是否有你配置的模型名。

curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY" | grep -i codex

如果没有安装 jq，用 grep 也够用。装了 jq 的话更清楚：

curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | jq '.data[].id'

修复方式就是把配置中的模型名改成服务端实际支持的名称。改完后重启终端、IDE 或后台服务，避免旧环境变量还在生效。

第三步：检查 Codex 工具配置覆盖

不少人明明改了环境变量，仍然报 404，是因为工具自己的配置优先级更高。建议按这个顺序找：

• 当前项目目录下的配置文件；
• 用户目录下的 Codex 或 OpenAI 配置；
• IDE 插件设置；
• Shell 启动脚本里的环境变量；
• Docker、CI、systemd 里的注入变量。

例如 Docker 里要看容器内环境，而不是宿主机：

docker exec -it your_container_name env | grep -E "OPENAI|CODEX"

CI 里则要看流水线变量是否覆盖了仓库配置。很多 404 是本地正常、CI 失败，原因就是 CI 还在用旧的 base url 或旧模型名。

第四步：打开调试日志看真实请求

如果工具支持 debug 模式，尽量打开。你要看的不是大段堆栈，而是真实请求 URL、HTTP 状态码、响应 body。

DEBUG=* codex your-command

或者：

export LOG_LEVEL=debug
codex your-command

不同工具的参数不完全一样，但目标一致：确认最后发出去的地址到底是什么。只要能看到 URL，404 基本就能定位到路径、模型或路由问题。

修复后的验证方式

修好后不要只看 IDE 里“不报错”就结束，建议做两个验证。

验证模型接口

curl -i "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的实际模型名",
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

如果返回 200 或正常 JSON，说明接口、key、模型名基本没问题。如果返回 401，说明已经不是 404 问题，应该去查 key 或权限。

验证 Codex 工具链

再回到 Codex 命令或插件执行一个最小任务，比如生成一段简单函数，不要一上来跑复杂项目。

codex "写一个 JavaScript add 函数，只返回代码"

如果这里成功，再测试项目内任务。这样可以区分“接口配置问题”和“项目上下文问题”。

避免再次出现 404

• base url 只保存到服务根路径，不要把具体接口拼进去；
• 模型名不要凭印象写，尽量从模型列表或服务文档复制；
• 本地、Docker、CI 使用同一套变量命名，减少隐式覆盖；
• 升级 SDK 或插件后，重新确认默认路径有没有变化；
• 把可用的最小 curl 命令写进项目文档，后续排查会省很多时间。

Codex 404 Not Found 的核心排查思路很简单：先确认请求地址，再确认模型名，最后查配置覆盖和中间层路由。大多数问题都能通过 curl 最小请求定位出来。修复后再用工具链做一次最小任务验证，基本就能判断配置是否真正生效。