从安装到第一次对话：Grok Build 入门

Grok Build 是一个可扩展的编码 agent。它能读你的仓库、改文件、跑命令，日常入口是全屏 TUI：不带参数执行 grok，会打开支持鼠标的终端界面。同一套能力也可以无头跑在脚本或机器人里，或通过 Agent Client Protocol（ACP）接到其他应用；驱动它的模型 grok-4.6 还能直接打 xAI API。

三种用法

写代码时打开交互 TUI：不带参数执行 grok 即可。脚本、CI 或机器人里用无头模式，把提示词交给 -p，不必开界面：

grok -p "Explain this codebase"
grok -p "Explain the architecture" --output-format streaming-json

ACP 把同一套 agent 接到其他应用，对应命令是 grok agent stdio。编辑器或内部工具要嵌进去，走这条，不用再包一层 TUI。

grok-4.6 也可以直接打 xAI API。你已经有自己的 agent loop、IDE 插件或编码工具时，不必经过 TUI：

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "input": "Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}"
  }'

安装与第一次登录

macOS / Linux 与 Windows

macOS 和 Linux 用这条安装脚本：

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

这条命令在 Windows 的 Git Bash 或 MSYS2 里同样可用。WSL 会装到 Linux 二进制，按上面这条走。

原生 Windows 用 PowerShell：

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

PowerShell 安装器会把 %USERPROFILE%\.grok\bin 写进当前用户的 PATH。新开一个终端，确认命令在：

grok --version

以后升级用 grok update。完整参数看 grok --help，子命令帮助是 grok <subcommand> --help。

浏览器登录、API Key 与远程设备码

装好后进项目目录，直接启动：

cd your-project
grok

第一次启动会打开浏览器做登录。完成后凭证缓存在 ~/.grok/auth.json，之后的会话会复用；令牌会在后台刷新，续不上时再提示你重新登录。

机器上没有浏览器，比如 CI、容器、纯 SSH 环境，改用 API Key：

export XAI_API_KEY="xai-..."
grok

Key 从 console.x.ai 申请。已经用浏览器登录过的机器上，缓存的会话 token 优先于 XAI_API_KEY。想改走 Key，先清掉会话：

grok logout

grok logout 没有额外参数，作用就是退出并清除缓存凭证。换账号或登录状态不对时，重新走一遍：

grok login

默认仍是打开浏览器。SSH、远程桌面、没有本机浏览器的环境，加上设备码：

grok login --device-auth

终端会打出 URL 和 code。换一台有浏览器的设备打开那个地址、输入 code，Grok Build 会轮询到登录完成为止。--device-code 是同一选项的别名。

在仓库里开第一次会话

务必在目标仓库里启动。grok 以当前目录为工作区，规则、技能、插件和 MCP 都按这个目录去发现。空目录里问「这个仓库做什么」没有意义。

cd your-project
grok

TUI 起来后，不必先想复杂任务。下面两个起步提示就够用来确认它读得懂仓库：

Explain this repo.
@src/main.rs Walk me through this file.

第一条让它按目录结构讲项目在干什么。第二条用 @ 点名一个文件，让它按文件走读。把 src/main.rs 换成你仓库里真实存在的路径即可。

如果改过配置、装过技能或 MCP，却不确定当前目录到底吃进了什么，先不要猜，直接检查：

grok inspect

它会列出这个目录发现的配置来源、instructions、skills、plugins、hooks 和 MCP servers。需要给脚本读时加上 --json。改完 ~/.grok/config.toml 之后跑一次，能立刻看到自定义模型或其他项有没有被捡起来。TUI 里切换模型用 /model <name>。

配置放在哪

界面里的外观、通知一类选项，优先在 TUI 的 /settings 里改。需要落盘、进仓库或给团队复用的项，才去碰配置文件。

用户级 config.toml 和 $GROK_HOME

个人默认写在用户级配置里：

• macOS / Linux：~/.grok/config.toml
• Windows：%USERPROFILE%\.grok\config.toml

家目录可以用 $GROK_HOME 改掉。设了之后，配置文件就变成 $GROK_HOME/config.toml，不要一边改 ~/.grok、一边还开着另一个 GROK_HOME。

一份最小可参考的用户配置如下。复制到 $GROK_HOME/config.toml；没有设 GROK_HOME 时就是 ~/.grok/config.toml：

[models]
default = "grok-build"                       # recommended for coding / agent sessions
web_search = "grok-4.6"                      # model used by client-side web_search tool

[model."grok-4.6"]
model = "grok-4.6"                           # id sent to the API
base_url = "https://api.x.ai/v1"             # provider endpoint
name = "Grok 4.6"                            # shown in model picker
description = "Grok 4.6 from xAI"
env_key = "XAI_API_KEY"                      # env var holding the API key
api_backend = "responses"                    # chat_completions | responses | messages
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
context_window = 1000000
extra_headers = { "x-api-key" = "xai-..." }
supports_backend_search = true               # if the endpoint supports Grok-hosted server-side search tools

[ui]
compact_mode = false
theme = "auto"
show_thinking_blocks = true

grok-build 是编码 / agent 会话的推荐默认；grok-4.6 是打 API 时的模型 ID，也常用在客户端 web_search 上。两个名字不要混着当同一个配置键用。

五层范围

Grok Build 的设置不是只有用户文件。从会话覆盖到企业策略，一共五层：

项目级配置范围很窄：只能写 MCP servers、plugins 和 permission rules，不能拿仓库里的文件覆盖整份用户配置。权限、沙箱是个人日常会碰到的项；managed 锁定和无头部署属于企业侧，入门阶段知道这两层存在即可。

改完任何一层，回到仓库跑 grok inspect。它告诉你当前目录实际吃进了哪些配置，比对着路径猜更准。