学习 AI

简体中文

English

简体中文

English

外观

Grok Build 教程 ​

本页覆盖 Grok Build（可执行文件 grok）从安装到日常使用的完整链路。参数清单见 速查表，概念辨析见 术语表，场景化配方见 Cookbook。

Grok Build 处于 beta 阶段且发版极快（latest 在 2026-08-12 到 2026-08-16 之间从 1.0.3 到 1.0.5），本页刻意不写死版本号；命令与配置若与你机器上的实际行为不符，先看 x.ai/build/changelog。

1. 安装 ​

官方提供三条安装通道。

bash
curl -fsSL https://x.ai/cli/install.sh | bash
powershell
irm https://x.ai/cli/install.ps1 | iex
bash
npm install -g @xai-official/grok

验证安装：

bash
grok version

仓库 README 的安装片段写的是 grok --version。CLI Reference 列出的命令是 grok version。

命名提示：从源码自行编译得到的二进制叫 xai-grok-pager，官方安装包把它作为 grok 分发（README 原文："The binary artifact is named xai-grok-pager; official installs ship it as grok."）。

2. 认证 ​

四种方式，来自 docs.x.ai/build/enterprise：

方式怎么做适用场景
浏览器 OIDCgrok login（首次启动会自动打开浏览器）本机开发
设备码grok login --device-auth（RFC 8628）SSH / 远程机器 / 无浏览器
API Keyexport XAI_API_KEY="xai-..." 后再运行 grokCI、容器
外部认证提供方配置 auth_provider_command企业统一身份

凭证解析优先级（高 → 低）：model.api_key > model.env_key > 当前会话 token > XAI_API_KEY。

订阅要求：发布公告（2026-05-25）写的是 "Available now to all SuperGrok and X Premium Plus subscribers."，营销页 x.ai/build 当前挂着 "Available to try for Free"，Grok 4.6 公告 又写过限时 "2x included usage inside Grok Build … for the first week"。三处口径不同，且都没有给出可引用的免费额度数字。以你账号登录后实际看到的额度为准，不要猜数字。

退出登录：grok logout。

3. 第一次运行 ​

bash
cd your-project
grok

无参数启动即进入交互式 TUI（cli/reference 原文："Running grok with no arguments starts the interactive TUI."）。

官方建议的第一批提示词（overview）：

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

@ 引用文件。装完先跑一次 grok inspect——它会打印 Grok 在当前目录发现的一切：配置来源、指令文件（含 token 数）、skills、plugins、hooks、MCP 服务器。配置没生效时这是第一诊断命令。

bash
grok inspect
grok inspect --json

4. TUI 必备键位 ​

完整键位表在 TUI 里按 Ctrl+.（Windows 或不支持 Kitty 键盘协议的终端用 Ctrl+X）查看。下表是入门够用的一组，来自 keyboard-shortcuts：

键位作用
Enter发送
Shift+Enter换行（VS Code / Cursor / Windsurf / Zed 的内置终端识别不了，改用 Alt+Enter）
Shift+Tab循环切换 Normal → Plan → Auto（可用时）→ Always-approve
Esc中断当前动作
Esc Esc清空输入框；输入框为空时打开 rewind（keyboard-shortcuts）
Ctrl+Enter / Ctrl+I插话（interject，在 VS Code 系终端里是 Ctrl+L）
Ctrl+P 或 ?命令面板
Ctrl+T待办面板
Ctrl+B后台任务面板
Ctrl+G任务面板
Ctrl+S会话面板
Ctrl+M输入框聚焦时切换多行；未聚焦时打开模型选择器
Ctrl+\Dashboard
Ctrl+O切到 always-approve
F2 / Ctrl+,设置
Ctrl+Q / Ctrl+D退出（VS Code 系终端里只有 Ctrl+D）

终端不兼容时（复制粘贴失效、按键错乱），先在 TUI 里跑 /terminal-setup 自检，详见 terminal-support。

5. 权限：先搞懂这两件事是分开的 ​

这是 Grok Build 最容易用错的地方。官方 permissions 原文：

"Permissions decide which tool calls may run. The sandbox is separate: it limits what an approved call can do on the filesystem and network."

