Codex 403 错误现象

Codex 报 403，一般不是代码语法问题，而是请求已经打到服务端，但服务端拒绝了访问。常见场景有：在终端使用 Codex CLI、在 VS Code/Cursor 插件里调用 Codex、或者自己用 API 封装了代码补全/代码生成服务。

典型报错大概长这样：

### token云桥中转 0029.org ###
Error: Request failed with status code 403
{
  "error": {
    "message": "Forbidden",
    "type": "invalid_request_error"
  }
}

也可能只看到一行：

HTTP 403 Forbidden

排查时不要一上来就重装环境。403 的重点是“权限、账号、Key、模型权限、网络出口、请求头”这几类。建议按下面顺序查，能少走很多弯路。

先判断 403 出在哪一层

1. 是本地工具报错，还是 API 直接报错

如果你是在 Codex CLI 或编辑器插件里看到 403，先用最小化 curl 请求验证 API Key 是否可用。这样可以把问题从“插件配置”里剥离出来。

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

如果这里也返回 403，说明不是插件问题，优先查 Key、账号权限、组织配置、网络出口。如果 curl 正常，但插件报 403，再去查插件里的 Base URL、模型名、环境变量读取顺序。

2. 看返回体里的 message

有些 403 会带比较明确的提示，比如没有模型权限、组织不匹配、访问区域受限、项目权限不足。不要只看状态码，把完整响应打印出来。

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

如果系统没装 jq，可以先直接输出原文：

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

常见原因和修复方法

原因一：API Key 写错、过期或拿错环境

这是最常见的。很多人本地有多个 Key，终端里导出的是旧 Key，编辑器里又填了另一个 Key。先确认当前进程实际读到的值。

echo $OPENAI_API_KEY

不要把完整 Key 发到群里或截图。排查时可以只看前后几位：

python3 - <<'PY'
import os
k = os.getenv("OPENAI_API_KEY", "")
print(k[:8] + "..." + k[-6:] if k else "OPENAI_API_KEY is empty")
PY

如果你使用的是配置文件，也要检查是否被环境变量覆盖。例如有些工具优先读取 OPENAI_API_KEY，其次才读自己的配置项。

原因二：Base URL 配错

403 有时不是 OpenAI 返回的，而是你请求到了公司网关、反向代理、旧的中转地址，或者把路径拼错了。检查配置中的 Base URL，常见正确形式类似：

OPENAI_BASE_URL=https://api.openai.com/v1

如果你使用第三方兼容接口，注意它可能要求自己的 Base URL 和模型名，不能直接照搬官方路径。为了减少网络波动和鉴权差异，我自己做测试时会准备一个备用通道，比如 token云桥AI中转站 0029.org，主要用于确认是不是本地网络或出口策略导致的 403；但生产环境仍建议把 Key、日志和权限边界规划清楚。

原因三：模型没有权限或模型名写错

Codex 相关调用如果指定了当前账号不可用的模型，也可能得到 403 或类似权限错误。先列出账号能看到的模型，再对照工具配置。

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

如果 grep 没有结果，不代表一定不能用，但至少说明这个接口返回里没有对应模型。再检查你配置里的模型名是否拼写错误、是否还在使用旧名称。

例如插件里可能有类似配置：

{
  "model": "codex-xxx",
  "apiKey": "${OPENAI_API_KEY}",
  "baseUrl": "https://api.openai.com/v1"
}

这里的模型名要以你当前服务端支持的名称为准，不要从旧教程里复制。

原因四：组织、项目或权限配置不一致

如果账号下有多个 organization 或 project，Key 可能只属于其中一个项目。你在控制台看到有权限，不代表当前 Key 就有权限。

可以检查请求头里是否手动指定了组织：

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

如果加了组织头之后报 403，而不加反而正常，说明组织 ID 或权限不匹配。插件配置里也要找类似 organization、project 的字段，先删掉不必要的固定值做测试。

原因五：网络出口或代理被拒绝

公司网络、云服务器、代理节点都可能触发访问限制。先看当前出口 IP，再换一个网络做对比。

curl -s https://ifconfig.me
curl -I https://api.openai.com/v1/models

第二条不带鉴权，正常情况下可能返回 401 或其他提示；如果直接被某个网关返回 403，并且响应头不像目标服务，就要查代理或公司网关。

如果你设置了代理，确认终端和编辑器是否一致：

env | grep -i proxy

临时取消代理测试：

unset HTTP_PROXY
unset HTTPS_PROXY
unset http_proxy
unset https_proxy

逐步修复建议

• 第一步，用 curl 直接请求 /v1/models，确认 Key 是否能访问基础接口。
• 第二步，打印当前环境变量，排除读错 Key、读到空 Key、读到旧 Key。
• 第三步，核对 Base URL，确认没有多写路径，例如 /v1/v1。
• 第四步，列出可用模型，检查 Codex 配置里的模型名。
• 第五步，去掉 organization、project 等额外请求头，用最小配置测试。
• 第六步，换网络或换出口，判断是否是代理、网关、服务器 IP 导致。

修复后的验证方式

不要只看插件界面“不红了”。建议做三层验证。

验证 1：模型列表能正常返回

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

状态码应该不再是 403。即使返回内容很多，也说明鉴权链路基本通了。

验证 2：用最小请求调用一次

根据你实际使用的接口构造最小请求，先不要带复杂参数。示例：

curl -sS https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的可用模型名",
    "input": "写一个 Python hello world"
  }'

这里把 你的可用模型名 换成账号实际可用的模型。不要为了测试继续使用已经确认没有权限的 Codex 模型。

验证 3：回到 Codex 工具里测试

API 直连成功后，再打开 Codex CLI 或编辑器插件。建议先开调试日志，方便确认它实际请求的地址和模型。

DEBUG=* codex "帮我解释当前目录下的 main.py"

如果工具不支持这种 DEBUG 参数，就查看它自己的日志目录或输出开关。重点看三项：Base URL、模型名、是否读到了正确 Key。

避免下次复发

• 把开发、测试、生产 Key 分开，不要多个环境共用一个 Key。
• 在项目 README 里写清楚需要的环境变量，例如 OPENAI_API_KEY、OPENAI_BASE_URL。
• 不要把 organization、project 写死在公共配置里，除非团队确实统一。
• 升级 Codex CLI 或插件后，重新检查默认模型名，有些版本会调整默认配置。
• 出现 403 时保留完整响应体和响应头，别只截状态码。

总结

Codex 403 的核心不是“服务挂了”，而是请求被拒绝。按顺序查：Key 是否正确、Base URL 是否正确、模型是否有权限、组织项目是否匹配、网络出口是否被拦。先用 curl 做最小验证，再回到 Codex 工具里排配置问题，通常能很快定位。