xai-org/grok-build · 上手攻略

• 仓库：xai-org/grok-build
• 链接：https://github.com/xai-org/grok-build
• 分类：AI Coding Agent / TUI
• 作者：Tom
• 更新：2026-07-16

这是什么

Grok Build 是 xAI（马斯克旗下人工智能公司）发布的终端原生 AI 编程智能体（coding agent），用 Rust 编写，发布于 2026 年 5 月。定位与 GitHub Copilot 的 Claude Code、OpenAI 的 Codex CLI 同类，但打出三模态这张牌：交互式 TUI（满屏鼠标交互）、无头 CLI（脚本/CI 用）、以及 ACP（Agent Client Protocol，通过 JSON-RPC 接入 IDE 或其他工具）。

核心由以下几个 crate 构成： - xai-grok-pager：TUI 渲染层（滚动、提示词、模态） - xai-grok-shell：智能体运行时，含 leader/stdio/headless 入口 - xai-grok-tools：工具实现（终端、文件编辑、搜索等） - xai-grok-workspace：宿主机文件系统、VCS、执行、检查点

一句话：用 Rust 重写的专业级终端编程智能体，支持交互、无头、ACP 三种运行模式。

解决什么问题

如果你在日常开发中需要： - 在代码库里做复杂的多文件修改，而不是单点问答 - 让 AI 直接执行 git、shell、文件搜索等操作 - 把 AI 编程能力嵌入自己的脚本、CI 或 IDE 插件

传统的 Copilot/ChatGPT 只能对话，不能自主执行。Grok Build 的工具链（tools）是直接内建的，智能体可以自己调用完成工作。同时它兼容 Claude Code 的所有配置文件（CLAUDE.md、.claude/、marketplace、plugins、MCP）和 AGENTS.md 家族，无需重写规则即可平移。

快速安装

官方脚本（推荐，macOS / Linux / Git Bash / WSL）

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

Windows PowerShell

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

从源码构建

需要 Rust 工具链（由 rust-toolchain.toml pinning）、protoc（可用 bin/protoc dotslash launcher）：

# TUI 模式
cargo run -p xai-grok-pager-bin

# release 二进制
cargo build -p xai-grok-pager-bin --release
# 产物在 target/release/xai-grok-pager（官方安装后命名为 grok）

验证安装

grok --version

⚠️ 截至 2026-07-16，macOS 和 Linux 为官方一级支持；Windows 编译/测试为 best-effort 级别。

核心用法

1. 交互式 TUI（最常用）

cd your-project/
grok

首次启动会打开浏览器进行身份认证。无浏览器环境（远程机器/容器）可设 API key 跳过：

export XAI_API_KEY="xai-..."
grok

进入后常用命令： - @src/main.rs — 让 Grok 分析指定文件 - /plan — 进入计划模式，先规划再动手 - /model <name> — 切换模型 - /context — 查看当前上下文用量 - /usage — 查看积分/配额消耗

2. 无头 CLI（脚本 / CI / 自动化）

grok -p "Explain this codebase"
grok -p "Review this diff" --output-format json

常用 flag：

3. ACP 模式（IDE / 工具集成）

grok agent stdio

通过 JSON-RPC stdin/stdout 对接外部应用，官方示例为 Node.js 接入代码（见 docs.x.ai）。

4. 模型切换与自定义模型

Grok Build 支持切换任意模型，包括自定义端点。编辑 ~/.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 验证，然后用 /model my-model 切换。

5. 技能（Skills）、插件、Hooks、MCP

Grok Build 从以下路径自动发现扩展：

• ./.grok/skills/（向上遍历到仓库根）
• ~/.grok/skills/
• ~/.grok/plugins/
• 插件内置 skills/ 目录

所有扩展可通过 TUI 内置的统一扩展模态管理（/plugins、/hooks、/skills、/mcps 均指向同一个 Modal）。

Claude Code 兼容性：Grok Build 零配置兼容 Claude Code 的所有 ecosystem（marketplaces、plugins、skills、MCPs、agents、hooks 及 CLAUDE.md/Claude.md/.claude/rules/ 文件），放在 .grok/ 旁即可。

AGENTS.md 兼容性：同样读取 AGENTS.md 系列文件。

典型适用场景

1. 大型代码库探索与修改：比如 10 万行遗留项目，先 /plan 让 Grok 梳理架构，再让它批量改文件。
2. 自动化 Code Review：无头模式跑 grok -p "Review this diff"，JSON 输出进 CI pipeline。
3. 需要实时网络搜索的编码任务：Grok 内置 Web Search + X Search，在编程流程里实时查文档/资料。
4. 团队规则迁移：现有 Claude Code 规则直接迁移到 Grok，无需重写。
5. 跨模态内容生成：同一 Grok 产品线含 /imagine（图）和 /imagine-video（视频），适合生成文档配图或 demo 素材。

坑与注意

⚠️ 数据隐私（重要！）

Reddit 用户发现（2025 年）Grok Build CLI 会将整个仓库（包括完整 git 历史和 .env 文件）上传到 xAI 云端，且默认 opt-out 并不能完全阻止。有报道称为"wire-captured"。在处理私有代码、含密钥项目、或受合规约束的代码库时，务必先确认你所在组织的合规要求，再决定是否使用。

使用 /privacy 命令可在会话内查看和切换隐私/数据保留状态。

⚠️ 积分配额不透明

xAI 未公开 Grok Build 固定每日配额数字，主要靠 /usage 实时观察。API 侧 grok-build-0.1 定价为（参考，2026-05-26，随时可能变动）： - 输入：$1.00 / 1M tokens - 缓存输入：$0.20 / 1M tokens - 输出：$2.00 / 1M tokens - 工具调用（如 web_search）：约 $5 / 1k 次

⚠️ 订阅门槛

Grok Build 早期 beta 仅向 SuperGrok 和 X Premium Plus 用户开放。非订阅用户安装后无法认证使用。

⚠️ Windows 支持级别低

官方明确说 macOS 和 Linux 是一级支持；Windows 构建是 best-effort，不在 CI 里跑测试。

⚠️ TUI 首次认证需浏览器

无浏览器环境（SSH 远程、容器）需提前设 XAI_API_KEY，否则会卡住。

⚠️ 根 Cargo.toml 是生成文件

仓库根目录的 Cargo.toml 是生成的，不要直接编辑。改单个 crate 的功能请编辑对应 crates/*/Cargo.toml。

与同类对比

最大差异化：Grok Build 是三合一（交互 + 无头 + ACP），且与 Claude Code 生态完全双向兼容，加上实时网络搜索，是目前最接近"一站式编程智能体平台"的产品。但隐私问题必须纳入评估，敏感项目谨慎使用。

一句话推荐结论

如果你在 xAI 生态内、需要一个终端原生、交互与自动化兼备的编程智能体，Grok Build 是目前最完整的选择；但隐私敏感场景下不要用，优先考虑 Claude Code。