环境：macOS 14 / Windows 11 双机验证，Node 22，Codex CLI v0.134+
记录于 2026 年 8 月，所有报错和配置都是真实复现的，不是编的。

先说结论，省时间的直接看这里

上周在群里看到有人问：“Codex 装好了，config.toml 也写了，为什么一启动就是 AuthenticationError？”

底下一堆回复：有的说重装，有的说换 API Key，有的说改环境变量。看着就头疼——因为这三个答案对应的根本不是同一个问题。

我自己上个月刚把这三个坑挨个踩了一遍，最惨的一次折腾到凌晨一点。今天把笔记整理出来，按"现象 → 根因 → 修复"的结构写，你照着对号入座就行。

三个坑速览：

#	现象	根因一句话
1	改了 config.toml 还是 401	shell 里残留旧的环境变量，优先级把它劫持了
2	明明 Key 是对的，却报 401/404	base_url 没以 /v1 结尾，请求打到了错误路径
3	换了 Key 还是认旧账号	~/.codex/auth.json 里的 OAuth 凭据没清

下面一个一个拆。

前置知识：Codex 启动时到底怎么找凭据？

不搞清楚这个，后面的修复方案你记不住。

Codex（不管是 CLI 还是桌面端，底层是同一套认证逻辑）启动时会按一个固定优先级去找你的身份凭证。这个顺序是写死在代码里的，画出来大概是这样：

看懂这张图，你就明白为什么"改了配置文件没用"了——因为排在前面的凭据把后面的全挡住了。

三个坑，本质上都是这张图里某个节点出了问题。

坑一：环境变量劫持——你改的 config.toml 根本没被读到

现象

你在 ~/.codex/config.toml 里写好了新的 Key：

model = "gpt-5.1-codex"
model_provider = "openai"

[model_providers.openai]
api_key = "sk-新的key写在这里了"

保存、重启终端、启动 codex，啪，还是 AuthenticationError: 401。

你开始怀疑人生：文件路径没错啊？语法没错啊？

根因

回头看我上面那张图——环境变量的优先级高于 config.toml。

你大概率是之前某次跟着教程执行过这么一句：

export OPENAI_API_KEY="sk-旧的或者随便填的key"

而且顺手写进了 ~/.zshrc 或 ~/.bashrc。于是每次 codex 启动，第一件事就是读这个环境变量，拿着旧 Key 直接去请求，config.toml 里你刚写的新 Key 连被加载的机会都没有。

验证方法很简单，一行命令：

echo $OPENAI_API_KEY

如果输出的 Key 和你在 config.toml 里写的不一样，恭喜，就是它干的。

修复

把 shell 配置里的残留删掉：

# 1. 编辑你的 shell 配置文件
vim ~/.zshrc    # bash 用户改成 ~/.bashrc

# 2. 找到 export OPENAI_API_KEY=... 那一行，删掉或注释掉

# 3. 让配置生效
source ~/.zshrc

# 4. 确认已经清干净
echo $OPENAI_API_KEY   # 应该输出空行

然后重新启动 codex，这次它会老老实实去读 config.toml。

⚠️ 一个容易忽略的细节：如果你用的是第三方兼容端点，config.toml 里的字段叫 env_key，这个值必须和环境变量名逐字符一致，包括大小写。我见过有人写成 openai_api_key（小写），照样读不到。

坑二：base_url 少了个 /v1，401 报得你莫名其妙

现象

用中转服务或者自建的 OpenAI 兼容端点，Key 本身在别的地方（比如 curl）测试是通的，但配进 Codex 就 401，有时候是 404，有时候直接超时。

根因

这是 Codex 配置里最阴险的一个坑。base_url 必须以 /v1 结尾，差一个字符都不行。

Codex 拼接请求路径的方式是 base_url + /responses（新版走 Responses API）或 base_url + /chat/completions。它不会帮你补 /v1。

对比一下：

