1. 为什么我要把 Sub2API 和 Codex CLI 串起来如果你正在用 Codex CLI 写代码大概率遇到过这种尴尬每台机器都要单独配一遍 API Token团队里谁换了 Key 就得挨个通知本地调试和服务器跑批用的还是两套凭证。Sub2API 这个自托管项目解决的就是这个问题——它把上游的 OpenAI/Codex 账号统一收口对外只暴露一个网关地址和一组 API TokenCodex CLI 只要把base_url指过来就能用。Sub2API 本质上是一个 API Token 管理与调度服务跑在 Docker 里自带 PostgreSQL 和 Redis支持分组、账号池、余额和并发控制。它适合需要在本地或服务器统一管理 API Token 的开发者尤其是手里有多个 Codex 账号、想让 Codex CLI 走统一入口的场景。这篇就按我实际部署的链路走一遍Docker Compose 起服务、后台建分组和账号、签发 Token、改~/.codex/config.toml、最后用curl和codex双重验证。中间踩过的坑比如 503 账号调度失败、请求打到根路径返回 HTML都会单独拎出来讲。整个链路的核心检索词就三个Sub2API 负责托管Docker Compose 负责部署Codex CLI 负责消费。把这三段打通你就有了一套可迁移、可备份、可团队共用的 Token 配置链路。2. 部署前的环境准备与 TaoToken 前置说明先说环境。Sub2API 官方推荐 Linux 服务器加 Docker Compose 部署我实测下来 Ubuntu 22.04 和 Debian 12 都没问题。硬性要求是 Docker 20.10、Docker Compose v2或者旧版独立的docker-compose命令并且开放 TCP 端口 8080。如果你打算公网访问记得在安全组里放行同时后面会讲怎么加反向代理。docker --version docker compose version两条命令能正常输出版本号就行。如果只有旧版 Compose把后面所有docker compose换成docker-compose即可逻辑完全一样。关于上游账号来源这里有个容易混淆的点。Sub2API 自己不管上游凭证它需要你提供一个可用的 OpenAI/Codex 账号做 OAuth 授权。如果你希望统一管理多家模型的 Token、又不想在每台机器上散落配置可以先用 TaoToken 这类平台把 Key 集中管起来再决定哪些走 Sub2API 调度。TaoToken 的模型对话入口适合先验证模型连通性控制台用来管理 API Keys接入文档里有完整的鉴权说明。它的 API 地址是https://taotoken.net/api官网在https://taotoken.net/。这一步不是必须的但如果你后面要接多个上游提前把 Key 管好会省很多事。注意Sub2API 的部署目录建议固定比如/opt/sub2api因为它的数据持久化、备份和迁移都围绕这个目录展开。换目录会导致 Compose 找不到卷。3. 用 Docker Compose 起 Sub2API 服务官方提供了一键部署脚本它会自动下载 Compose 配置、创建.env、生成 PostgreSQL 密码、JWT 密钥和 TOTP 加密密钥还会建好数据持久化目录。我建议直接用脚本省得手写一堆密钥。mkdir -p /opt/sub2api cd /opt/sub2api curl -sSL \ https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh \ | bash脚本跑完后目录里会有docker-compose.yml和.env。启动服务docker compose up -d旧版 Compose 用docker-compose up -d。启动后检查容器docker ps正常情况下你会看到三个容器sub2api、sub2api-redis、sub2api-postgres。如果只看到一两个多半是镜像没拉全或者端口冲突先看日志docker logs -f --tail200 sub2api健康检查用这个curl http://127.0.0.1:8080/health返回正常状态就说明服务起来了。浏览器访问http://服务器IP:8080进管理后台。如果管理员密码是自动生成的从日志里捞docker logs sub2api 21 | grep -i admin password这里有个细节.env里存着数据库密码和 JWT 密钥千万别提交到公开仓库。我习惯部署完立刻把.env备份到密码管理器然后给目录设权限chmod 600 .env。4. 后台配置分组、账号与 API Token 的对应关系后台配置是整条链路最容易出错的地方核心就一句话API Key 所属分组必须和上游账号所属分组一致。三者关系是分组串起来的账号进分组Key 也进同一个分组调度时才能匹配上。4.1 创建分组进管理后台 → 分组管理 → 新建分组比如建一个叫codex的分组。初次测试建议启用分组、暂时不设复杂模型白名单、不设模型映射、用默认倍率。等链路跑通再回来加限制。4.2 添加上游账号进管理后台 → 账号管理 → 添加账号添加 OpenAI/Codex OAuth 账号并完成设备授权。必须确认四件事账号状态为启用、OAuth 授权成功、并发数至少为 1、账号已经加入前面创建的codex分组。最后一条是最容易漏的。光建账号和分组不够必须在账号编辑页里把账号挂到对应分组上。我见过太多人卡在这里日志里一直报no available accounts其实就是账号没进组。4.3 创建 API Token进管理后台 → API Key 管理 → 新建 API Key设置分组为codex、状态启用、余额足够。这里的分组必须和账号所属分组一致否则调度阶段直接返回 503。配置完成后你手里应该有一个形如sk-xxxx的 Token。这个 Token 就是 Codex CLI 要用的凭证。5. 验证请求别拿根地址当接口测很多人部署完直接curl http://服务器IP:8080结果返回一堆 HTML就以为服务坏了。其实根地址返回的是管理后台页面它根本不调用模型。正确的测试方式是打/responses接口。export SUB2API_KEY你的新Token curl -sS -i http://127.0.0.1:8080/responses \ -H Authorization: Bearer $SUB2API_KEY \ -H Content-Type: application/json \ --data-raw { model: gpt-5.3-codex, input: 只回复 pong }公网测试把127.0.0.1换成服务器 IP 即可。成功时返回的是模型响应 JSON而不是 HTML 或 503。当前 Sub2API 版本同时处理裸/responses和/v1/responses所以 Codex CLI 那边两种路径都能接。如果这一步返回 503先别急着改配置直接看服务端日志定位docker logs --since10m sub2api 21 | grep -Ei -C 10 \ account_select_failed|no available|oauth|401|403|429|cooldown日志里出现openai.account_select_failed且excluded_account_count: 0基本就是候选账号列表为空回到账号管理检查分组归属。6. Codex CLI 接入 config.toml 配置服务端通了接下来让 Codex CLI 走 Sub2API。先建配置目录mkdir -p ~/.codex nano ~/.codex/config.toml写入以下内容model gpt-5.3-codex model_provider sub2api preferred_auth_method apikey [model_providers.sub2api] name Sub2API base_url http://服务器IP:8080 env_key OPENAI_API_KEY wire_api responses几个参数说明一下。model_provider指向下面定义的sub2api段base_url填你的 Sub2API 地址注意不要带/v1Codex 会自己拼/responsesenv_key指定从哪个环境变量读 Tokenwire_api responses表示走 Responses API 协议。设置 Token 环境变量export OPENAI_API_KEY你的Sub2API TokenmacOS 永久保存echo export OPENAI_API_KEY你的Sub2API Token ~/.zshrc source ~/.zshrcLinux Bash 永久保存echo export OPENAI_API_KEY你的Sub2API Token ~/.bashrc source ~/.bashrc然后直接启动codexCodex 会向http://服务器IP:8080/responses发请求。如果配置正确你会看到模型正常响应。如果 Codex 报连接错误先用第 5 节的curl确认服务端本身没问题再回头查config.toml的缩进和引号——TOML 对格式比较敏感base_url少了引号或者多了斜杠都会出问题。7. 本篇常见报错排查7.1 401 Unauthorized原因通常是 Token 错误、Token 已禁用或者 Authorization 请求头格式不对。检查一下你导出的变量echo ${OPENAI_API_KEY:0:8}...确认前缀和后台签发的一致。如果 Token 曾经在聊天或截图里暴露过立刻在后台禁用并重新生成。7.2 403 Insufficient account balanceSub2API 用户余额不足、API Key 额度不足或者分组计费配置导致余额不够。处理方式是进后台 → 用户管理 / 余额管理增加余额。7.3 503 No available accounts这是最高频的错误原因基本都在账号侧API Key 所属分组没有上游账号、账号没加入分组、账号被禁用、并发数为 0或者 OAuth 账号已失效。优先检查账号管理 → 编辑账号 → 分组确认账号挂在 Key 所在的那个分组里。7.4 503 Service temporarily unavailable看服务端日志docker logs --since10m sub2api 21 | grep -Ei -C 10 \ account_select_failed|no available|oauth|401|403|429|cooldown如果出现openai.account_select_failed且excluded_account_count: 0说明候选账号列表为空还是分组归属问题。7.5 返回 HTML 页面说明请求打到了/而不是/responses。检查 Codex 的base_url有没有多写路径或者curl测试时是不是漏了/responses后缀。8. 运维、备份与安全收尾日常运维命令记几条就够docker ps docker logs -f --tail200 sub2api docker restart sub2api docker compose restart sub2api更新镜像cd /opt/sub2api docker compose pull docker compose up -d备份用本地目录持久化版本最省事直接打包整个部署目录cd /opt docker compose -f /opt/sub2api/docker-compose.yml down tar czf sub2api-backup-$(date %F).tar.gz sub2api/ docker compose -f /opt/sub2api/docker-compose.yml up -d恢复就是解包后docker compose up -d。安全方面几条硬规矩不要在聊天、截图或日志里公开完整 Token已公开的立即禁用重签.env不要上传公开仓库生产环境建议加 HTTPS 反向代理并限制管理后台访问来源定期备份 PostgreSQL 和部署目录镜像版本尽量固定别长期用latest。如果你后面要把这套链路接到更多模型或团队协作场景可以顺手看看 TaoToken 的 Coding Plan它适合长期编码和 Agent 类任务配合 Sub2API 做上游调度会更顺。接入文档里有完整的鉴权和路径说明API Keys 页面用来签发和管理凭证。把 Sub2API 当本地网关、TaoToken 当上游 Key 池这套组合在团队里迁移起来会轻松很多。