Grok Build 接入第三方 API 上游

记一下 Grok Build（grok CLI / TUI）怎么接第三方或自建 API。材料主要来自本机 grok 0.2.101 自带的用户手册：~/.grok/docs/user-guide/11-custom-models.md、05-configuration.md、02-authentication.md，以及 ~/.grok/README.md 里 Custom Models 那一段。文中第三方以 OpenAI 兼容网关为主（Sub2API、其他 2api 中转）；Azure / AWS 只顺带对照一下协议形态。后半的 Sub2API 段是按本机实际上游跑通后补的。

Grok Build 本身就支持自定义模型端点，不用改二进制。改的是用户配置：

text

~/.grok/config.toml

通常我会：

继续留着 grok login 的 session 和官方模型（比如 grok-4.5）
在配置里加几段 [model.xxx]，各自带上第三方的 base_url 和 key
用 /model、-m，或者 [models] default 切换

上游如果提供 OpenAI 兼容的 Chat Completions、Responses，或者 Anthropic Messages，就可以用 api_backend 对接。

字段以你当前 CLI 版本自带的文档为准。升级大版本后，最好再扫一眼 Custom Models 章节。

文档和命令在哪

本机安装包里的路径（版本升级后内容可能变）：

文档	本机路径
Custom Models	`~/.grok/docs/user-guide/11-custom-models.md`
Configuration	`~/.grok/docs/user-guide/05-configuration.md`
Authentication	`~/.grok/docs/user-guide/02-authentication.md`
README	`~/.grok/README.md` 里 Custom Models 一节

命令：

bash

~/.grok/bin/grok --version   # 或者 PATH 里的 grok
grok models
grok -m <模型名> -p "ping"

TUI 里：

text

/model <名字>
# 或 /m <名字>
# 焦点在 scrollback 时，Ctrl+M 可以开 model picker

什么都不改时走哪

没写自定义模型时，Grok 走 xAI 默认通道：

鉴权：grok login 的 session（~/.grok/auth.json），或者环境变量 XAI_API_KEY
模型列表：从官方代理预取。本机缓存里常见 origin 是 https://cli-chat-proxy.grok.com/v1/models
具体有哪些模型，以 grok models 输出为准。我这边常见是 grok-4.5、grok-composer-2.5-fast
官方预取条目里，api_backend 经常是 responses

接第三方是在现有配置上加模型，一般不用先 grok logout。

官方支持的三种接法

1. 按模型写 `[model.xxx]`（最常用）

官方写得最全，也最适合官方和多家第三方并存。

toml

# ~/.grok/config.toml

[model.my-upstream]
model = "grok-4.5"                        # 发给上游 API 的 model 字段
base_url = "https://api.example.com/v1" # OpenAI 兼容根路径，一般带 /v1
name = "My Upstream Grok"               # picker 里的显示名
description = "Sub2API / 中转"            # 可选
api_key = "sk-..."                      # 可选；更建议 env_key
env_key = "MY_UPSTREAM_API_KEY"         # 可选；字符串或数组，第一个非空生效
api_backend = "responses"               # chat_completions | responses | messages
temperature = 0.7                       # 可选
top_p = 0.95                            # 可选
max_completion_tokens = 8192            # 可选
context_window = 128000                 # 建议按上游真实窗口填
extra_headers = { "X-Request-Tags" = "team=dev" }  # 可选，原样附加请求头

几个字段：

字段	干什么
段名 `my-upstream`	CLI / picker 里用的逻辑名，例如 `/model my-upstream`
`model`	请求体里的 model id；不写就用段名
`base_url`	上游 API 根路径
`api_backend`	协议；不写默认 `chat_completions`
`api_key` / `env_key`	这个模型自己的凭证
`extra_headers`	非 Bearer 鉴权时用，比如 Anthropic 的 `x-api-key`，或某些 Azure 的 `api-key`
`context_window`	给 auto-compact 用。自定义模型最好写上，不然可能按默认 20 万估
`supports_reasoning_effort`	是否允许 `/effort`、`--effort`（自定义条目默认关，见下文）
`supports_backend_search`	是否声明支持后端 web search；网关没这能力就别开

凭证顺序（官方文档）：

该模型的 api_key
该模型的 env_key（可写数组，取第一个非空）
已登录的 session token（这个模型没配 key 时）
全局 XAI_API_KEY（旧名 GROK_CODE_XAI_API_KEY 也认）

