From 3f48b61fc7fb93b2261b9bfb4fc00247df4b6be5 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 19:16:39 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20Sub2API=20Grok=20?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E8=B0=83=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- .../R2.2.37_Task_Report.md | 94 +++++++++++++++++++ docs/MDTODO/sub2api-upstream-reliability.md | 3 + 2 files changed, 97 insertions(+) create mode 100644 docs/MDTODO/details/sub2api-upstream-reliability/R2.2.37_Task_Report.md diff --git a/docs/MDTODO/details/sub2api-upstream-reliability/R2.2.37_Task_Report.md b/docs/MDTODO/details/sub2api-upstream-reliability/R2.2.37_Task_Report.md new file mode 100644 index 00000000..781cfcb7 --- /dev/null +++ b/docs/MDTODO/details/sub2api-upstream-reliability/R2.2.37_Task_Report.md @@ -0,0 +1,94 @@ +# R2.2.37 Sub2API 原生 Grok 接入 Codex 调查报告 + +## 调查边界 + +本任务只读检查 `Wei-Shaw/sub2api` 官方仓库最新发布标签、主线源码、发布说明、issue 和合并 PR；未修改 PK01 runtime、YAML、源码或部署。 + +## 版本基线 + +- 官方仓库最新发布标签为 `v0.1.155`，提交 `41cec0db059ffb82d0efdcfcf07a24ab51fbfe97`，发布时间为 2026-07-14。 +- 官方最新发布说明：。 +- `v0.1.155` 已包含原生 Grok provider、Grok OAuth、xAI API Key、Codex Responses 兼容、Grok 渠道健康监控和近期 Grok 兼容修复。 + +## 核心结论 + +最新 Sub2API 已原生支持 Grok 上游接入 Codex，普通接入不需要修改 Sub2API 源码。正确链路是： + +```text +Codex CLI + -> Sub2API /v1/responses + -> Sub2API API Key 绑定的 platform=grok 分组 + -> platform=grok 的 OAuth 或 API Key 账号 + -> OAuth: cli-chat-proxy.grok.com/v1/responses + API Key: api.x.ai/v1/responses +``` + +不要把 Grok 配置成 `platform=openai` 的自定义 base URL。原生 Grok 路径负责 OAuth 刷新、CLI 身份头、请求字段净化、模型映射、配额观察、429 冷却和 Grok 专属健康监控；伪装成 OpenAI 会绕过这些能力。 + +## 官方源码证据 + +### 路由与分组选择 + +- `backend/internal/server/routes/gateway.go` 把 `PlatformOpenAI` 和 `PlatformGrok` 都识别为 OpenAI Responses 兼容平台。 +- `/v1/responses`、`/responses` 和 `/backend-api/codex/responses` 均可由 Grok 分组进入 OpenAI gateway。 +- API Key 所绑定分组的平台决定请求走哪个 provider，因此客户端使用的是 Sub2API API Key，不是直接使用 xAI Key。 + +### Grok 专用转发 + +- `backend/internal/service/openai_gateway_forward.go` 在账号平台为 `grok` 时直接调用 `forwardGrokResponses`。 +- `backend/internal/service/openai_gateway_grok.go` 同时接受 `oauth` 和 `api_key` 两种 Grok 账号。 +- 转发前会映射模型、净化 xAI 不兼容字段和工具，OAuth 请求还会带 Grok CLI 身份与缓存路由信息。 +- Codex WebSocket Responses 入站被接受，但 Grok 上游实际桥接为 HTTP/SSE，并非 xAI WebSocket 透传。 + +### 模型映射 + +- `backend/internal/pkg/xai/models.go` 默认包含 `grok-4.5`、`grok-4.3`、`grok-build-0.1`、`grok-composer-2.5-fast` 和 Grok 4.20 系列。 +- 默认别名包括 `grok -> grok-4.5`、`grok-latest -> grok-4.5`、`grok-build -> grok-build-0.1`、`grok-composer -> grok-composer-2.5-fast`。 +- 最清晰的 Codex 配置是直接请求 `grok-4.5`。只有消费端必须沿用其他模型名时，才在 Grok 账号的 `model_mapping` 中显式映射；不建议用 `gpt-*` 名称长期伪装 Grok，以免模型归因、价格和排障语义混乱。 + +## Sub2API 配置步骤 + +1. 在管理后台创建原生 Grok 账号： + - 订阅账号：选择 `Grok -> OAuth` 并完成 xAI 授权；推理默认走 `https://cli-chat-proxy.grok.com/v1`。 + - 官方计费 API：选择 `Grok -> API Key`，base URL 使用 `https://api.x.ai/v1`。 +2. 创建平台为 `grok` 的分组，并把 Grok 账号加入该分组。 +3. 创建一个 Sub2API API Key，并把该 Key 指派给 Grok 分组。 +4. 先验证该 Key 的 `/v1/models` 能看到 `grok-4.5`，再做 `/v1/responses` 的同步、流式和工具调用 smoke。 +5. 对 OAuth 账号保持保守并发起步；是否提高并发应由实际首 Token、429 和渠道健康数据决定。 + +## Codex 客户端配置模板 + +`~/.codex/config.toml` 可使用独立 provider，避免覆盖现有默认 provider： + +```toml +model_provider = "sub2api_grok" +model = "grok-4.5" + +[model_providers.sub2api_grok] +name = "Grok via Sub2API" +base_url = "https:///v1" +wire_api = "responses" +requires_openai_auth = true +supports_websockets = false +``` + +认证使用绑定 Grok 分组的 Sub2API API Key，通过 Codex 既有 `auth.json` 或受控凭据入口注入；不要把 xAI Key 直接交给 Codex，也不要把密钥写入仓库。初次接入建议保持 HTTP Responses；Sub2API 虽支持 Codex WebSocket 入站，但 Grok 上游仍为 HTTP/SSE，只有完成真实 WS smoke 后再启用 Codex WebSocket 标记。 + +## 官方 issue 与修复演进 + +- 原生 Grok 订阅支持由 PR #3310 引入，明确覆盖 `/v1/responses`、`/responses` 和 `/backend-api/codex/responses`：。 +- PR #3558 补齐 Codex/OpenAI 兼容路由、WebSocket 入站桥接和 Codex 请求净化：。 +- Issue #3952 记录旧实现缺失 Grok CLI 版本身份头会被 OAuth 上游以 426 拒绝：。 +- PR #4009 修复 CLI 身份头、OAuth 路由、`additional_tools`、Composer 推理参数，并加入 xAI API Key 账号：。 +- `v0.1.152` 已发布上述关键修复，`v0.1.155` 又修复 Grok reasoning `content:null` 422、缓存路由和监控能力，因此新接入应直接以 `v0.1.155` 为基线。 + +## 风险与验收重点 + +- OAuth 与 API Key 是不同上游路径，不能混用 base URL：OAuth 走订阅 CLI proxy，API Key 走 `api.x.ai`。 +- Codex 的私有/新增 Responses 字段可能领先 xAI schema；`v0.1.155` 已清理已知的 `additional_tools`、不兼容 reasoning 字段和 `content:null`，仍应以真实工具调用 smoke 为准。 +- Grok quota 是被动观察上游 rate-limit header；首次成功请求前显示 unknown 属正常现象。 +- `401` 表示凭据问题，`403` 表示权限或订阅 entitlement，`429` 会进入临时不可调度；这些应按真实错误分类，不能统一当网络失败。 + +## 建议 + +直接采用 `v0.1.155` 的原生 Grok provider，优先建立独立 Grok 分组和独立 Sub2API Key，以 `grok-4.5 + Responses + HTTP` 作为首个受控配置。无需 Sub2API 源码变更；下一步若要落地，应先把账号、分组、Key 和模型映射声明进 owning YAML，再走受控 plan/apply 和最小 smoke。 diff --git a/docs/MDTODO/sub2api-upstream-reliability.md b/docs/MDTODO/sub2api-upstream-reliability.md index 208bcdac..89cd3d13 100644 --- a/docs/MDTODO/sub2api-upstream-reliability.md +++ b/docs/MDTODO/sub2api-upstream-reliability.md @@ -133,6 +133,9 @@ #### R2.2.36 [completed] 由 Artificer 优化 Sub2API 利润统计 CLI 的单次聚合与渐进披露，减少 7 天成本利润计算中的重复查询、外部解析和手工算术；默认 Kubernetes 风格与显式 JSON 都应直接保留紧凑汇总，账号明细语义化下钻，缺失历史成本时输出参数化利润公式；不修改 runtime 或部署，关联 [GitHub issue #2043](https://github.com/pikasTech/unidesk/issues/2043)，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.2.36_Task_Report.md)。 +#### R2.2.37 [in_progress] + +把 `~/.codex/config.toml.grok` 和 `~/.codex/auth.json.grok` 调整为通过 Sub2API 原生 Grok 分组接入 Codex；保留密钥脱敏和文件权限，先验证现有 Key 的分组/模型能力，再修改并做最小只读配置验收，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.2.37_Task_Report.md)。 ### R2.3 [completed] 调查并收敛 Sub2API 原生 system-log 索引未保留策略事件的能力缺口，关联 [Issue #2027](https://github.com/pikasTech/unidesk/issues/2027)，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.3_Task_Report.md)。