Codex 订阅与客户端

已有个人密钥时，直接按下面配置客户端。还没有密钥，先完成第一次使用，或请管理员提供登录账号。

客户端配置

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

Codex 配置示例

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 配置语义。

**配置完成后：**发一条消息并确认回复，然后查看日常使用。下面的账号、额度和协议细节可按需查阅。

添加账号

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

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

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

订阅额度

账号页面展示已启用 Codex 账号的额度窗口、剩余百分比、重置倒计时和观测时间，以及上游提供的额外模型限制。可用重置卡数量单独显示：未提供时为「未知」，明确返回零时才为 0。查看列表及按需兑换见重置卡。缺失额度保持未知；刷新失败保留旧快照并显示警告。到达重置时间不代表已经补充额度，应刷新额度确认当前状态。

查询时先读取 https://chatgpt.com/backend-api/wham/usage，再读取独立的 https://chatgpt.com/backend-api/wham/rate-limit-reset-credits。两个请求使用所选账号的凭据，并共用 20 秒期限；每份响应最多读取 128 KiB。重置卡详情请求失败或未提供数量时，正常额度仍可用，并保留额度响应中已有的有效卡数。额度响应和快照只保存规范化后的额度与数量，不保存卡 ID、原始响应或凭据。

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

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

这些数据描述订阅账号额度；成员额度由用量分配单独记账，不是实际账单。按比例分配使用设定的 Token 或内部金额总预算，直接计入请求上报用量。详细路由规则见资源组调度。

重置卡

工作空间管理员可查看和使用已启用、无需重新授权的 Codex 账号的重置卡，普通成员无此管理权限。「定时使用」和「额度耗尽时使用」默认均关闭；查看或刷新列表不会消耗卡片。

配置与使用

打开「订阅账号」，在 Codex 账号卡片点击「重置卡设置」，查看卡片列表、可用数量和观测时间。数量「未知」与明确返回 0 不同。
按需开启「定时使用」「额度耗尽时使用」，也可同时开启。单次计划填写未来的日期和时间；每天计划填写时间；每周计划选择星期和时间。先确认弹窗显示的系统时区。
设置共享每日上限（1 至 100 张，默认 1 张），点击「保存设置」。确认保存成功提示；定时模式还应显示下次执行时间。
需要手动使用时，先保存修改，再点击「立即使用一张」。每次最多使用一张，结果在执行记录中查看；仅打开设置不会兑换。

列表与到期优先规则

列表显示卡片名称、状态、获得时间和到期时间，并区分可用、兑换中、已使用、已过期、未知及不支持的卡片类型，不直接展示原始卡 ID。「下一张使用」标记说明自动选择顺序，弹窗不提供手动选卡；有待确认兑换时不显示该标记。可用数量大于零也不保证存在符合条件的卡片。

每次新的手动、定时或额度耗尽兑换都会重新读取卡片明细，并显式传入 credit_id。只选择可用、受支持且未过期的卡，优先最早到期的，无到期时间的排在最后；到期时间相同则优先较早获得的卡，再按稳定 ID 排序。没有符合条件的卡就跳过。无法确认列表时跳过，不退回上游默认选卡。首次加载失败与空列表保持区分；刷新失败保留旧列表并显示警告，可点击「刷新卡片」重试。

定时与额度限制

额度耗尽模式后台约每分钟检查一次，要求新鲜有效的额度快照、已知且大于零的卡数，以及主额度明确不可用。百分比达到 100%、网络错误或数据未知本身不会触发。手动和定时使用也要求新鲜额度数据及已知的正数卡数。

两种模式和手动使用共享每日上限，按系统时区的本地日期计数，成功和待确认兑换均占用次数。停用或需要重新授权的账号会跳过；错过超过五分钟的计划不补执行，夏令时跳过不存在的本地时间，同一本地日期的重复小时只安排一次。修改系统时区后重新计算后续计划。关闭浏览器不影响后台执行；演示模式不启动自动任务，也不允许兑换。

结果与排查

看到的情况	下一步
无法获取卡片明细或没有符合条件的卡	刷新卡片，检查状态及到期时间；未确认选卡时不会兑换。
额度未知或不可用	刷新额度，处理连接失败或重新授权问题。
已达到每日上限	等待下一个本地日期，或确认需要后提高上限并保存。
重置结果待确认	点击「核对待确认结果」；结果确认前该账号不会发起新的兑换。

服务商决定账号资格及可重置的额度窗口。兑换使用 POST /backend-api/wham/rate-limit-reset-credits/consume，已识别结果为 reset、already_redeemed、nothing_to_reset 和 no_credit。成功后刷新额度和卡数，不清除其他网关限制，也不保证一次解除所有限制。

发送前将选中卡 ID 与 redeem_request_id 一起持久化。超时或未知响应会保留待确认状态；核对时即使库存或到期状态变化，仍复用同一组参数，卡数变化不能单独证明兑换结果。旧版本留下的待确认请求保留原来省略 credit_id 的行为。结果明确后清除选中卡 ID，额度快照和公开执行记录、审计输出均不保留该 ID。执行记录不保存凭据、原始响应或服务商个人资料；删除账号会删除设置与执行记录。

管理员浏览器接口为：GET /api/accounts/{id}/resets 读取设置和记录，GET /api/accounts/{id}/resets/cards 读取规范化卡片明细，PUT /api/accounts/{id}/resets 保存设置，POST /api/accounts/{id}/resets/consume 或 POST /api/accounts/{id}/resets/retry 发起兑换或核对结果。接口使用浏览器会话和工作空间角色校验，网关 API 密钥不能授权访问。卡片查询复用凭据、代理和账号生命周期校验，排除个人资料标识、头像地址及原始响应。兑换属于服务商内部协议，可能变化；合成测试不代表已验收真实账号资格和线上兑换。

设置变更与手动成功操作进入管理审计；自动执行结果保存在有界执行记录中。

凭据加密与刷新

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

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

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

网关接口

路径	作用
`GET /v1/models`	返回密钥所在资源组允许的模型目录
`POST /v1/responses`	Responses JSON 或 SSE
`POST /v1/responses/compact`	Codex 非流式压缩
`GET /v1/responses`，升级 WebSocket	连续对话与连接内上下文
`POST /v1/chat/completions`	Chat Completions 协议转换

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

请求体、WebSocket 消息和重建后的上下文默认限制为 128 MiB，可通过 SUBLANE_MAX_REQUEST_BODY_MB 调整；响应体和流事件分别限制为 8 MiB。配置方式见部署指南。

已有会话绑定的账号被禁用或删除时不会自动替换。主动换模型时，携带完整可重放历史且原账号不支持新模型可重新选取账号；上游续接仍保留原绑定，详见模型路由。其他有意切换账号的情况应开启新会话。请求取消会释放上游工作和并发配额。

版本与验证

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

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