在 Windows 11 上搭建 Sub2API 服务：从 WSL2 到 Codex CLI 完整指南

一、安装 WSL2 + Ubuntu

1.1 启用 WSL2

在 Windows 11 中以管理员身份打开 PowerShell，执行以下命令安装 WSL2：

wsl —install

1.2 重启并配置 Ubuntu

1.3 验证 WSL 版本

检查当前 WSL 版本：

wsl –l –v

如果 Ubuntu 的版本不是 VERSION 2，执行以下命令升级：

wsl —set-default–version 2
wsl —set-version Ubuntu 2

1.4 进入 Ubuntu 环境

wsl

1.5 更新系统并安装基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ca-certificates nano openssl

二、安装 Docker

2.1 推荐方案：Docker Desktop（新手友好）

docker version
docker compose version
docker run hello-world

2.2 备选方案：Docker Engine

如果不想安装 Docker Desktop，可以在 Ubuntu 内直接安装 Docker Engine：

docker compose version

三、安装 Codex CLI

3.1 安装 Node.js（使用 nvm）

OpenAI 官方推荐在 WSL 中使用 nvm 安装 Node.js：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

关闭并重新打开 Ubuntu 终端，然后执行：

nvm install 22
node -v
npm -v

3.2 安装 Codex CLI

npm i -g @openai/codex
codex –version

3.3 登录 OpenAI 账号（可选）

如果直接使用 OpenAI 官方服务：

codex –login

注意：如果后续要使用 Sub2API，主要使用 Sub2API 生成的 API Key 和自定义 provider 配置，此步骤可跳过。

四、部署 Sub2API

4.1 使用官方一键部署脚本

Sub2API 官方推荐使用 Docker Compose 部署，提供了一键部署脚本：

mkdir -p ~/apps/sub2api-deploy
cd ~/apps/sub2api-deploy

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

4.2 启动服务

docker compose up -d
docker compose ps
docker compose logs -f sub2api

4.3 访问管理界面

在浏览器中打开：

http://localhost:8080

如果 Windows 浏览器无法访问，先获取 WSL IP 地址：

hostname -I

然后使用以下地址访问：

http://WSL_IP:8080

4.4 初始化配置

进入安装向导后，按照提示完成：

• 数据库配置
• Redis 配置
• 管理员账号初始化

提示：Docker Compose 版本已包含 PostgreSQL 和 Redis 容器，通常使用默认配置即可。

五、Sub2API 后台基础配置

5.1 添加上游账号

在 Sub2API 后台添加实际使用的上游服务账号：

• OpenAI
• Claude
• Gemini
• Antigravity
• 其他支持的 API 服务

5.2 创建用户

• 创建新用户或直接使用管理员账号

5.3 生成 API Key

5.4 确认模型名称

在 Sub2API 后台确认可用的模型名称，例如：

• gpt-5-codex
• gpt-5.1-codex
• 或其他后台映射的模型名称

重要：后续 Codex 配置中的 model 参数必须与后台可用模型名称一致。

六、配置 Codex 使用 Sub2API

6.1 创建 Codex 配置文件

mkdir -p ~/.codex
nano ~/.codex/config.toml

6.2 编辑配置文件

将以下内容写入 config.toml：

model = "将此处替换为Sub2API后台可用模型名"
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

6.3 设置环境变量

临时设置 API Key：

export SUB2API_API_KEY="sk-你的Sub2API-Key"

永久生效设置：

echo 'export SUB2API_API_KEY="sk-你的Sub2API-Key"' >> ~/.bashrc
source ~/.bashrc

6.4 测试连接

codex "用一句话介绍当前目录"

6.5 故障排除

• 模型不存在错误：修改 ~/.codex/config.toml 中的 model 参数
• 鉴权失败：检查 SUB2API_API_KEY 是否为 Sub2API 后台生成的正确 Key

七、常用运维命令

7.1 Sub2API 服务管理

cd ~/apps/sub2api-deploy

# 查看服务状态
docker compose ps

# 查看实时日志
docker compose logs -f sub2api

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 更新镜像
docker compose pull

# 重新启动
docker compose up -d

7.2 WSL 管理

# 更新 WSL
wsl —update

# 关闭 WSL
wsl —shutdown

7.3 Codex CLI 管理

# 更新 Codex CLI
npm i -g @openai/codex

# 查看版本
codex –version

# 查看安装位置
which codex

八、Nginx 反向代理配置

8.1 重要配置项

如果后续将 Sub2API 部署到服务器并使用 Nginx 反向代理，Sub2API README 特别提醒：

在 Nginx 的 http 块中添加以下配置：

underscores_in_headers on;

8.2 配置说明

• 此配置允许请求头中包含下划线
• 避免 Nginx 丢弃带下划线的请求头
• 确保 Sub2API 的粘性会话和多账号调度功能正常工作

九、安全提醒

9.1 使用风险提示

Sub2API README 明确提示：

• 该项目用于技术学习和研究
• 使用中转、订阅配额分发等功能可能违反部分上游服务条款
• 存在账号封禁或服务中断风险，需自行承担

9.2 生产环境安全建议

十、常见问题与解决方案

10.1 Docker Compose 启动失败问题

问题现象：

错误原因： 本地版 docker-compose.local.yml 需要读取 deploy/.env 文件，但当前目录缺少该文件或文件中缺少必要的环境变量（如 POSTGRES_PASSWORD）。

解决方案：

cd E:\\project\\sub2api\\deploy
copy .env.example .env
notepad .env

POSTGRES_USER=sub2api
POSTGRES_PASSWORD=设置一个强密码
POSTGRES_DB=sub2api

ADMIN_EMAIL=admin@sub2api.local
ADMIN_PASSWORD=设置管理员密码

JWT_SECRET=设置随机字符串
TOTP_ENCRYPTION_KEY=设置随机字符串
TZ=Asia/Shanghai

[guid]::NewGuid().ToString("N") + [guid]::NewGuid().ToString("N")

复制生成的字符串两次，分别填入 JWT_SECRET 和 TOTP_ENCRYPTION_KEY。POSTGRES_PASSWORD 也可以使用相同方法生成。

mkdir data
mkdir postgres_data
mkdir redis_data

docker compose –f docker-compose.local.yml up –d

docker compose –f docker-compose.local.yml ps
docker compose –f docker-compose.local.yml logs –f sub2api

http://localhost:8080

10.2 数据库密码相关错误处理

如果启动后仍报数据库密码相关错误：

十一、参考文档