mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-21 08:01:41 +00:00
fix: align official quota windows
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
# 官方 Codex 请求链路解包记录
|
||||
|
||||
本记录基于官方 macOS Codex Desktop 包解包结果,用于校准 `codex-proxy-rs` 的 Codex 上游请求实现。
|
||||
|
||||
- 官方包路径:`/tmp/codex-desktop-official/dmg-extract/Codex Installer/Codex.app`
|
||||
- App 版本:`26.616.81150`
|
||||
- Build:`4306`
|
||||
- app.asar 解包目录:`/tmp/codex-desktop-official/app-asar`
|
||||
- 原生二进制:`Contents/Resources/codex`,Mach-O arm64,当前 Linux 环境不能直接运行,只能用静态字符串和 JS bundle 取证。
|
||||
|
||||
## 总结
|
||||
|
||||
官方 Desktop 的主对话请求链路不是 webview 直接 `fetch /codex/responses`。webview 负责 UI、设置和额度展示;认证头、远端控制、真实 Codex 请求链路主要在 Electron main bundle 和 `Resources/codex` 原生二进制里。
|
||||
|
||||
当前可确认的官方形态:
|
||||
|
||||
- 对话主通道同时存在 `responses_http` 和 `responses_websocket` 两类 transport。
|
||||
- WebSocket beta 头为 `OpenAI-Beta: responses_websockets=2026-02-06`。
|
||||
- 请求头会携带 `Authorization`、`ChatGPT-Account-Id`、`originator`、`User-Agent`。
|
||||
- 原生二进制包含 `x-client-request-id`、`x-oai-attestation`、`x-responsesapi-include-timing-metrics`、`x-codex-installation-id`、`x-codex-turn-state` 等请求相关字段。
|
||||
- 请求体/WS payload 关键字段包含 `model`、`instructions`、`input`、`parallel_tool_calls`、`previous_response_id`、`store`、`include`、`client_metadata`。
|
||||
- 官方响应处理以 `response.completed` 作为完成边界;二进制里有 `stream closed before response.completed` 和 `remote compaction v2 stream closed before response.completed`。
|
||||
- 官方 WebSocket 失败存在回退路径,二进制里有 `websocket connection is unavailable`、`Falling back from WebSockets to HTTPS transport.`、`try_switch_fallback_transport`。
|
||||
- Cloudflare/cookie 风控存在官方实现,二进制里有 `ChatGptCloudflareCookieStore`、`set_cookies`、`cookies`。
|
||||
|
||||
## 官方证据
|
||||
|
||||
### Electron main
|
||||
|
||||
文件:`/tmp/codex-desktop-official/app-asar/.vite/build/main-dSxbxAhH.js`
|
||||
|
||||
关键函数:
|
||||
|
||||
- `v_({ action, appServerClient, desktopOriginator, headers, refreshToken })`:调用 `appServerClient.getAuthToken`。
|
||||
- `y_(headers, token, { desktopOriginator })`:写入认证和 surface 头。
|
||||
- `x_(token)`:解析 JWT 中 `https://api.openai.com/auth.chatgpt_account_id`。
|
||||
- `S_()`:生成 `Codex Desktop/<appVersion> (<platform>; <arch>)`。
|
||||
|
||||
可确认请求头:
|
||||
|
||||
- `Authorization: Bearer <token>`
|
||||
- `ChatGPT-Account-Id: <jwt auth.chatgpt_account_id>`
|
||||
- `originator: <desktopOriginator>`
|
||||
- `User-Agent: Codex Desktop/<version> (<platform>; <arch>)`
|
||||
|
||||
同一 bundle 还包含 remote control WebSocket:
|
||||
|
||||
- path:`/codex/remote/control/client`
|
||||
- remote control 同样通过 `getAuthHeaders` 获取认证头。
|
||||
- 解析入站头时同时接受 `ChatGPT-Account-Id` 和 `chatgpt-account-id`。
|
||||
|
||||
### 原生 codex 二进制
|
||||
|
||||
文件:`/tmp/codex-desktop-official/dmg-extract/Codex Installer/Codex.app/Contents/Resources/codex`
|
||||
|
||||
`strings` 可见的请求链路证据:
|
||||
|
||||
- `responses_websockets=2026-02-06`
|
||||
- `OpenAI-Beta`
|
||||
- `x-client-request-id`
|
||||
- `x-oai-attestation`
|
||||
- `x-responsesapi-include-timing-metrics`
|
||||
- `/responses/compact`
|
||||
- `x-codex-installation-id`
|
||||
- `responses_http`
|
||||
- `responses/responses`
|
||||
- `responses_websocket`
|
||||
- `websocket connection is unavailable`
|
||||
- `x-codex-turn-state`
|
||||
- `auth_manager_missing`
|
||||
- `recovery_succeeded`
|
||||
- `recovery_failed_permanent`
|
||||
- `recovery_failed_transient`
|
||||
- `stream closed before response.completed`
|
||||
- `model`
|
||||
- `instructions`
|
||||
- `input`
|
||||
- `parallel_tool_calls`
|
||||
- `previous_response_id`
|
||||
- `ResponsesWsRequest`
|
||||
- `response.create`
|
||||
- `store`
|
||||
- `include`
|
||||
- `client_metadata`
|
||||
|
||||
这些是二进制字符串证据,不等价于完整源码控制流;但足以证明官方包中存在这些 transport、请求字段、恢复状态和完成边界。
|
||||
|
||||
### Webview 额度逻辑
|
||||
|
||||
相关文件:
|
||||
|
||||
- `webview/assets/thread-context-inputs-B6tQCr7t.js`
|
||||
- `webview/assets/use-rate-limit-DfBgdYGx.js`
|
||||
- `webview/assets/rate-limit-rows-B5kE6YOz.js`
|
||||
- `webview/assets/usage-settings-BMxGTDii.js`
|
||||
- `webview/assets/codex-api-AUWtp9Y7.js`
|
||||
|
||||
确认点:
|
||||
|
||||
- `thread-context-inputs` 查询 `/wham/usage`,query key 为 `rate-limit-status`,失败 401/403/404 时返回 `null`。
|
||||
- `use-rate-limit` 把 `rate_limit.primary_window`、`secondary_window` 转成 `primary`、`secondary` bucket,并遍历 `additional_rate_limits`。每个 additional item 会按 `limit_name` 建一个独立 snapshot。
|
||||
- `rate-limit-rows` 将每个 snapshot 的 `primary` 和 `secondary` 按 `windowDurationMins` 从小到大排序为多行,5 小时、周、月分别映射成 `five-hour`、`weekly`、`monthly` key。
|
||||
- `usage-settings` 识别:
|
||||
- `300` 分钟:`5 hour usage limit`
|
||||
- `10080` 分钟:`Weekly usage limit`
|
||||
- `1440` 分钟:`Daily usage limit`
|
||||
- `30 * 1440` 分钟:`Monthly usage limit`
|
||||
- 月限额优先使用 `spend_control.individual_limit`;没有该字段时才从 30d rate-limit row 中取。
|
||||
- `codex-api` 有 `/wham/rate-limit-reset-credits` 和 `/consume`,用于额度 reset credit 的读取/消费。
|
||||
|
||||
结论:5h 和 7d/周限额可以同时出现,通常是同一个 snapshot 的 `primary_window` 与 `secondary_window`。30d/月限额是单独抽出来展示;free 账号常见只有月/30d 限额。
|
||||
|
||||
#### 限额组合还原
|
||||
|
||||
官方 webview 不是只取一个“当前限额”。它先把 `/wham/usage` 归一成 snapshot 列表:
|
||||
|
||||
- core snapshot:来自顶层 `rate_limit`,包含 `primary` 和 `secondary` 两个可选窗口。
|
||||
- additional snapshots:来自 `additional_rate_limits[]`,每个有 `limit_name` 的条目各自拥有 `primary` 和 `secondary`。
|
||||
- 月限额:展示层优先读取 `spend_control.individual_limit`;如果没有该字段,才在 core rows 里寻找 30d window。
|
||||
- workspace monthly:企业/workspace 路径还可能从 workspace monthly usage 单独构造一个 monthly row。
|
||||
|
||||
因此官方 UI 里出现的组合是合理的:
|
||||
|
||||
- `5h + 7d`:通常是同一个 snapshot 的 primary/secondary 窗口,官方会显示成两行 short-term rows。
|
||||
- `30d`:如果来自 `spend_control.individual_limit`,官方会作为 monthly usage limit 单独显示,并把 core 里的 30d row 从通用 rows 里过滤掉。
|
||||
- `free`:常见只看到 monthly/30d,是因为短周期窗口可能不存在,或者月限额由 spend control 提供。
|
||||
- model/additional:例如 `gpt-5.3-codex-spark` 这类 additional limit 会按 `limit_name` 单独组成 snapshot,和 core 限额不是同一行。
|
||||
|
||||
官方阻断判断也不是单看 `rate_limit.limit_reached`:`rate_limit.allowed === false`、`credits` 不可用、`spend_control.reached === true` 都会进入“额度不可用”的判断路径。additional limit 的阻断是按对应 `limit_name` 独立判断,不能简单等同于整个账号不可用。
|
||||
|
||||
### 官方响应事件
|
||||
|
||||
文件:
|
||||
|
||||
- `app-asar/.vite/build/worker.js`
|
||||
- `app-asar/.vite/build/workspace-root-drop-handler-DYf1cfzL.js`
|
||||
|
||||
可见的 OpenTelemetry/事件处理名单:
|
||||
|
||||
- operation:`responses.create`、`chat.completions.create`、`embeddings.create`
|
||||
- stream events:`response.created`、`response.in_progress`、`response.failed`、`response.completed`、`response.incomplete`、`response.queued`
|
||||
- delta/item events:`response.output_text.delta`、`response.output_item.added`、`response.function_call_arguments.delta`、`response.function_call_arguments.done`、`response.output_item.done`
|
||||
|
||||
官方 worker 会从流事件里收集 response id、model、timestamp、usage、finish reason、text 和 tool calls。
|
||||
|
||||
## 当前项目对齐
|
||||
|
||||
### Transport 选择
|
||||
|
||||
当前实现:`src/upstream/protocol/responses.rs`
|
||||
|
||||
- `force_http_sse = true` -> `HttpSse`
|
||||
- `previous_response_id.is_some()` -> `WebSocketRequired`
|
||||
- `use_websocket = true` -> `WebSocketPreferred`
|
||||
- 其他情况 -> `HttpSse`
|
||||
- `WebSocketRequired` 不允许 HTTP SSE fallback。
|
||||
|
||||
这和官方二进制里 `previous_response_id`、`responses_websocket`、`try_switch_fallback_transport` 的证据方向一致。
|
||||
|
||||
### HTTP SSE
|
||||
|
||||
当前实现:`src/upstream/transport/client.rs`
|
||||
|
||||
- POST `/codex/responses`
|
||||
- `Accept: text/event-stream`
|
||||
- body 为 `CodexResponsesRequest`
|
||||
- 非 2xx 转为 `CodexClientError::Upstream`,保留 status、body、`retry-after`、`set-cookie`
|
||||
- 非流式读取完整 SSE 文本并提取 usage
|
||||
- 流式返回 `bytes_stream`
|
||||
|
||||
### WebSocket
|
||||
|
||||
当前实现:
|
||||
|
||||
- `src/upstream/transport/websocket.rs` 把 base URL 的 `/codex/responses` 转成 `wss://.../codex/responses` 或 `ws://.../codex/responses`。
|
||||
- `src/upstream/transport/client.rs` 复用同一套请求头构造 WebSocket opening headers。
|
||||
- WebSocket 请求会写 audit artifact,包含 opening snapshot 和 payload snapshot。
|
||||
- 如果启用了 pool,会按账号/session 复用连接。
|
||||
|
||||
当前 WebSocket fallback:
|
||||
|
||||
- `WebSocketPreferred` 发生连接/transport 类错误时允许 fallback 到 HTTP SSE。
|
||||
- `WebSocketRequired` 不 fallback。
|
||||
- 上游明确 HTTP 状态错误不会被当作普通 WS 连接错误降级。
|
||||
|
||||
这对应官方二进制里的:
|
||||
|
||||
- `websocket connection is unavailable`
|
||||
- `Falling back from WebSockets to HTTPS transport.`
|
||||
- `try_switch_fallback_transport`
|
||||
|
||||
### 请求头
|
||||
|
||||
当前实现:`src/upstream/transport/client.rs`
|
||||
|
||||
基础 header 来自 fingerprint:
|
||||
|
||||
- `authorization`
|
||||
- `chatgpt-account-id`
|
||||
- `originator`
|
||||
- `user-agent`
|
||||
- `sec-ch-ua`
|
||||
- fingerprint 默认 header 和 header order
|
||||
|
||||
Responses 请求额外写入:
|
||||
|
||||
- `content-type: application/json`
|
||||
- `cookie`
|
||||
- `accept: text/event-stream`
|
||||
- `openai-beta: responses_websockets=2026-02-06`
|
||||
- `x-openai-internal-codex-residency: us`
|
||||
- `x-client-request-id`
|
||||
- `x-codex-installation-id`
|
||||
- `session_id`
|
||||
- `x-codex-window-id`
|
||||
- `x-codex-turn-state`
|
||||
- `x-codex-turn-metadata`
|
||||
- `x-codex-beta-features`
|
||||
- `x-responsesapi-include-timing-metrics`
|
||||
- `version`
|
||||
- `x-codex-parent-thread-id`
|
||||
- 条件写入 `x-openai-subagent`
|
||||
|
||||
官方二进制还出现 `x-oai-attestation`。当前项目没有构造该头;仅凭静态字符串无法确认其生成条件、签名来源和是否每次请求都必需,不能用固定值或伪造值补齐。
|
||||
|
||||
### 请求携带的数据
|
||||
|
||||
当前请求体:`src/upstream/protocol/responses.rs`
|
||||
|
||||
核心字段:
|
||||
|
||||
- `model`
|
||||
- `instructions`
|
||||
- `input`
|
||||
- `stream`
|
||||
- `store`
|
||||
- `reasoning`
|
||||
- `tools`
|
||||
- `tool_choice`
|
||||
- `parallel_tool_calls`
|
||||
- `text`
|
||||
- `service_tier`
|
||||
- `previous_response_id`
|
||||
- `prompt_cache_key`
|
||||
- `include`
|
||||
- `client_metadata`
|
||||
|
||||
不会序列化但影响 header/transport 的字段:
|
||||
|
||||
- `use_websocket`
|
||||
- `force_http_sse`
|
||||
- `turn_state`
|
||||
- `turn_metadata`
|
||||
- `beta_features`
|
||||
- `version`
|
||||
- `include_timing_metrics`
|
||||
- `codex_window_id`
|
||||
- `parent_thread_id`
|
||||
|
||||
OpenAI 入口支持从 body 或 header 读取这些 Codex 上下文字段:`src/proxy/openai/responses.rs`。
|
||||
|
||||
### SSE / WS 响应处理
|
||||
|
||||
当前实现:
|
||||
|
||||
- `src/upstream/protocol/responses.rs` 将 SSE 收集为 `Completed`、`Failed`、`MissingCompleted`、`Empty`。
|
||||
- `response.output_text.delta` 会累积文本。
|
||||
- `response.completed` 是成功边界。
|
||||
- `error` 或 `response.failed` 是失败边界。
|
||||
- 缺少 `response.completed` 时返回 `MissingCompleted`。
|
||||
|
||||
WebSocket 事件:
|
||||
|
||||
- `src/upstream/protocol/websocket.rs` 会跳过内部 `codex.rate_limits` 事件,不直接下发给 OpenAI 客户端。
|
||||
- 对 `response.completed`、`response.created`、`response.output_text.delta` 和各类 output item 做官方形状校验。
|
||||
- `src/upstream/protocol/events.rs` 解析 `codex.rate_limits`,转换成 `x-codex-primary-*`、`x-codex-secondary-*`、`x-codex-code-review-*` 等 rate-limit header pairs。
|
||||
|
||||
调度层:
|
||||
|
||||
- `src/proxy/dispatch/responses.rs` 在非流式和流式完成时记录 usage、event log、transport、rateLimitHeaders。
|
||||
- live stream 结束后再次按 `response.completed` 判定完成状态;未完成会记录 `missing_completed`。
|
||||
- live WebSocket 捕获到的 rate-limit 更新和 turn-state 更新会在 finalize 阶段合并。
|
||||
|
||||
### 风控和恢复
|
||||
|
||||
官方证据:
|
||||
|
||||
- `ChatGptCloudflareCookieStore`
|
||||
- `set_cookies`
|
||||
- `cookies`
|
||||
- `auth_manager_missing`
|
||||
- `recovery_succeeded`
|
||||
- `recovery_failed_permanent`
|
||||
- `recovery_failed_transient`
|
||||
|
||||
当前实现:
|
||||
|
||||
- `src/proxy/dispatch/cloudflare.rs` 从 `chatgpt.com` cookie store 为 `/codex/responses`、`/codex/responses/compact`、`/codex/usage` 拼接 cookie。
|
||||
- 捕获上游 `set-cookie` 并按账号持久化。
|
||||
- 403 body 命中 `cf-mitigated`、`cf-chl-bypass`、`_cf_chl`、`cf_chl`、`attention required`、`just a moment` 时进入 Cloudflare challenge cooldown。
|
||||
- 404 空 body 作为 path-block,立即删除账号 cookie,多次后禁用账号。
|
||||
- 调度层会在 Cloudflare challenge/path-block 后换号或返回明确错误。
|
||||
|
||||
### 额度和限流
|
||||
|
||||
官方 webview 使用 `/wham/usage` 获取额度;原生二进制有 `parse_rate_limit_event` 和 `codex.rate_limits`。
|
||||
|
||||
当前实现:
|
||||
|
||||
- `/wham/usage` 响应归一化在 `src/upstream/accounts/quota/mod.rs`。
|
||||
- `rate_limit.primary_window` / `secondary_window` -> `snapshots[].primary` / `snapshots[].secondary`
|
||||
- `additional_rate_limits[]` -> 独立 `snapshots[]`,`source = "additional"`,保留 `limit_name` / `metered_feature`
|
||||
- `spend_control.individual_limit` -> `monthly_limit`,优先作为月限额展示;没有该字段时才从 core 30d window 生成 `monthly_limit`
|
||||
- WebSocket 内部 `codex.rate_limits` 事件由 `src/upstream/protocol/events.rs` 解析。
|
||||
|
||||
本项目对齐官方后的展示约定:
|
||||
|
||||
- `5小时限额` 和 `周限额` 归入 `shortTerm` group,可以同时出现。
|
||||
- `月限额` 归入 `monthly` group,优先来自 `spend_control.individual_limit`,再回退到 30d rate-limit window。
|
||||
- additional/model 限额不覆盖 core 限额,作为独立 window 行保留;如果同一个 additional limit 同时有 5h/7d,也会拆成两行。
|
||||
- WebSocket `codex.rate_limits` 被动刷新只携带短周期窗口时,输出同样的 `snapshots` 结构,并保留已有 `monthly_limit`、`credits`、`spend_control` 和 additional snapshots,避免把 `/wham/usage` 拿到的月限额或 additional 限额冲掉。
|
||||
|
||||
### 真实数据验证
|
||||
|
||||
2026-06-25 使用本地 `.runtime` active free 账号调用 `GET /api/admin/accounts/quota`,经项目真实解密、请求官方 `/wham/usage`、归一化并落库。
|
||||
|
||||
官方实时响应形态:
|
||||
|
||||
- `plan_type = free`
|
||||
- `rate_limit.primary_window.limit_window_seconds = 2592000`
|
||||
- `rate_limit.primary_window.used_percent = 6`
|
||||
- `rate_limit.secondary_window = null`
|
||||
- `spend_control.individual_limit = null`
|
||||
- `credits.has_credits = false`
|
||||
|
||||
项目归一化结果:
|
||||
|
||||
- `snapshots[0].source = "core"`
|
||||
- `snapshots[0].primary.window_minutes = 43200`
|
||||
- `snapshots[0].secondary = null`
|
||||
- `monthly_limit.source = "rate_limit"`
|
||||
- 管理端账号列表返回 `quota.windows[0].group = "monthly"`、`labelDisplay = "月限额"`、`windowSeconds = 2592000`
|
||||
|
||||
结论:本地真实 free 账号确认为 30d/月限额单独展示。当前本地没有 active 的 5h+7d 账号可实时验证组合返回;该组合路径由官方 bundle 证据和项目测试覆盖。
|
||||
|
||||
## 当前差距
|
||||
|
||||
- `x-oai-attestation` 只确认官方二进制里存在,未确认生成算法、触发条件、签名材料和失败行为;当前项目不实现该头。
|
||||
- 原生二进制不能在当前 Linux 环境执行,无法做动态断点或真实 app-server 调用链追踪。
|
||||
- 官方包里没有 source map,JS bundle 为压缩产物;函数名和局部变量名不能视为稳定 API。
|
||||
- WebSocket 降级策略目前按现有项目实现理解为连接/transport 错误可降级,显式上游状态错误不降级;官方二进制字符串能证明有降级路径,但不能单独证明完整条件矩阵。
|
||||
|
||||
## 实现建议
|
||||
|
||||
短期不建议伪造 `x-oai-attestation`。如果后续真实链路出现必须 attestation 的 403/401,再单独做动态取证或抓官方运行态请求,确认该头来源后实现。
|
||||
|
||||
当前项目更应该保持:
|
||||
|
||||
- `responses_websockets=2026-02-06` beta 头。
|
||||
- `x-client-request-id`、`x-codex-installation-id`、`x-codex-window-id`、`x-codex-turn-state`、`x-codex-turn-metadata` 的透传。
|
||||
- `previous_response_id` 强制 WebSocket。
|
||||
- `WebSocketPreferred` 可降级 HTTP SSE,`WebSocketRequired` 不降级。
|
||||
- `codex.rate_limits` 内部事件不下发给客户端,但用于刷新账号限额状态。
|
||||
- Cloudflare cookie 捕获、重放、challenge cooldown、path-block 清 cookie/禁用账号。
|
||||
Reference in New Issue
Block a user