1. 为什么要在 Windows 11 上折腾 WSL2 Docker Codex 这套组合如果你平时主力机是 Windows 11又想跑 Codex CLI 这类偏 Linux 生态的 AI 开发工具直接在 PowerShell 里硬装往往会遇到路径、权限、依赖一堆问题。WSL2 的价值就在于它给你一个几乎原生的 Linux 内核Ubuntu 里的 Docker、Node、Git 全部按 Linux 习惯工作而 Windows 这边只负责图形界面和文件互访。这套「Windows 11 WSL2 Ubuntu Docker Codex Sub2API」的组合本质上是把本地 AI 开发环境拆成两层Windows 管桌面Ubuntu 管服务。Codex CLI 是 OpenAI 官方出的命令行编码助手安装后通过codex login走浏览器授权默认会把凭证写进~/.codex/auth.json。问题在于很多开发者希望把请求统一收口到自己的网关方便做密钥管理、用量统计和多模型切换这时候就需要把auth.json里的接入地址改掉。Sub2API 就是干这个的——它是一个本地 API 网关用 Docker 部署能把上游模型请求转发出去同时给你一个 Web 后台看调用情况。这篇教程面向的是已经会用基本命令行、但没在 WSL2 里完整搭过这套链路的开发者。我会从开启 WSL2 开始一路走到 Codex 的auth.json改到 TaoToken 并验证连通。全程命令都可以直接复制遇到报错我在第 5 节列了对照表。适合谁想在 Windows 上做本地 AI 容器环境、又不想把机器搞乱的开发者不适合谁只想点几下鼠标就完事、完全不碰终端的人。先说清楚一个前提TaoToken 在这里扮演的是「统一接入层」的角色Codex 通过它拿到模型能力Sub2API 负责本地转发和观测。三者关系是 Codex → Sub2API本地→ TaoToken接入→ 模型。你完全可以跳过 Sub2API 直接让 Codex 连 TaoToken但加上 Sub2API 后本地调试和日志会清楚很多。2. TaoToken 前置准备拿 Key、认接口、理清 auth.json 要改什么在动 Codex 之前先把 TaoToken 这边的准备工作做完否则后面改完auth.json还是会 401。你需要三样东西一个可用的 API Key、Base URL、以及要调用的 Model ID。这三件套在 Codex 的配置里缺一不可很多人只改了地址没改模型名结果请求发出去报model not found。第一步打开 TaoToken 官网注册并登录。地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册流程很常规邮箱加密码即可。登录后进入控制台找到 API Keys 页面新建一个 Key。建议给这个 Key 起个能认出来的名字比如wsl2-codex-local方便以后在用量列表里区分。Key 只在创建时完整显示一次复制后先存到安全的地方。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为base_url使用。Codex 的auth.json里通常有一个base_url字段把它指向这里即可。如果你用的是兼容 OpenAI 协议的客户端一般填到/v1之前具体看客户端要求Codex 这边按下面给的片段填就行。第三步确定 Model ID。进模型对话页面可以看到当前可用的模型列表选一个你常用的比如gpt-4o或claude-3-5-sonnet这类。把模型名记下来后面写进配置。这里有个坑不同模型对参数的支持不一样Codex 默认会带一些字段如果模型不支持可能会报参数错误遇到就换模型试。第四步理解auth.json的结构。Codex 登录后生成的auth.json大致长这样字段名以你本地实际为准{ OPENAI_API_KEY: sk-xxxxxxxx, base_url: https://api.openai.com/v1, model: gpt-4o }我们要做的就是把这个文件里的OPENAI_API_KEY换成 TaoToken 的 Keybase_url换成 TaoToken 的地址model换成你要用的模型。改之前先备份原文件cp ~/.codex/auth.json ~/.codex/auth.json.bak出问题能回滚。如果你还想用 Sub2API 做本地转发那base_url就先指向本地网关比如http://localhost:8787/v1然后在 Sub2API 的后台里把上游配成 TaoToken。这样 Codex 的请求先到本地再到 TaoToken。两种方式都行看你是否需要本地日志。3. 可复制配置从 WSL2 安装到 auth.json 落地这一节是整篇的核心命令按顺序执行即可。我按「Windows 侧 → Ubuntu 侧 → Docker → Codex」的顺序排你跟着敲不会乱。3.1 Windows 11 开启 WSL2 并装 Ubuntu以管理员身份打开 PowerShell开始菜单搜 PowerShell右键「以管理员身份运行」执行wsl.exe --install如果之前装过旧版本先更新wsl.exe --update这条命令会自动下载 Ubuntu 并设为默认发行版完成后重启电脑。重启后 Ubuntu 会自动弹出终端提示Enter new UNIX username:输入admin然后设置密码输入时不显示正常现象。装完在 PowerShell 里验证wsl --list --verbose看到Ubuntu Running 2就说明 WSL2 生效了。如果 VERSION 显示 1执行wsl --set-version Ubuntu 2切换。3.2 Ubuntu 基础环境与 Node.js 20进入 UbuntuPowerShell 敲wsl或开始菜单搜 Ubuntu先更新系统sudo apt update sudo apt upgrade -y sudo apt install -y git curl wget unzip nano装 Node.js 20curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v3.3 Docker Desktop 与 WSL 集成去 Docker 官网下载 Docker Desktop for Windows 安装。装完打开进Settings → Resources → WSL Integration把 Ubuntu 的开关打开点Apply Restart。回到 Ubuntu 验证docker version能看到 Client 和 Server 两段就说明联动成功。3.4 安装 Codex CLI 并生成 auth.jsonnpm install -g openai/codex codex --version codex logincodex login会拉起浏览器授权完成后~/.codex/auth.json就生成了。先备份cp ~/.codex/auth.json ~/.codex/auth.json.bak3.5 把 auth.json 改到 TaoToken用 nano 编辑nano ~/.codex/auth.json替换成下面这份配置Key 换成你自己的{ OPENAI_API_KEY: sk-你的TaoToken密钥, base_url: https://taotoken.net/api, model: gpt-4o }保存退出CtrlO 回车CtrlX。如果你走 Sub2API 本地转发base_url改成http://localhost:8787/v1然后在 Sub2API 后台把上游地址配成 TaoToken。3.6 Sub2API 的 Docker 部署可选但推荐克隆项目并进部署目录cd ~ git clone https://github.com/Wei-Shaw/sub2api.git cd sub2api/deploy执行官方部署脚本curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash脚本会自动生成.env、密钥和数据库目录。启动容器docker compose -f docker-compose.local.yml up -d docker ps看管理员密码docker compose -f docker-compose.local.yml logs sub2api | grep admin password后台默认在http://localhost:8080建议改端口避免冲突编辑.env里的SERVER_PORT8787然后docker compose down docker compose up -d。登录邮箱adminsub2api.local密码用日志里那个。3.7 目录结构与日常流程建议所有项目放~/projectsmkdir -p ~/projects cd ~/projects以后 Git、Docker、Codex 项目都丢这里备份和迁移都方便。4. 验证请求确认 Codex 真的走通了 TaoToken配置改完不代表通了必须实际发一次请求。最直接的方式是用 Codex 跑一个最小任务同时观察返回内容。先确认auth.json内容正确cat ~/.codex/auth.json检查base_url是不是https://taotoken.net/apiKey 有没有多余空格。然后跑一个简单提问codex 用一句话解释什么是 WSL2如果返回了正常回答说明链路通了。如果走 Sub2API同时开一个终端看日志docker compose -f docker-compose.local.yml logs -f sub2api你应该能在日志里看到一条进来的请求记录包含模型名和状态码 200。这一步很关键它证明请求确实经过了本地网关。再验证一下模型是否按你配的走。在 Codex 里问一个只有特定模型才知道的问题或者直接看 Sub2API 后台的调用记录模型名应该和你auth.json里写的一致。如果发现模型名不对回去检查配置有没有被其他配置文件覆盖Codex 有时会读环境变量OPENAI_API_KEY用env | grep OPENAI查一下有没有冲突。还有一种验证方式是用 curl 直接打 TaoToken 的接口排除 Codex 本身的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:ping}]}返回带choices的 JSON 就说明 Key 和地址都没问题。这一步能快速区分是 Codex 配置问题还是 TaoToken 侧问题。实测下来最容易出问题的是base_url结尾的斜杠。有的客户端要求带/v1有的不要Codex 这边按https://taotoken.net/api填即可多一个斜杠可能就 404。验证通过后建议把这份auth.json也备份一份到~/projects下重装系统时直接恢复。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来你遇到哪个对哪个。401 Unauthorized九成是 Key 问题。先cat ~/.codex/auth.json看 Key 有没有复制全、有没有换行符。然后确认这个 Key 在 TaoToken 控制台里是启用状态、没过期、额度没用完。如果走 Sub2API检查 Sub2API 后台里配的上游 Key 是不是同一个。还有一种情况是环境变量OPENAI_API_KEY覆盖了文件里的值unset OPENAI_API_KEY再试。local proxy failed / connection refused这是 Codex 连不上你配的base_url。如果指向http://localhost:8787/v1先docker ps看 Sub2API 容器在不在跑curl http://localhost:8787能不能通。WSL2 里 localhost 转发有时会抽风试试用127.0.0.1代替localhost。如果指向 TaoToken 还报这个检查网络和 DNScurl -v https://taotoken.net/api看握手是否正常。reading choices / unexpected response说明请求发出去了但返回的 JSON 结构不对。常见原因是base_url少写或多写了/v1导致打到了错误的路径。Codex 期望的是 OpenAI 兼容格式确认 TaoToken 的地址填对。另一个原因是模型名写错返回了错误对象而不是choices数组回去核对 Model ID。OAuth 相关报错codex login走的是浏览器 OAuth如果卡在授权页或报 token 交换失败先确认系统时间准确WSL2 时间漂移会导致 token 校验失败执行sudo hwclock -s同步。如果之前登录过又改了配置删掉~/.codex/auth.json重新codex login再改。注意改到 TaoToken 后就不需要再走 OAuth 了直接用 Key 即可。Docker 相关docker: command not found说明 WSL Integration 没开回 Docker Desktop 设置里勾 Ubuntu。port is already allocated是端口占用改.env里的SERVER_PORT。permission denied加sudo或把用户加进 docker 组sudo usermod -aG docker $USER然后重开终端。WSL 启动失败管理员 PowerShell 执行wsl --shutdown等几秒再wsl。如果还不行wsl --update更新内核。排查顺序建议先 curl 直连 TaoToken 确认 Key 和地址再 curl 本地 Sub2API 确认网关最后跑 Codex。逐层排除比一上来就怀疑 Codex 快得多。6. 把链路固定下来日常使用与后续接入环境搭好之后日常使用其实很简单。每次开机Windows 这边不用管进 Ubuntu 敲wslDocker Desktop 会自动把 WSL 集成拉起来。检查一下docker psSub2API 容器如果在跑就直接用 Codex。如果没跑cd ~/sub2api/deploy docker compose -f docker-compose.local.yml up -d一条命令起来。Codex 的auth.json改好后就固定了除非换 Key 或换模型否则不用再动。建议把这份配置和 Sub2API 的.env一起放进~/projects做版本管理换机器时直接恢复。模型方面TaoToken 控制台里可以随时看用量Codex 的每次调用都会记进去方便你估算消耗。如果你后面想接更多工具比如 Cline、Claude Code 这类思路是一样的Base URL 填 https://taotoken.net/api Key 用同一个Model ID 按需选。Codex 这边因为用的是auth.json改起来最直接。需要长期跑编码任务或 Agent 的可以了解下 Coding Plan适合高频调用场景只是偶尔验证模型的用模型对话页面就够了。接入文档在 https://taotoken.net/api 旁边能找到遇到协议细节可以对照。最后提醒一句auth.json里存的是明文 Key别把它提交到 Git 仓库。.gitignore里加上auth.json和.env这是很多人踩过的坑。环境搭一次能用很久把命令存成脚本下次重装十分钟就能恢复。