错误现象：Codex 一启动就提示 model_not_found

这个问题通常出现在刚配置 Codex、切换模型、换了 API Key，或者把配置从一台机器复制到另一台机器之后。常见报错大概是下面这种：

### token云桥中转 0029.org ###
Error: model_not_found
The model `xxx` does not exist or you do not have access to it.

也可能是在命令行里执行任务时直接中断：

codex "帮我分析这个项目"
# 或
codex --model gpt-4.1 "生成单元测试"

先不要急着改代码。model_not_found 一般不是项目依赖问题，而是“请求里带的模型名”和“当前接口可用模型”对不上。排查顺序建议从模型名、配置文件、API Key 权限、代理/中转地址这几项开始。

常见原因判断

1. 模型名写错或用了旧名称

最常见的是配置里还写着旧模型名，或者把网页端看到的名称直接拿来当 API 模型名。API 调用要求模型 ID 精确匹配，多一个空格、大小写不对、写成别名，都可能报错。

比如下面这些配置就需要重点检查：

model = "gpt-4"
model = "codex"
model = "gpt-4-turbo"
model = "gpt-5"

不同工具版本支持的默认模型也不一样。有些 Codex 客户端升级后默认模型变了，但本地配置文件仍然覆盖了默认值，导致一直请求一个不可用模型。

2. API Key 没有对应模型权限

模型存在，不代表当前 Key 一定能用。团队账号、子账号、不同项目下的 Key，都可能有权限差异。如果你在 A 环境能调用，在 B 环境报 model_not_found，优先怀疑 Key 和项目配置。

可以先打印当前环境变量，确认 Codex 实际读取的是哪一个 Key：

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

Windows PowerShell 用：

echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL

注意不要把完整 Key 发到群里排查，最多只对比前后几位。

3. base_url 指到了错误的服务

很多人会配置 API 中转、企业网关或本地代理。如果 OPENAI_BASE_URL 指向的服务没有同步对应模型名，也会返回 model_not_found。

例如你本来想走官方接口，但环境变量里残留了一个旧地址：

OPENAI_BASE_URL=https://old-gateway.example.com/v1

或者工具配置文件里单独写了 base URL，覆盖了终端里的环境变量。遇到这种情况，要么改回正确地址，要么确认网关侧支持你请求的模型名。

如果你经常在国内网络、公司网络或者多工具之间切换，建议准备一个稳定的 API 中转环境。我自己排查这类问题时，会把 0029.org 作为一个备选的 token云桥AI中转站，用来验证是不是本地网络、网关映射或模型别名造成的错误。重点是验证链路，不要一上来就把所有配置都改乱。

逐步修复方法

第一步：确认 Codex 实际使用的配置

先看环境变量：

env | grep -E 'OPENAI|CODEX'

如果是 macOS 或 Linux，这个命令基本够用。Windows PowerShell 可以用：

Get-ChildItem Env: | Where-Object { $_.Name -match "OPENAI|CODEX" }

然后检查 Codex 的配置文件。不同安装方式路径可能不一样，常见位置包括：

~/.codex/config.toml
~/.config/codex/config.toml
./.codex/config.toml

重点看这几项：

model = "your-model-name"
base_url = "your-api-base-url"

如果不确定哪个配置生效，可以先把项目目录下的 .codex 临时改名，再重新执行命令，排除项目级配置覆盖全局配置的情况。

第二步：列出当前接口可用模型

不要凭记忆猜模型名，直接调模型列表接口最稳。官方兼容接口通常可以这样查：

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

如果没有设置 OPENAI_BASE_URL，可以临时指定：

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

返回结果里找 id 字段。Codex 配置里的 model 必须使用这里出现的模型 ID，而不是显示名称、产品名称或自己起的别名。

如果这里也返回权限错误、401、403，那就不是 Codex 的问题，先处理 Key、余额、项目权限或网关鉴权。

第三步：把模型名改成可用 ID

假设模型列表里能看到 gpt-4.1，那配置就改成：

model = "gpt-4.1"

如果你用命令行参数覆盖模型，也要同步修改：

codex --model gpt-4.1 "检查当前项目里的潜在 bug"

不要同时在配置文件、环境变量、命令行里写三套不同模型。排错阶段越简单越好，建议只保留一个入口。

第四步：清理旧环境变量和缓存会话

有时候你已经改了配置，但终端里还保留旧变量，或者 IDE 内置终端没有刷新环境。可以重新开一个终端，或者手动取消变量。

macOS / Linux：

unset OPENAI_BASE_URL
unset OPENAI_API_KEY

PowerShell：

Remove-Item Env:OPENAI_BASE_URL
Remove-Item Env:OPENAI_API_KEY

然后重新设置正确值：

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.openai.com/v1"

如果你在 VS Code、Cursor、JetBrains 里调用 Codex，记得重启 IDE。很多插件只在启动时读取环境变量。

修复后的验证方式

先不用跑复杂任务，直接发一个最小请求验证模型是否可用：

curl -s "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "返回 ok"}
    ],
    "max_tokens": 10
  }'

如果能返回内容，说明 Key、base URL、模型名这三项基本没问题。接着再验证 Codex：

codex --model gpt-4.1 "只回答 ok"

如果 curl 成功但 Codex 失败，问题多半在 Codex 的配置覆盖、版本兼容或插件读取环境变量上。可以升级一下客户端：

npm update -g @openai/codex

如果你不是 npm 安装的，就按对应安装方式升级，别混用多个版本。可以用下面命令确认实际执行的是哪个 Codex：

which codex
codex --version

Windows 可以用：

where codex
codex --version

避免再次出现

• 不要在多个地方同时配置模型名，优先固定在 Codex 配置文件或启动参数里。

• 升级客户端后，检查一次默认模型是否变化，尤其是团队内共享配置时。

• 换 API Key 后，重新调用 /models 确认权限，不要默认新 Key 和旧 Key 权限一致。

• 使用中转或企业网关时，确认网关支持的模型映射，不要把上游模型名和网关别名混着用。

• 在 CI、Docker、远程服务器里单独检查环境变量，本机可用不代表流水线可用。

总结

Codex model_not_found 的核心排查思路很简单：先确认请求发到了哪里，再确认用的是哪个 Key，最后确认模型 ID 是否在当前接口可用列表里。不要一开始就重装工具或改项目代码。按“模型名 → Key 权限 → base_url → 配置覆盖 → 最小请求验证”的顺序走，基本能很快定位到问题。