从零配置 Grok Build

准备（Preparation） ​

预留约 10 分钟。需要 CC Switch v3.20.0、Grok Build，以及一把只给本机使用的可撤销 Key。修改 Provider 前备份 ~/.grok/config.toml。Grok Build 需要包含 api_backend 的完整模型 Profile；Base URL 本身不是兼容性设置。

本教程覆盖自定义 API Provider。Grok Build 官方浏览器 OAuth 仍是独立的 xAI 登录路径，不能与梭子蟹 API Key 互换。

下载（Download） ​

从 xAI Grok Build 官方仓库安装。其已发布二进制安装命令为：

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

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

CC Switch 只从官方 v3.20.0 Release下载，并选择匹配操作系统和架构的资源。运行安装命令前先检查内容，不要使用镜像或重打包版本。

官方安装说明没有确认每个 Grok Build Release 都支持同一种稳定的 grok --version 命令。因此在 Grok Build UI 打开 关于（About），确认显示版本与安装版本一致；没有显示或不一致时不要继续。在 CC Switch 也打开 关于（About），确认 v3.20.0。

首次启动（First launch） ​

先运行一次 grok。若要保留官方 xAI Profile，完成官方浏览器认证，然后退出 Grok Build。这会建立原生 ~/.grok 目录。备份中要保留原 Profile；新增自定义 Provider 不得抹掉唯一可用的 OAuth 路径。

添加 Provider 前，再次在 CC Switch 关于（About） 确认 v3.20.0；若不一致，停止并安装匹配的官方 Release。

API Key 与分组（API Key and group） ​

在梭子蟹控制台创建专用 <API_KEY>，并分配到允许目标端点与模型的分组。只记录 Key 标签、分组和创建时间，不记录完整 Key。这把 Key 用于自定义 Provider，不是官方浏览器 OAuth 账户。

模型目录：GET /v1/models（Model catalog） ​

修改 CC Switch 前，用同一把 Key 请求 GET https://suoxie.codes/v1/models，从 data[].id 原样复制一个值作为 <MODEL_FROM_V1_MODELS>。

Windows PowerShell：

$secureKey = Read-Host 'API key' -AsSecureString
$credential = [System.Net.NetworkCredential]::new('', $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
curl.exe --fail-with-body https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"

macOS / Linux：

read -rsp 'API key: ' SUOXIE_API_KEY && printf '\n'
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"

这一步只建立模型可见性基线，不证明端点接受下文选择的 Grok Build backend。

在 CC Switch 配置 Provider ​

在 CC Switch 选择 Grok Build，点击 +，创建如 suoxie-responses 的 Provider。Base URL 填 https://suoxie.codes/v1，输入专用 Key，模型填 <MODEL_FROM_V1_MODELS>，选择真实 API backend，并填写已核实的上下文窗口。CC Switch 会把当前 Profile 写入 ~/.grok/config.toml。

原生 TOML 结构必须包含 [models].default 和对应的 [model.<profile>] 表：

[models]
default = "suoxie-responses"

[model.suoxie-responses]
name = "Suoxie Responses"
model = "<MODEL_FROM_V1_MODELS>"
base_url = "https://suoxie.codes/v1"
api_backend = "responses"
context_window = 128000
api_key = "<API_KEY>"

context_window = 128000 只是示例值，应替换为已核实的模型限制。Profile 也可以声明 env_key 而不是内联 api_key，但 Grok Build 只读取被点名的环境变量，因此该变量必须存在于进程环境中。

模型映射与协议（Model mapping and protocol） ​

[models].default 必须指向现有 Profile 表，Profile 的 model 必须与 <MODEL_FROM_V1_MODELS> 完全一致。api_backend 是必填项。只有直连端点接受预期 Responses 方言时才用 responses。OpenAI Chat 或 Anthropic 上游需要相应 CC Switch 代理/转换路由；只改 api_backend 或 Base URL 不能完成协议转换。

保存、启用与重启（Save, enable, and restart） ​

保存 Provider，在 CC Switch 中设为当前 Grok Build Provider，并等待 TOML 写入完成。完全退出 Grok Build（包括后台进程）后再启动 grok，使其重新读取 config.toml。本地路由接管启用后，后续路由 Provider 切换可能热生效，但首次接管和每次普通 TOML 修改都应从新进程验证。

直连 Responses backend 保留配置的 https://suoxie.codes/v1 Base URL。若 backend 是 Chat Completions 或 Anthropic，打开 Settings -> Advanced -> Routing Service -> App Routing，先启动 Routing Service，再打开 Grok Build 应用开关。服务显示运行且 Grok Build 开关已启用即为成功信号；有效本地转换路由是 http://127.0.0.1:15721/grokbuild/v1。未启用 App Routing 时，不要把该本地 URL 用于直连 backend。

首个请求（First request） ​

在可丢弃的空目录运行 grok，确认选中的 Profile 和 <MODEL_FROM_V1_MODELS>，只发送 Reply with OK。成功标准是 Grok Build 经配置 backend 返回简短文本；成功的模型列表或可见的 Provider 卡片都不够。

验证后清理临时 shell 变量：

Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
Remove-Variable secureKey, credential -ErrorAction SilentlyContinue

unset SUOXIE_API_KEY

Key 用量（Key usage） ​

打开 Key 用量，按请求时间、专用 Key、分组、端点和模型筛选，核对请求数、输入/输出 Token 与费用。确认记录端点与直连 backend 或 CC Switch 代理路由一致。重复请求前先刷新并扩大时间范围。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

停止 Grok Build，在 CC Switch 重新启用此前验证可用的 Provider，或恢复私有的修改前 config.toml。先恢复旧 Provider 并验证短请求，再关闭 Routing Service 或 Grok Build 应用开关。CC Switch 状态保存在 ~/.cc-switch/cc-switch.db，备份目录是 ~/.cc-switch/backups/；恢复前保留两者。不要删除唯一 TOML 备份，也不要用未验证的自定义文件覆盖官方 Profile。

内联 api_key 会使 config.toml 含凭据；若 env_key 点名的变量出现在日志或共享启动脚本中，同样不安全。配置与备份不得进入公开仓库、截图、录屏、共享工单或云同步目录。确认旧 Provider 的短请求成功后，再撤销本轮临时测试 Key。怀疑泄露时立即撤销该 Key，在正确分组创建替代 Key，更新 Provider，重启 Grok Build，并在 Key 用量中核对一次新请求。