订阅账号
Codex、Claude、Antigravity、Grok 这类按订阅计费的账号，可完成 OAuth 授权，也可导入已有 OAuth JSON。接进来之后，它们和 API 密钥共用同一套调度。
和 API 密钥的区别§
对网关来说，订阅账号和 API 密钥都只是「一池凭据」——轮转、重试、冷却、健康隔离完全共用一套机制， 你不需要为订阅账号单独维护一套运维逻辑。
差别只在三处：
- 接入方式——完成一次 OAuth 授权，或导入已有 OAuth JSON
- 凭据会过期——网关自动刷新；遇到授权异常时，可手动刷新凭据或重新连接账号
- 有额度窗口——订阅按周期计量，管理台会展示剩余额度与重置时间
接入一个账号§
订阅账号也是建在分组里的。进入「分组 → 新建分组」，选择 Codex、Claude、Antigravity 或 Grok，然后连接账号或导入凭据。
授权入口常驻展开，不折叠——远程部署时需要手动复制链接与回调地址，是高频路径而非兜底方案。
接入方式分三类，取决于渠道和你是否已有授权凭据：
- 本地回调（Codex、Claude、Antigravity）——浏览器完成授权后， 上游会跳回本机的一个固定端口，网关在那里接住授权码
- 设备码（Grok）——页面给出一个验证码，你在上游网站输入它完成授权，不需要任何回调端口
- OAuth JSON 导入（全部四个订阅渠道）——上传或粘贴已有的 OAuth JSON， 不需要在这台机器上完成本地回调
导入支持 CPA 兼容、官方 Codex、官方 Claude Code 及 sub2api OAuth JSON，可上传多文件或账号数组；不支持 PAT 或缺少必要刷新凭据的文件。
订阅分组可设置自定义 HTTPS 上游根地址或路径前缀，代理需承接对应渠道的调用、模型发现与额度查询，不会隐式回退官方业务地址。OAuth 授权与 Token 刷新仍使用官方端点。
回调端口§
走本地回调的三个渠道，端口是上游客户端写死的，不能自定义：
| 渠道 | 回调端口 | 说明 |
|---|---|---|
| Codex | 1455 | 回调地址 http://localhost:1455/auth/callback |
| Claude | 54545 | 由上游客户端固定 |
| Antigravity | 51121 | 由上游客户端固定 |
| Grok | 不需要 | 设备码授权，不占用本机端口 |
Docker Compose 默认会把这三个端口发布出来，和主服务一样只绑定到 127.0.0.1：
ports: - "$${BIND_ADDRESS:-${HOST:-127.0.0.1}}:$${PORT:-3001}:$${PORT:-3001}" - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:1455:1455" # Codex - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:54545:54545" # Claude - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:51121:51121" # Antigravity
因为端口由上游固定、无法更改，一台主机上同一时刻只能有一个默认 Compose 实例使用本地回调授权。其他实例可导入已有 OAuth JSON；Grok 也可使用设备码。
远程部署怎么授权§
这是最容易卡住的一步。服务跑在远程服务器上时，你浏览器里的 localhost 指向的是你自己的电脑，不是服务器， 授权完成后跳转会失败。
解决办法有三种，任选其一：
- 手动粘贴回调地址——授权页面跳转失败后， 把浏览器地址栏里那串完整的回调 URL 复制出来，粘贴回管理台的回调输入框。 网关会从中取出授权码完成流程。这是最通用的做法， 不需要改任何网络配置。
- SSH 端口转发——把服务器的回调端口映射到本机， 让
localhost真的能通到服务器：
ssh -L 1455:127.0.0.1:1455 user@your-server # Claude 用 54545，Antigravity 用 51121 # 转发保持连接期间完成授权即可
已有 OAuth JSON 时，直接上传或粘贴导入即可，不需要回调端口。
回调端口不应该暴露到公网。可以手动粘贴回调、使用 SSH 转发，或导入已有 OAuth JSON；无需把 OAUTH_CALLBACK_BIND_ADDRESS 改为 0.0.0.0。
四种授权状态§
每个订阅账号都有一个授权状态，排障时先看它：
| 状态 | 含义 | 该怎么做 |
|---|---|---|
| 就绪 | 凭据有效，正常参与调度 | 无需处理 |
| 刷新中 | 网关正在刷新凭据 | 等待即可，通常几秒完成 |
| 需重新授权 | 上游拒绝刷新，或现有授权已失效 | 尝试刷新凭据；仍失败时重新连接或导入 |
| 结果未知 | 刷新请求没拿到明确结果，可能是网络问题 | 尝试刷新凭据；仍失败时重新连接或导入 |
「刷新凭据」在账号卡片的更多菜单中，用于恢复授权；「刷新额度」更新额度信息，满足恢复条件时也会解除额度冷却。 手动停用的账号需先启用，才能刷新凭据。
额度窗口、重置时间、授权状态在同一屏内可见。
额度信息怎么读§
首次导入后同步额度，获取当前额度和重置时间； 升级后额度未更新或显示异常，也可主动刷新一次。
额度数值不决定轮转顺序；上游限流响应仍会触发冷却与切换。额度通过主动同步和上游响应更新，可能存在延迟。
当新额度观测中唯一匹配的窗口已用比例下降至少 5 个百分点时，会解除该账号及其模型的额度冷却；主动同步与被动更新均适用。不会解除其他原因或自定义规则的冷却，也不会恢复授权、启用账号、解除拉黑或清空失败计数。
所以额度那栏的用途是让你判断要不要再加账号， 而不是用来预测网关下一次会选谁。想确认是否有候选分组和可用凭据，用 监控与排障 里的路由检查。
进入 Codex 分组，点击 Modern 的「同步额度」或 Classic 的「同步」。上游返回正余额或不限量状态时，账号卡片显示「点数」；未显示不代表余额为零。
点数与周期额度、重置额度分别展示，不累加，也不参与调度。
Codex 和 Claude 账号可能提供重置额度，卡片展示可用次数及到期时间。需在管理台手动确认消费，不会自动使用；完成后刷新额度确认结果。若结果未知，等待并核对原操作，不要重复发起新的重置。
使用前提§
- 只接你有权使用的账号，并遵守各服务商的订阅条款。 共享或转售订阅额度通常是违规的。
- 订阅渠道依赖上游的 OAuth 与兼容协议，上游改动时可能需要跟随更新，这类变化不在网关的控制范围内。
- 凭据在本地加密存储，但能解密它的密钥和数据库必须一起备份， 见 安全与上生产。