1. 为什么要在 Windows 11 上折腾 Sub2API Codex CLI如果你在 Windows 11 上写代码又想用 Codex CLI 这类命令行 AI 编程工具大概率会遇到一个尴尬Codex CLI 官方对 Windows 原生支持并不算顺滑很多依赖和脚本默认按 Linux 环境设计。而 Sub2API 这类自建 API 聚合服务又需要 Docker、PostgreSQL、Redis 一整套容器编排。把这两件事塞进 Windows 11最省心的路径就是 WSL2。WSL2 是 Windows 11 自带的 Linux 子系统本质是一个轻量虚拟机能跑完整的 Ubuntu 内核。你可以在里面装 Docker、跑容器、装 Node.js同时用 Windows 的浏览器访问服务。Sub2API 则是一个开源的 API 聚合与分发服务能把多个上游模型账号统一成一个 API Key 对外提供Codex CLI 只要指向这个统一入口就能用。这套组合适合谁适合手头有多个模型账号、想让 Codex CLI 走统一通道的开发者也适合想在自己机器上做本地 API 网关实验的技术爱好者。整条链路是Windows 11 → WSL2 Ubuntu → Docker 跑 Sub2API → Codex CLI 通过统一 Key 接入。下面我从零开始把每一步的命令和配置都写清楚。2. 前置准备WSL2、Docker 与 TaoToken 统一 Key2.1 启用 WSL2 并安装 Ubuntu在 Windows 11 里以管理员身份打开 PowerShell执行wsl --install这条命令会自动启用虚拟机平台、安装 WSL2 内核并拉取 Ubuntu。重启计算机后系统会弹出 Ubuntu 初始化窗口按提示创建 Linux 用户名和密码。装完后验证版本wsl -l -v如果 Ubuntu 的 VERSION 显示为 1手动升级wsl --set-default-version 2 wsl --set-version Ubuntu 2进入 Ubuntu 环境并更新基础工具wsl sudo apt update sudo apt upgrade -y sudo apt install -y curl git ca-certificates nano openssl2.2 安装 Docker新手最省事的方案是 Docker Desktop for Windows。安装后在 Settings → General 勾选 Use the WSL 2 based engine再到 Settings → Resources → WSL Integration 里开启你的 Ubuntu 集成。回到 Ubuntu 终端验证docker version docker compose version docker run hello-world如果你不想装 Docker Desktop也可以在 Ubuntu 内直接安装 Docker Engine前提是 WSL 已启用 systemd。两种方式选一种即可后面都用docker compose操作。2.3 TaoToken 统一 Key 的定位Sub2API 负责把上游账号聚合成一个入口而 TaoToken 在这里扮演的是统一 Key 与 API 通道的角色。你可以把它理解成一把总钥匙Codex CLI 不需要分别配置多个上游只要拿到一个统一 Key指向统一 API 地址就能完成模型调用。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址不带 UTMhttps://taotoken.net/api需要先去控制台创建 API Key后面配置 Codex CLI 时会用到。创建入口在 API Keys 页面文档在接入文档里遇到鉴权问题优先翻这两处。3. 可复制配置部署 Sub2API 并接入 Codex CLI3.1 用 Docker Compose 部署 Sub2API在 Ubuntu 里建目录并拉取部署脚本mkdir -p ~/apps/sub2api-deploy cd ~/apps/sub2api-deploy curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash启动服务并查看状态docker compose up -d docker compose ps docker compose logs -f sub2api浏览器打开http://localhost:8080进入安装向导。如果 Windows 浏览器访问不了先拿 WSL 的 IPhostname -I然后用http://WSL_IP:8080访问。向导里按提示填数据库、Redis 和管理员账号Docker Compose 版本已内置 PostgreSQL 和 Redis 容器默认配置通常够用。3.2 Sub2API 后台基础配置进入后台后做三件事添加上游账号、创建用户、生成 API Key。上游账号按你实际持有的服务填生成出来的 Key 是sk-xxxx格式这就是 Codex CLI 要用的凭证。同时确认后台可用的模型名称比如gpt-5-codex或后台映射的其他名字后面config.toml里的model必须和它一致。3.3 Codex CLI 的 config.toml 骨架先装 Node.js 和 Codex CLIcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash # 重开终端后 nvm install 22 npm i -g openai/codex codex --version创建配置文件mkdir -p ~/.codex nano ~/.codex/config.toml写入以下骨架把model换成你后台真实可用的模型名model gpt-5-codex model_provider sub2api [model_providers.sub2api] name Sub2API base_url http://localhost:8080/v1 env_key SUB2API_API_KEY wire_api responses supports_websockets false设置环境变量临时生效export SUB2API_API_KEYsk-你的Sub2API-Key永久生效echo export SUB2API_API_KEYsk-你的Sub2API-Key ~/.bashrc source ~/.bashrc3.4 settings.json 与 WSL2 端口转发如果你习惯用 JSON 管理配置可以在~/.codex/settings.json里放一份等价骨架{ model: gpt-5-codex, model_provider: sub2api, model_providers: { sub2api: { name: Sub2API, base_url: http://localhost:8080/v1, env_key: SUB2API_API_KEY, wire_api: responses, supports_websockets: false } } }WSL2 默认会把 localhost 映射到 Windows但有时需要显式转发。在 Windows PowerShell管理员里执行netsh interface portproxy add v4tov4 listenport8080 listenaddress0.0.0.0 connectport8080 connectaddress(wsl hostname -I).Trim()查看已有转发规则netsh interface portproxy show all不需要时删除netsh interface portproxy delete v4tov4 listenport8080 listenaddress0.0.0.04. 验证请求一次 curl 确认链路可用配置完成后先用 curl 直接打 Sub2API 的接口确认服务本身活着curl -s http://localhost:8080/v1/models \ -H Authorization: Bearer $SUB2API_API_KEY | head -c 500如果返回模型列表 JSON说明 Sub2API 和 Key 都正常。接着测 Codex CLIcodex 用一句话介绍当前目录预期结果是 Codex CLI 通过sub2api这个 provider 发出请求Sub2API 转发到上游再把结果返回终端。如果这一步能出内容整条链路就通了。想单独验证 TaoToken 统一通道可以再打一次curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500把TAOTOKEN_API_KEY换成你在控制台创建的 Key。这一步能返回模型列表说明统一 Key 通道本身没问题剩下的就是 Sub2API 与 Codex CLI 的对接细节。5. 本篇常见错排查5.1 Docker Compose 启动失败提示缺少 .env本地版docker-compose.local.yml需要读取deploy/.env缺文件或变量为空都会启动失败。解决方式cd ~/apps/sub2api-deploy/deploy cp .env.example .env nano .env至少保证这些字段有值POSTGRES_USERsub2api POSTGRES_PASSWORD设置一个强密码 POSTGRES_DBsub2api ADMIN_EMAILadminsub2api.local ADMIN_PASSWORD设置管理员密码 JWT_SECRET设置随机字符串 TOTP_ENCRYPTION_KEY设置随机字符串 TZAsia/Shanghai生成随机串可以用openssl rand -hex 32然后建数据目录并重启mkdir -p data postgres_data redis_data docker compose -f docker-compose.local.yml up -d docker compose -f docker-compose.local.yml ps5.2 数据库密码相关报错如果启动后仍报数据库密码错误检查.env里的POSTGRES_PASSWORD等号后不能为空避免中文、空格和引号。之前启动失败过的话补好.env再执行一次up -d通常就能恢复。5.3 Codex CLI 报模型不存在这是最常见的坑。config.toml里的model必须和 Sub2API 后台可用模型名完全一致大小写和连字符都不能错。改完配置后重开终端再试。5.4 鉴权失败先确认SUB2API_API_KEY是 Sub2API 后台生成的 Key不是 TaoToken 的 Key两者别混。再确认环境变量在当前 shell 里真的生效echo $SUB2API_API_KEY如果为空说明~/.bashrc没 source 或者写错了文件。5.5 Nginx 反向代理丢请求头如果后续把 Sub2API 放到服务器并用 Nginx 反代记得在http块加underscores_in_headers on;否则带下划线的请求头会被 Nginx 丢弃Sub2API 的粘性会话和多账号调度会异常。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔用 Codex CLI 跑一两个任务上面的配置已经够用。但如果你打算把 Codex CLI 当成日常编码助手甚至接进 Agent 工作流建议把 Key 管理和通道稳定性单独考虑。TaoToken 的 Coding Plan 适合长期编码和 Agent 场景模型对话入口适合临时验证模型效果API Keys 页面负责凭证管理接入文档负责排障。遇到接入问题优先看 API Keys 和接入文档验证模型效果走模型对话长期跑编码任务再考虑 Coding Plan。安全方面有几条硬建议不要把 API Key 写进公开仓库用环境变量或密钥管理服务固定好JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD这几个关键配置生产环境配好防火墙和 HTTPS定期更新依赖。Sub2API 这类自建聚合服务用于技术学习和研究上游账号的使用需自行评估风险。最后留一个实用习惯每次改完config.toml或.env先跑一次docker compose logs -f sub2api看日志再用 curl 打一次/v1/models最后才用codex发真实请求。三步走下来问题基本能定位到具体环节不用靠猜。