1. 从 ChatGPT Work 到 Codex：为什么今天要动 auth.json
2026 年 7 月 25 日这一周，AI 基础设施的关键词几乎都指向同一个方向：入口在收拢，通道在统一。ChatGPT 桌面端把 Chat、Work、Codex 拆成三个工作模式，GitHub Copilot 把 Claude Opus 5、Gemini 3.6 Flash、Kimi K2.7 Code 塞进同一个模型选择器，Windows 11 这边 KB5101650 和 KB5121767 一个正式一个带外，运维得分开处理。对每天在终端里敲命令的开发者来说，这些新闻最后都会落到一个很具体的问题上：我本地这套 Codex CLI，endpoint 到底指向哪里，Key 从哪来，模型 ID 写没写死。
Codex 的配置文件auth.json就是这件事的落点。它决定了 CLI 启动时用哪个 API 地址、带哪个凭据、默认调哪个模型。默认情况下它指向官方通道，但很多团队在做多模型对比、成本核算或者统一 Key 管理时，会希望把 endpoint 换成一个兼容 OpenAI 协议的聚合入口。TaoToken 提供的正是这样一个统一 Key/API 通道，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api 。
这篇不是新闻复述，而是一次可复现的接入检查。我会把auth.json的完整片段贴出来，逐条说明每个字段的作用，然后用一次真实请求验证返回、看日志确认、再准备一套失败回退方案。适合谁：本地已经装了 Codex CLI、想把它接到统一通道的开发者；正在做多模型切换、需要集中管理 Key 的团队；以及被 GitHub Models 7 月 30 日退役逼着迁移、想顺手把 Codex 通道也理顺的人。整个过程不需要改系统代理，不需要动网络层，只改一个 JSON 文件加一次重启。
需要先明确一点：Codex 的auth.json属于本地凭据文件，改之前一定先备份。我见过有人直接覆盖，结果原 Key 丢了还得重新走一遍登录。下面每一步都假设你在自己的开发机上操作，路径以 macOS/Linux 的~/.codex/和 Windows 的%USERPROFILE%\.codex\为准。
2. TaoToken 前置：拿到 Key 并确认通道可用
在动auth.json之前，得先把 TaoToken 这边的凭据准备好。这一步不复杂，但顺序不能反——先有 Key，再改配置，否则 CLI 启动时会因为拿不到凭据直接报 401。
先访问控制台创建 API Key。入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，登录后进 API Keys 页面，新建一个 Key。建议按用途命名，比如codex-local-dev，这样后面在日志里看到调用来源时能对上号。Key 只在创建时完整显示一次，复制后先存到密码管理器或者本地临时文件，别直接贴在聊天窗口里。
Key 拿到后，先别急着写进auth.json，用一条 curl 确认通道本身是通的。这一步能帮你把「Key 无效」和「配置写错」两类问题分开：
curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" | head -c 500如果返回一段包含模型列表的 JSON，说明 Key 和通道都没问题。如果返回 401，先检查 Key 有没有复制完整、有没有多余空格；如果返回 404，检查 URL 是不是写成了https://taotoken.net/api（根地址）而不是带/v1/models的完整路径。这里有个容易踩的坑：TaoToken 的 API 根是https://taotoken.net/api，但 OpenAI 兼容接口的实际路径是/api/v1/...，写配置时 base URL 填https://taotoken.net/api，SDK 或 CLI 会自动补/v1，别手动拼成/api/v1再让工具补一次，会变成/api/v1/v1。
模型 ID 也要提前确认。Codex 默认可能写的是某个官方模型名，但走统一通道时，模型 ID 必须和通道侧登记的保持一致。你可以从上面/v1/models的返回里挑一个，比如常见的gpt-4o、claude-sonnet-4-20250514这类。如果团队里有人用 Claude Code，那边的配置逻辑类似，但文件路径和字段名不同，别把两套配置混在一个文件里。
关于 Coding Plan 和长期编码场景，如果你的 Codex 主要跑后台代理任务、批量重构或者多轮工具调用，可以看一下 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它针对的就是这种持续消耗的场景。但这一步不是必须的，先用按量 Key 把通道跑通，再决定要不要换套餐。
最后提醒一句：Key 属于敏感凭据，auth.json不要提交到 Git。如果你在团队仓库里看到有人把auth.json加进了版本控制，第一件事是让他撤销 Key 并加进.gitignore。这个文件默认就在用户目录下，正常不会被仓库跟踪，但有人为了「方便同步」手动复制进项目目录，那就危险了。
3. 可复制配置：auth.json 完整片段与字段说明
现在进入核心步骤。Codex 的auth.json结构不复杂，但字段名和嵌套层级要对上，写错一个 key 名就会静默回退到默认通道，你以为是走 TaoToken，实际还在打官方地址。
先找到文件位置。macOS/Linux：
ls -la ~/.codex/auth.jsonWindows PowerShell：
Test-Path "$env:USERPROFILE\.codex\auth.json"如果文件不存在，说明你还没登录过 Codex CLI，先跑一次codex login生成初始文件，再改。改之前备份：
cp ~/.codex/auth.json ~/.codex/auth.json.bak下面是完整的auth.json片段。注意OPENAI_API_KEY和OPENAI_BASE_URL这两个字段是 Codex 读取通道信息的关键，model字段决定默认模型：
{ "OPENAI_API_KEY": "sk-你的TaoTokenKey", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "gpt-4o", "provider": "openai", "tokens": { "access_token": "sk-你的TaoTokenKey", "refresh_token": "" } }逐字段说明。OPENAI_API_KEY填 TaoToken 控制台创建的 Key，注意不要带Bearer前缀，CLI 会自己加。OPENAI_BASE_URL填https://taotoken.net/api，这是根地址，不要带/v1。model填你在/v1/models里确认过的模型 ID。provider保持openai，因为 TaoToken 走的是 OpenAI 兼容协议。tokens里的access_token有些 Codex 版本会优先读它，所以和OPENAI_API_KEY保持一致最稳，refresh_token留空即可，走静态 Key 不需要刷新流程。
如果你用的是 TOML 风格的配置（部分 Codex 版本或周边工具支持config.toml），对应片段是这样：
[model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" [profiles.default] model_provider = "taotoken" model = "gpt-4o"这种写法把 Key 放在环境变量TAOTOKEN_API_KEY里，配置文件本身不含明文凭据，更适合团队共享配置模板。设置环境变量：
export TAOTOKEN_API_KEY="sk-你的TaoTokenKey"Windows PowerShell：
$env:TAOTOKEN_API_KEY = "sk-你的TaoTokenKey"两种方式选一种就行，别同时写，否则可能出现优先级冲突。我实测下来，JSON 方式对个人开发机最直接，TOML 方式适合需要把配置纳入 dotfiles 仓库的场景。改完保存，退出所有 Codex 进程，重新启动。注意 Codex 有些版本会缓存配置，不重启不生效。
还有一个细节：如果你之前登录过官方账号，auth.json里可能残留account_id或id_token字段。这些字段在走第三方通道时可能触发额外的校验逻辑，建议删掉，只保留上面列出的字段。删之前对比一下备份文件，确认没删掉必要内容。
4. 验证请求：从返回结果到日志确认
配置写完，接下来是验证。这一步不能只看「命令没报错」就完事，要看到真实的模型返回和日志里的 endpoint 记录，才算接入成功。
第一步，跑一个最小请求。用 Codex CLI 的非交互模式：
codex exec "用一句话说明什么是 API 网关" --model gpt-4o如果配置正确，你会看到模型返回的一句话解释。如果卡住不动或者报连接错误，先别改配置，往下看日志。
第二步，看 Codex 的日志确认实际请求地址。日志位置通常在~/.codex/log/下：
tail -n 50 ~/.codex/log/codex.log | grep -i "base_url\|endpoint\|taotoken"预期能看到类似POST https://taotoken.net/api/v1/chat/completions的记录。如果日志里出现的是官方地址，说明OPENAI_BASE_URL没被读到，检查字段名拼写和 JSON 格式（用python -m json.tool ~/.codex/auth.json验证语法）。
第三步，用 curl 直接打一次 chat completions，把 CLI 层和通道层分开验证：
curl -s 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": "回复 OK 两个字母"}], "max_tokens": 10 }'预期返回结构里choices[0].message.content是OK。如果这一步通了但 CLI 不通，问题在 Codex 配置；如果这一步就不通，问题在 Key 或通道。
第四步，验证多轮和工具调用场景。Codex 的价值在于代理任务，单轮问答通了不代表工具调用通。跑一个需要读文件的请求：
codex exec "读取当前目录的 README.md 并总结第一段" --model gpt-4o观察日志里是否有多次请求往返。如果工具调用阶段报reading choices相关错误，通常是返回结构里choices字段缺失或格式不符，这种情况多半是模型 ID 写错，通道侧返回了错误结构而不是标准 completion。
成功的结果长这样：CLI 正常输出总结内容，日志里每次请求都指向taotoken.net/api，没有回退到官方地址的记录。到这一步，接入就算完成了。把这次验证的命令和返回记下来，后面团队里其他人接入时可以直接复用这套检查动作。
5. 常见报错排查：401、local proxy failed 与 reading choices
接入过程里最容易撞上的几类报错，我按出现频率排一下，每条都给对照现象和处理动作。
401 Unauthorized。现象是 CLI 启动或首次请求就报 401，日志里能看到invalid_api_key或authentication failed。原因通常是三种：Key 复制时带了空格或换行；auth.json里OPENAI_API_KEY和tokens.access_token不一致，CLI 读了后者；Key 在控制台被撤销或过期。处理动作：先用第 2 节的 curl 单独验证 Key，通了再检查auth.json两个字段是否一致。如果 curl 也 401，回控制台重新建 Key。
local proxy failed。现象是请求发不出去，报连接被拒绝或超时，日志里出现local proxy failed或connection refused。这个报错和 TaoToken 本身无关，通常是本地有残留的代理环境变量（HTTP_PROXY、HTTPS_PROXY）指向了一个已经关掉的本地代理端口。处理动作：检查环境变量，临时清掉再试：
unset HTTP_PROXY HTTPS_PROXY ALL_PROXYWindows PowerShell：
Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue注意这里说的是清掉本地失效的代理设置，不是让你去配什么网络工具。TaoToken 的通道直接可达，不需要额外网络层。
reading choices 相关错误。现象是请求发出去了，但解析返回时失败，报cannot read property 'choices' of undefined或类似。原因是通道返回的不是标准 completion 结构，多半是模型 ID 写错，通道侧返回了一个错误对象。处理动作：用第 4 节的 curl 带上同样的模型 ID 打一次，看返回体里有没有choices。如果没有，把模型 ID 换成/v1/models里确认存在的那个。
OAuth 相关报错。现象是 CLI 提示需要重新登录或OAuth token expired。这是因为auth.json里残留了官方账号的 OAuth 字段，CLI 优先走了 OAuth 流程。处理动作：删掉auth.json里的id_token、account_id、expires_at等字段，只保留第 3 节列出的字段，重启 CLI。
配置不生效。现象是改完auth.json后请求还是走官方地址。原因通常是 CLI 进程没完全退出，或者存在多个配置文件（比如项目目录下还有一个.codex/auth.json覆盖了用户目录的）。处理动作：ps aux | grep codex确认没有残留进程，然后检查项目目录有没有局部配置。
排查顺序建议固定成：先 curl 验 Key 和通道，再验auth.json语法，再看日志确认 endpoint，最后才怀疑模型 ID。这个顺序能把大部分问题挡在前两步。
6. 把通道固定下来：CTA 与后续动作
接入验证通过之后，建议做两件收尾的事。一是把这次用到的配置片段和验证命令整理成一个内部文档，团队里其他人接入时不用重新踩一遍。二是把 Key 的管理方式定下来，个人开发机可以用明文auth.json，团队共享场景建议走环境变量加配置模板，避免 Key 散落在多个文件里。
如果你还想验证其他模型在统一通道下的表现，可以直接用模型对话入口试：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，不用改本地配置就能对比不同模型的返回。接入过程中遇到通道侧的报错，先查接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面按错误码列了处理方式。Key 的创建和轮换在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
回到今天这波动态本身，GitHub Models 7 月 30 日退役是个硬时间点，还在用旧 endpoint 的项目这周就得动。Windows 那边的 KB5121767 只建议受 Intel IPF 影响的设备装，别看到「带外更新」就全量推。ChatGPT Work 和 Copilot 的模型选择器在扩，但企业策略没开的话成员照样看不到。这些变化最后都会落到「你的工具连的是哪个通道、用哪个 Key、默认哪个模型」这三个问题上。把auth.json理顺，后面不管入口怎么变，本地这套编码环境都是可控的。
