Grok CLI 与 Grok Build：安装与配置

“Grok CLI”现在可能指两个不同的工具：

• Grok Build：xAI 官方推出的 coding agent；
• 社区 Grok CLI：由社区维护、与 xAI 没有隶属关系的开源工具。

官方 Grok Build 和社区 Grok CLI 均已使用 BetterToken API Key、Base URL 和 Model ID，通过 BetterToken 返回模型回复（社区 Grok CLI 1.1.7、Grok Build 1.0.13）。Grok Build 可使用 api_backend = "chat_completions"；请勿使用 responses（参阅 Grok Build）。本文优先介绍配置更直接的社区 Grok CLI。

两个工具都使用 grok 命令。若同时安装，终端只会运行 PATH 中排在前面的版本，可能导致配置不生效。建议只保留一个版本，或在独立环境中分别安装。

Grok CLI 与 Grok Build 有什么区别？

对比项	官方 Grok Build	社区 Grok CLI
维护方	xAI	superagent-ai/grok-cli，与 xAI 无隶属关系
适合谁	希望使用 xAI 官方 coding agent 的用户	希望通过自定义 Base URL 调用模型的用户
默认认证方式	浏览器登录或 XAI_API_KEY	GROK_API_KEY
自定义 Base URL	在 ~/.grok/config.toml 中配置	使用 GROK_BASE_URL
模型设置	在配置文件中定义模型 alias	使用 GROK_MODEL
通过 BetterToken 调用模型	文本请求已验证（1.0.13，仅限 chat_completions）	文本请求已验证（1.1.7）
启动命令	grok	grok

本文只介绍通过 BetterToken 发送文本和代码模型请求。X Search、语音转写、图像和视频等依赖 xAI 专属接口的功能不在本文支持范围内。

使用社区 Grok CLI 接入 BetterToken

以下命令适用于 macOS、Linux 和 WSL。社区版在原生 Windows 上的安装与配置尚未验证。

安装

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
grok --version

已经安装 Bun 的用户也可以使用：

bun add -g grok-dev

旧的 @vibe-kit/grok-cli 已不是项目当前 README 推荐的安装方式。

配置 BetterToken

export GROK_BASE_URL="https://bettertoken.ai/v1"
export GROK_API_KEY="YOUR_API_KEY"
export GROK_MODEL="YOUR_MODEL_ID"

将 YOUR_MODEL_ID 替换为模型广场中的完整 Model ID。使用你自己的 BetterToken API Key：注册并获取。

验证连接

grok -p "只回复：OK"

能够返回模型回复，才说明 API Key、Base URL 和 Model ID 均已生效。客户端能够启动，不能证明模型请求已经成功。

社区 Grok CLI 1.1.7 通过 BetterToken 返回了模型回复。该结果仅覆盖本页配置的基础文本请求；文件读取工具调用和 xAI 专属功能尚未验证。测试中，客户端还发送了返回 503 的辅助请求，但最终回复仍成功返回，因此退出码为 0 不代表每个请求都成功。如果遇到延迟，请在控制台查看请求记录。

已经打开的 Grok CLI 会话不会自动读取新的环境变量。修改配置后，请退出并重新启动。

切换模型

修改 GROK_MODEL，填入另一个完整 Model ID，然后重新启动 Grok CLI 并再次运行短请求。

官方 Grok Build

Grok Build 是 xAI 官方终端 coding agent，可通过交互式 TUI、headless 模式或 ACP 使用。

安装

macOS / Linux / WSL

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

Windows PowerShell

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

使用 xAI 账号或 API Key

首次启动时，Grok Build 会打开浏览器完成认证。对于没有浏览器的环境，xAI 文档提供 XAI_API_KEY 方式：

export XAI_API_KEY="YOUR_XAI_API_KEY"
grok

可选：在 Grok Build 中配置 BetterToken

Grok Build 支持 OpenAI-compatible 自定义模型，可以设置 Base URL、Model ID、认证环境变量和请求协议。

[model.bettertoken]
model = "YOUR_MODEL_ID"
base_url = "https://bettertoken.ai/v1"
name = "BetterToken"
env_key = "BETTERTOKEN_API_KEY"
api_backend = "chat_completions"

[models]
default = "bettertoken"

BETTERTOKEN_API_KEY 是本例自定义的变量名，不是 Grok Build 固定要求的名称。Grok Build 会读取 env_key 指定的环境变量。

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
grok inspect
grok -p "只回复：OK" -m bettertoken

Grok Build 1.0.13 使用 api_backend = "chat_completions" 返回了模型回复。同一版本使用 api_backend = "responses" 时，收到了 HTTP 200 流式响应，但解析失败（unknown variant response.metadata），因此请保留 chat_completions。工具调用和 xAI 专属接口尚未验证。

避免 grok 命令冲突

macOS / Linux / WSL

type -a grok
grok --version

Windows PowerShell

Get-Command grok -All
grok --version

type -a grok 和 Get-Command grok -All 可以列出多个同名命令。如果安装了两个客户端，请删除不用的版本或调整 PATH。

常见错误

现象	排查方式
安装后启动了错误的 Grok	列出所有 grok 命令并检查路径与版本。
Grok Build 报错 unknown variant response.metadata	将 BetterToken 模型的配置设为 api_backend = "chat_completions"，然后重新运行 grok inspect。
官方 Grok Build 打开浏览器	这是 Grok Build 的默认登录流程。使用 xAI 时可以继续登录；使用 BetterToken 时，请配置自定义模型。
401 或 Unauthorized	Grok Build 自定义模型读取 env_key 指定的变量；社区版读取 GROK_API_KEY。只需设置当前客户端使用的变量。
model not found	从模型广场复制完整 Model ID，然后重启客户端。
请求仍发往 xAI	社区版检查 GROK_BASE_URL；Grok Build 运行 grok inspect，确认 base_url 和当前模型 alias。
xAI 专属功能不可用	BetterToken 只处理本页说明的模型请求。X Search、语音和媒体功能请使用 xAI 官方 API。

• 对比所有支持的工具
• API 错误、状态码与限流

可用模型与功能限制

配置时，请从模型广场复制支持 OpenAI-compatible 调用的完整 Model ID。仅凭客户端允许修改 Base URL，不能推断某个模型系列的请求、工具调用或上下文格式已经兼容。

本页只覆盖文本和代码模型请求。X Search、语音转写、图像生成、视频生成及其他 xAI 专属接口不通过 BetterToken 提供。

来源与相关指南

• Grok Build：xAI 官方介绍
• Grok Build：xAI Settings Reference
• 社区 Grok CLI：当前仓库
• BetterToken OpenAI-compatible 与 Anthropic-compatible 协议说明
• BetterToken 模型广场