# Grok 安装配置教程：Grok Build、Cline、Codex 与 CC Switch

> 使用 Passion8 API Key 接入 Grok：选择 Cline、Grok Build 或 Codex，配置 Base URL、config.toml 与 CC Switch，保留安装、验证和排错步骤。

URL: https://docs.passion8.cc/docs/grok
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

通过 Passion8 使用 Grok，只需**本站 API Key、可用模型 ID 和 `https://passion8.cc/v1` 地址**。VS Code 推荐 Cline；官方 Grok Build 和已有 Codex 用户可继续使用本页的配置文件教程。本站接入不需要 xAI 账号或官方 OAuth 登录。

## 选择你的使用方式

| 场景 | 教程 | 接入方式 |
| --- | --- | --- |
| VS Code 编程、读文件与审阅 diff | [Cline 编辑器配置](https://docs.passion8.cc/docs/grok/vscode) | 本站地址、Key、模型，不要求 xAI 登录 |
| 自己的应用调用 Grok | [Grok API 与 SDK](https://docs.passion8.cc/docs/grok/api) | OpenAI 兼容 Chat / Responses |
| 学会完成一个可审查的小改动 | [Grok 编程工作流](https://docs.passion8.cc/docs/grok/workflow) | 项目规则、计划、修改、测试 |
| 使用官方 Grok Build 或已有 Codex | 本页下方详细步骤 | 手动配置或 CC Switch |

Cline 是第三方编辑器客户端；当前核对的 xAI 官方编程入口为 Grok Build 的 TUI、headless 与 ACP。不要把市场中的同名社区扩展直接当作 xAI 官方插件。

Grok 模型可以用两种方式接入 Passion8:

| 方式 | 适合场景 | 配置位置 |
| --- | --- | --- |
| xAI 官方 Grok Build CLI | 想用 `grok` 原生 TUI / headless / agent 命令 | `~/.grok/config.toml` |
| Codex CLI / Codex App | 已经习惯 Codex 工作流,只想把模型换成 Grok | `~/.codex/auth.json` 与 `~/.codex/config.toml`,或 CC-Switch 的 GPT 供应商 |

两种方式都使用 OpenAI 兼容地址 `https://passion8.cc/v1`,模型示例为 `grok-4.7`。模型 ID 以 [控制台模型广场](https://passion8.cc) 实际可用为准。




官方 Grok Build 和 Codex 不是同一个客户端。Grok Build 读取 `~/.grok/config.toml`;Codex 读取 `~/.codex/auth.json` 与 `~/.codex/config.toml`。不要把两边配置文件混用。




## 方式一:官方 Grok Build CLI

官方 Grok Build 是 xAI 的原生 CLI。本文保留 Grok Build v0.2.93 接入记录的步骤，并于 2026-10-11 对照官方安装、自定义模型和 Grok 4.7 文档更新。运行版本请以 `grok --version` 为准；若配置字段调整，先用 `grok inspect` 查看当前识别到的配置来源、模型和认证方式。

### 安装 Grok CLI






### macOS / Linux / WSL


终端执行官方安装脚本:

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





### Windows


PowerShell 执行官方安装脚本:

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








安装完成后,新开一个终端窗口,确认命令可用:

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

macOS / Linux / WSL 正常情况下,`which grok` 会指向 `~/.local/bin/grok`,并进一步链接到 `~/.grok/bin/grok`。




macOS / Linux / WSL 如果提示 `grok: command not found`,把 `~/.local/bin` 加入 `PATH`,然后重新打开终端:




```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

需要更新 Grok CLI 时运行:

```bash
grok update
```

### 接入前准备

| 项目 | 值 |
| --- | --- |
| Passion8 API Key | 在控制台「令牌」里创建,复制完整 `sk-...` |
| Base URL | `https://passion8.cc/v1` |
| 模型 ID | 以 [控制台模型广场](https://passion8.cc) 实际可用为准,示例使用 `grok-4.7` |
| 配置文件 | `~/.grok/config.toml` |

先确认你用的是官方 Grok Build:

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

如果 `which grok` 指向 `~/.local/bin/grok` 或 `~/.grok/bin/grok`,通常就是官方 Grok Build。

### 推荐配置

直接把 Key 写进 `api_key` 字段:

```toml
[model.passion8-grok]
model = "grok-4.7"
base_url = "https://passion8.cc/v1"
name = "grok-4.7"
context_window = 500000
api_key = "sk-你的 Passion8 API Key"

[models]
default = "passion8-grok"
```




`default` 填的是 `[model.passion8-grok]` 的段名别名,不是模型 ID。这里的模型 ID 是上方的 `model = "grok-4.7"`。







自定义模型如果不写 `context_window`,Grok Build 会按默认 `200000` 显示 `/context` 占用和触发 auto-compact。当前官方 Grok 4.7 页面列出 500,000 token 窗口，因此该模型可写 `500000`；其他模型需要重新核对，不能照搬;改完后重启会话或 `/new` 再看 `/context`。




### 更安全的环境变量写法

不想把 Key 明文写进 `config.toml` 时,可以用 `env_key` 指向环境变量名:

```toml
[model.passion8-grok]
model = "grok-4.7"
base_url = "https://passion8.cc/v1"
name = "grok-4.7"
context_window = 500000
env_key = "PASSION8_API_KEY"

[models]
default = "passion8-grok"
```

再把 Key 放进 shell 配置:

```bash
echo 'export PASSION8_API_KEY="sk-你的 Passion8 API Key"' >> ~/.zshrc
source ~/.zshrc
```

### 测试中转站

先用 curl 验证 Key、Base URL 和模型是否可用:

```bash
curl -s https://passion8.cc/v1/models \
  -H "Authorization: Bearer $PASSION8_API_KEY"
```

再试跑一句:

```bash
curl -s https://passion8.cc/v1/chat/completions \
  -H "Authorization: Bearer $PASSION8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "messages": [{"role": "user", "content": "reply with OK"}],
    "max_tokens": 10
  }'
```

如果 curl 正常返回,但 `grok` 仍然跳浏览器 OAuth,问题通常在 `~/.grok/config.toml`。

### 验证 Grok CLI

```bash
grok -p "Reply with exactly: RELAY_OK"
```

能返回 `RELAY_OK` 后，再到 Passion8 控制台核对对应时间、模型和用量记录；不要仅凭回答内容判断路由。

### 常见错误

| 现象 | 原因 | 修复 |
| --- | --- | --- |
| 配了中转站仍跳 x.ai OAuth | Grok 没读到可用 Key 或默认模型 | 检查 `api_key` / `env_key` 和 `[models].default` |
| `env_key = "sk-..."` | `env_key` 写成了密钥本身 | 改成 `api_key = "sk-..."`,或让 `env_key` 指向环境变量名 |
| `default = "grok-4.7"` | `default` 写成了模型 ID | 改成 `[model.xxx]` 的别名,例如 `default = "passion8-grok"` |
| `/context` 只显示 `200k` | 自定义模型没写 `context_window` | 在 `[model.xxx]` 加 `context_window = 500000`,然后重启会话 |
| `GROK_BASE_URL` / `GROK_API_KEY` 无效 | 这是社区版 Grok CLI 的常见写法 | 官方 Grok Build 改 `~/.grok/config.toml` |
| curl 能通、CLI 不通 | 中转站没问题,本地配置没命中 | 运行 `grok inspect`,检查配置来源和认证方式 |


### 认证优先级

Grok Build 会优先读取模型配置里的 Key。实测排查顺序可以按下面理解:

```text
model.api_key > model.env_key > 当前登录 session > XAI_API_KEY
```

如果 `api_key` 缺失、`env_key` 又写错,它可能回退到登录 session;没有 session 时就会触发浏览器 OAuth。

### 常用命令

```bash
grok                         # 进入交互式 TUI
grok "帮我看看这个项目"        # 带初始指令进入 TUI
grok -p "解释 auth 模块"      # 单次运行,打印结果后退出
grok logout                  # 登出,排除旧 session 干扰
grok inspect                 # 查看配置来源、模型和认证方式
grok --version               # 查看版本
```




不要把 `~/.grok/config.toml`、shell 配置或任何包含 `sk-...` 的截图提交到公开仓库。给 Grok 单独创建一个 Passion8 API Key,后续需要时可以单独吊销。




## 方式二:Codex CLI / App 接入 Grok

如果你更习惯 Codex CLI 或 Codex App,也可以让 Codex 走 Passion8 的 `grok-4.7`。这种方式本质上是“Codex 客户端 + Grok 模型”:客户端还是 Codex,底层请求模型换成 Grok。


**为什么问它模型还是 GPT?**

这是正常现象。Codex CLI / App 有自己的默认系统提示词和身份提示词,所以你在对话里问“你是什么模型”时,它仍可能回答 GPT / Codex。这不代表请求没有走 Grok。不要用模型自报身份判断是否配置成功;请看 Passion8 用量日志、模型计费记录,不要用响应速度或风格替代用量记录。







Codex 接 Grok 时,不要直接套用普通 GPT 供应商的完整 `config.toml`。部分参数 Grok / Responses 兼容路径不支持。下面是最小可用配置。




### 用 CC-Switch 配置

在 CC-Switch 顶部切到 GPT / Codex 供应商区域,新增一个供应商,填写:

| 字段 | 值 |
| --- | --- |
| 供应商名称 | `custom` 或 `Passion8 Grok` |
| API Base URL | `https://passion8.cc/v1` |
| API Key | `sk-你的 Passion8 API Key` |
| 模型 | `grok-4.7` |

保存后,确认 CC-Switch 维护的是 Codex 的两份配置:

| 文件 | 用途 |
| --- | --- |
| `auth.json` | 保存 `OPENAI_API_KEY` |
| `config.toml` | 保存 provider、model、wire_api、base_url 和上下文窗口 |

无论用 CC-Switch 还是手写,最终 `config.toml` 都应包含下面这组**相同**字段与数值(文档故意不写本机 `model_catalog_json` 路径)。

### auth.json

```json
{
  "OPENAI_API_KEY": "sk-你的 Passion8 API Key"
}
```

### config.toml

```toml
model_provider = "custom"
model = "grok-4.7"
model_reasoning_effort = "high"
model_context_window = 500000
model_auto_compact_token_limit = 475000

[model_providers]
[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://passion8.cc/v1"
```




官方 Grok 4.7 页面列出 500,000 token 窗口；`model_context_window = 500000` 与 `model_auto_compact_token_limit = 475000` 是此处的客户端预算（约 95% 自动压缩），不是对每条网关渠道上限的保证。`high` 是官方支持的推理档位；原配置的 `none` 不在该模型当前支持列表中。CC-Switch 保存后如果缺这两项,或 catalog 里窗口写成几百万,Codex 都不会及时 auto-compact,长会话容易直接撞上游上限报错。保存后请打开 `~/.codex/config.toml` 核对与上表一致;长会话也可手动 `/compact`。




### 手动配置

不想用 CC-Switch 时,直接写上面同一份 `auth.json` 和 `config.toml`,不要另写一套不同的窗口数值。






### macOS


手动写文件时,路径通常是:

```bash
~/.codex/auth.json
~/.codex/config.toml
```

测试:

```bash
codex "用一句话回复: GROK_RELAY_OK"
```





### Windows


手动写文件时,路径通常是:

```powershell
$env:USERPROFILE\.codex\auth.json
$env:USERPROFILE\.codex\config.toml
```

测试:

```powershell
codex "用一句话回复: GROK_RELAY_OK"
```








Codex App 使用同一套 Codex 配置。保存 CC-Switch 供应商后,重新打开 Codex App 或新建会话再测试。

## 账户、费用与排错

还没有 API Key 时，从 [快速开始](https://docs.passion8.cc/docs/quickstart) 创建账户和令牌。余额与费用口径见 [充值与账单](https://docs.passion8.cc/docs/billing)，不要把客户端的官方订阅与 Passion8 API 余额混用。鉴权、Base URL、模型不可用等问题见 [常见问题](https://docs.passion8.cc/docs/faq)；当前可用模型及价格以控制台为准。

## 核对来源

核对日期：2026-10-11。官方目录包含 `grok-4.7`，支持 `low`、`medium`、`high`、`xhigh` 推理档位；本站是否开放以控制台为准。

- [Grok Build 安装与自定义模型](https://docs.x.ai/build/overview)
- [Grok 4.7 模型字段与窗口](https://docs.x.ai/developers/models/grok-4.7)

官方概览确认 `model`、`base_url`、`name`、`env_key` 和 `[models].default`；`api_key`、认证优先级及默认 200k 显示来自原有版本接入记录，升级后用 `grok inspect` 验证，不作为所有未来版本的保证。