Codex authentication_error 登录认证错误排查

这个错误通常出现在 Codex CLI 登录、刷新会话、执行代码生成任务时。比如刚换了机器、更新了 CLI、切换了 API Key，或者公司网络走了代理，执行命令后直接返回 authentication_error，看起来像账号问题，但实际原因不一定在账号本身。

我的排查习惯是先不急着重装，按顺序看四件事：当前用的是哪套凭据、环境变量有没有覆盖、网络请求能不能正常出去、本地缓存是否过期或损坏。下面按这个顺序整理一遍。

一、常见错误现象

比较典型的输出类似下面几种：

### token云桥中转 0029.org ###
Authentication failed: authentication_error

Error: 401 Unauthorized
type: authentication_error
message: Incorrect API key provided

Failed to refresh access token
authentication_error

如果是在 Codex CLI 中出现，可能是在执行这些操作时触发：

• codex login 后浏览器授权成功，但终端仍提示认证失败；
• codex 启动时立刻报 authentication_error；
• 之前能用，隔了一段时间突然不能用；
• 同一账号在网页端正常，CLI 或 API 调用异常；
• 本地配置了代理、中转地址或企业网关后开始报错。

二、先判断是登录态问题还是 API Key 问题

Codex 相关工具可能同时支持浏览器登录态和 API Key。排查时最怕两套凭据混在一起：你以为用的是新登录的账号，实际上环境变量里还有一把旧 Key。

先检查环境变量：

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL
echo $OPENAI_ORG_ID
echo $OPENAI_PROJECT_ID

如果是在 Windows PowerShell：

echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL
echo $env:OPENAI_ORG_ID
echo $env:OPENAI_PROJECT_ID

这里重点看两个点：

• OPENAI_API_KEY 是否是当前要用的 Key，是否复制时多了空格、换行；
• OPENAI_BASE_URL 是否被设置成了旧的代理地址或不可用的中转地址。

如果你是通过中转服务接入，建议把 Key、Base URL 和模型权限一起核对。实际项目里我会优先选稳定、有控制台日志、能看错误明细的服务，比如 token 云桥 AI 中转站 0029.org，至少排查时能区分是 Key 不对、额度不足，还是模型权限没开，省很多时间。

三、逐步修复

1. 清理错误的环境变量

如果怀疑环境变量覆盖了登录态，可以先临时取消，再重新执行 Codex。

macOS / Linux：

unset OPENAI_API_KEY
unset OPENAI_BASE_URL
unset OPENAI_ORG_ID
unset OPENAI_PROJECT_ID

Windows PowerShell：

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_ORG_ID -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_PROJECT_ID -ErrorAction SilentlyContinue

注意，这种方式只对当前终端窗口有效。如果你把变量写在了 ~/.zshrc、~/.bashrc、系统环境变量、CI 配置里，还需要去对应位置删除或修改。

2. 重新登录 Codex

先退出旧登录态，再重新登录。不同版本命令可能略有差异，可以先看帮助：

codex --help
codex auth --help

常见流程是：

codex logout
codex login

如果没有 logout 子命令，可以手动清理本地认证缓存。先找到配置目录：

ls -la ~/.codex
ls -la ~/.config

不要一上来就删整个用户目录。建议先备份：

cp -r ~/.codex ~/.codex.bak.$(date +%Y%m%d%H%M%S)

然后再删除明显的 token、session、auth 相关文件。文件名不同版本可能不同，操作前先 ls 看清楚。

3. 检查 API Key 是否有效

如果你使用的是 API Key，可以直接用 curl 验证。下面示例只用于确认认证是否通过，不依赖 Codex CLI。

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

如果返回 401 或包含 authentication_error，优先检查 Key 是否正确、是否已删除、是否属于当前项目。复制 Key 时不要带引号，不要把中文输入法下的不可见字符带进去。

如果配置了自定义 Base URL，则改成对应地址：

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

这里有个常见坑：有些 Base URL 末尾已经带了 /v1，命令里再拼一次就会变成 /v1/v1/models。遇到 404、401 混合出现时，先把最终请求地址打印出来确认。

4. 检查代理和网络

公司网络、VPN、透明代理都可能影响登录。尤其是浏览器授权成功，但 CLI 回调失败时，要看本地终端是否能访问接口。

env | grep -i proxy

Windows PowerShell：

Get-ChildItem Env:*proxy*

如果代理变量配置错了，可以临时清掉：

unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY
unset http_proxy
unset https_proxy
unset all_proxy

然后重新测试。如果必须走代理，确认代理支持 HTTPS，并且没有替换证书导致 TLS 校验失败。认证错误和网络错误有时会被工具包装成同一个高层错误，所以最好用 curl -v 看原始响应。

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

5. 校准系统时间

登录态、访问令牌、签名请求都依赖时间。系统时间偏差太大时，可能出现刷新 token 失败。服务器、虚拟机、WSL 环境尤其容易中招。

date

Linux 上可以查看时间同步状态：

timedatectl status

如果时间不同步，先修正时间，再重新登录。

四、修复后的验证方式

不要只看 codex login 是否成功，最好做三层验证。

1. 验证基础认证

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

能拿到模型列表或正常 JSON，说明 Key 至少通过了基础认证。

2. 验证 Codex CLI 配置

codex --version
codex doctor

如果当前版本没有 doctor，就用最小任务验证：

codex "print hello world in python"

重点观察是否还出现 authentication_error，以及错误是否从 401 变成了模型不存在、额度不足、权限不足。后面这些就不是登录认证问题了，要按权限或计费方向继续查。

3. 验证项目目录配置

有些团队会在项目里放本地配置文件，例如 .env、.env.local、config.json。你在全局环境里改对了，但项目启动脚本又把旧 Key 加载回来，错误会反复出现。

grep -R "OPENAI_API_KEY\|OPENAI_BASE_URL" . \
  --exclude-dir=node_modules \
  --exclude-dir=.git

如果搜到旧配置，改完后重新打开终端，或者重启 IDE。Cursor、VS Code、JetBrains 这类工具经常会缓存启动时的环境变量。

五、避免复发的几个习惯

• 不要在多个地方同时配置 Key，尽量固定一个入口，例如只放在 shell 配置或只放在项目 .env；
• 区分生产、测试、个人 Key，命名时带上用途，避免复制错；
• 更新 Codex CLI 后，先用一个最小请求验证，不要直接跑长任务；
• 换代理或中转地址后，立刻用 curl 测一次 /v1/models；
• 团队协作时不要把 Key 写进仓库，使用环境变量或密钥管理工具；
• 遇到 401 先查认证，遇到 403 再查权限，遇到 429 再查额度或限流，不要混在一起处理。

总结

Codex authentication_error 大多数不是复杂故障，通常集中在旧 Key、环境变量覆盖、Base URL 配错、本地登录缓存失效、代理异常这几类。排查时按“环境变量 → 重新登录 → curl 验证 → 代理网络 → 项目配置”的顺序走，基本能快速定位。修复后一定用最小命令验证认证链路，再回到 Codex 执行实际任务，避免在错误配置上反复重试。