1. Windows 下 Codex 跑不起来，多半卡在 auth.json 这一步

如果你在 Windows 上装完 Codex CLI，敲下第一条命令却看到401 Unauthorized或者一直转圈，问题大概率不在安装本身，而在auth.json这个文件没配对。Codex 是 OpenAI 推出的命令行编码代理工具，能在终端里读代码、改文件、跑命令，适合习惯用命令行干活的开发者。它默认走 OpenAI 官方接口，但国内网络环境下直连经常超时，所以很多人会把它指向一个兼容 OpenAI 协议的网关地址，让请求先落到能稳定访问的入口上。

我试过在 Windows 11 上从零装一遍，踩的坑集中在三处：一是auth.json的存放路径找错，二是Base URL写成了带/v1或漏了/v1，三是环境变量和配置文件打架。这篇就把这三件事拆开讲清楚，给你可直接复制的auth.json片段、准确的目录路径，以及一条最小请求命令来验证鉴权和模型返回是否正常。全程不需要你懂什么底层原理，照着做就行。

先明确一个概念：Codex CLI 读取配置有两个来源，一个是环境变量，一个是~/.codex/auth.json和~/.codex/config.toml。在 Windows 上，~指的是你的用户目录，通常是C:\Users\你的用户名。很多人以为配置文件放在项目目录里就行，结果 Codex 根本不读，白折腾半天。记住这个路径，后面所有操作都围绕它展开。

另外提醒一句，Codex 的版本迭代比较快，配置字段名可能随版本微调。如果你照着配完发现字段不认，先用codex --version确认版本，再去官方文档核对字段。下面给的配置以当前主流版本为准，覆盖了绝大多数场景。

2. 装 Codex 之前，先把 Node 和 TaoToken 的 Key 准备好

Codex CLI 是通过 npm 分发的，所以第一步是确认你的 Windows 上有 Node.js。打开 PowerShell，输入node -v，如果返回类似v20.x.x就说明有了。没有的话去 Node 官网下 LTS 版本，安装时记得勾选自动配置 PATH。装完重开一个 PowerShell 窗口，再验证一次node -v和npm -v，两个都能出版本号才算过关。

Node 搞定后，用一条命令全局安装 Codex：

npm install -g @openai/codex

装完输入codex --version，能打印版本号就说明 CLI 本体到位了。这一步如果报npm ERR! code EACCES之类的权限错误，多半是 npm 全局目录权限问题，用管理员身份重开 PowerShell 再装一次通常能解决。

接下来是拿 Key。Codex 需要一个能访问模型接口的凭证，这里用 TaoToken 的 API Key。登录 TaoToken 官网，进控制台，在 API Keys 页面创建一个新 Key，复制下来先存到记事本里。这个 Key 就是后面auth.json里要填的东西。注意 Key 只在创建时完整显示一次，关掉页面就看不到了，所以务必先存好。

创建 Key 的入口在这里：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codex_windows_authjson

拿到 Key 之后，还要确认你要用的模型 ID。Codex 默认会请求gpt-5-codex这类模型，你需要在配置里显式指定一个 TaoToken 支持的模型 ID。进模型对话页面可以查看当前可用的模型列表：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codex_windows_authjson

把 Key 和模型 ID 都准备好，就可以进入配置环节了。这里强调一下，Key 属于敏感信息，不要提交到 Git 仓库，也不要在截图里露出来。后面我们会把它写进本地配置文件，这个文件默认不会被同步。

3. 手把手改 auth.json 和 config.toml，把 Base URL 落到 TaoToken

Codex 的配置目录在 Windows 上是C:\Users\你的用户名\.codex。如果这个目录不存在，手动建一个。在这个目录下，我们需要两个文件：auth.json和config.toml。前者放鉴权信息，后者放模型和接口地址。

先建auth.json，内容如下，把sk-开头的那串换成你自己的 Key：

{ "OPENAI_API_KEY": "sk-你的TaoToken密钥" }

注意这个文件是纯 JSON，不能有注释，不能有多余逗号，否则 Codex 解析时会直接报错退出。保存时确认编码是 UTF-8，Windows 记事本默认可能是带 BOM 的 UTF-8，建议用 VS Code 保存为无 BOM 的 UTF-8。

然后是config.toml，这个文件决定请求发到哪里、用哪个模型：

model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

这里有几个点要盯紧。base_url必须是https://taotoken.net/api/v1，结尾的/v1不能少，也不能写成/v1/带斜杠，否则请求路径会拼错。env_key写OPENAI_API_KEY，Codex 会去读auth.json里同名的字段。wire_api用responses，这是 Codex 新版默认的接口形态；如果你的版本较老只认chat，把它改成chat再试。

