Grok Build 中转站API接入配置教程

# Grok Build 中转站配置教程

> 适用：`grok`（xAI 的终端编程智能体 Grok Build）  
> 中转站地址：`https://api.zaimod.com/v1`  
> 主线：**建令牌 → 装 grok → 写一份 `~/.grok/config.toml` → 发一句话确认走的是你的余额**，约 10 分钟

---

## 一、先弄清这是哪条线

Grok Build 是 xAI 的终端编程智能体，命令就是 `grok`。它有三种用法：交互式 TUI、`-p` 无头模式（脚本 / CI）、以及 ACP 协议供别的编辑器调用。定位和 Claude Code、Codex CLI、Gemini CLI 是同一类东西 —— **不是 Grok 网页版，也不是 grok.com 的会员订阅**。

这一点必须先说清，因为很多人第一次配完会去 grok.com 看"为什么我的额度没动"。本教程走的是 **API Key 计费**：请求打到中转站，扣中转站余额，和 xAI 账号、X Premium、SuperGrok 订阅都没有关系，也不需要注册 xAI。

| 你手上的东西         | 配这个文档之后                   |
| -------------- | ------------------------- |
| xAI / X 账号     | **不需要**，全程不登录 xAI         |
| grok.com 订阅额度  | **不消耗**，也不会显示在那边          |
| 中转站令牌（分组 Grok） | 走这个，按量扣费                  |
| 浏览器 OAuth 登录态  | 反而要清掉，否则可能抢在 Key 前面（见第八章） |

**版本节奏要有心理准备**：Grok Build 在 2026 年 8 月 7 日发布 1.0.0 转正，之后基本一两天一个版本。原文截图里的 `grok 0.2.101` 属于 0.x 时代，已经落后一大截。所以本教程**不把版本号当成判断依据**，只把"命令能跑、配置能读到"当依据。

---

## 二、一分钟速查表

| 项目   | 填什么                                                                         |
| ---- | --------------------------------------------------------------------------- |
| 配置文件 | `~/.grok/config.toml`（Windows：`C:\Users\<用户名>\.grok\config.toml`）           |
| 服务地址 | `[endpoints] models_base_url = "https://api.zaimod.com/v1"` —— **必须带 `/v1`** |
| 请求协议 | `api_backend = "responses"`（走 `/v1/responses`）                              |
| 凭证   | `[model."…"]` 里 `api_key = "…"`，或 `env_key = "环境变量名"`                       |
| 令牌分组 | **Grok**（截图里那条分组说明是「满血自建 Grok 号池」，倍率 0.15x）                                 |
| 默认模型 | `[models] default` 指向某个 `[model.*]` 的**条目名**，不是模型 ID                        |
| 验证   | `grok inspect` 看配置有没有读进去 → `grok` 里发一句话 → 输入框右下角显示 `Grok 4.5`               |

**三个反直觉的点先说在前面：**

1. **地址要带 `/v1`**。这是本系列里少见的"带路径"派系（Claude Code、ChatGPT Sidebar 那些都是纯域名）。Grok Build 的规则很直接：模型列表取 `{base_url}/models`，请求发到 `{base_url}/responses`。写成纯域名就会变成 `https://api.zaimod.com/models` —— 实测 404。
2. **`[model."grok-4.5"]` 的引号不是排版习惯**。模型 ID 里有点号，裸写 `[model.grok-4.5]` 会被 TOML 解析成三段 key，条目名直接错位，`/model` 列表里找不到它。手改模型名时最容易把引号丢掉。
3. **一个 TOML 语法错误会让整份用户配置失效**，而 CLI 不会红字喊你。所以每次改完先跑 `grok inspect`，这是唯一权威的"到底读进去了没有"。

---

## 三、第一步：建令牌（分组 Grok）

**1. 控制台 → 令牌管理 → 创建令牌**

**2. 名称**随意，建议 `grok`，一眼能认出是给这条线用的。

**3. 令牌分组选「Grok」**

**4.「模型限制列表」留空**

![](/uploads/editor/20261101/img_6ae62ad2c149c3.59581028.png)

**5. 提交 → 回到令牌列表 → 「密钥」列 → 复制密钥**

---

## 四、第二步：安装 grok

### 4.1 Windows（PowerShell）

按 `Win+R`，输入 `powershell` 回车，然后：

```powershell
irm https://x.ai/cli/install.ps1 | iex
```

装完**必须重开一个 PowerShell 窗口**再验证。原因是安装器只把 `%USERPROFILE%\.grok\bin` 加到**用户级 PATH**，并对当前会话临时生效 —— 不重开时新窗口之外的旧会话读不到。