权限决定「这次工具调用能不能跑」，沙箱决定「跑起来能碰到什么」，两者正交，可以同时开。

TUI 模式和 headless 的 --permission-mode 是两套词。TUI 循环的是 Ask / Auto / Always-approve；CI 用的是 Claude Code 风格的 dontAsk / acceptEdits（见 enterprise 与 速查表）。不要混着写。

三档 TUI 权限模式：

模式行为怎么进
Ask（默认）未被 allow 规则覆盖的一律弹确认—
Auto分类器自动放行安全工具，危险的仍可能弹确认（deny 规则与 hooks 依然生效）/auto、Shift+Tab（该特性开启时）
Always-approve自动放行工具调用（deny 规则与 PreToolUse hooks 依然生效）/always-approve、Ctrl+O、Shift+Tab、grok --always-approve

默认模式只能写在用户级 ~/.grok/config.toml（项目级 .grok/config.toml 不生效）：

toml
[ui]
permission_mode = "auto"  # 或 "ask" | "always-approve"

规则写法（--allow / --deny 接受同样的 pattern）：

toml
[permission]
rules = [
  { action = "allow", tool = "bash", pattern = "git *" },
  { action = "allow", tool = "read" },
  { action = "deny",  tool = "bash", pattern = "rm -rf *" },
]

三条必须记住的规则：

  1. deny 永远赢过 allow，完整优先级是 deny > ask > allow（settings/reference），不是「后写覆盖先写」。
  2. 支持的过滤器：Bash、Edit、Read、Grep、MCPTool、WebFetch、WebSearch。
  3. 交互里点的「always allow」对 rm、git push 这类危险 pattern 仍会再次弹确认；只有配置文件或 CLI 里的显式 allow 规则才会真正自动放行。

6. 沙箱：默认是关的 ​

sandbox：Linux 用 Landlock，macOS 用 Seatbelt，默认 off。

Profile可读可写子进程联网场景
off不限不限允许默认，无沙箱
workspace全部CWD、~/.grok/、临时目录允许常规开发
devbox全部除 /data 外的顶层目录允许云端 devbox
read-only全部仅 ~/.grok/ 与临时目录阻止代码审查、审计
strictCWD 与系统路径CWD、~/.grok/、临时目录阻止不可信仓库

三种开启方式：grok --sandbox workspace、[sandbox] profile = "workspace"、GROK_SANDBOX=workspace。

两个必须知道的限制（官方明确列出）：

  • 子进程网络限制只在 Linux 生效，macOS 上 read-only / strict 的网络阻断是 no-op。
  • 内置 profile 不会永久保护 ~/.ssh 这类敏感路径，要自己写 deny 列表：
toml
# ~/.grok/sandbox.toml
[profiles.my-profile]
extends = "workspace"
restrict_network = true
deny = ["/secrets", "**/.env", "**/*.pem"]

Linux 上要用「可读但拒绝某些路径」的能力需要系统装 bubblewrap。

7. 计划模式 ​

/plan [描述] 进入计划模式，/view-plan（别名 /show-plan、/plan-view）查看。计划评审界面里的按键：a 批准、s 要求修改、c 评论、q 退出、Tab 切换焦点。

两个要点（plan-mode）：

  • 计划模式与权限模式互相独立：即使处于 auto 或 always-approve，计划评审界面也不会被跳过。
  • 计划模式下只有会话计划文件可编辑，但 bash 仍可通过重定向写文件——它不是硬隔离，需要硬隔离请配沙箱。

8. 会话管理 ​

会话按工作目录存放在 ~/.grok/sessions/（sessions）。

目的做法
恢复上一个会话grok -c（或 --continue）
选择恢复grok --resume（不带 ID 时列出可选）
恢复指定会话grok --resume <id>
TUI 内恢复/resume
从当前会话分叉/fork [指令]，可加 --worktree / --no-worktree
回退历史/rewind，或输入框为空时 Esc Esc
压缩上下文/compact [重点]；也会自动压缩
看上下文占用/context、/session-info
列出 / 搜索 / 删除grok sessions list / search / delete
导出grok export <session-id> [output]，--clipboard 进剪贴板
改标题/rename（别名 /title）