用法：

bash

export MY_UPSTREAM_API_KEY="sk-..."

grok models
grok -m my-upstream -p "ping"

# TUI 里: /model my-upstream

想默认就用它：

toml

[models]
default = "my-upstream"

只对新建 session 生效。 resume 旧对话会沿用当时的模型，不会自动切到新 default。环境变量 GROK_DEFAULT_MODEL 也能盖默认，优先级高于 config。

2. 全局换 catalog / 网关

适合整机只走一个 OpenAI 兼容网关，而且网关真有 /v1/models：

bash

export GROK_MODELS_BASE_URL="https://api.acme.com/v1"
export XAI_API_KEY="网关签发的 key"   # Authorization: Bearer
# 列表 URL 和 {base}/models 不一致时再设
export GROK_MODELS_LIST_URL="https://api.acme.com/v1/models"
grok

或写配置：

toml

[endpoints]
models_base_url = "https://api.acme.com/v1"

行为大概是：

启动时拉 {base_url}/models（或 GROK_MODELS_LIST_URL）
推理请求打到这个 base
鉴权改走 API Key，不再依赖 grok login session

也可以和方式 1 一起用：[endpoints] 定默认 base，个别 [model.*] 只覆盖 api_key 之类。

我自己如果要同时挂官方、Sub2API、外部中转，不会用全局 models_base_url 把官方 catalog 顶掉，还是按模型分段更清楚。

3. 覆盖内置模型名

只改官方模型的一部分字段，没写的继承默认：

toml

[model.grok-4.5]
base_url = "https://api.example.com/v1"
api_key = "sk-..."
api_backend = "responses"

优先级（官方）：

你的 [model.*]（最高）
远程 /v1/models 预取
硬编码默认（最低）

名字还叫 grok-4.5，流量却走代理，看起来省事。覆盖内置名时，一般会继承官方 catalog 里的能力声明（例如 supports_reasoning_effort、可选 effort 列表），不用自己再抄一遍。

对照测试和排障时，我更愿意用方式 1 起一个独立名字，避免和官方能力混在一起；那就得自己补 supports_reasoning_effort 等字段。

`api_backend` 三种协议

toml

api_backend = "chat_completions"  # 默认；/v1/chat/completions
# api_backend = "responses"       # /v1/responses
# api_backend = "messages"        # Anthropic /v1/messages

值	协议	常见场景
`chat_completions`	OpenAI Chat Completions	多数 OpenAI 兼容中转、Ollama、Together
`responses`	OpenAI Responses	官方 `grok-4.5` / Composer 当前 catalog；部分新网关
`messages`	Anthropic Messages	Claude 直连，常配 `extra_headers` 里的 `x-api-key`

文档里 Claude 示例的结构：

toml

[model.claude-opus]
model = "claude-opus-4-6"
base_url = "https://api.anthropic.com/v1"
name = "Claude Opus 4.6"
api_backend = "messages"
context_window = 200000
extra_headers = { "x-api-key" = "sk-ant-...", "anthropic-version" = "2023-06-01" }

接第三方时我一般这么试：

先看上游文档写的是 Chat 还是 Responses
对齐 Grok / xAI 订阅代理的，先试 responses
401、404 或空响应，再改 chat_completions
个别 BYOK 对流式 tool 不兼容时，给这个模型设 stream_tool_calls = false（全局也能在 [models] 下设）

官方模型和第三方一起用

比较省心的布局：

text

官方 session  →  grok-4.5 / grok-composer-2.5-fast（catalog 默认）
Sub2API       →  [model.sub2api-grok]、[model."sub2api-composer-2.5"]
外部中转      →  [model.vendor-...]

注意：

自定义模型配了 api_key 或 env_key 后，这个模型用 key，不会拿 session 去打第三方
没配 key 的官方模型，继续用 grok login 的 session
第三方 key 别写进 git。优先 env_key，key 放 shell 环境或密钥管理工具
picker 里会同时出现官方名和自定义名。展示名写成 via Sub2API 之类，少误点
只想日常用自定义、又怕手滑点到官方：可以 [models] hidden_models = ["grok-4.5", "grok-composer-2.5-fast"]，或更严的 allowed_models

如果要把 web_search 也指到自定义模型，官方要求同时有 [models] web_search 和对应的 [model.*]，而且 web search 走 Responses 路径。模型上再声明 supports_backend_search = true 时，才会按后端搜索能力处理。网关没这能力就别开，照抄字段没意义。

