Files

T

Codex 3f48b61fc7 docs: 记录 Sub2API Grok 接入调查

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-07-15 08:31:28 +02:00

5.9 KiB

Raw Blame History

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 源码。正确链路是：

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 配置步骤

在管理后台创建原生 Grok 账号：
- 订阅账号：选择 Grok -> OAuth 并完成 xAI 授权；推理默认走 https://cli-chat-proxy.grok.com/v1。
- 官方计费 API：选择 Grok -> API Key，base URL 使用 https://api.x.ai/v1。
创建平台为 grok 的分组，并把 Grok 账号加入该分组。
创建一个 Sub2API API Key，并把该 Key 指派给 Grok 分组。
先验证该 Key 的 /v1/models 能看到 grok-4.5，再做 /v1/responses 的同步、流式和工具调用 smoke。
对 OAuth 账号保持保守并发起步；是否提高并发应由实际首 Token、429 和渠道健康数据决定。

Codex 客户端配置模板

~/.codex/config.toml 可使用独立 provider，避免覆盖现有默认 provider：

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。

5.9 KiB Raw Blame History Unescape Escape