Codex 订阅与客户端

SubLane 优先支持 Codex 订阅接入。管理员管理订阅凭据，成员通过个人网关密钥访问模型。执行器基于 CLIProxyAPI，授权、存储、刷新和公网接口生命周期由 SubLane 管理。

添加账号

在订阅账号页面选择添加账号，使用浏览器授权或导入 auth.json。支持 Codex CLI 的嵌套 tokens 结构及扁平导出格式，不支持官方 API Key。

浏览器授权后，将完整的 http://localhost:1455/auth/callback?... 地址复制回表单。最后的 localhost 连接失败是正常的，因为 SubLane 不监听该回调端口。

验证连接会刷新并保存账号模型目录。账号可启用、禁用、重新授权或删除。重新授权不能更换上游身份；删除本地账号会删除其保存的凭据，但不会主动撤销服务商的登录。

客户端配置

1. 在个人 API 密钥页面创建密钥，选择自己有权访问的账号分组。
2. 使用该密钥查询 /v1/models，选取实际返回的模型 ID。
3. 在客户端进程环境中设置 SUBLANE_API_KEY。
4. 将以下字段合并到用户级 ~/.codex/config.toml，替换实例地址和模型 ID。

model = "<model-id-from-your-account>"
model_provider = "sublane"

[model_providers.sublane]
name = "SubLane"
base_url = "http://127.0.0.1:8080/v1"
env_key = "SUBLANE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = true

网络部署填写实际 HTTPS 地址。使用 HTTP/SSE 时将 supports_websockets 设为 false。

已经运行的桌面客户端不会自动继承另一个终端中刚导出的环境变量。请在能够读取密钥的环境中重新启动客户端，并确认它读取了预期的用户级配置。现有协议测试不等于完整的真实桌面客户端验收。

API 密钥页面提供配置指南；也可以选择 CC Switch 导入。CC Switch 使用自身的认证文件存储方式，不保留此处的环境变量与 WebSocket 配置语义。

订阅额度

账号页面显示上游实际返回的额度窗口、剩余百分比、重置时间及观测时间。数据缺失保持未知，读取失败不等于额度耗尽。刷新失败保留旧快照并标记过期。

到达上游报告的重置时间不会凭空把额度恢复为满值，必须重新获取实际快照。新会话选择会排除快照新鲜且主额度耗尽的账号；已有绑定会话得到额度相关拒绝，不会自动换号。

额度快照持久化到 SQLite。新鲜数据最多复用两分钟；过期数据可先返回并后台刷新。主动刷新有冷却，同一账号的并发刷新共享一次上游请求。页面只在刷新进行中轮询本地状态，空闲时不周期性请求服务商。

这些数据描述订阅账号额度，不是成员账单或 Token 预算。详细路由规则见账号池调度。

凭据加密与刷新

账号访问令牌、刷新令牌和 ID Token 使用 AES-256-GCM 加密。实例在数据库旁创建私有的 credentials.key，它不是初始化密码，也不需要手动填写。

数据库和密钥要一起备份。已有加密数据时，密钥缺失、不匹配或无效会阻止启动，不能通过重新生成密钥恢复访问。

SubLane 是唯一刷新所有者：先持久化轮换后的凭据，再发布给请求。上游 401 最多触发一次刷新和同一账号的一次重试，并发请求复用已刷新的结果。

网关接口

HTTP 请求必须携带完整输入；HTTP previous_response_id 被拒绝，避免丢失上下文。WebSocket 使用有界的连接内历史，未知续接 ID 需要重新提交完整历史。每轮都重新校验成员、密钥、分组和模型权限。

已有会话绑定的账号被禁用或删除时不会自动替换。客户端应在有意切换账号后开启新会话。请求取消会释放上游工作和并发配额。

版本与验证

Codex 发现模型、额度元数据及转发使用实例配置的有效客户端版本。目录过少或为空时，检查系统设置，过旧的客户端版本可能只能取得隐藏或不完整的模型列表。

自动化测试使用合成凭据和本地模拟上游。Codex CLI 0.152.1 曾通过模拟上游的 HTTP/SSE 与 WebSocket 测试；真实订阅授权、真实模型请求与桌面端需另外验证。不要把安全上限或空闲资源观测作为吞吐和内存承诺。