```powershell
grok --version
where.exe grok
```

![验证安装：grok --version 有输出即可](images/grok-build/01-version.png)

### 4.2 macOS / Linux

```bash
curl -fsSL https://x.ai/cli/install.sh | bash
```

装完同样重开终端：

```bash
grok --version
which -a grok
```

`.grok` 是隐藏目录，访达里按 `Command+Shift+.` 才看得见。macOS 的登录 shell 不读 `.bashrc`，安装脚本会替你在 `.bash_profile` 里补一行 —— 如果你自己维护 dotfiles，注意别被覆盖成两份 PATH。

### 4.3 装在哪儿、装了什么

安装器解出**两个**二进制到 `~/.grok/bin`（Windows 是 `%USERPROFILE%\.grok\bin`）：

- `grok` —— 交互式 CLI
- `agent` —— ACP 服务端，给编辑器 / 其它客户端调用

想换位置就在运行安装命令前设 `GROK_BIN_DIR`。只支持 x86_64 与 aarch64，其它架构会直接退出。

### 4.4 装不上时的两条备选路

**① x.ai 直连不通**。本机实测 `https://x.ai/cli/install.ps1` 与 `https://x.ai/cli/install.sh` 均返回 000（连接不通），`docs.x.ai` 同样。安装脚本有兜底：取不到通道指针时会改用 `storage.googleapis.com` 上的制品仓库，所以"命令没报错但卡住"通常是这一段在等超时。开代理是最省事的解法。

**② npm 安装**（需要 Node.js 20+）：

```bash
npm install -g @xai-official/grok
```

这条路适合本来就统一用 npm 管工具链的人，之后更新走 npm（`npm update -g @xai-official/grok`），不再走 `grok update`。

> **别用 `brew install grok`**。Homebrew 里那个 `grok` 是同名的正则表达式工具，装完 `grok --version` 会输出一段你完全看不懂的版本信息 —— 已经有人在这上面排查了半天。

---

## 五、第三步：写 `config.toml`

配置文件在 `~/.grok/config.toml`。设了 `GROK_HOME` 的话是 `$GROK_HOME/config.toml`；Windows 上也支持 `%USERPROFILE%\.grok\config.toml`。

### 5.1 Windows

```powershell
New-Item -ItemType Directory -Force "$HOME\.grok" | Out-Null
notepad "$HOME\.grok\config.toml"
```

PowerShell 里 `$HOME` 和 `$env:USERPROFILE` 是同一个路径，两种写法都行。

### 5.2 macOS

```bash
mkdir -p ~/.grok
touch ~/.grok/config.toml
open -e ~/.grok/config.toml
```

### 5.3 Linux

```bash
mkdir -p ~/.grok
nano ~/.grok/config.toml
```

nano 里粘完按 `Ctrl+O` 保存、回车确认文件名、`Ctrl+X` 退出。

### 5.4 粘贴这段

```toml
[models]
default = "grok-4.5"
web_search = "grok-4.5"

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

[model."grok-4.5"]
model = "grok-4.5"
name = "Grok 4.5"
description = "Grok 4.5 via api.zaimod.com"
api_key = "你的API_KEY"
api_backend = "responses"
context_window = 1000000
```

然后把 `你的API_KEY` 换成第三章复制的真 Key（只替换这段占位文字，别把引号弄丢）。

字段逐个说清：

| 字段                            | 作用                                            | 写错的后果                           |
| ----------------------------- | --------------------------------------------- | ------------------------------- |
| `[models] default`            | 启动时用哪个条目                                      | 填了不存在的条目名 → 报模型不存在              |
| `[models] web_search`         | 联网搜索工具用哪个模型                                   | 指向不存在的条目 → 搜索工具不可用（不一定报错）       |
| `[endpoints] models_base_url` | 模型发现 + 主要推理的统一地址                              | 少 `/v1` → 404；多写 `/v1/v1` → 404 |
| `[model."…"]`                 | 条目名（别名），`default` 和 `/model` 认的是它             | 裸写带点的名字 → 条目名被拆错                |
| `model`                       | 真正发给 API 的模型 ID                               | 与模型广场不一致 → 404 / 模型不存在          |
| `name`                        | 模型选择器里显示的名字                                   | 只影响显示                           |
| `api_key` / `env_key`         | 二选一：明文 Key，或环境变量名                             | 两个都写时 `api_key` 优先              |
| `api_backend`                 | `responses` / `chat_completions` / `messages` | 与地址能力不匹配 → 404 或解析失败            |
| `context_window`              | 声明上下文长度，影响 UI 与自动压缩时机                         | 写大于上游真实上限 → 长对话在上游被拒            |

