跳到主要内容

Grok Build 集成图灵平台指南

Grok Build 是 xAI 提供的终端 AI 编程 Agent。它支持全屏 TUI、headless 命令行和 Agent Client Protocol（ACP），可以读取代码库、执行命令、修改文件并管理多轮任务。Grok Build 支持自定义 OpenAI 兼容模型端点，因此可以直接接入图灵平台。

推荐配置

本文使用图灵平台的 turing/grok-4.6，通过 v1/chat/completions 接口调用。配置解析与模型发现已在 Grok Build 1.0.5、图灵 live 中国区环境中验证；如需验证实际推理调用，请按下方的可选测试命令执行。

前置要求​

  • 已获得图灵平台 API Key（获取方式）
  • macOS / Linux / WSL2，或 Windows PowerShell
  • 能够在启动 Grok Build 的 shell 中设置 TURING_API_KEY
  • 建议使用 Grok Build 最新稳定版；本文配置字段按 1.0.5 版本验证

步骤 1：安装 Grok Build​

macOS / Linux / WSL2​

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

安装完成后重新打开终端，或按安装器提示把 ~/.grok/bin 加入 PATH。验证安装：

grok --version

Windows PowerShell​

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

PowerShell 安装器会把 %USERPROFILE%/.grok/bin 加入用户级 PATH。重新打开 PowerShell 后执行：

grok --version

步骤 2：准备 Turing API Key​

Grok Build 的自定义模型配置通过 env_key 读取 API Key 所在的环境变量。配置文件只保存环境变量名，不保存明文 Key。

macOS / Linux / WSL2​

当前终端临时设置：

export TURING_API_KEY="your-turing-api-key"

需要长期生效时，将同一行加入 ~/.zshrc（bash 用户加入 ~/.bashrc），然后重新加载：

source ~/.zshrc

不显示 Key 内容也可以检查变量是否存在：

if [ -n "${TURING_API_KEY:-}" ]; then
  echo "TURING_API_KEY is set"
else
  echo "TURING_API_KEY is missing"
fi

Windows PowerShell​

$env:TURING_API_KEY = "your-turing-api-key"

如需写入用户环境变量，可使用 setx TURING_API_KEY "your-turing-api-key"，然后重新打开 PowerShell。

保护 API Key

真实 Key 只应保存在 shell 配置、系统环境变量或安全的 Secret 管理系统中。不要把它写入 ~/.grok/config.toml、项目文件、文档、截图、代码仓库或共享聊天；Grok 配置文件只保留环境变量名 TURING_API_KEY。

步骤 3：配置自定义模型​

Grok Build 的用户级配置文件是 ~/.grok/config.toml（Windows 为 %USERPROFILE%/.grok/config.toml）。保留文件中已有的 [cli]、[marketplace] 等配置；如果文件已经有 [models] 表，请在同一张表中合并 default，不要重复创建 TOML 表。模型配置可以追加在文件末尾：

[models]
default = "turing-grok-4.6"

[model."turing-grok-4.6"]
model = "turing/grok-4.6"
base_url = "https://live-turing.cn.llm.tcljd.com/api/v1"
name = "Turing Grok 4.6"
api_backend = "chat_completions"
env_key = "TURING_API_KEY"
模型别名中的句点必须加引号

[model."turing-grok-4.6"] 是 TOML 的完整表名。不要写成 [model.turing-grok-4.6]：TOML 会把句点拆成嵌套键，Grok Build 会把末段 6 当成未知配置字段，随后找不到默认模型。

配置项说明​

配置项作用
[models].default新会话默认使用的模型选择器名称；必须与下面的表名一致
[model."turing-grok-4.6"]Grok Build 中显示的模型选择器名称；这里用别名避免与请求 ID 混淆
model实际发给图灵 API 的模型 ID，必须保持为 turing/grok-4.6
base_url图灵中国区 OpenAI 兼容根地址；不要附加 /chat/completions
api_backend请求协议；chat_completions 对应 /v1/chat/completions，也是 Grok 的默认协议
env_key保存 API Key 的环境变量名；本文使用 TURING_API_KEY

