X-Code Docs

主题

Grok Build 配置指南 ​

Grok Build 是 xAI 推出的终端编码助手。主配置文件为 ~/.grok/config.toml，可把模型请求接入 X-Code API 的 OpenAI 兼容端点。

不要把真实 Key 发给别人

下面示例里的 sk-xxxxx 只是占位符。请用你在 X-Code 控制台 创建的 API Key 替换，不要在截图、聊天记录、公开仓库或工单里展示真实密钥。

安装 ​

Windows ​

打开 PowerShell，执行官方安装命令：

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

安装完成后，重新打开终端，确认可用：

powershell
grok --version

macOS / Linux / WSL ​

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

安装完成后，重新打开终端，确认可用：

bash
grok --version

API 配置 ​

配置文件 ​

Windows ​

  1. 按 Win + R，输入 %userprofile%\.grok 后回车，打开 Grok Build 配置目录。
  2. 若目录中没有 config.toml，请手动创建该文件。
  3. 将以下内容写入 config.toml：
toml
[models]
default = "grok-4.5"
web_search = "grok-4.5"

[endpoints]
models_base_url = "https://api-cn.x-code.cc/v1"

[model."grok-4.5"]
model = "grok-4.5"
name = "Grok 4.5"
description = "Grok 4.5 via X-Code API"
api_key = "sk-xxxxx"
api_backend = "responses"
context_window = 500000

macOS / Linux / WSL ​

创建配置目录并编辑配置文件：

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

将以下内容写入 config.toml：

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

[endpoints]
models_base_url = "https://api-cn.x-code.cc/v1"

[model."grok-4.5"]
model = "grok-4.5"
name = "Grok 4.5"
description = "Grok 4.5 via X-Code API"
api_key = "sk-xxxxx"
api_backend = "responses"
context_window = 500000

将 sk-xxxxx 替换为你在 X-Code 控制台创建的 API Key。

配置项说明 ​

配置项说明
[models] default新会话默认使用的模型
[models] web_searchGrok Build 内置 web_search 工具使用的模型
[endpoints] models_base_url统一模型网关入口，填 X-Code 的 OpenAI 兼容端点
[model."grok-4.5"] model实际请求上游时使用的模型 ID
api_key当前模型使用的 X-Code API Key
api_backend = "responses"使用 Responses API（Grok 4.5 推荐）
context_window上下文窗口大小，影响自动压缩等行为

使用环境变量保存 Key ​

如果不想把令牌直接写进 config.toml，可以把 api_key = "sk-xxxxx" 改成：

toml
env_key = "XCODE_API_KEY"

然后在系统环境变量中配置 XCODE_API_KEY。

注意： env_key 填的是环境变量名，不是 API Key 本身。

macOS / Linux ​

在 ~/.bashrc 或 ~/.zshrc 中添加：

bash
export XCODE_API_KEY="sk-xxxxx"

重新加载：

bash
source ~/.bashrc

Windows PowerShell（当前会话） ​

powershell
$env:XCODE_API_KEY = "sk-xxxxx"

或在系统环境变量中永久添加：

变量名值
XCODE_API_KEY你的 API Key

配置文件位置 ​

文件路径
配置文件~/.grok/config.toml
Windows 配置目录%USERPROFILE%\.grok\

测试配置 ​

检查 Grok Build 是否读取到配置：

bash
grok inspect

发送一次最小测试请求：

bash
grok -p "只回复 ok" -m grok-4.5

如果输出类似：

text
ok

说明配置已经生效。

启动 ​

配置完成后，进入项目目录运行：

bash
cd your-project
grok

常用命令：

bash
grok                         # 交互式 TUI
grok -p "解释这个代码库"       # 无界面单次提问
grok -m grok-4.5             # 指定模型
grok models                  # 列出模型

常见问题 ​

把 Key 写到 env_key 后无法使用？ ​

env_key 只能填写环境变量名（例如 XCODE_API_KEY），不能填写真的 API Key。

如果想直接把令牌写在配置文件里，请使用：

toml
api_key = "sk-xxxxx"

提示模型不存在或无权限？ ​

请检查：

  1. X-Code 令牌是否支持你填写的模型（如 grok-4.5）
  2. models_base_url 是否为 https://api-cn.x-code.cc/v1
  3. model = "grok-4.5" 是否与控制台可用模型名称一致
  4. API Key 是否复制完整，前后不要有多余空格

修改 config.toml 后未生效？ ​

关闭当前 Grok 会话后重新启动，或先执行 grok inspect 确认加载的配置路径与内容。