**关于 `models_base_url` 的 `/v1`**：控制台「API 信息」面板把线路拆成四条 —— 主站正式线路、海外线路、常驻备用域名、长连接流式场景通道。Grok Build 是 SSE 流式长连接，理论上"长连接流式通道"也适配，但原文用的是主站域名，本教程保持一致。新平台这几条线合并成一个域名 `api.zaimod.com`，所以只填一个地址即可。

### 5.5 别急着"删除原有内容"

**如果这个文件是安装器刚生成的，里面有一段要留着**：

```toml
[cli]
installer = "internal"
```

安装器会写这个字段来标记自己是从哪条通道装的（npm 装的会写 `"npm"`），`grok update` / 自动更新据此决定更新方式。整份删掉之后，更新逻辑会退回默认猜测，运气不好就是"更新完变成另一条通道的版本"。

正确做法：**保留 `[cli]` 段，只替换 `[models]` / `[endpoints]` / `[model.*]` 这些业务段**。文件是空的（新建）就整段粘，无所谓。

---

## 六、第四步：启动与验证

```console
grok
```

第一次启动若弹出浏览器登录页，先别登 —— 那是走 xAI 官方账号。按 `Ctrl+C` 退出，回第八章看"会话 token 抢 Key"那条。

进入 TUI 后发一句：

```console
你好
```

![](/uploads/editor/20261101/img_6ae62b2c73d263.79291918.png)

### 6.1 看这三处，比"能回话"更硬

| 位置     | 正常值                                 | 说明                                               |
| ------ | ----------------------------------- | ------------------------------------------------ |
| 输入框右下角 | `Grok 4.5`                          | 就是你 `[model."grok-4.5"]` 里的 `name`。显示别的名字说明配置没读到 |
| 右上角    | `10K / 1.0M`                        | 已用 / 上限。`1.0M` 来自 `context_window`，说明这份配置生效了     |
| 消息下方   | `Thought for 0.1s`、`Worked for 14s` | 说明走的是带 reasoning 的模型链路                           |

最硬的判据其实是**后台**：控制台「使用日志」里出现这条调用，才算真的走了中转。TUI 里显示得再正常，只要日志没有记录，就说明请求打在别处。

### 6.2 三条命令行自查

```console
grok inspect
grok models
grok -p "只回复 ok" -m grok-4.5
```

- `grok inspect`：列出当前目录实际加载的配置来源，并对**被拒的字段给警告**。加 `--json` 可给脚本读。改完配置第一件事就是跑它。
- `grok models`：列出当前能用的模型（含自定义条目）。空的或只有内置几条，就是 `base_url` / TOML 层级有问题。
- `grok -p`：无头模式，一行命令验证完整链路，适合先排除 TUI 干扰。

### 6.3 改完配置要重启

`config.toml` 有变动时 Grok Build 通常会在 1 秒左右重载，但**改完立刻在旧会话里试是很容易踩空的**。稳妥做法：`Ctrl+C` 退出，重新 `grok`。

---

## 七、进阶：Key 不进文件、多模型、联网搜索

### 7.1 把 Key 挪进环境变量

把 `api_key = "你的API_KEY"` 换成：

```toml
env_key = "GROK_API_KEY"
```

然后设真正的环境变量：

```powershell
[Environment]::SetEnvironmentVariable("GROK_API_KEY", "你的API_KEY", "User")
```

```bash
export GROK_API_KEY="你的API_KEY"
echo 'export GROK_API_KEY="你的API_KEY"' >> ~/.zshrc
```

`env_key` 填的是**变量名**，不是 Key 本身 —— 这是最常见的误填。设完要重开终端，已经开着的窗口读不到新变量。

**权限收一下**（Linux / macOS）：

```bash
chmod 600 ~/.grok/config.toml
```

Windows 上就别把这个文件放进任何同步盘或共享目录。原文没提这点，但 `config.toml` 里躺着明文 Key，和密码同级。

### 7.2 一次登记多个模型

```toml
[models]
default = "grok-4.5"

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

[model."grok-4.5"]
model = "grok-4.5"
name = "Grok 4.5"
api_key = "你的API_KEY"
api_backend = "responses"
context_window = 1000000

[model."grok-4.7"]
model = "grok-4.7"
name = "Grok 4.7"
api_key = "你的API_KEY"
api_backend = "responses"
context_window = 500000
```

