1. 为什么要在 WSL2 Ubuntu 里跑 CodexCodex 是 OpenAI 推出的命令行编程助手能读项目、改代码、跑测试、做代码审查适合把它当成一个待在终端里的结对程序员。它原生面向类 Unix 环境在 Windows 上直接跑会遇到路径分隔符、权限模型、符号链接这几类麻烦所以更稳的做法是把它装进 WSL2 的 Ubuntu 里再用 VS Code 的 WSL 远程模式做联调。这篇教程解决的就是这条链路Windows 上确认 WSL2、在 Ubuntu 里装好 Codex、把请求通道切到 TaoToken 的统一 Key最后在 VS Code 里验证一次完整调用。适合三类人一是刚接触 Codex、想在本机跑通工作流的开发者二是已经在用 VS Code 远程开发、想把 AI 助手接进现有项目的人三是手里有多个模型服务、希望用一个 Key 统一管理调用入口的团队。我试过把项目放在/mnt/c下直接跑文件监听和 git 操作都明显变慢后来统一挪到~/code才顺畅。所以下面所有路径示例都以 Linux 家目录为基准你照着敲就行。先明确一个概念Codex CLI 本身是客户端它需要一个模型服务来响应请求。默认它走 ChatGPT 登录但很多团队希望用统一的 API 通道方便计费和切换模型。TaoToken 提供的就是这样一个统一入口一个 Key 可以对接多种模型配置方式兼容 OpenAI 风格的 Base URL。下面会把它作为 Codex 的后端通道来接。整个流程分四步确认 WSL 版本、装 Codex、配置 TaoToken 通道、VS Code 联调验证。每一步都有可复制的命令和配置片段遇到报错在第五节对照排查。2. 前置准备WSL2 版本确认与 TaoToken Key 获取这一节做两件事把 Windows 侧的 WSL2 环境确认好再去 TaoToken 拿一个可用的 API Key。顺序不要颠倒因为 Codex 新版已经不支持 WSL1版本不对后面全白搭。2.1 确认并切换到 WSL2打开 Windows PowerShell不是 CMD运行wsl -l -v输出里会列出已安装的发行版和版本号。如果 Ubuntu 那一列显示1执行转换wsl --set-version Ubuntu 2转换过程可能要几分钟取决于发行版大小。如果提示没有安装任何发行版先装一个wsl --install -d Ubuntu装完重启一次再回到wsl -l -v确认版本是 2。这一步是整个教程的地基版本错了后面 Codex 启动会直接报环境不支持。2.2 进入 Ubuntu 并更新基础工具在 PowerShell 里输入wsl回车就进入 Ubuntu 终端。先更新包索引并装好 curl 和 gitsudo apt update sudo apt install -y curl gitcurl用来下载安装脚本git用来克隆项目两个都是后面要用的。装完可以用git --version和curl --version确认。2.3 获取 TaoToken 统一 Key打开 TaoToken 官网注册后在控制台的 API Keys 页面创建一个新 Key。建议按用途命名比如codex-wsl方便以后区分。创建后立刻复制保存页面刷新后通常不再完整显示。拿到 Key 之后先别急着写进配置用一条 curl 验证它能不能通curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的Key返回一个模型列表的 JSON 就说明 Key 有效、网络可达。如果返回 401说明 Key 复制错了或者被禁用回控制台重新生成一个。这一步提前排掉鉴权问题后面配置 Codex 时就不会把网络问题和配置问题混在一起。TaoToken 的 API 入口是https://taotoken.net/api注意配置 Base URL 时通常要带上/v1具体以文档为准。控制台、API Keys、接入文档这几个页面建议都收藏一下排障时会反复用到。3. 安装 Codex 并写入 TaoToken 配置片段环境确认完这一节装 Codex 并把它指向 TaoToken。核心是三个东西Base URL、API Key、Model ID缺一个都跑不起来。3.1 安装 Codex CLI在 Ubuntu 终端里执行官方安装脚本curl -fsSL https://chatgpt.com/codex/install.sh | sh装完检查版本codex --version能打印出版本号就说明二进制装好了。如果提示command not found多半是安装目录没进 PATH重新开一个终端窗口或者手动把~/.local/bin之类目录加进 PATH。3.2 写入 TaoToken 配置Codex 支持通过配置文件指定模型服务。在用户目录下创建配置目录和文件mkdir -p ~/.codex然后编辑~/.codex/config.toml写入下面这段。注意把你的Key换成上一步拿到的真实 Keymodel gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY wire_api chat这段配置做了三件事声明默认模型、定义一个叫taotoken的 provider、把 Base URL 指向 TaoToken 的 API 入口。env_key表示 Key 从环境变量读取不硬编码在文件里更安全。接着把 Key 写进 shell 环境变量。编辑~/.bashrcecho export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc验证变量生效echo $TAOTOKEN_API_KEY能打印出 Key 就对了。如果你用的是 zsh把上面~/.bashrc换成~/.zshrc。3.3 三件套对照表配置里最容易出错的就是这三个值的对应关系单独列出来对照配置项值说明Base URLhttps://taotoken.net/api/v1请求入口注意带/v1API Key控制台生成的 Key通过TAOTOKEN_API_KEY环境变量注入Model ID如gpt-4o必须是 TaoToken 支持的模型名这三者必须同时正确。Base URL 错会连不上Key 错会 401Model ID 错会返回模型不存在。排障时按这个顺序逐个核对。3.4 项目目录建议把代码放在 Linux 家目录下不要放/mnt/cmkdir -p ~/code cd ~/code git clone 你的仓库地址 cd 项目目录/mnt/c是 Windows 文件系统挂载点跨系统访问会带来性能损耗和权限、符号链接问题。放在~/code下Codex 的文件操作和 git 命令都会正常很多。4. 启动 Codex 并验证一次完整调用链路配置写完这一节做实际验证。目标是看到 Codex 成功响应一次请求证明从终端到 TaoToken 的整条链路是通的。4.1 启动并检查状态在项目目录下运行codex第一次启动时如果配置正确它会直接使用config.toml里的 provider不再强制走 ChatGPT 登录。进入交互界面后先看状态/status这里会显示当前使用的模型和 provider。确认 provider 是taotoken、模型是你配置的那个。如果显示的还是默认 ChatGPT说明配置文件没被读到检查~/.codex/config.toml路径和格式。4.2 发一条真实请求在交互界面里输入一个具体任务比如解释一下这个项目的目录结构并指出入口文件Codex 会读取项目文件、组织上下文然后返回分析结果。看到它准确说出你的目录和入口文件就说明模型调用成功了。这一步同时验证了三件事网络通、鉴权过、模型可用。如果想让 Codex 先熟悉项目可以运行/init它会生成一个AGENTS.md把项目说明固化下来后续对话质量会更稳。4.3 常用命令速查跑通之后这几个命令会经常用到/status 查看当前会话状态 /model 切换模型和推理强度 /permissions 设置文件和命令权限 /review 审查代码改动/permissions建议一开始设保守一点只允许读和必要写操作确认行为符合预期后再放开。4.4 VS Code 远程联调Windows 侧装好 VS Code 和 WSL 扩展后在 Ubuntu 项目目录里运行code .VS Code 会以 WSL 远程模式打开项目。左下角应显示WSL: Ubuntu集成终端的路径应是/home/...开头。在集成终端里再跑一次codex确认在 VS Code 环境下同样能正常响应。这样你就有了一个完整工作流VS Code 里写代码集成终端里用 Codex 做分析和修改两边共享同一个 Linux 文件系统不会出现路径不一致的问题。5. 常见报错排查401、local proxy failed 与模型不存在配置过程中最容易卡在几个固定报错上这一节按现象对照原因逐个解决。5.1 401 Unauthorized现象请求返回 401或者 Codex 提示鉴权失败。原因通常是 Key 没被正确读取。先在终端确认环境变量echo $TAOTOKEN_API_KEY如果为空说明~/.bashrc没生效重新source一次或者检查是不是写进了错误的 shell 配置文件。如果变量有值但仍 401用 curl 单独测一次curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEYcurl 也 401就是 Key 本身的问题回控制台重新生成。curl 能通但 Codex 不通检查config.toml里env_key的名字是否和实际环境变量名完全一致大小写敏感。5.2 local proxy failed现象提示本地代理失败或连接被拒绝。这类报错多半是 Base URL 写错或者本机有残留的代理环境变量干扰。先检查配置里的base_url是不是https://taotoken.net/api/v1有没有多写或少写/v1。再检查环境变量env | grep -i proxy如果有HTTP_PROXY、HTTPS_PROXY之类的残留值临时清掉再试unset HTTP_PROXY HTTPS_PROXY5.3 reading choices 相关报错现象解析响应时提示读取choices字段失败。这通常是wire_api配置和实际接口不匹配。TaoToken 走 OpenAI 兼容格式时wire_api应设为chat。如果设成了别的值响应结构对不上就会解析失败。改回chat后重启 Codex。5.4 模型不存在现象提示 model not found 或类似信息。说明config.toml里的model值不是 TaoToken 支持的模型名。用 5.1 里的 curl 命令拉一次模型列表从返回结果里挑一个准确的 ID 填进去。模型名区分大小写别凭记忆写。5.5 OAuth 登录相关提示现象启动时仍提示登录 ChatGPT 或 OAuth 流程。说明 Codex 没读到你的 provider 配置回退到了默认登录方式。检查~/.codex/config.toml是否存在、model_provider是否指向taotoken、TOML 格式有没有语法错误比如引号不配对。改完重新启动 Codex。5.6 终端输出内容丢失如果 Codex 输出时前面内容被截断或丢失多半是终端工具的问题。换一个终端试试比如用 Git Bash 或 VS Code 集成终端通常就正常了。这属于显示层问题不影响实际调用。6. 把 Codex 接进日常开发流链路跑通只是起点真正省时间的是把它嵌进日常节奏。几个实际用下来比较顺的做法。项目初始化时跑一次/init生成AGENTS.md把技术栈、目录约定、测试命令写进去。之后每次对话 Codex 都会参考这份说明回答更贴合项目不用反复解释背景。改代码前先让它读比如「看一下src/api下的请求封装指出错误处理缺失的地方」。确认它的理解对了再让它动手改。这样能避免它基于错误理解直接改文件。提交前用/review过一遍改动它会指出潜在问题。配合/permissions控制它能碰哪些文件初期建议只给读权限确认行为稳定后再逐步放开写权限。模型选择上简单任务用轻量模型复杂重构再切到推理更强的模型用/model随时切换。TaoToken 的统一 Key 在这里的好处是不用为每个模型单独配一套鉴权切换成本低。最后提醒一点项目始终放在~/code这类 Linux 路径下VS Code 用 WSL 远程模式打开终端和编辑器共享同一文件系统。这套组合跑顺之后Windows 上的开发体验和原生 Linux 基本没差别Codex 也能稳定工作。
1. 为什么要在 WSL2 Ubuntu 里跑 CodexCodex 是 OpenAI 推出的命令行编程助手能读项目、改代码、跑测试、做代码审查适合把它当成一个待在终端里的结对程序员。它原生面向类 Unix 环境在 Windows 上直接跑会遇到路径分隔符、权限模型、符号链接这几类麻烦所以更稳的做法是把它装进 WSL2 的 Ubuntu 里再用 VS Code 的 WSL 远程模式做联调。这篇教程解决的就是这条链路Windows 上确认 WSL2、在 Ubuntu 里装好 Codex、把请求通道切到 TaoToken 的统一 Key最后在 VS Code 里验证一次完整调用。适合三类人一是刚接触 Codex、想在本机跑通工作流的开发者二是已经在用 VS Code 远程开发、想把 AI 助手接进现有项目的人三是手里有多个模型服务、希望用一个 Key 统一管理调用入口的团队。我试过把项目放在/mnt/c下直接跑文件监听和 git 操作都明显变慢后来统一挪到~/code才顺畅。所以下面所有路径示例都以 Linux 家目录为基准你照着敲就行。先明确一个概念Codex CLI 本身是客户端它需要一个模型服务来响应请求。默认它走 ChatGPT 登录但很多团队希望用统一的 API 通道方便计费和切换模型。TaoToken 提供的就是这样一个统一入口一个 Key 可以对接多种模型配置方式兼容 OpenAI 风格的 Base URL。下面会把它作为 Codex 的后端通道来接。整个流程分四步确认 WSL 版本、装 Codex、配置 TaoToken 通道、VS Code 联调验证。每一步都有可复制的命令和配置片段遇到报错在第五节对照排查。2. 前置准备WSL2 版本确认与 TaoToken Key 获取这一节做两件事把 Windows 侧的 WSL2 环境确认好再去 TaoToken 拿一个可用的 API Key。顺序不要颠倒因为 Codex 新版已经不支持 WSL1版本不对后面全白搭。2.1 确认并切换到 WSL2打开 Windows PowerShell不是 CMD运行wsl -l -v输出里会列出已安装的发行版和版本号。如果 Ubuntu 那一列显示1执行转换wsl --set-version Ubuntu 2转换过程可能要几分钟取决于发行版大小。如果提示没有安装任何发行版先装一个wsl --install -d Ubuntu装完重启一次再回到wsl -l -v确认版本是 2。这一步是整个教程的地基版本错了后面 Codex 启动会直接报环境不支持。2.2 进入 Ubuntu 并更新基础工具在 PowerShell 里输入wsl回车就进入 Ubuntu 终端。先更新包索引并装好 curl 和 gitsudo apt update sudo apt install -y curl gitcurl用来下载安装脚本git用来克隆项目两个都是后面要用的。装完可以用git --version和curl --version确认。2.3 获取 TaoToken 统一 Key打开 TaoToken 官网注册后在控制台的 API Keys 页面创建一个新 Key。建议按用途命名比如codex-wsl方便以后区分。创建后立刻复制保存页面刷新后通常不再完整显示。拿到 Key 之后先别急着写进配置用一条 curl 验证它能不能通curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的Key返回一个模型列表的 JSON 就说明 Key 有效、网络可达。如果返回 401说明 Key 复制错了或者被禁用回控制台重新生成一个。这一步提前排掉鉴权问题后面配置 Codex 时就不会把网络问题和配置问题混在一起。TaoToken 的 API 入口是https://taotoken.net/api注意配置 Base URL 时通常要带上/v1具体以文档为准。控制台、API Keys、接入文档这几个页面建议都收藏一下排障时会反复用到。3. 安装 Codex 并写入 TaoToken 配置片段环境确认完这一节装 Codex 并把它指向 TaoToken。核心是三个东西Base URL、API Key、Model ID缺一个都跑不起来。3.1 安装 Codex CLI在 Ubuntu 终端里执行官方安装脚本curl -fsSL https://chatgpt.com/codex/install.sh | sh装完检查版本codex --version能打印出版本号就说明二进制装好了。如果提示command not found多半是安装目录没进 PATH重新开一个终端窗口或者手动把~/.local/bin之类目录加进 PATH。3.2 写入 TaoToken 配置Codex 支持通过配置文件指定模型服务。在用户目录下创建配置目录和文件mkdir -p ~/.codex然后编辑~/.codex/config.toml写入下面这段。注意把你的Key换成上一步拿到的真实 Keymodel gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY wire_api chat这段配置做了三件事声明默认模型、定义一个叫taotoken的 provider、把 Base URL 指向 TaoToken 的 API 入口。env_key表示 Key 从环境变量读取不硬编码在文件里更安全。接着把 Key 写进 shell 环境变量。编辑~/.bashrcecho export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc验证变量生效echo $TAOTOKEN_API_KEY能打印出 Key 就对了。如果你用的是 zsh把上面~/.bashrc换成~/.zshrc。3.3 三件套对照表配置里最容易出错的就是这三个值的对应关系单独列出来对照配置项值说明Base URLhttps://taotoken.net/api/v1请求入口注意带/v1API Key控制台生成的 Key通过TAOTOKEN_API_KEY环境变量注入Model ID如gpt-4o必须是 TaoToken 支持的模型名这三者必须同时正确。Base URL 错会连不上Key 错会 401Model ID 错会返回模型不存在。排障时按这个顺序逐个核对。3.4 项目目录建议把代码放在 Linux 家目录下不要放/mnt/cmkdir -p ~/code cd ~/code git clone 你的仓库地址 cd 项目目录/mnt/c是 Windows 文件系统挂载点跨系统访问会带来性能损耗和权限、符号链接问题。放在~/code下Codex 的文件操作和 git 命令都会正常很多。4. 启动 Codex 并验证一次完整调用链路配置写完这一节做实际验证。目标是看到 Codex 成功响应一次请求证明从终端到 TaoToken 的整条链路是通的。4.1 启动并检查状态在项目目录下运行codex第一次启动时如果配置正确它会直接使用config.toml里的 provider不再强制走 ChatGPT 登录。进入交互界面后先看状态/status这里会显示当前使用的模型和 provider。确认 provider 是taotoken、模型是你配置的那个。如果显示的还是默认 ChatGPT说明配置文件没被读到检查~/.codex/config.toml路径和格式。4.2 发一条真实请求在交互界面里输入一个具体任务比如解释一下这个项目的目录结构并指出入口文件Codex 会读取项目文件、组织上下文然后返回分析结果。看到它准确说出你的目录和入口文件就说明模型调用成功了。这一步同时验证了三件事网络通、鉴权过、模型可用。如果想让 Codex 先熟悉项目可以运行/init它会生成一个AGENTS.md把项目说明固化下来后续对话质量会更稳。4.3 常用命令速查跑通之后这几个命令会经常用到/status 查看当前会话状态 /model 切换模型和推理强度 /permissions 设置文件和命令权限 /review 审查代码改动/permissions建议一开始设保守一点只允许读和必要写操作确认行为符合预期后再放开。4.4 VS Code 远程联调Windows 侧装好 VS Code 和 WSL 扩展后在 Ubuntu 项目目录里运行code .VS Code 会以 WSL 远程模式打开项目。左下角应显示WSL: Ubuntu集成终端的路径应是/home/...开头。在集成终端里再跑一次codex确认在 VS Code 环境下同样能正常响应。这样你就有了一个完整工作流VS Code 里写代码集成终端里用 Codex 做分析和修改两边共享同一个 Linux 文件系统不会出现路径不一致的问题。5. 常见报错排查401、local proxy failed 与模型不存在配置过程中最容易卡在几个固定报错上这一节按现象对照原因逐个解决。5.1 401 Unauthorized现象请求返回 401或者 Codex 提示鉴权失败。原因通常是 Key 没被正确读取。先在终端确认环境变量echo $TAOTOKEN_API_KEY如果为空说明~/.bashrc没生效重新source一次或者检查是不是写进了错误的 shell 配置文件。如果变量有值但仍 401用 curl 单独测一次curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEYcurl 也 401就是 Key 本身的问题回控制台重新生成。curl 能通但 Codex 不通检查config.toml里env_key的名字是否和实际环境变量名完全一致大小写敏感。5.2 local proxy failed现象提示本地代理失败或连接被拒绝。这类报错多半是 Base URL 写错或者本机有残留的代理环境变量干扰。先检查配置里的base_url是不是https://taotoken.net/api/v1有没有多写或少写/v1。再检查环境变量env | grep -i proxy如果有HTTP_PROXY、HTTPS_PROXY之类的残留值临时清掉再试unset HTTP_PROXY HTTPS_PROXY5.3 reading choices 相关报错现象解析响应时提示读取choices字段失败。这通常是wire_api配置和实际接口不匹配。TaoToken 走 OpenAI 兼容格式时wire_api应设为chat。如果设成了别的值响应结构对不上就会解析失败。改回chat后重启 Codex。5.4 模型不存在现象提示 model not found 或类似信息。说明config.toml里的model值不是 TaoToken 支持的模型名。用 5.1 里的 curl 命令拉一次模型列表从返回结果里挑一个准确的 ID 填进去。模型名区分大小写别凭记忆写。5.5 OAuth 登录相关提示现象启动时仍提示登录 ChatGPT 或 OAuth 流程。说明 Codex 没读到你的 provider 配置回退到了默认登录方式。检查~/.codex/config.toml是否存在、model_provider是否指向taotoken、TOML 格式有没有语法错误比如引号不配对。改完重新启动 Codex。5.6 终端输出内容丢失如果 Codex 输出时前面内容被截断或丢失多半是终端工具的问题。换一个终端试试比如用 Git Bash 或 VS Code 集成终端通常就正常了。这属于显示层问题不影响实际调用。6. 把 Codex 接进日常开发流链路跑通只是起点真正省时间的是把它嵌进日常节奏。几个实际用下来比较顺的做法。项目初始化时跑一次/init生成AGENTS.md把技术栈、目录约定、测试命令写进去。之后每次对话 Codex 都会参考这份说明回答更贴合项目不用反复解释背景。改代码前先让它读比如「看一下src/api下的请求封装指出错误处理缺失的地方」。确认它的理解对了再让它动手改。这样能避免它基于错误理解直接改文件。提交前用/review过一遍改动它会指出潜在问题。配合/permissions控制它能碰哪些文件初期建议只给读权限确认行为稳定后再逐步放开写权限。模型选择上简单任务用轻量模型复杂重构再切到推理更强的模型用/model随时切换。TaoToken 的统一 Key 在这里的好处是不用为每个模型单独配一套鉴权切换成本低。最后提醒一点项目始终放在~/code这类 Linux 路径下VS Code 用 WSL 远程模式打开终端和编辑器共享同一文件系统。这套组合跑顺之后Windows 上的开发体验和原生 Linux 基本没差别Codex 也能稳定工作。
