1. Windows 上跑 Codex 到底卡在哪Codex CLI 是一个跑在终端里的编码智能体能读你的项目文件、执行命令、按自然语言指令改代码适合习惯命令行、想让 AI 直接动手改仓库的开发者。但它在 Windows 原生环境下的体验一直不算好路径分隔符、权限模型、npm 全局安装目录、终端编码这几件事凑在一起很容易出现命令找不到、配置文件读不出来、请求发不出去的情况。我自己第一次在 Windows 上装的时候codex -V能出版本号可一进项目就报连接错误排查半天才发现是配置文件编码带了 BOM。所以这篇的路线很明确不在原生 Windows 上硬扛而是先用 WSL 准备一个 Linux 环境再在里面装 Node.js 和 Codex最后把请求通道指向 TaoToken 的统一 Key。这样你既保留了 Windows 的桌面习惯又拿到了 Linux 下稳定的运行环境。整条链路我会给到可直接复制的命令、Node.js 版本选择理由、settings.json与config.toml的配置骨架以及一条能验证 Codex 是否真的调通 API 的测试动作。适合刚接触 Codex、或者装了但一直跑不起来的人跟着做。2. 前置准备WSL 与 TaoToken 统一 Key2.1 为什么优先选 WSL 而不是原生 WindowsCodex CLI 的很多行为依赖 POSIX 语义比如文件权限、符号链接、shell 解析。原生 Windows 下这些都要靠兼容层模拟出问题的概率明显更高。WSL2 本质是一个轻量虚拟机跑的是真正的 Linux 内核Codex 在里面和在 Ubuntu 服务器上没区别。你不需要双系统也不用折腾分区装完重启一次就能用。2.2 安装 WSL以管理员身份打开 PowerShell执行wsl --install这条命令会默认装好 WSL2 和 Ubuntu 发行版。装完必须重启电脑重启后系统会让你设置 Linux 用户名和密码这个密码在后面sudo时会用到记牢。如果你的系统提示wsl --install不可用先执行wsl --update更新一下 WSL 组件。重启后从开始菜单搜索 Ubuntu 或 WSL 打开终端先确认版本wsl --list --verbose看到VERSION是2就对了。如果显示 1用wsl --set-version Ubuntu 2切换。2.3 拿到 TaoToken 统一 KeyCodex 需要一个能接收 OpenAI 兼容请求的通道。TaoToken 提供统一 Key把不同模型的调用收敛到一个入口省得你为每个模型单独配一套密钥。操作路径是登录控制台在 API Keys 页面创建一个新密钥复制出来备用。这个 Key 只显示一次建议先粘到临时文本里。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接口基地址统一用https://taotoken.net/api注意这个地址后面不加任何查询参数。文档页在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时对照着看。3. 在 WSL 里装 Node.js 并配置 Codex3.1 Node.js 版本怎么选Codex CLI 要求 Node.js 18 以上。我建议直接上 20 LTS 或 22 LTS原因是 18 已经进入维护末期部分依赖包开始要求更高版本。用 NodeSource 源装比apt自带的版本新命令如下curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node --version npm --version两条都出版本号才算成功。如果node命令找不到检查一下是不是装到了别的 shell 环境里which node看下路径。3.2 安装 Codex CLInpm install -g openai/codex codex -Vcodex -V能输出版本号说明 CLI 本体装好了。如果报permission denied不要用sudo npm install -g那样会把文件属主搞乱。正确做法是配置 npm 的用户级全局目录npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新执行安装命令。3.3 创建配置目录与文件Codex 读取的是用户主目录下的.codex文件夹。在 WSL 里执行mkdir -p ~/.codex接着创建认证文件auth.jsoncat ~/.codex/auth.json EOF { OPENAI_API_KEY: 你的TaoToken密钥 } EOF把你的TaoToken密钥换成第 2.3 步复制的值。注意这里用的是 heredoc 写法不会引入 BOM比在 Windows 记事本里存文件安全得多。再创建config.toml这是 Codex 的主配置model_provider taotoken model gpt-5.1 model_reasoning_effort high disable_response_storage true preferred_auth_method apikey [model_providers.taotoken] name taotoken base_url https://taotoken.net/api wire_api responses几个字段说明一下。model_provider指向下面定义的 provider 名base_url就是 TaoToken 的接口地址末尾不要加斜杠wire_api用responses走的是新版接口协议disable_response_storage关掉服务端存储适合对数据流向有要求的场景。model_reasoning_effort控制推理预算复杂任务用high日常改代码用medium就够简单问答可以降到low。3.4 关于 settings.json 的说明有些教程会提到settings.json那是 Codex 在部分版本里用于存放编辑器侧或会话侧偏好的文件和auth.json、config.toml分工不同。如果你在项目里看到.codex/settings.json它通常放的是项目级覆盖项比如临时切换模型。核心的密钥和 provider 配置仍然以~/.codex/auth.json和~/.codex/config.toml为准。项目级settings.json骨架可以这样写{ model: gpt-5.1, model_reasoning_effort: medium }放在项目根目录的.codex/下只对当前项目生效不会污染全局配置。4. 验证 Codex 能否正常调用 API配置写完别急着开干先做一次连通性验证。在 WSL 终端里进入任意一个项目目录cd ~/your-project codex启动后输入一句最简单的指令比如让它解释当前目录下的某个文件解释一下 package.json 里都定义了什么如果 Codex 能正常返回内容说明 Key、base_url、wire_api 三处都对了。如果卡住不动或者报 401、404按下一节的排查表逐项对。再补一个更直接的验证方式用 curl 打一次接口确认网络层通不通curl -s https://taotoken.net/api/models \ -H Authorization: Bearer 你的TaoToken密钥 | head -c 300能返回模型列表的 JSON 片段就说明 Key 和网络都没问题问题只可能出在 Codex 的配置解析上。5. 本篇常见错误排查5.1 codex 命令找不到先确认which codex有没有输出。没有的话多半是 npm 全局 bin 目录不在 PATH 里。按 3.2 节配置~/.npm-global后重新source ~/.bashrc。如果是在 Windows 的 PowerShell 里直接敲codex那当然找不到Codex 装在 WSL 里必须在 WSL 终端里用。5.2 配置文件读取失败或报编码错误这是 Windows 用户最容易踩的坑。如果你用记事本编辑过auth.json或config.toml文件头可能被塞进 BOMCodex 解析 JSON 时会直接失败。解决办法是全部在 WSL 里用catheredoc 重建或者用 VS Code 的 WSL 远程模式编辑保存时选 UTF-8 无 BOM。5.3 请求返回 401 或 403九成是 Key 的问题。检查auth.json里的值有没有多余空格、引号是否配对、有没有把控制台里显示的掩码当成真实 Key。另外确认preferred_auth_method设成了apikey否则 Codex 可能走别的认证分支。5.4 请求返回 404base_url写错了。正确值是https://taotoken.net/api不要写成https://taotoken.net/api/带尾斜杠也不要自己拼/v1。wire_api要和 provider 支持的协议一致用responses。5.5 WSL 里网络不通先ping taotoken.net看解析。如果 WSL 完全没网检查 Windows 防火墙有没有拦 WSL 的虚拟网卡或者执行wsl --shutdown后重新打开终端。公司网络环境下如果走了特殊出口策略需要按内网规定处理这里不展开。5.6 推理预算改了不生效model_reasoning_effort改完要重启 Codex 进程当前会话不会热加载。另外项目级settings.json会覆盖全局config.toml如果你在项目里改过记得两处对齐。6. 后续怎么用得更顺跑通之后日常使用有几个小习惯能省事。一是把常用项目的启动封装成 alias比如alias cxcd ~/work/api codex省得每次敲路径。二是推理预算按任务分级写业务代码用medium做架构设计或排查疑难 bug 再切high能明显省额度。三是 Key 不要硬编码进任何提交到仓库的文件~/.codex/auth.json在用户目录下天然不会被 git 跟踪这点比放项目里安全。如果你后面要长期跑编码任务或者接 Agent 工作流可以看下 Coding Plan额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想先在网页里试试模型对话效果不用装环境也能验证 Key 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite配置过程中卡在某一类报错直接对照接入文档的字段说明最快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后提醒一句WSL 里的~/.codex和 Windows 用户目录下的%USERPROFILE%\.codex是两个完全独立的位置。你在 WSL 里配好了就别再去 Windows 那边重复配一遍否则容易两边打架排查时也容易看错文件。
Codex Windows 安装指南：WSL 与 Node.js 环境配置 TaoToken 统一 Key
1. Windows 上跑 Codex 到底卡在哪Codex CLI 是一个跑在终端里的编码智能体能读你的项目文件、执行命令、按自然语言指令改代码适合习惯命令行、想让 AI 直接动手改仓库的开发者。但它在 Windows 原生环境下的体验一直不算好路径分隔符、权限模型、npm 全局安装目录、终端编码这几件事凑在一起很容易出现命令找不到、配置文件读不出来、请求发不出去的情况。我自己第一次在 Windows 上装的时候codex -V能出版本号可一进项目就报连接错误排查半天才发现是配置文件编码带了 BOM。所以这篇的路线很明确不在原生 Windows 上硬扛而是先用 WSL 准备一个 Linux 环境再在里面装 Node.js 和 Codex最后把请求通道指向 TaoToken 的统一 Key。这样你既保留了 Windows 的桌面习惯又拿到了 Linux 下稳定的运行环境。整条链路我会给到可直接复制的命令、Node.js 版本选择理由、settings.json与config.toml的配置骨架以及一条能验证 Codex 是否真的调通 API 的测试动作。适合刚接触 Codex、或者装了但一直跑不起来的人跟着做。2. 前置准备WSL 与 TaoToken 统一 Key2.1 为什么优先选 WSL 而不是原生 WindowsCodex CLI 的很多行为依赖 POSIX 语义比如文件权限、符号链接、shell 解析。原生 Windows 下这些都要靠兼容层模拟出问题的概率明显更高。WSL2 本质是一个轻量虚拟机跑的是真正的 Linux 内核Codex 在里面和在 Ubuntu 服务器上没区别。你不需要双系统也不用折腾分区装完重启一次就能用。2.2 安装 WSL以管理员身份打开 PowerShell执行wsl --install这条命令会默认装好 WSL2 和 Ubuntu 发行版。装完必须重启电脑重启后系统会让你设置 Linux 用户名和密码这个密码在后面sudo时会用到记牢。如果你的系统提示wsl --install不可用先执行wsl --update更新一下 WSL 组件。重启后从开始菜单搜索 Ubuntu 或 WSL 打开终端先确认版本wsl --list --verbose看到VERSION是2就对了。如果显示 1用wsl --set-version Ubuntu 2切换。2.3 拿到 TaoToken 统一 KeyCodex 需要一个能接收 OpenAI 兼容请求的通道。TaoToken 提供统一 Key把不同模型的调用收敛到一个入口省得你为每个模型单独配一套密钥。操作路径是登录控制台在 API Keys 页面创建一个新密钥复制出来备用。这个 Key 只显示一次建议先粘到临时文本里。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接口基地址统一用https://taotoken.net/api注意这个地址后面不加任何查询参数。文档页在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时对照着看。3. 在 WSL 里装 Node.js 并配置 Codex3.1 Node.js 版本怎么选Codex CLI 要求 Node.js 18 以上。我建议直接上 20 LTS 或 22 LTS原因是 18 已经进入维护末期部分依赖包开始要求更高版本。用 NodeSource 源装比apt自带的版本新命令如下curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node --version npm --version两条都出版本号才算成功。如果node命令找不到检查一下是不是装到了别的 shell 环境里which node看下路径。3.2 安装 Codex CLInpm install -g openai/codex codex -Vcodex -V能输出版本号说明 CLI 本体装好了。如果报permission denied不要用sudo npm install -g那样会把文件属主搞乱。正确做法是配置 npm 的用户级全局目录npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新执行安装命令。3.3 创建配置目录与文件Codex 读取的是用户主目录下的.codex文件夹。在 WSL 里执行mkdir -p ~/.codex接着创建认证文件auth.jsoncat ~/.codex/auth.json EOF { OPENAI_API_KEY: 你的TaoToken密钥 } EOF把你的TaoToken密钥换成第 2.3 步复制的值。注意这里用的是 heredoc 写法不会引入 BOM比在 Windows 记事本里存文件安全得多。再创建config.toml这是 Codex 的主配置model_provider taotoken model gpt-5.1 model_reasoning_effort high disable_response_storage true preferred_auth_method apikey [model_providers.taotoken] name taotoken base_url https://taotoken.net/api wire_api responses几个字段说明一下。model_provider指向下面定义的 provider 名base_url就是 TaoToken 的接口地址末尾不要加斜杠wire_api用responses走的是新版接口协议disable_response_storage关掉服务端存储适合对数据流向有要求的场景。model_reasoning_effort控制推理预算复杂任务用high日常改代码用medium就够简单问答可以降到low。3.4 关于 settings.json 的说明有些教程会提到settings.json那是 Codex 在部分版本里用于存放编辑器侧或会话侧偏好的文件和auth.json、config.toml分工不同。如果你在项目里看到.codex/settings.json它通常放的是项目级覆盖项比如临时切换模型。核心的密钥和 provider 配置仍然以~/.codex/auth.json和~/.codex/config.toml为准。项目级settings.json骨架可以这样写{ model: gpt-5.1, model_reasoning_effort: medium }放在项目根目录的.codex/下只对当前项目生效不会污染全局配置。4. 验证 Codex 能否正常调用 API配置写完别急着开干先做一次连通性验证。在 WSL 终端里进入任意一个项目目录cd ~/your-project codex启动后输入一句最简单的指令比如让它解释当前目录下的某个文件解释一下 package.json 里都定义了什么如果 Codex 能正常返回内容说明 Key、base_url、wire_api 三处都对了。如果卡住不动或者报 401、404按下一节的排查表逐项对。再补一个更直接的验证方式用 curl 打一次接口确认网络层通不通curl -s https://taotoken.net/api/models \ -H Authorization: Bearer 你的TaoToken密钥 | head -c 300能返回模型列表的 JSON 片段就说明 Key 和网络都没问题问题只可能出在 Codex 的配置解析上。5. 本篇常见错误排查5.1 codex 命令找不到先确认which codex有没有输出。没有的话多半是 npm 全局 bin 目录不在 PATH 里。按 3.2 节配置~/.npm-global后重新source ~/.bashrc。如果是在 Windows 的 PowerShell 里直接敲codex那当然找不到Codex 装在 WSL 里必须在 WSL 终端里用。5.2 配置文件读取失败或报编码错误这是 Windows 用户最容易踩的坑。如果你用记事本编辑过auth.json或config.toml文件头可能被塞进 BOMCodex 解析 JSON 时会直接失败。解决办法是全部在 WSL 里用catheredoc 重建或者用 VS Code 的 WSL 远程模式编辑保存时选 UTF-8 无 BOM。5.3 请求返回 401 或 403九成是 Key 的问题。检查auth.json里的值有没有多余空格、引号是否配对、有没有把控制台里显示的掩码当成真实 Key。另外确认preferred_auth_method设成了apikey否则 Codex 可能走别的认证分支。5.4 请求返回 404base_url写错了。正确值是https://taotoken.net/api不要写成https://taotoken.net/api/带尾斜杠也不要自己拼/v1。wire_api要和 provider 支持的协议一致用responses。5.5 WSL 里网络不通先ping taotoken.net看解析。如果 WSL 完全没网检查 Windows 防火墙有没有拦 WSL 的虚拟网卡或者执行wsl --shutdown后重新打开终端。公司网络环境下如果走了特殊出口策略需要按内网规定处理这里不展开。5.6 推理预算改了不生效model_reasoning_effort改完要重启 Codex 进程当前会话不会热加载。另外项目级settings.json会覆盖全局config.toml如果你在项目里改过记得两处对齐。6. 后续怎么用得更顺跑通之后日常使用有几个小习惯能省事。一是把常用项目的启动封装成 alias比如alias cxcd ~/work/api codex省得每次敲路径。二是推理预算按任务分级写业务代码用medium做架构设计或排查疑难 bug 再切high能明显省额度。三是 Key 不要硬编码进任何提交到仓库的文件~/.codex/auth.json在用户目录下天然不会被 git 跟踪这点比放项目里安全。如果你后面要长期跑编码任务或者接 Agent 工作流可以看下 Coding Plan额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想先在网页里试试模型对话效果不用装环境也能验证 Key 是否可用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite配置过程中卡在某一类报错直接对照接入文档的字段说明最快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后提醒一句WSL 里的~/.codex和 Windows 用户目录下的%USERPROFILE%\.codex是两个完全独立的位置。你在 WSL 里配好了就别再去 Windows 那边重复配一遍否则容易两边打架排查时也容易看错文件。
