这条路线解决什么
Sub2API 是服务端账号池，不是桌面客户端，也不是普通单机用户的首选。部署时只依赖稳定概念：Linux/容器环境、数据库与缓存、HTTPS、管理员账号和数据备份。不要复制可能过时的完整部署命令，以项目官方 README 和部署文档为准。
部署与账号池共同步骤
- 部署并登录 Sub2API 管理端。
- 添加 OpenAI/Codex 账号。
- 选择 OAuth 或项目当前支持的导入方式。
- 核对账号状态、套餐、额度和失败原因。
- 创建账号组或账号池。
- 配置调度、并发和禁用规则。
- 创建下游用户或 API Key。
- 仅把用户 Key 提供给客户端，不要把管理员 Key 发给用户。
- 复制 HTTPS Base URL。
- 用最小请求检查 /v1/models 和 /v1/responses。
- 再配置 CC Switch 或 Codex++。
完整链路
上游负责账号与 API，下游客户端负责把接口配置给 Codex。
- OpenAI 账号
- Sub2API 服务器账号池
- CC Switch / Codex++
- Codex
适合哪些用户
- 有服务器和运维能力的用户
- 多设备、多用户或需要账号池调度的团队
- 已经部署 Sub2API 并登录管理端的用户
开始前准备
- 已有服务器、域名和运维能力。
- 理解 HTTPS、数据库、日志与密钥管理。
- 已按 Sub2API 官方 README 部署并登录管理端。
- 账号池中至少有一个健康可用的 OpenAI 账号。
方案 A：Sub2API → CC Switch → Codex
CC Switch 只保存客户端配置，不代替服务器权限控制；Base URL 是远程 HTTPS 地址，API Key 是下游用户 Key。
把 Sub2API 接口配置到 CC Switch
步骤与 Cockpit 方案相近，但必须使用远程 HTTPS Base URL 和下游用户 Key。
从官方 Release 安装 CC Switch
只从 farion1231/cc-switch 的 GitHub Releases 页面下载对应系统版本。
完成标志：CC Switch 安装完成。
打开 Codex 面板并添加自定义供应商
在 CC Switch 中打开 Codex 面板，添加自定义供应商。
完成标志：新供应商卡片已创建。
填入 Sub2API HTTPS Base URL
粘贴 Sub2API 管理端提供的远程 HTTPS Base URL，不填写本地地址。
完成标志：Base URL 是远程 HTTPS 地址。
填入下游用户 Key
粘贴 Sub2API 下游用户 Key，不能使用管理员 Key。
完成标志：客户端只持有用户 Key。
卡住了：拿到管理员 Key 时先撤销并重新签发，不要把管理员 Key 配到客户端。
选择协议并填写模型名
协议按 Sub2API 当前接口选择，Codex 通常使用 Responses；模型名以 /v1/models 或管理端模型列表为准。
完成标志：协议和模型名与服务器当前接口一致。
启用供应商并重启 Codex
启用供应商后重启 Codex CLI / Desktop。
完成标志：Codex 已加载新供应商配置。
执行最小请求
发送最小请求，确认服务器调度日志显示请求落到预期账号池。
完成标志：最小请求成功，服务器日志出现对应记录。
知道如何切回官方
确认 CC Switch 中切换回 OpenAI Official 的方法。
完成标志：关闭第三方路线后可恢复官方配置。
方案 B：Sub2API → Codex++ → Codex Desktop
Codex++ 固定指 BigPizzaV3/CodexPlusPlus；在中转注入中填写 Sub2API HTTPS Base URL 与下游用户 Key，并通过 Codex++ 启动。
把 Sub2API 接口配置到 Codex++
远程服务不可用时应先检查服务器、域名、TLS 和账号池，不要反复重装 Codex。
安装官方 Codex Desktop 与 Codex++
先安装官方 Codex Desktop，再按系统版本安装 Codex++。
完成标志：两个程序都已安装。
打开 Codex++ Manager 进入中转注入
启动 Codex++ Manager，进入中转注入或供应商配置。
完成标志：你已进入配置界面。
填写 Sub2API HTTPS Base URL
粘贴远程 HTTPS Base URL，不填写本地地址或旧示例端口。
完成标志：Base URL 已填写。
填写下游用户 Key
粘贴下游用户 Key，不要使用管理员 Key。
完成标志：客户端只持有用户 Key。
选择上游协议并应用配置
按 Sub2API 当前接口选择协议并应用配置。
- 选择上游协议：上游原生支持 Responses API 时选择 Responses；上游只支持 Chat Completions 时选择 Chat Completions，由 Codex++ 的本地协议代理转换为 Responses。具体名称以当前 Codex++ 版本界面为准。
完成标志：配置已保存。
退出旧 Codex 并通过 Codex++ 启动
退出已经运行的 Codex，从 Codex++ 启动入口重新启动 Codex Desktop。
完成标志：Codex 已通过 Codex++ 启动，注入配置生效。
执行最小请求
发送最小请求，确认请求到达服务器账号池。
完成标志：最小请求成功，服务器日志出现记录。
远程故障时先查服务器
服务不可用时依次检查服务器、域名、TLS 和账号池，不要反复重装 Codex。
完成标志：你按服务器链路排查，而不是重装客户端。
清除中转注入恢复官方
按版本说明清除中转注入，恢复官方线路。
完成标志：你已知道如何回滚。
如何确认成功
- HTTPS 证书正常。
- 管理端未暴露给普通用户。
- 用户 Key 权限和额度符合预期。
- 账号池至少有一个健康账号。
- 调度日志显示请求落到预期账号。
- 客户端看不到管理员密钥。
- 请求失败不会把完整凭证写入公开日志。
常见错误
| 问题 | 可能原因 | 处理动作 |
|---|---|---|
| 客户端请求 401 | 使用了管理员 Key，或用户 Key 已失效。 | 改用下游用户 Key，必要时重新签发并撤销旧 Key。 |
| HTTPS 证书告警 | 证书过期、域名不匹配或使用自签名证书。 | 先修复域名、TLS 和证书链，再继续配置客户端。 |
| 账号池没有健康账号 | 账号被禁用、额度用完或调度规则排除了全部账号。 | 在管理端查看账号状态、额度和失败原因。 |
| 请求没有到达服务器 | 客户端走了旧配置、DNS 或网络问题。 | 检查客户端供应商配置、域名解析和防火墙，不要重装 Codex。 |
- 问题
- 客户端请求 401
- 可能原因
- 使用了管理员 Key，或用户 Key 已失效。
- 处理动作
- 改用下游用户 Key，必要时重新签发并撤销旧 Key。
- 问题
- HTTPS 证书告警
- 可能原因
- 证书过期、域名不匹配或使用自签名证书。
- 处理动作
- 先修复域名、TLS 和证书链，再继续配置客户端。
- 问题
- 账号池没有健康账号
- 可能原因
- 账号被禁用、额度用完或调度规则排除了全部账号。
- 处理动作
- 在管理端查看账号状态、额度和失败原因。
- 问题
- 请求没有到达服务器
- 可能原因
- 客户端走了旧配置、DNS 或网络问题。
- 处理动作
- 检查客户端供应商配置、域名解析和防火墙，不要重装 Codex。
安全与隐私
常见问题
Sub2API 能当作普通桌面客户端使用吗？
不能。Sub2API 是服务端账号池和 API 分发服务，需要服务器、HTTPS、数据库和运维能力。
管理员 Key 和用户 Key 有什么区别？
管理员 Key 管理整个服务，只能保留在服务器管理端；用户 Key 只代表下游用户的权限和额度，客户端只应拿到用户 Key。
可以复制旧版部署命令直接执行吗？
不要。部署命令可能过时，应以 Sub2API 官方 README 和部署文档为准，且不把示例管理员密钥或数据库密码写进页面。
远程服务不可用为什么要先查服务器？
远程链路涉及服务器、域名、TLS、账号池和日志，反复重装 Codex 不会解决上游问题。