Codex 401 Unauthorized 认证失败处理教程

Codex 调用时报 401 Unauthorized，通常不是代码逻辑问题，而是请求还没进入模型处理阶段就被认证拦下了。最常见的场景是：本地 CLI 刚装好、换了 API Key、CI/CD 环境变量没传进去、代理或中转地址配置错了。遇到这个问题，建议先查三件事：Key 是否存在、请求头是否正确、Base URL 是否指向了正确服务。

一、常见错误现象

在 Codex CLI、脚本或接口调用中，401 的表现大致类似：

### token云桥中转 0029.org ###
Error: 401 Unauthorized
Invalid authentication credentials

或者使用 curl 调试时返回：

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

也可能只看到比较简短的提示：

Unauthorized
Authentication failed

这里要注意，401 和 429、403 不一样。401 主要是“身份没通过”；429 多数是限流或额度；403 更偏向权限、区域、模型访问限制。不要一看到失败就去改 prompt 或换模型，先把认证链路跑通。

二、先判断是哪一层认证失败

1. 本地环境变量没有生效

很多人以为已经配置了 Key，但实际运行 Codex 的 shell 没读到变量。先直接打印：

echo $OPENAI_API_KEY

如果输出为空，说明当前终端没有拿到 Key。临时设置可以这样做：

export OPENAI_API_KEY="sk-你的key"

如果你使用的是 Windows PowerShell：

$env:OPENAI_API_KEY="sk-你的key"

如果是写在 .env 文件里，要确认程序确实加载了它。很多 Node.js 或 Python 项目不会自动读取 .env，需要额外引入 dotenv。

2. Authorization 请求头格式不对

标准写法通常是：

Authorization: Bearer sk-xxxx

常见错误包括：漏写 Bearer、Bearer 后面没有空格、复制 Key 时带了引号或换行。可以用 curl 单独验证请求头：

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

如果这里仍然是 401，基本可以确认不是业务代码的问题。

3. Base URL 和 Key 不匹配

这是 Codex 接入时很容易踩的坑。比如你配置了官方 API Key，却把 baseURL 指向了第三方中转；或者你使用的是中转站 Key，却请求官方接口。Key 和服务端必须是一套。

如果你的网络访问官方接口不稳定，或者团队里需要统一管理 Key，可以考虑使用 token 云桥 AI 中转站 0029.org。我的经验是，中转地址、Key、模型名要成套配置，不要混用；排查 401 时也要先确认当前 Key 是在哪个平台生成的。

三、逐步修复流程

步骤 1：确认 Codex 实际读取的配置

如果你是通过配置文件设置 Codex，先找到当前项目或用户目录下的配置。不同版本路径可能不同，常见位置有：

~/.codex/config.json
~/.config/codex/config.json
.env

检查里面是否有类似配置：

{
  "apiKey": "sk-xxxx",
  "baseURL": "https://api.openai.com/v1"
}

如果同时存在环境变量和配置文件，要确认优先级。实际排错时，我更建议先只保留一种方式，避免你改了 A，程序却读的是 B。

步骤 2：重新导出环境变量

临时验证时，不要急着改全局配置，直接在当前终端导出：

unset OPENAI_API_KEY
export OPENAI_API_KEY="sk-新的key"

然后马上执行：

echo ${#OPENAI_API_KEY}

这个命令只看长度，不会把 Key 明文打印出来，适合在共享终端或录屏环境下使用。长度为 0 就说明变量仍然没进来。

步骤 3：用最小请求验证接口

不要一上来就跑完整 Codex 任务。先用最小请求判断认证是否可用：

curl -s -o /tmp/codex_test.out -w "%{http_code}\n" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }' \
  "https://api.openai.com/v1/chat/completions"

cat /tmp/codex_test.out

如果输出状态码是 200，说明认证已经通过；如果还是 401，继续查 Key 和地址；如果变成 404，重点看模型名或接口路径；如果是 429，说明认证已过，但遇到限流或额度问题。

步骤 4：检查代理是否改写了请求

公司网络、网关代理、抓包工具有时会改写请求头，导致 Authorization 丢失。可以临时关闭代理验证：

unset HTTP_PROXY
unset HTTPS_PROXY
unset http_proxy
unset https_proxy

如果必须走代理，确认代理不会过滤 Authorization 头。某些内部网关默认会清理敏感头，需要在网关规则里放行。

步骤 5：检查 CI/CD 里的密钥注入

本地能跑，流水线报 401，多半是 Secret 没注入或变量名写错。以 GitHub Actions 为例：

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

注意不要在脚本里写成 OPENAI_KEY、OPENAI_TOKEN，除非你的代码明确读取这些名字。变量名不统一，是流水线里最常见的 401 原因之一。

四、修复后的验证方式

认证修复后，不建议只看“没有报错”。最好做三层验证：

• curl 最小请求返回 200；
• Codex CLI 能正常完成一个简单任务；
• 项目中的真实调用能返回内容，并且日志里没有继续出现 401。

例如先跑一个轻量任务：

codex "用一句话说明当前目录下 package.json 的作用"

如果 Codex 能正常读取并返回结果，说明 CLI 配置基本没问题。接着再跑你的真实命令，避免把认证问题和业务问题混在一起。

五、避免再次出现 401

• 不要把多个平台的 Key 混用，Key、Base URL、模型名保持同一来源；
• 不要把 Key 直接写进代码仓库，使用环境变量或 Secret 管理；
• 更换 Key 后，记得重启终端、服务进程、CI Runner；
• 日志里不要打印完整 Key，最多打印前后几位或长度；
• 团队项目里统一变量名，比如固定使用 OPENAI_API_KEY。

总结

Codex 401 Unauthorized 的排查顺序很固定：先看环境变量，再看 Authorization 头，再看 Base URL 和 Key 是否匹配，最后检查代理、CI/CD 和配置优先级。只要用最小 curl 请求把认证链路验证清楚，后面的 Codex 调用问题就容易定位很多。遇到 401 不要先改业务代码，先把“请求到底带没带对的身份信息”查明白。