opencodex 管理 API 凭证契约全解：Codex 账户池、OAuth 多账号与 API-Key 池的调用协议

本文基于 opencodex 仓库中devlog/_fin/260720_issue180_cli_account_parity/003_management_api_contracts.md的调研结论，系统梳理代理进程暴露的/api/*管理端点：从客户端认证与端口发现、到 Codex（ChatGPT）账户池、通用 OAuth 多账号与 API-Key 池三大家族凭证契约，再到 provider 能力判别矩阵与 CLI 账号命令（list/current/use）的落地要点。读者读完可掌握为 CLI、GUI 或脚本对接 opencodex 管理面所需的全部请求形状、鉴权前提与语义边界。

一、管理面契约的总闸门：认证与跨域防线

所有/api/*管理路由都由代理进程自身提供，并统一穿过两道检查：

1. 管理鉴权：requireApiAuth(req, config, "management")（见 src/server/index.ts 的调用入口）。即使用户环境不要求 API 认证（loopback 绑定），管理面也要求请求携带合法的 Host 与 Origin。
2. 来源检查：handleManagementAPI在进入任何业务 handler 之前，先调用isAllowedManagementOrigin(req, config)，跨域来源直接返回 403（src/server/management-api.ts）：

if (!isAllowedManagementOrigin(req, config)) { return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config); }

同时，所有 POST/PUT/PATCH 请求在 handler 缓冲 body 之前会拒绝超过 2 MiB 的载荷（返回 413request body too large），避免管理面被超大 JSON 拖垮（src/server/management-api.ts）。

• 错误约定：一律返回 JSON{ "error": string }；codex-auth相关端点有时额外附加code/reason字段。
• 浏览器安全头：管理面响应带X-Frame-Options: DENY与Content-Security-Policy: frame-ancestors 'none'（src/server/auth-cors.ts）。
• CORS 头：管理面额外放行X-OpenCodex-GUI-Origin、X-OpenCodex-CSRF-Token两个自定义请求头（src/server/auth-cors.ts）。

Origin校验采取“进程推导 origin 精确匹配”策略：无Origin头、与Host推导出的 origin 完全一致、或命中运维配置的corsAllowOrigins列表时才放行——后者专门覆盖 TLS 终结器把进程观测到的http://…变为外部https://…的场景（src/server/auth-cors.ts）。

二、客户端鉴权与端口解析：CLI 连代理的第一公里

2.1 绑定地址决定鉴权强度

isApiAuthRequired(config)的实现极简：绑定地址为 loopback（localhost/127.0.0.1/::1/[::1]之一）时返回false，否则返回true（src/server/auth-cors.ts）：

export function isApiAuthRequired(config: Pick<OcxConfig, "hostname">): boolean { return !isLoopbackHostname(config.hostname); }

两种情形下管理面的要求不同：

这些头是跨数据面与管理面共享的白名单的一部分：STATIC_ALLOWED_REQUEST_HEADERS中明确包含X-OpenCodex-API-Key与X-Api-Key（src/server/auth-cors.ts）。CLI 侧的既有惯例是runningProxyUpdateHeaders()——读取configuredAdminToken()后注入X-OpenCodex-API-Key头（src/oauth/login-cli.ts）。

2.2 端口阶梯（canonical）

findLiveProxy()按固定优先级定位正在运行的代理（src/server/proxy-liveness.ts）：

1. PID 文件：readAlivePid（src/config.ts）——从 pid 文件读取存活进程；
2. runtime-port.json：readRuntimePort（src/config.ts）——读取运行时记录的真实端口；
3. /healthz身份探针：isOpencodexHealthz（src/server/proxy-liveness.ts）——对候选端口发起健康检查，确认是 opencodex 自己的/healthz；
4. 兜底：config.port ?? 10100。

配置目录为OPENCODEX_HOME环境变量指定目录，缺省为~/.opencodex（src/config.ts）。

值得注意的是configuredPort()直接解析_corsOrigin（默认http://localhost:10100），且任何准入检查都不依赖端口号——loopback 谓词只认 hostname（src/server/auth-cors.ts）。

三、Family A —— Codex（ChatGPT）账户池契约

Codex 账户池路由由handleCodexAuthAPI统一处理（src/server/management-api.ts 动态导入 src/codex/auth-api/routes.ts）。其身份规则：

• 主账户（Codex App 登录）id 恒为__main__（MAIN_CODEX_ACCOUNT_ID，src/codex/main-account.ts）；
• 池账户 id 必须匹配^[a-zA-Z0-9._-]{1,64}$；
• token 永不离服务端，邮箱一律经maskEmail掩码后展示（src/lib/privacy.ts）。

完整端点契约如下表：

实现细节佐证：配额查询直接遍历listAccountQuotas()内存表（routes.ts）；reset-credits 消费端具备幂等 operationId 与 503 忙碌语义（routes.ts）。

四、Family B —— 通用 OAuth provider 账户契约

管理面在 src/server/management-api.ts 的 accounts/logout 区块（约 L1427-L1471）处理通用 OAuth 账户。有效 provider 集合由listOAuthProviders()给出：xai、anthropic、kimi、kiro、google-antigravity、cursor、github-copilot；chatgpt通过isPublicOAuthProvider排除在公开列表外（src/oauth/index.ts）。未知 provider 一律 400"unknown oauth provider"。

存储层背景：OAuth token 存在~/.opencodex/auth.json，按 provider 名组织为ProviderAccountSet{ activeAccountId, accounts: [{ id, credential, needsReauth?, addedAt? }] }；旧的单凭证形态（{ access, refresh, expires, ... }）在加载时自动归一化，首次以新形态落盘会先备份auth.json.pre-multiauth，防止降级加载器静默丢弃刷新 token（src/oauth/store.ts）。

五、Family C —— API-Key 池契约

API-Key 池仅对isKeyAuthProvider判定的 provider 开放——即鉴权方式既非 oauth 也非 forward 的已配置 provider（src/providers/api-keys.ts）。池定义在provider.apiKeyPool（src/types.ts），provider.apiKey镜像当前 active 条目。key id 为sha256(key)[:8]前 8 位（src/providers/api-keys.ts）；掩码规则maskApiKey：first4****last4，长度 ≤ 8 时整体显示****，${ENV}引用原样展示（src/providers/api-keys.ts）。

相邻端点（注意区分）：

• GET /api/key-providers：key 登录选择器的元数据；
• GET/POST/DELETE /api/keys：代理自身的准入 key（admission keys）——POST 返回完整ocx_…key，且只返回一次，用于外部客户端接入代理。

六、Provider 能力判别矩阵

程序化判别依据两个字段：authKind（src/providers/registry.ts）与codexAccountMode（值为"direct" | "pool"，见 src/types.ts），二者均通过GET /api/provider-presets暴露（src/providers/derive.ts）。

已知缺口：多账户与替换式单槽的差异无法仅凭 HTTP 判别。SINGLE_SLOT_PROVIDERS常量只覆盖chatgpt（src/oauth/store.ts）；kiro 的替换行为来自无身份凭证分支（登录时未提取 accountId/email，src/oauth/store.ts）。因此 CLI 必须硬编码已知的替换式集合（kiro）或向用户展示通用提示。

七、服务端缺失契约与 CLI 落地结论

调研同时记录了五条对 CLI 账号命令有直接影响的“服务端缺口”：

1. 没有跨 provider 的聚合账户视图——CLI 必须扇出：先GET /api/oauth/providers，再对每个 provider 调GET /api/oauth/accounts，并对每个 key-provider 调GET /api/providers/keys（Codex 池是唯一自带聚合的）；
2. Codex 池没有手动粘贴 code 的登录路径（仅浏览器流程）——openai 的account add保持浏览器流，超出最小命令集范围；
3. 没有可经 HTTP 推导的多/替换标志（见矩阵缺口）；
4. PUT /api/codex-auth/active不强制立即切换——已 pin 线程保留原账户，CLI 输出必须注明"applies to new sessions/threads"；
5. 可容忍的不对称：DELETE /api/codex-auth/accounts与DELETE /api/keys对未知 id 返回 200；/api/oauth/logout走 query 参数。

最终结论：issue #180 的最小范围（list/current/use）不需要任何新的服务端契约——三大家族已经完整暴露了所需的读取与切换能力。这为 CLI 账号子命令的实现划定了清晰的集成边界：读操作走扇出式聚合，切换操作分别落在PUT /api/codex-auth/active（Codex 池）、PUT /api/oauth/accounts/active（OAuth 多账号）与PUT /api/providers/keys/active（Key 池）之上，并各自遵守上文表格中的鉴权、掩码与幂等语义。