base_url 只写到 /api/v1，Grok Build 会根据 api_backend 自动拼接 /chat/completions。Turing 后端内部虽然把该模型映射到 xAI 的 grok-4.6，客户端仍必须发送公开模型 ID turing/grok-4.6。

如果希望 Grok Build 按图灵模型目录的 500K 上下文窗口估算自动压缩，可以在模型表中额外加入：

context_window = 500000

这是可选优化；不加入也不影响本文已验证的基本配置。

步骤 4：检查配置并启动​

先让 Grok Build 检查它发现的配置来源和模型：

grok inspect
grok models

预期能看到：

Default model: turing-grok-4.6
* turing-grok-4.6 (default)

grok models 可能同时提示无法刷新官方 cli-chat-proxy 模型目录（例如没有 xAI 登录凭据）。只要自定义模型显示为 using its own API key 且被列为 default，这个提示不影响 Turing 配置。

如需发起一次最小推理请求进行端到端验证（会消耗一次 API 配额），可以执行：

grok -p "只回复 OK" -m turing-grok-4.6 --max-turns 1 --no-alt-screen

交互式 TUI​

进入项目目录后直接启动：

cd your-project
grok

也可以显式指定模型：

grok -m turing-grok-4.6

在已打开的 TUI 中可用 /model turing-grok-4.6 切换模型。

Headless​

适合脚本、自动化和 CI：

grok -p "解释这个仓库的架构" -m turing-grok-4.6

需要机器可读输出时：

grok -p "检查当前改动中的潜在问题" -m turing-grok-4.6 --output-format streaming-json

ACP / IDE 集成​

Grok Build 也可以作为 ACP Agent 运行，供支持 ACP 的编辑器或自建客户端连接：

grok agent --always-approve --model turing-grok-4.6 stdio

--always-approve 适合由外部客户端托管权限的自动化场景；交互式使用时建议保留默认的逐次确认。

模型能力与调用注意事项​

图灵模型目录中的 turing/grok-4.6 目前标注为：

  • 支持文本与图片输入、文本输出
  • 支持工具调用与 Thinking
  • 支持 v1/chat/completions、v1/messages、v1/responses
  • 输入和输出上限均为 500K Tokens
  • Turing 目录将服务端 Web Search 标为不支持；不要把它配置成 Grok 的 [models].web_search 模型

本文默认使用 Chat Completions，因为它是 Grok 自定义模型的默认协议，也是最直接的 Turing 接入方式。若改用 responses 或 messages，请同时确认 Grok Build 当前版本和具体模型的请求字段兼容性。

价格、缓存计费和模型上下线状态会变化，请以模型列表中的实时信息为准。当前目录显示的参考价为输入 $2、输出 $6、缓存读 $0.5（每百万 Tokens）；单次输入达到 ≥200K 时适用阶梯计价，缓存输入也按对应规则计算。

常见问题​

现象处理
默认模型没有出现在 grok models检查表头是否写成 [model."turing-grok-4.6"]，并确认 [models].default 完全一致；重新运行 grok inspect
grok models 提示 No auth credentials for cli-chat-proxy这是官方模型目录刷新提示；确认 Turing 模型显示 using its own API key 即可
HTTP 401 / 403确认启动 Grok 的 shell 中存在 TURING_API_KEY，其中是仍有效的图灵平台 API Key；不要把 live Key 与 test 地址混用
HTTP 404base_url 应为 https://live-turing.cn.llm.tcljd.com/api/v1；不要漏掉 /v1，也不要手动重复添加 /chat/completions
Model not found / Model not existmodel 必须是图灵模型列表中的公开 ID turing/grok-4.6，不要改成内部上游 ID xai/grok-4.6
修改配置后仍使用旧模型配置在会话启动时读取；退出并重新启动 Grok，已有会话也可能保留创建时的模型

参考文档​

返回​

← 返回 AI 编程工具概述