Sub2API 示例

Sub2API 是一类常见的订阅配额分发 + OpenAI 兼容转发网关。它 README 里的 Grok Build CLI Configuration 和 Grok 官方 Custom Models 字段是对得上的；下面是按本机实际上游跑通后整理的写法。

管理端先准备：

加 Grok 上游账号（OAuth 订阅或 xAI API Key）
建 Grok group，把账号挂进去
发一张绑定这个 group 的 API Key（sk-...）
用户侧可以用 Use Key → Grok CLI 生成配置，也可以手写

手写时 base_url 是 Sub2API 的公网地址加 /v1，不是 api.x.ai：

toml

# ~/.grok/config.toml

[models]
default = "sub2api-grok"
web_search = "sub2api-grok"
default_reasoning_effort = "high"

[model.sub2api-grok]
model = "grok-4.5"
base_url = "https://your-sub2api.example.com/v1"
name = "Grok 4.5 via Sub2API"
description = "Grok 4.5 through a Sub2API Grok group"
env_key = "SUB2API_API_KEY"
api_backend = "responses"
context_window = 500000
supports_reasoning_effort = true
# supports_backend_search = true   # group / 上游确认支持再开

[model."sub2api-composer-2.5"]
model = "grok-composer-2.5-fast"
base_url = "https://your-sub2api.example.com/v1"
name = "Composer 2.5 via Sub2API"
description = "Composer 2.5 through Sub2API"
env_key = "SUB2API_API_KEY"
api_backend = "responses"
context_window = 200000
supports_reasoning_effort = true
# supports_backend_search = true

几点对应关系：

配置	含义
段名 `sub2api-grok`	Grok Build 里的逻辑 id：`/model sub2api-grok`、`default`
`model = "grok-4.5"`	请求体发给上游的 model id，不是你在 picker 里看到的逻辑名
`api_backend = "responses"`	和当前官方 catalog 一致；请求打到 `{base}/responses`
`supports_reasoning_effort = true`	自定义条目默认不继承官方 effort 能力，要自己开
段名带点	必须写成 `[model."sub2api-composer-2.5"]`，见下节踩坑

Sub2API 文档里提到的 Grok 相关路径包括 /v1/responses、/v1/chat/completions、/v1/messages（会转到 Responses）等。Grok Build 这边按上面用 responses + /v1 就够了。

连通性：

bash

export SUB2API_API_KEY="sk-..."

curl -sS "https://your-sub2api.example.com/v1/models" \
  -H "Authorization: Bearer $SUB2API_API_KEY" | head

grok models
# 期望看到 * sub2api-grok (default)

grok -m sub2api-grok -p "Reply with sub2api-ok"
grok -m sub2api-grok --effort high -p "Reply with effort-ok"

key 别打进日志仓库。api_key 明文写进 config.toml 能跑，但更建议 env_key。

本机踩过的坑

1. 思考等级：`current model does not support reasoning effort`

TUI 的 /effort、CLI 的 --effort / --reasoning-effort，只看当前模型 catalog 里的 supports_reasoning_effort。
自定义 [model.*] 不会自动继承官方 grok-4.5 的 effort 元数据。段里只写了 base_url 和 key 时，客户端直接拒绝，报：

text

current model does not support reasoning effort

处理：

toml

[model.sub2api-grok]
# ...
supports_reasoning_effort = true

或者方式 3 覆盖内置名 [model.grok-4.5]，让它继承官方的 effort 列表。

打开开关之后：

客户端会下发 reasoning_effort
非法等级会提示可选列表，例如 xhigh, high, medium, low（以你这版 catalog 为准）
不保证上游 / 网关真的消费这个字段。本机实测：grok-4.5 经 Sub2API 回写过 reasoning_effort=Medium/High；Composer 即使开了开关，响应元数据也可能是 None

官方 catalog 里 grok-composer-2.5-fast 本身也是 supports_reasoning_effort: false。给 Composer 自定义条目硬开，最多是 UI / CLI 不拦，效果另说。

2. TOML 段名带点会被拆开

toml

# 错：TOML 把裸点号当嵌套表
[model.sub2api-composer-2.5]
# 解析结果更像 model.sub2api-composer-2 下再挂 5
# grok models 里可能变成 sub2api-composer-2
# base_url / api_key 挂歪，请求会掉回官方 cli-chat-proxy 然后 404

