1. Codex auth.json 报 401 与 OAuth refresh 失败的真实场景

如果你在本地用 Codex CLI 或者带 Codex 插件的编辑器，某天突然开始疯狂报401 Unauthorized，或者日志里反复出现OAuth refresh failed、token expired、invalid_grant这类字样，大概率不是网络断了，而是auth.json这个鉴权文件里的字段和当前使用的通道对不上了。Codex 的鉴权链路其实不复杂：它读一个本地 JSON 文件，从里面拿 access token、refresh token、account 信息，然后带着这些凭证去请求模型接口。问题在于，这个文件的结构在不同版本、不同登录方式下会变，一旦你手动改过、或者从别的地方复制过一份，字段名、层级、过期时间任意一处不对，整条链路就断了。

我遇到的具体表现是这样的：终端里执行一次代码补全请求，返回体里error.code是invalid_api_key，但同一台机器上换个工具用同一个 Key 又是通的。这说明 Key 本身没问题，是 Codex 读取凭证的方式出了岔子。进一步翻~/.codex/auth.json，发现里面还残留着上一套 OAuth 流程写入的tokens对象，而OPENAI_API_KEY字段是空的。Codex 优先走 OAuth 分支，refresh 时拿旧 refresh token 去换新 token，服务端返回refresh_token_reused或者直接 401，于是每次请求都失败。

这个场景特别容易出现在几种情况下：一是你之前用账号密码或浏览器授权登录过，后来想换成统一 Key 通道，但没清干净旧字段；二是从同事那里拷了一份auth.json做参考，结果里面的expires_at是过去的；三是升级 Codex 版本后，新版本对字段校验更严，旧格式直接不认。核心矛盾就一句话：auth.json 里同时存在多套鉴权信息时，Codex 的选择顺序和你的预期不一致。

要定位这个问题，先别急着删文件。你可以先看一眼当前 auth.json 的完整内容，重点确认三件事：auth_mode或等价的模式字段是什么、tokens对象是否存在且非空、OPENAI_API_KEY或api_key字段有没有值。如果tokens存在但 refresh 一直失败，那就是 OAuth 分支在捣乱；如果api_key为空但模式又指向 key 鉴权，那就是字段缺失。把这两类情况分清楚，后面的改法才有针对性。很多人一上来就重装 Codex，其实文件没动对，重装十遍还是 401。

2. 把 Codex 接到 TaoToken 统一通道的前置准备

在动手改auth.json之前，需要先把 TaoToken 这边的接入信息准备好。TaoToken 提供的是统一的 API 通道，你只需要一个 Key 和一个 Base URL，就能让 Codex 走这条通道请求模型，不用再维护 OAuth 那套 refresh 逻辑。对本地开发来说，这能省掉大量 token 过期的排查时间。

第一步是拿到 API Key。打开 https://taotoken.net/api-keys ，登录后创建一个新的 Key。建议按用途命名，比如codex-local-dev，方便以后区分。创建完立刻复制保存，页面刷新后就看不到完整 Key 了。这个 Key 就是后面要写进auth.json的核心凭证。

第二步是确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api，注意这里不要加任何查询参数，直接用它作为请求根地址。Codex 在拼接具体路径时会自己补上/v1/...之类的后缀，你只需要给到根。

第三步是确定要用的 Model ID。Codex 场景下通常用编码能力强的模型，你可以先在 https://taotoken.net/models 上看当前支持的模型列表，记下你打算用的那个 ID，比如gpt-4o、claude-3-5-sonnet这类。Model ID 必须和平台上的完全一致，大小写、连字符都不能错，否则请求会返回model_not_found。

第四步是找到你的auth.json路径。不同系统下位置不一样：macOS 和 Linux 一般在~/.codex/auth.json，Windows 在%USERPROFILE%\.codex\auth.json。如果你用的是带 Codex 插件的编辑器，有些版本会把它放在项目目录下的.codex/里，优先读项目级配置。先用ls或文件管理器确认文件确实存在，再决定改哪一个。

这四步做完，你手里应该有三样东西：一个 Key、一个 Base URL、一个 Model ID。这三件套是后面所有配置的基础，缺一个都跑不通。如果你之前从没配过 Codex，auth.json可能根本不存在，那就需要手动创建，目录也要一并建好。别小看这一步，路径写错是后面 401 之外第二常见的坑。

3. 可复制的 auth.json 配置片段与字段对照

现在进入正题，直接给你一份可以照着改的auth.json。这份配置的核心思路是：让 Codex 走 API Key 通道，彻底绕开 OAuth refresh。先看完整片段，再逐字段解释。

{ "auth_mode": "apikey", "OPENAI_API_KEY": "sk-你的TaoTokenKey", "api_key": "sk-你的TaoTokenKey", "base_url": "https://taotoken.net/api", "model": "gpt-4o", "tokens": null, "last_refresh": null, "expires_at": null }

把上面这段里的sk-你的TaoTokenKey替换成你在 API Keys 页面创建的真实 Key，model换成你实际要用的 Model ID。注意base_url结尾不要带斜杠，Codex 拼接路径时对多余斜杠的处理在不同版本里不一致，容易出404。

下面这张表把关键字段和它们的作用、常见错误值对照清楚，方便你排查：

这里要特别强调tokens字段。很多人改的时候只填了 Key，但没把原来的tokens对象清掉，结果 Codex 一看tokens非空，还是走 OAuth 分支，refresh 照样失败。所以最稳妥的做法是把它显式设为null，而不是删掉这个字段——有些版本对字段缺失和字段为 null 的处理不一样，显式 null 更安全。

如果你用的是 TOML 格式的配置文件（部分 Codex 发行版支持config.toml），等价写法是这样：

