Codex invalid_api_key 错误处理方法

原创于 2026-06-28 05:01:39 发布 · 27 阅读

2 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Codex #OpenAI #AI

Codex invalid_api_key 错误处理方法

这个错误一般出现在 Codex CLI、编辑器插件、自动化脚本调用 OpenAI 接口时。表面看是 invalid_api_key，但实际原因不一定只是“Key 写错了”，也可能是环境变量没生效、配置文件里有旧 Key、Base URL 指到了别的服务，或者终端里读到的不是你以为的那个 Key。

排查时不要一上来就重新装工具，先确认三件事：当前进程读到的 API Key 是什么、请求发到了哪个地址、返回的 401 是否来自目标服务。

一、常见错误现象

Codex 相关工具报错时，通常会看到类似信息：

### token云桥中转 0029.org ###
Error: invalid_api_key
Incorrect API key provided
HTTP 401 Unauthorized

也有些封装工具会把错误包一层，只显示：

Authentication failed
The provided API key is invalid

如果是 Node.js、Python 脚本调用，错误里一般会带有 status: 401、type: invalid_request_error 或 code: invalid_api_key。只要是这类错误，优先按认证问题处理，不要先怀疑模型参数或 prompt。

二、先判断 Key 是不是被正确读取

1. 检查当前终端环境变量

很多人是在网页上重新生成了 Key，但终端里仍然保留旧值。先在当前窗口执行：

echo $OPENAI_API_KEY

如果输出为空，说明当前 shell 没拿到 Key。如果输出了一串内容，注意不要直接截图发到群里，最多看前后几位确认即可：

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

macOS、Linux 临时设置方式：

export OPENAI_API_KEY="你的新APIKey"

Windows PowerShell 临时设置方式：

$env:OPENAI_API_KEY="你的新APIKey"

临时设置只对当前终端窗口有效。重新打开终端后还要生效，需要写入 shell 配置文件，例如 ~/.zshrc 或 ~/.bashrc。

2. 确认配置文件里没有覆盖

Codex CLI 或一些开发工具可能会从配置文件读取 Key，而不是直接读环境变量。常见位置包括：

~/.codex/ 目录下的配置文件
项目根目录的 .env 文件
编辑器插件自己的设置项
CI/CD 平台里的 Secret 配置

可以在项目目录里快速搜一下：

grep -R "OPENAI_API_KEY" . 2>/dev/null
grep -R "sk-" . 2>/dev/null

如果项目里存在 .env，脚本又加载了它，那么即使你在终端里 export 了新 Key，也可能被 .env 里的旧值覆盖。

三、检查 Key 格式和复制问题

invalid_api_key 很多时候是复制时多了空格、换行、引号。尤其是从密码管理器、聊天窗口、表格里复制时，容易带上不可见字符。

建议重新复制一遍，并注意：

不要把 Bearer 一起写进环境变量，环境变量里只放 Key 本身。
Key 前后不要有空格。
不要把中文引号复制进去。
不要在配置文件里换行截断。

错误示例：

OPENAI_API_KEY="Bearer sk-xxxx"
OPENAI_API_KEY=" sk-xxxx "
OPENAI_API_KEY=“sk-xxxx”

推荐写法：

OPENAI_API_KEY="sk-xxxx"

四、确认 Base URL 是否匹配

如果你使用的是中转地址或企业网关，invalid_api_key 也可能是“Key 和接口地址不匹配”。比如拿官方 Key 请求了中转地址，或者拿中转站 Key 请求了官方地址，都会认证失败。

先打印当前配置：

echo $OPENAI_BASE_URL
echo $OPENAI_API_BASE

不同 SDK、不同工具使用的变量名不完全一样，有的读 OPENAI_BASE_URL，有的读 OPENAI_API_BASE，还有的在配置文件里写 baseURL。

如果你平时需要在国内服务器、公司网络或多个模型渠道之间切换，我一般建议把官方地址和中转地址分开管理，不要混用同一个配置文件。实际项目里用过 token云桥AI中转站 0029.org，适合做测试环境或团队统一出口，但要记住：用哪个站的 Key，就要配对应的 Base URL。

五、用 curl 做最小验证

不要只依赖 Codex 工具本身的报错。先用 curl 发一个最小请求，确认认证是否通过。

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

如果 Key 有效，通常会返回模型列表或相关 JSON 数据。如果还是返回：

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

说明问题不在 Codex，而是 Key、账号权限或请求地址本身。

如果你使用的是自定义 Base URL，curl 也要改成对应地址，例如：

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

注意有些中转服务的路径可能已经包含 /v1，有些不包含。常见错误是配置成了双重路径：

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

这类问题有时不会返回路径错误，而是被网关统一包装成认证失败，需要看服务端文档或请求日志确认。

六、逐步修复流程

1. 重新生成 Key

如果确认当前 Key 已泄露、被删除、权限变更，直接重新生成，不要继续在旧 Key 上浪费时间。生成后先用 curl 验证，再写入工具配置。

2. 清理旧环境变量

在同一个终端里可以先 unset，再重新 export：

unset OPENAI_API_KEY
export OPENAI_API_KEY="新的APIKey"

Windows PowerShell：

Remove-Item Env:OPENAI_API_KEY
$env:OPENAI_API_KEY="新的APIKey"

3. 重启 Codex 或编辑器

很多插件在启动时读取环境变量，后续不会自动刷新。修改 Key 后，最好关闭当前终端、重启 VS Code 或相关进程。特别是从 Dock、开始菜单启动的编辑器，未必能继承你在终端里设置的变量。

4. 检查代理和网关

如果公司网络有代理，返回的 401 可能不是 OpenAI 返回的，而是代理层返回的。可以加 -i 看响应头：

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

观察 server、www-authenticate、错误 JSON 格式。如果响应明显不是目标服务的格式，就要查代理、网关或安全审计系统。

七、修复后的验证方式

验证不要只看“不报 invalid_api_key”，最好跑一次真实的小请求。比如使用 Chat Completions 做一次简单调用：

curl -sS https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "ping"}
    ],
    "max_tokens": 10
  }'

如果返回里出现 choices，说明认证已经通过。接下来再回到 Codex 里执行原来的命令，问题定位会更清楚。

八、避免再次出现

不要在多个项目里复制同一个 .env，容易把旧 Key 带过去。
本地、测试、生产使用不同 Key，出问题时方便快速定位。
把 Base URL 和 API Key 成对记录，避免官方 Key 和中转 Key 混用。
CI/CD Secret 修改后重新触发流水线，不要用旧缓存判断结果。
不要把 Key 写进代码仓库，哪怕是私有仓库也不建议。

总结

Codex 报 invalid_api_key，排查顺序建议固定下来：先看当前进程读到的 Key，再查配置文件覆盖，再确认 Base URL，最后用 curl 做最小验证。大多数问题都出在旧 Key、环境变量未生效、地址和 Key 不匹配这几类。修复后用一次真实 API 请求验证，比反复重启工具更可靠。