# 对：段名加引号
[model."sub2api-composer-2.5"]

改完后 grok models 应完整显示 sub2api-composer-2.5。

3. default 配了，进来还是官方模型

多半是 resume 了旧 session。[models] default 只作用于新建会话；旧对话记住了当时的 grok-4.5 + OAuth。

新开一局，或
在旧对话里 /model sub2api-grok

另外：日志里 wire 名仍可能是 model_id=grok-4.5（请求体里的 model 字段），和逻辑名 sub2api-grok 不是一回事。看展示名「via Sub2API」、或 RUST_LOG 里的 base_url / auth_type=ApiKey 更准。

4. 后台仍会碰到官方域名

就算主对话走 Sub2API，feedback、模型预取等仍可能访问 cli-chat-proxy.grok.com。这和「当前选中模型的推理是否打第三方」要分开看。

其他第三方中转

中转写 Azure / AWS 上游时，Grok 侧没有单独插件配置，还是方式 1。model 填面板上的模型名，base_url 填对方给的 OpenAI 兼容根路径：

toml

[model."vendor-proxy-grok"]
model = "上游面板里的模型名"
base_url = "https://vendor.example.com/v1"
name = "Vendor Grok"
env_key = "VENDOR_PROXY_API_KEY"
api_backend = "responses"    # 不通再改 chat_completions
context_window = 128000
supports_reasoning_effort = true   # 上游真支持再开

云厂商直连时的常见形态（只是对照，不是 Grok 专用字段）：

上游	常见 base（示意）	备注
Azure AI Foundry v1	`https://<resource>.openai.azure.com/openai/v1/` 或 `...services.ai.azure.com/openai/v1/`	`model` 多半是 deployment name；鉴权可能是 Bearer，也可能是 `api-key` 头（后者用 `extra_headers`）
AWS Bedrock Mantle（文档里的 Grok 4.3）	`https://bedrock-mantle.<region>.api.aws/openai/v1`	model id 如 `xai.grok-4.3`；用 Bedrock API key，按 OpenAI 客户端方式调

几件容易踩坑的事：

云上有没有 grok-4.5 或 Composer，看厂商当前 model card，别默认等于 xAI cli-chat-proxy 上的同名模型
中转后台写 Azure / AWS 上游，客户端验证不了。只能看延迟、tool 调用是否正常、账单里记的是不是你以为的那条
Grok Build 不内置 AWS SigV4 或 Azure AD 自动刷新。要么 API Key，要么前面加一层网关，要么用 auth_provider_command 吐 token

多上游并排

toml

# 不写 default，或 default = "grok-4.5"，官方默认就还在

[model.sub2api-grok]
model = "grok-4.5"
base_url = "https://your-sub2api.example.com/v1"
name = "Sub2API Grok 4.5"
env_key = "SUB2API_API_KEY"
api_backend = "responses"
context_window = 500000
supports_reasoning_effort = true

[model."vendor-a-grok"]
model = "grok-4.5"
base_url = "https://vendor-a.example/v1"
name = "VendorA Grok"
env_key = "VENDOR_A_API_KEY"
api_backend = "chat_completions"
context_window = 128000

bash

export SUB2API_API_KEY="sk-..."
export VENDOR_A_API_KEY="sk-..."

grok models
# /model sub2api-grok
# /model vendor-a-grok
# /model grok-4.5

怎么验证

按顺序做，少瞎猜：

版本：grok --version，字段以该版本用户手册为准
上游直连：curl 测 /v1/models，再测 /v1/responses 或 /v1/chat/completions
配置语法：TOML 段名带点时写成 [model."a.b"]；用 env_key 时确认环境变量已经 export
grok models 里能不能看到自定义名，default 星号是否对
推理：grok -m <名> -p "ping"
effort（若开了开关）：grok -m <名> --effort high -p "ping"；乱填等级应列出可选值，而不是 does not support
Agent：让它读一个无关紧要的本地文件，再改一行。能聊天不代表 tool loop 稳
确认真打到第三方，不是官方 OAuth：

bash

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log \
  grok -m sub2api-grok --effort medium -p "ping"

# 期望大致看到：
# - base_url=https://your-sub2api.../v1
# - auth_type=ApiKey（或 sampling 里 auth_prefix=sk-...）
# - applying reasoning_effort override ... effort=medium
# - http ... endpoint=https://your-sub2api.../v1/responses
#
# 不该是：
# - 主推理打到 cli-chat-proxy.grok.com 且 Auth: Oidc
# - current model does not support reasoning effort

