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 只顺带对照一下协议形态。

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 万估

凭证顺序（官方文档）：

该模型的 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"

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，流量却走代理，看起来省事。对照测试和排障时，我更愿意用方式 1 起一个独立名字，避免和官方能力混在一起。

`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.vendor-...]

注意：

自定义模型配了 api_key 或 env_key 后，这个模型用 key，不会拿 session 去打第三方
没配 key 的官方模型，继续用 grok login 的 session
第三方 key 别写进 git。优先 env_key，key 放 shell 环境或密钥管理工具

如果要把 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

[models]
# 日常默认改走网关时再打开
# default = "sub2api-grok"
# web_search = "sub2api-grok"

[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_backend_search = true   # group / 上游确认支持再开

Composer 同理，模型名以网关实际开放的列表为准：

toml

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

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
grok -m sub2api-grok -p "Reply with sub2api-ok"

key 别打进日志仓库。

其他第三方中转

中转写 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

云厂商直连时的常见形态（只是对照，不是 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-4.5"]
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

[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-4.5
# /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 里能不能看到自定义名
推理：grok -m <名> -p "ping"
Agent：让它读一个无关紧要的本地文件，再改一行。能聊天不代表 tool loop 稳
官方文档给的调试方式：

bash

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok -m <名> -p "ping"
# 看 model / sampling / base_url / 401 等

接上了也可能不好用

能力	官方 cli-chat-proxy	第三方网关
纯对话	一般正常	看上游
Agent 工具循环 / 流式 tool	catalog 上调过	参差不齐
`supports_backend_search`	部分官方模型为 true	多数中转是 false
上下文和 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`
官方和第三方并存	独立模型名；默认继续用官方 catalog
整机只走一个网关	`GROK_MODELS_BASE_URL` 或 `[endpoints] models_base_url`
Sub2API	`base_url = https://<域名>/v1`，`api_backend = "responses"`，key 用 group 签的 `sk-`
验证	curl → `grok models` → `-p` 冒烟 → 带 tool 的真实任务
文档真相源	本机 `~/.grok/docs/user-guide/11-custom-models.md`

配置改完后新开一个 grok 会话再测。已经在跑的进程不一定立刻重读全部策略。

Grok Build 接入第三方 API 上游 ​

文档和命令在哪 ​

什么都不改时走哪 ​

官方支持的三种接法 ​

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

2. 全局换 catalog / 网关 ​

3. 覆盖内置模型名 ​

api_backend 三种协议 ​

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

Sub2API 示例 ​

其他第三方中转 ​

多上游并排 ​

怎么验证 ​

接上了也可能不好用 ​

安全 ​

和 Codex 配第三方的对照 ​

改完记得 ​

Grok Build 接入第三方 API 上游

文档和命令在哪

什么都不改时走哪

官方支持的三种接法

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

2. 全局换 catalog / 网关

3. 覆盖内置模型名

`api_backend` 三种协议

官方模型和第三方一起用

Sub2API 示例

其他第三方中转

多上游并排

怎么验证

接上了也可能不好用

安全

和 Codex 配第三方的对照

改完记得