订阅账号
Codex、Claude、Antigravity、Grok 这类按订阅计费的账号，走 OAuth 授权而不是填密钥。接进来之后，它们和 API 密钥共用同一套调度。
和 API 密钥的区别§
对网关来说，订阅账号和 API 密钥都只是「一池凭据」——轮转、重试、冷却、健康隔离完全共用一套机制， 你不需要为订阅账号单独维护一套运维逻辑。
差别只在三处：
- 接入方式——不是粘贴密钥，而是完成一次 OAuth 授权
- 凭据会过期——网关自动刷新；刷新失败时该账号会进入需要重新授权的状态
- 有额度窗口——订阅按周期计量，管理台会展示剩余额度与重置时间
接入一个账号§
订阅账号也是建在分组里的。进入分组 → 导入渠道凭据 → 新建分组，把接入方式选成订阅账号， 再选具体渠道（Codex / Claude / Antigravity / Grok），然后完成授权。
授权入口常驻展开，不折叠——远程部署时需要手动复制链接与回调地址，是高频路径而非兜底方案。
授权流程分两类，取决于渠道：
- 本地回调（Codex、Claude、Antigravity）——浏览器完成授权后， 上游会跳回本机的一个固定端口，网关在那里接住授权码
- 设备码（Grok）——页面给出一个验证码，你在上游网站输入它完成授权，不需要任何回调端口
回调端口§
走本地回调的三个渠道，端口是上游客户端写死的，不能自定义：
| 渠道 | 回调端口 | 说明 |
|---|---|---|
| Codex | 1455 | 回调地址 http://localhost:1455/auth/callback |
| Claude | 54545 | 由上游客户端固定 |
| Antigravity | 51121 | 由上游客户端固定 |
| Grok | 不需要 | 设备码授权，不占用本机端口 |
Docker Compose 默认会把这三个端口发布出来，和主服务一样只绑定到 127.0.0.1：
ports: - "$${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 实例。 需要跑多个实例时，只有一个能使用本地回调授权；其余实例要么改用设备码渠道， 要么在授权时临时停掉占用端口的那个实例。
远程部署怎么授权§
这是最容易卡住的一步。服务跑在远程服务器上时，你浏览器里的 localhost 指向的是你自己的电脑，不是服务器， 授权完成后跳转会失败。
解决办法有两个，任选其一：
- 手动粘贴回调地址——授权页面跳转失败后， 把浏览器地址栏里那串完整的回调 URL 复制出来，粘贴回管理台的回调输入框。 网关会从中取出授权码完成流程。这是最通用的做法， 不需要改任何网络配置。
- SSH 端口转发——把服务器的回调端口映射到本机， 让
localhost真的能通到服务器：
ssh -L 1455:127.0.0.1:1455 user@your-server # Claude 用 54545，Antigravity 用 51121 # 转发保持连接期间完成授权即可
回调端口不应该暴露到公网。用上面两种方式之一即可完成授权， 没有必要把 OAUTH_CALLBACK_BIND_ADDRESS 改成 0.0.0.0。
四种授权状态§
每个订阅账号都有一个授权状态，排障时先看它：
| 状态 | 含义 | 该怎么做 |
|---|---|---|
| 就绪 | 凭据有效，正常参与调度 | 无需处理 |
| 刷新中 | 凭据即将过期，网关正在自动续期 | 等待即可，通常几秒完成 |
| 需重新授权 | 自动刷新失败，多为上游撤销了授权或密码变更 | 重新走一次授权流程 |
| 结果未知 | 刷新请求没拿到明确结果，可能是网络问题 | 先观察，持续未恢复再重新授权 |
额度窗口、重置时间、授权状态在同一屏内可见。
额度信息怎么读§
管理台会展示订阅账号的剩余额度和重置时间。但要理解一点：
额度信息不参与调度决策。它是从上游响应里被动观察到的， 存在延迟，也不一定覆盖所有计费维度。真正触发账号切换的是上游返回的限流响应—— 当某个账号被限流，网关会立即让它冷却并换用其他账号， 不管此时显示的额度是多少。
所以额度那栏的用途是让你判断要不要再加账号， 而不是用来预测网关下一次会选谁。想确认是否有候选分组和可用凭据，用 监控与排障 里的路由检查。
使用前提§
- 只接你有权使用的账号，并遵守各服务商的订阅条款。 共享或转售订阅额度通常是违规的。
- 订阅渠道依赖上游的 OAuth 与兼容协议，上游改动时可能需要跟随更新，这类变化不在网关的控制范围内。
- 凭据在本地加密存储，但能解密它的密钥和数据库必须一起备份， 见 安全与上生产。