如果你更习惯用环境变量而不是auth.json，也可以在 PowerShell 里设置：

[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY','sk-你的TaoToken密钥','User')

但要注意，环境变量和auth.json同时存在时，优先级可能因版本而异，容易互相覆盖导致排查困难。建议二选一，本文以auth.json为准，配置更集中，换机器时也好迁移。

配置写完后，目录结构应该是这样：

C:\Users\你的用户名\.codex\ ├── auth.json └── config.toml

确认无误后，就可以进入验证环节了。

4. 一条命令验证鉴权和模型返回是否正常

配置写完别急着开大项目，先用最小请求确认链路通。打开 PowerShell，进一个空目录，运行：

codex exec "用一句话说明什么是快速排序"

这条命令会让 Codex 以非交互模式执行一次请求，把提示词发给模型并打印返回。如果一切正常，你会在终端看到模型生成的一句话解释，说明鉴权通过、Base URL 正确、模型 ID 有效。

如果想让 Codex 直接改文件，可以进一个测试项目目录，运行交互模式：

codex

进入交互界面后，输入一个简单任务，比如「在当前目录创建一个 hello.py，打印 hello world」，观察它是否能正常读取文件、生成内容。这一步能验证的不只是接口连通，还有文件读写权限。

想更直观地确认请求确实落到了 TaoToken，可以打开控制台的用量日志页面，看是否有对应的调用记录。有记录就说明请求确实经过了网关，而不是走了别的路径。

验证通过后，你还可以测一下流式输出是否正常。在交互模式里让它生成一段稍长的代码，观察输出是不是逐字出现的。如果卡住不动最后一次性吐出，可能是wire_api设置和版本不匹配，回到config.toml调整。

这里给一个判断标准：只要codex exec能返回内容，且控制台有调用记录，就说明整条链路是通的。剩下的就是把它用起来，而不是继续折腾配置。

5. 常见报错对照：401、local proxy failed、reading choices 怎么排

配置过程中最容易撞上的几个报错，我按出现频率排一下，给你对照排查。

401 Unauthorized：这是鉴权失败。九成是auth.json里的 Key 写错、过期，或者env_key字段名和auth.json里的键名对不上。先确认auth.json里是OPENAI_API_KEY，config.toml里env_key也是OPENAI_API_KEY。再确认 Key 没有多余空格或换行。如果 Key 是从网页复制的，注意别把前后的引号也复制进去。

local proxy failed / connection refused：这个报错说明 Codex 尝试连接的地址不通。检查base_url是不是写成了https://taotoken.net/api/v1，有没有多写端口号，有没有被系统代理拦截。如果你本机开了某些网络工具，先关掉再试，避免请求被劫持到错误地址。

reading choices 相关报错：通常是接口返回结构和 Codex 预期的不一致。多数情况是wire_api设错了。新版 Codex 用responses，老版用chat，两者返回结构不同。把wire_api改成另一个值再试。如果还不行，确认模型 ID 是否拼写正确，模型不存在时返回体也会缺字段。

OAuth 相关报错：如果你之前用官方登录方式认证过，auth.json里可能残留了 OAuth 的 token 字段，和 API Key 模式冲突。解决办法是清空auth.json，只保留OPENAI_API_KEY一个字段，然后重新运行。

模型不存在 / model not found：模型 ID 写错了，或者你的账号没有该模型的权限。去模型对话页面确认可用模型列表，把config.toml里的model换成列表里存在的 ID。

排查时有个通用技巧：把config.toml里的base_url临时改成官方地址测试，如果官方能通而 TaoToken 不通，问题在网关配置；如果两边都不通，问题在本地环境或 Key。这样能快速定位问题在哪一层。

6. 配好之后怎么用：把 Codex 接进日常编码流程

链路通了之后，Codex 的用法其实很灵活。最基础的三种模式：codex exec "提示词"适合一次性任务，比如生成某个函数、解释一段代码；直接敲codex进交互模式，适合多轮对话式改代码；在项目目录里运行，它会自动把当前目录作为工作区，能读写文件。

如果你做长期编码或者想让 Codex 承担更多 Agent 类任务，比如批量重构、跨文件修改，可以考虑用 Coding Plan，额度更充足，适合持续调用：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codex_windows_authjson

日常排查配置问题、核对接口字段，接入文档是最快的参考：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codex_windows_authjson

想临时验证某个模型返回是否正常，不用改配置，直接去模型对话页面发一条消息就行：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=codex_windows_authjson

最后说个实用技巧：把~/.codex目录加入你的 dotfiles 备份，但记得把auth.json排除掉，只备份config.toml。这样换机器时配置能快速恢复，Key 则手动填一次，安全又省事。Codex 的配置一旦跑通，后面基本不用再动，把精力放回代码本身就好。