docs: 记录 Sub2API Grok 接入调查
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Codex
@@ -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。
|
||||
- 官方最新发布说明：<https://github.com/Wei-Shaw/sub2api/releases/tag/v0.1.155>。
|
||||
- `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://<sub2api-public-host>/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`：<https://github.com/Wei-Shaw/sub2api/pull/3310>。
|
||||
- PR #3558 补齐 Codex/OpenAI 兼容路由、WebSocket 入站桥接和 Codex 请求净化：<https://github.com/Wei-Shaw/sub2api/pull/3558>。
|
||||
- Issue #3952 记录旧实现缺失 Grok CLI 版本身份头会被 OAuth 上游以 426 拒绝：<https://github.com/Wei-Shaw/sub2api/issues/3952>。
|
||||
- PR #4009 修复 CLI 身份头、OAuth 路由、`additional_tools`、Composer 推理参数，并加入 xAI API Key 账号：<https://github.com/Wei-Shaw/sub2api/pull/4009>。
|
||||
- `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。
|
||||
@@ -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)。
|
||||
|
||||
Reference in New Issue
Block a user