headless 里拿会话 ID：

bash
grok -p "Start the refactor" --output-format json | jq -r '.sessionId'

9. 项目规则：AGENTS.md ​

Grok Build 的项目规则主文件是 AGENTS.md。加载顺序是先 ~/.grok/ 全局，再从仓库根目录逐级向下到当前目录（project-rules）。

它会读的文件：

  • AGENTS.md、Agents.md、AGENT.md
  • CLAUDE.md、Claude.md、CLAUDE.local.md
  • .grok/rules/ 下的 *.md，以及 .claude/rules/、.cursor/rules/

被 gitignore 的文件会跳过。单次覆盖用 --rules <TEXT>，整体替换系统提示词用 --system-prompt-override <TEXT>。grok inspect 会列出实际加载了哪些规则文件以及各自的 token 数——规则没生效时先看这里。

10. 切换模型 ​

bash
grok -m grok-build-0.1 -p "重构这个模块"

TUI 内用 /model（别名 /m）或 Ctrl+M。推理强度用 /effort 或 --effort <LEVEL>。

接自建 / 第三方 OpenAI 兼容端点（overview）：

toml
# ~/.grok/config.toml（Windows: %USERPROFILE%\.grok\config.toml）
[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

改完用 grok inspect 确认被识别，再 grok -p "Hello" -m my-model 验证。

11. Headless 模式 ​

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

常用参数（headless-scripting）：

参数作用
-p, --single <PROMPT>发送单次提示
-s, --session-id <ID>创建或复用一个命名的 headless 会话
-r, --resume <ID> / -c, --continue恢复会话
--cwd <PATH>指定工作目录
--output-format <FMT>plain（人读）/ json（结束时一个对象）/ streaming-json（逐行 JSON 事件）
--always-approve免确认
--no-alt-screen内联输出，不接管整屏

headless 会话存在 ~/.grok/sessions。

CI 里务必禁用自动更新：加 --no-auto-update，或在 ~/.grok/config.toml 里持久化：

toml
[cli]
auto_update = false

12. ACP：嵌进编辑器或自建编排器 ​

bash
grok agent stdio

以 ACP（Agent Client Protocol）agent 身份在 stdin/stdout 上跑 JSON-RPC。官方示例的握手顺序（headless-scripting）：

  1. initialize，传 protocolVersion: 1 和 clientCapabilities（fs.readTextFile / fs.writeTextFile / terminal）
  2. authenticate：设了 XAI_API_KEY 就选 xai.api_key，否则用 cached_token（都没有时官方报错文案是 "Run grok login first, or set XAI_API_KEY."）
  3. session/new，传 { cwd, mcpServers: [] }
  4. session/prompt，传 prompt: [{ type: "text", text: "..." }]

关键细节：session/prompt 的返回值只是完成元数据，助手正文是通过 session/update 的 agent_message_chunk 事件流式送达的——只看返回值会以为没输出。

13. 更新与排错 ​

bash
grok update --check        # 只检查
grok update                # 更新
grok update --version <V>  # 指定版本
grok update --alpha        # 切 alpha 通道
grok update --stable       # 切回 stable
症状先查什么
配置 / 规则 / MCP 没生效grok inspect（看它到底读到了什么）
项目级配置项没生效项目 .grok/config.toml 只支持 [mcp_servers]、[plugins]、[permission] 三段，其余键必须写在 ~/.grok/config.toml
MCP 服务器起不来grok mcp doctor [name]，日志在 ~/.grok/logs/mcp/<server>.stderr.log
复制粘贴 / 按键异常/terminal-setup
网页抓取工具不工作GROK_WEB_FETCH 默认是 0（官方出于安全默认关闭），需显式开启
企业网络连不上必须放行 cli-chat-proxy.grok.com 与 auth.x.ai（enterprise）

反馈渠道是 TUI 里的 /feedback。不要给 xai-org/grok-build 提 PR——README 明确写了 "External contributions are not accepted."

相关页面 ​

为前端工程师打造 · 基于 VitePress 构建

版权所有 © 2024-present 学习 AI