auth_mode = "apikey" OPENAI_API_KEY = "sk-你的TaoTokenKey" base_url = "https://taotoken.net/api" model = "gpt-4o"

TOML 里没有tokens字段就代表不启用 OAuth，所以不用额外写 null。改完保存，别急着跑请求，先确认文件编码是 UTF-8，Windows 上用记事本改容易带 BOM，也会导致解析失败。

还有一个细节：如果你同时装了多个用到 Codex 的工具，它们可能各自读不同的auth.json。改完之后用cat ~/.codex/auth.json再确认一遍内容，确保你改的就是实际被读取的那份。这一步花十秒，能省掉半小时的无效排查。

4. 用 curl 验证 200 响应与 Codex 实际请求

配置改完，不要直接上 Codex 跑任务，先用 curl 单独验证通道是否通。这样能把「配置问题」和「Codex 自身问题」分开，定位效率高很多。

先验证 Key 和 Base URL 是否有效。执行下面这条命令，把 Key 和 Model ID 换成你自己的：

curl -s -o /dev/null -w "%{http_code}\n" \ https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5 }'

如果返回200，说明 Key、Base URL、Model ID 三件套都是对的，通道没问题。如果返回401，那就是 Key 本身无效或没带上；返回404，多半是路径拼错或 Model ID 不存在；返回400，检查 JSON 体格式。这一步拿到 200，再去看 Codex 才有意义。

接着验证 Codex 实际发出的请求。Codex 在运行时会打印调试日志，你可以临时把日志级别调高，观察它请求的 URL 和携带的 header。重点看两处：请求的 host 是不是taotoken.net，Authorization header 里是不是你的 Key。如果 host 还是原来的地址，说明base_url没生效，Codex 读的是别的配置源；如果 Authorization 是空的或还是旧 token，说明auth.json没被正确加载。

一个更直接的验证方式是用 Codex 跑一个最小任务，比如让它补全一行简单代码，同时观察终端输出。成功的情况下，你会看到请求正常返回，没有 401，也没有 refresh 相关日志。如果仍然报 401，把 curl 的 200 结果和 Codex 的报错放在一起对比，就能判断是「通道问题」还是「Codex 读取配置问题」。

实测下来，curl 返回 200 但 Codex 仍 401 的情况，九成是auth.json路径不对或者字段名不匹配。这时候回到第 3 步，确认你改的文件就是 Codex 实际读取的那个，并且auth_mode确实是apikey。把这两点锁死，问题基本就解决了。

5. 本篇常见错误排查对照

这一节把实际踩过的坑列出来，对照真实报错定位。每条都给出报错原文特征、根因和改法。

报错一：401 Unauthorized且响应体含invalid_api_key

这是最常见的。根因通常是auth.json里OPENAI_API_KEY为空，或者 Key 复制时带了空格、换行。改法：用cat -A ~/.codex/auth.json看有没有隐藏字符，重新粘贴 Key，确保sk-开头完整。如果 Key 确认无误，检查base_url是否指向https://taotoken.net/api，指向别处也会 401。

报错二：OAuth refresh failed/invalid_grant/refresh_token_reused

根因是tokens对象还在，Codex 走了 OAuth 分支。改法：把tokens显式设为null，expires_at和last_refresh也设为null，auth_mode改成apikey。改完重启 Codex 进程，让它重新读文件。

报错三：local proxy failed/connection refused

这个报错和鉴权无关，是本地代理或网络层的问题。检查你有没有设置HTTP_PROXY、HTTPS_PROXY环境变量指向一个没启动的本地端口。用env | grep -i proxy看一眼，有的话临时 unset 掉再试。注意这里说的是本地环境变量清理，不涉及任何网络工具配置。

报错四：reading choices/unexpected response format

根因是请求返回的结构和 Codex 预期的不一致，常见于base_url写成了带/v1的地址，导致路径重复拼接成/v1/v1/...。改法：base_url只写到https://taotoken.net/api，不要带/v1。另外确认 Model ID 是平台支持的，不支持的模型可能返回错误结构。

报错五：model_not_found

Model ID 拼写错误或该模型未开通。改法：去 https://taotoken.net/models 核对准确 ID，注意大小写和连字符。有些模型有版本后缀，别漏掉。

报错六：改了配置但行为没变

根因是改错了文件，或者 Codex 有缓存。改法：确认auth.json的实际路径，项目级配置优先级高于用户级；改完彻底退出 Codex 再启动，不要只重开窗口。

排查时建议按「先 curl 后 Codex、先 Key 后字段、先路径后内容」的顺序走，能最快缩小范围。把每次报错和对应改法记下来，下次遇到同类问题直接查表。

6. 长期编码场景的通道选择与接入入口

如果你只是偶尔用 Codex 补几行代码，上面这套 API Key 配置就够用了。但如果你把 Codex 当作日常主力编码工具，每天大量请求，那值得考虑更稳定的通道方案。TaoToken 的 Coding Plan 就是为这种长期、高频的编码场景准备的，它在统一 Key 的基础上做了额度管理和稳定性优化，适合把 Codex、Cline 这类工具长期挂在上面跑。

接入入口按用途分几个：

• 需要创建和管理 Key：https://taotoken.net/api-keys
• 查看支持的模型和 Model ID：https://taotoken.net/models
• 想直接在网页里验证模型效果：https://taotoken.net/chat
• 长期编码、Agent 场景：https://taotoken.net/coding-plan
• 完整接入文档：https://taotoken.net/doc

配置层面，无论你用哪种通道，核心三件套始终是 Base URL、Key、Model ID。把这三个值在auth.json里写对，Codex 的鉴权链路就稳了。剩下的就是按第 4 步用 curl 验证一次，确认 200 之后再投入日常使用。遇到 401 先别慌，按第 5 节的对照表逐条排，大部分问题都能在几分钟内定位。