条目都写全，别指望 `[endpoints]` 的 `base_url` 无条件继承到推理路由上 —— 老版本（含截图里的 0.2.101）在这个继承上有已知问题，表现为请求落回 xAI 官方并 401。**每个 `[model.*]` 里该写的字段都写上**，最保险。

TUI 里用 `/model` 切换，或启动时 `grok -m grok-4.7`。

### 7.3 联网搜索要单独配模型

`[models] web_search` 不是"开 / 关搜索"的开关，而是"搜索工具用哪个模型"。这个模型必须有对应的 `[model.*]` 条目才够得着：

```toml
[models]
web_search = "grok-4.5"

[model."grok-4.5"]
model = "grok-4.5"
supports_backend_search = true
```

`supports_backend_search = true` 表示该端点支持**服务端搜索工具**（由上游执行搜索并回传结果）。中转站是否透传这类服务端工具，各家不一样；不确定就先去掉这一行，让搜索走客户端工具。

### 7.4 更常用的几个可选项

| 字段                                                | 作用                                   |
| ------------------------------------------------- | ------------------------------------ |
| `base_url`                                        | 只给单个 `[model.*]` 覆盖地址（多供应商混用时用）      |
| `supports_reasoning_effort`                       | 打开 `/effort` 思考档控制（低 / 中 / 高 / 极高四档） |
| `temperature` / `top_p` / `max_completion_tokens` | 常规采样参数                               |
| `[auth] preferred_method = "api_key"`             | 强制走 Key，不让 OAuth 会话顶掉（见 8.1）         |
| `[session] auto_compact_threshold_percent`        | 上下文用到多少百分比时自动压缩，官方默认 85              |

---

## 八、常见问题

**8.1 进了 TUI 却弹出浏览器登录页，或者扣的是 xAI 官方额度**

以前在这台机器上 `grok login` 过（凭证在 `~/.grok/auth.json`），会话 token 的优先级可能压过 API Key。两种解法：

```console
grok logout
```

或在配置里钉死：

```toml
[auth]
preferred_method = "api_key"
```

`grok logout` 会清掉本地 OAuth 凭证；不想删就只用 `preferred_method`。

**8.2 `grok: command not found` / `无法将 grok 项识别为 cmdlet`**

安装目录 `~/.grok/bin` 没进 PATH。先确认文件在不在，再重跑一次安装器（它只改用户级 PATH，不需要管理员）。Windows 上有时得注销一次才彻底生效。

**8.3 401 `Invalid token`**

这台中转站对 Key 缺失和 Key 错误给的是同一条响应，实测响应体长这样：

```json
{"error":{"code":"","message":"Invalid token (request id: …)","type":"new_api_error"}}
```

说明**路径是对的、Key 不对**。按顺序查：占位文字有没有替换干净、复制时有没有带上 `Bearer ` 前缀、令牌是不是被禁用、`env_key` 填的是不是变量名而不是 Key 本身。

**8.4 404 而不是 401**

`models_base_url` 少了或多写了 `/v1`。正确是 `https://api.zaimod.com/v1`，请求会落到 `/v1/models`、`/v1/responses`。写成纯域名就是 `/models`，写成 `/v1/` 加代码再拼一次就可能出现 `/v1/v1/`。

**8.5 403**

令牌的「模型限制列表」里没有当前模型。留空，或把用到的模型加进去。

**8.6 `/model` 里只有内置模型，看不到自己配的**

三处按顺序查：`[model."…"]` 的引号有没有丢（点号在裸 key 里是非法的层级分隔符）；`default` 填的是条目名还是模型 ID；最后跑 `grok inspect` 看有没有字段警告。**单个 TOML 错误会让整份用户配置失效**，所以"全都没生效"往往不是配置写错，而是少了个引号。

**8.7 回复到一半断了**

`api_backend = "responses"` 对 SSE 事件的解析比较严格，未知事件类型会中断本回合。如果中转侧在长思考时发送心跳 / keep-alive 帧，就会表现成"说到一半停住"。换成 `chat_completions` 一般能绕开（前提是该模型支持）。

**8.8 中文路径 / 空格路径下启动**

在项目目录里启动，不要在用户主目录。`grok` 以当前目录为工作区，主目录启动会把它当成一个巨型仓库去索引。路径里带空格时用引号包住再 `cd`。

---

上一篇：Antigravity CLI 配置{else}上一篇：没有了下一篇：GLM Claude Code 配置{else}下一篇：没有了