# ❌ 错误写法——请求会打到 https://xxx.com/responses，直接 404 或被网关拒绝
base_url = "https://your-proxy.example.com"

# ❌ 也是错的——多了个斜杠，拼出来变成 /v1//responses
base_url = "https://your-proxy.example.com/v1/"

# ✅ 正确写法
base_url = "https://your-proxy.example.com/v1"

为什么有时候报的是 401 而不是 404？因为不少中转网关在根路径上挂了鉴权中间件，路径不对时统一返回 401。这就导致你以为"是 Key 的问题"，跑去反复换 Key，越换越乱。

修复

完整的一段可用配置长这样，直接抄结构：

model = "gpt-5.1-codex"
model_provider = "myproxy"

[model_providers.myproxy]
name = "MyProxy"
base_url = "https://your-proxy.example.com/v1"   # 注意 /v1，没有尾部斜杠
env_key = "MYPROXY_API_KEY"                       # 告诉 Codex 去读哪个环境变量
wire_api = "responses"                            # 第三方端点不支持 Responses API 时改成 "chat"

然后设置对应的环境变量：

echo 'export MYPROXY_API_KEY="sk-你的key"' >> ~/.zshrc
source ~/.zshrc

怎么判断端点支不支持 Responses API？

wire_api 这个字段是 2026 年初版本才加的，很多老教程没提。判断方法：

# 快速测试命令，把 URL 和 Key 换成你自己的
curl -s https://your-proxy.example.com/v1/responses \
  -H "Authorization: Bearer $MYPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.1-codex","input":"hi"}' | head -c 200

返回了 JSON（哪怕是业务报错）就说明路径通了；返回 404/405 就老老实实改成 wire_api = "chat"。

坑三：auth.json 残留——换了 Key，它还在用你的旧登录态

现象

你之前用 codex login 登录过 ChatGPT 账号（Plus/Pro 订阅那种），后来订阅到期了或者想换成 API Key 计费，于是在 config.toml 里配好了 Key。

启动之后，要么报 401（旧 token 过期），要么更诡异——它根本不认你的新 Key，还在那尝试用旧账号连。

根因

再看一遍最上面那张流程图的第一个分支：auth.json 的优先级是最高的。

codex login 成功后，OAuth 凭据会写进 ~/.codex/auth.json。只要这个文件在、且 token 没彻底失效，Codex 就直接走 ChatGPT 登录态，后面所有 API Key 配置全部跳过。

而当 token 处于"半死不活"状态（比如刷新失败但文件还在），就会卡在 reconnecting... 或者直接甩你一个 401。

修复

干掉这个文件，让认证流程重新走一遍：

# macOS / Linux
rm ~/.codex/auth.json

# Windows PowerShell
Remove-Item $env:USERPROFILE\.codex\auth.json

删完之后二选一：

• 想继续用账号登录：codex login，重新走一遍浏览器授权
• 想用 API Key：确保 config.toml / 环境变量配好（参考坑一坑二），直接启动即可

💡 顺手可以用官方诊断命令确认状态：codex doctor，它会逐项检查认证、网络、配置，哪一项带 ❌ 就修哪一项，比重装靠谱一百倍。

终极排查流程：401 出现后按这个顺序走

把三个坑串起来，完整的排查路径是这样：

最后说两句

写这篇的起因就是我在群里看到太多"重装试试"式的回答。Codex 的认证链路其实就三层——auth.json → 环境变量 → config.toml，90% 的授权失败都是这三层之间的优先级或者格式问题，跟软件本身没半点关系。

配置类的东西，记住一个原则：永远先验证当前生效的是哪一份，再去改。echo $OPENAI_API_KEY、codex doctor、cat ~/.codex/auth.json 这三条命令能帮你省掉大部分砸键盘的时刻。

如果这篇帮你省了时间，点个赞收藏一下；你遇到的其他 Codex 奇葩报错，评论区聊，我看到会回。