Grok

Grok 安装与接入教程

安装 xAI 官方 Grok Build,或用 Codex CLI / App 通过 CC-Switch 接入 Passion8 的 Grok 模型。

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.5。模型 ID 以控制台模型广场实际可用为准。

官方 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 实测记录整理;后续版本如果调整配置字段,先用 grok inspect 查看当前识别到的配置来源、模型和认证方式。

#安装 Grok CLI

终端执行官方安装脚本:

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

PowerShell 执行官方安装脚本:

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

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

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,然后重新打开终端:

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

需要更新 Grok CLI 时运行:

grok update

#接入前准备

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

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

which grok
grok --version

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

#推荐配置

直接把 Key 写进 api_key 字段:

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

[models]
default = "passion8-grok"

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

自定义模型如果不写 context_window,Grok Build 会按默认 200000 显示 /context 占用和触发 auto-compact。grok-4.5 建议写成 500000,与模型实际窗口一致;改完后重启会话或 /new 再看 /context。

#更安全的环境变量写法

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

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

[models]
default = "passion8-grok"

再把 Key 放进 shell 配置:

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

#测试中转站

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

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

再试跑一句:

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

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

#验证 Grok CLI

grok -p "Reply with exactly: RELAY_OK"

能返回 RELAY_OK,且不弹浏览器授权,说明 Grok Build 已通过 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.5"`	`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。实测排查顺序可以按下面理解:

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

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

#常用命令

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.5。这种方式本质上是“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.5`

保存后,确认 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

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

#config.toml

model_provider = "custom"
model = "grok-4.5"
model_reasoning_effort = "none"
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"

model_context_window = 500000 与 model_auto_compact_token_limit = 475000 是 grok-4.5 的推荐值(窗口 500k,约 95% 自动压缩)。CC-Switch 保存后如果缺这两项,或 catalog 里窗口写成几百万,Codex 都不会及时 auto-compact,长会话容易直接撞上游上限报错。保存后请打开 ~/.codex/config.toml 核对与上表一致;长会话也可手动 /compact。

#手动配置

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

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

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

测试:

codex "用一句话回复: GROK_RELAY_OK"

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

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

测试:

codex "用一句话回复: GROK_RELAY_OK"

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

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.

Support Emailsupport@passion8.cc Service Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right