接上了也可能不好用

能力	官方 cli-chat-proxy	第三方网关
纯对话	一般正常	看上游
Agent 工具循环 / 流式 tool	catalog 上调过	参差不齐
`supports_backend_search`	部分官方模型为 true	多数中转是 false
`supports_reasoning_effort`	官方 catalog 自带	自定义条目要手开；上游是否吃参数另说
上下文和 auto-compact	catalog 自带窗口	靠你填的 `context_window`
图像 / 视频等	另有官方能力	网关未必透传

官方还提到：全局 [models] stream_tool_calls = true 时，个别 BYOK 可能不兼容，可以只对那个模型关掉。

安全

key 不要进仓库。api_key 写进 config.toml 省事，但不合适；优先 env_key
config.toml 本机限制读取，例如 chmod 600
自建或中转转发订阅 / 云 API，可能踩上游 ToS。公司自建要有内部口径；个人中转自己担风险
请求会先到第三方网关再打上游，代码和 prompt 的出境面变大。敏感仓可以再配合关闭本机代码上传
别拿生产密钥做连通性测试

和 Codex 配第三方的对照

	Codex	Grok Build
配置文件	`~/.codex/config.toml`	`~/.grok/config.toml`
提供商	`[model_providers.xxx]` + 顶层 `model_provider`	`[model.xxx]` 直接写 `base_url`
协议字段	`wire_api`（例如 `responses`）	`api_backend`
第三方 token	例如 `experimental_bearer_token`	`api_key` / `env_key`
和账号登录并存	可登录 ChatGPT，底层再走 token	可保留 `grok login`，自定义模型单独 key

Codex 侧：账号登录 + 第三方 API。

改完记得

想做什么	大致怎么配
接一家 OpenAI 兼容上游	`[model.名字]` + `base_url` + `env_key` + 对的 `api_backend`
官方和第三方并存	独立模型名；`default` 指自定义；必要时 `hidden_models`
整机只走一个网关	`GROK_MODELS_BASE_URL` 或 `[endpoints] models_base_url`
Sub2API	`base_url = https://<域名>/v1`，`api_backend = "responses"`，key 用 group 签的 `sk-`
思考等级	自定义条目加 `supports_reasoning_effort = true`；或覆盖内置 `[model.grok-4.5]`
段名带点	`[model."a.b"]`，别写裸点
默认仍像官方	先确认是不是 resume 旧 session；再查 `/model` 和 `base_url`
验证	curl → `grok models` → `-p` → `--effort` → `RUST_LOG` 看 base_url / ApiKey
文档真相源	本机 `~/.grok/docs/user-guide/11-custom-models.md`

配置改完后新开一个 grok 会话再测。已经在跑的进程、以及 resume 的旧对话，不一定立刻变成你刚改的 default。

Grok Build 接入第三方 API 上游 ​

文档和命令在哪 ​

什么都不改时走哪 ​

官方支持的三种接法 ​

1. 按模型写 [model.xxx]（最常用） ​

2. 全局换 catalog / 网关 ​

3. 覆盖内置模型名 ​

api_backend 三种协议 ​

官方模型和第三方一起用 ​

Sub2API 示例 ​

本机踩过的坑 ​

1. 思考等级：current model does not support reasoning effort ​

2. TOML 段名带点会被拆开 ​

3. default 配了，进来还是官方模型 ​

4. 后台仍会碰到官方域名 ​

其他第三方中转 ​

多上游并排 ​

怎么验证 ​

接上了也可能不好用 ​

安全 ​

和 Codex 配第三方的对照 ​

改完记得 ​

Grok Build 接入第三方 API 上游

文档和命令在哪

什么都不改时走哪

官方支持的三种接法

1. 按模型写 `[model.xxx]`（最常用）

2. 全局换 catalog / 网关

3. 覆盖内置模型名

`api_backend` 三种协议

官方模型和第三方一起用

Sub2API 示例

本机踩过的坑

1. 思考等级：`current model does not support reasoning effort`

2. TOML 段名带点会被拆开

3. default 配了，进来还是官方模型

4. 后台仍会碰到官方域名

其他第三方中转

多上游并排

怎么验证

接上了也可能不好用

安全

和 Codex 配第三方的对照

改完记得