前言¶

2026 年以来，终端编码 Agent 的竞争焦点，正从「谁家模型更强」转向「Harness 是否透明、可审计、可自托管」。OpenAI 的 Codex CLI、anomalyco 的 OpenCode 先后以 Apache 2.0 / MIT 协议公开了 Agent 运行时；7 月 15 日，SpaceXAI（原 xAI）跟进，将 Grok Build——即 grok CLI 背后的编码 Agent 与全屏 TUI——以 Apache 2.0 协议发布至 GitHub 仓库 xai-org/grok-build。

官方公告见 Grok Build is Now Open Source。截至 2026 年 7 月底，该仓库 GitHub Star 已超过 2.3 万，成为继 Codex CLI、OpenCode 之后又一款重量级开源编码 Agent Harness。

本文基于官方博客、GitHub README 与 docs.x.ai/build 文档，梳理 Grok Build 开源了什么、代码如何组织、以及如何本地编译与接入自定义推理。

开源了什么¶

Grok Build 是 SpaceXAI 的终端编码 Agent。它在项目目录中理解代码库、编辑文件、执行 Shell 命令、检索网页，并管理长时任务。使用形态有三种：

1. 交互式 TUI：全屏、支持鼠标的终端界面；
2. Headless 模式：脚本、CI/CD 中通过 -p 非交互执行；
3. ACP 集成：通过 Agent Client Protocol，嵌入 IDE 或自定义应用。

本次开源的是 Harness 与 TUI 的 Rust 源码，并非 Grok 4.5 模型权重。官方明确，仓库涵盖以下模块：

仓库从 SpaceXAI 内部 monorepo 定期同步，根目录的 SOURCE_REV 文件记录对应 monorepo commit SHA。根 Cargo.toml 为生成文件，日常开发应修改各 crate 下的 Cargo.toml。

许可证：一等代码为 Apache License 2.0；third_party/ 及工具 crate 中引用的 Codex、OpenCode 等第三方实现保留原许可证，详见 THIRD-PARTY-NOTICES。

贡献政策：仓库为只读镜像，不接受外部 PR（见 CONTRIBUTING.md）。你可以 fork、修改、商用，但无法向上游合并。

代码架构一览¶

README 给出了清晰的 crate 分层，便于按需阅读源码：

若你想审计「Agent 如何决定执行哪条命令」，优先阅读 xai-grok-shell 与 xai-grok-tools；若关注交互体验，则看 xai-grok-pager。

Agent 循环与工具层¶

Grok Build 的 Agent 循环遵循常见的 ReAct 模式：模型输出结构化 tool call → Harness 在沙箱/工作区内执行 → 结果回注上下文 → 继续推理。

工具 crate（xai-grok-tools）实现了编码 Agent 的核心能力：文件读写与 diff、代码库搜索、终端命令执行、网页检索等。官方在 THIRD_PARTY_NOTICES.md 中注明，部分工具实现参考或移植自 openai/codex 与 sst/opencode，这与当前开源编码 Agent 生态互相借鉴的趋势一致。

工作区 crate（xai-grok-workspace）负责与真实文件系统、版本控制、执行检查点交互，是理解「Agent 改动如何落盘、如何回滚」的关键入口。

全屏 TUI 与 Headless¶

TUI crate 提供 scrollback、slash 命令、计划审查与行内 diff 查看器，支持鼠标交互。用户指南位于仓库内 crates/codegen/xai-grok-pager/docs/user-guide/，涵盖快捷键、主题、配置等。

Headless 用法适合自动化场景：

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

首次启动 TUI 时会打开浏览器完成认证；无图形环境可设置 API Key：

export XAI_API_KEY="xai-..."
grok

一键安装预编译二进制（macOS / Linux / Windows）：

curl -fsSL https://x.ai/cli/install.sh | bash   # macOS / Linux
irm https://x.ai/cli/install.ps1 | iex          # Windows PowerShell
grok --version

扩展系统：Skills、Plugins、Hooks 与 MCP¶

Grok Build 的扩展能力与 Claude Code、Cursor 等产品的 Skills / MCP 思路类似，但源码现已全部可读。

• Skills / Plugins / Marketplaces：按目录或 marketplace 配置加载，扩展 Agent 行为；
• Hooks：可在 config.toml 中定义，在特定生命周期介入；
• MCP Servers：通过 Model Context Protocol 挂载外部工具与数据源；
• Subagents：支持子 Agent 协作。

调试扩展加载情况，可使用：

grok inspect

该命令会列出当前目录发现的配置来源、instructions、skills、plugins、hooks 与 MCP servers。

Agent Client Protocol（ACP）集成¶

若目标是将 Grok Build 嵌入 IDE 或自研应用，而非在终端里手动对话，应使用 Agent Client Protocol。Grok 以 JSON-RPC over stdio 实现 ACP：

grok agent stdio

典型握手流程（详见 Headless & Scripting 文档）：

1. 发送 initialize，协商协议版本与客户端能力；
2. 根据返回的 authMethods 选择认证方式（如 cached_token 或 xai.api_key），发送 authenticate；
3. 调用 session/new 创建会话，再通过 session/prompt 下发任务；
4. 助手文本与工具生命周期事件以 session/update 通知流式返回。

官方文档列出的兼容客户端包括 Zed、Neovim（CodeCompanion、avante.nvim）等。社区已有基于 ACP 的 Vercel AI SDK Provider（ben-vargas/ai-sdk-provider-grok-build），Multica 等项目也将 grok agent stdio 作为一等运行时接入。

与 grok -p --output-format streaming-json 相比，ACP 能暴露完整的 tool call 生命周期与 MCP 配置，更适合 IDE 级集成。

本地编译与自定义模型¶

开源后，Grok Build 强调 local-first：自行编译 Harness，将 config.toml 中的 base_url 指向自有推理端点，即可在不依赖 xAI 云端 API 的情况下运行 Agent 框架（模型仍须自行提供）。

从源码构建¶

依赖：

• Rust：版本由 rust-toolchain.toml 锁定，rustup 首次构建时自动安装；
• DotSlash：Hermetic 工具链（如 bin/protoc）需要，cargo install dotslash 并确保在 PATH 中；
• protoc：Proto 代码生成所需。

git clone https://github.com/xai-org/grok-build.git
cd grok-build
cargo run -p xai-grok-pager-bin              # 构建并启动 TUI
cargo build -p xai-grok-pager-bin --release  #  release 二进制
cargo check -p xai-grok-pager-bin            # 快速校验

产物名为 xai-grok-pager；官方安装包将其 symlink 为 grok。

开发时建议针对单个 crate 操作，避免全 workspace 编译：

cargo check -p xai-grok-config
cargo test -p xai-grok-config
cargo clippy -p xai-grok-shell

自定义模型配置¶

用户级配置文件路径：~/.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"

更新配置后，Headless 指定模型：

grok -p "Hello" -m my-model

TUI 内可用 /model <name> 切换。若仍使用 xAI 官方模型，底层为 grok-4.5，亦可通过 xAI API 直接调用：

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

与 Codex CLI、OpenCode 的横向对比¶

Grok Build 的差异点在于：Harness 完全开源且模型无关，但仓库为只读同步，社区无法直接向官方主线贡献；工具层又透明引用了 Codex / OpenCode 的实现，适合作为「研究顶级产品 Agent 设计」的参考标本，而非期待共建的上游项目。

开发者可以怎么用¶

结合官方文档与仓库结构，几种典型路径如下：

1. 审计后再部署

在受监管仓库中启用 Agent 前，先阅读 xai-grok-tools 与沙箱相关 crate，确认命令执行边界与权限模型符合内控要求。

2. Fork 内部 Harness

Apache 2.0 允许修改与再分发。可在企业内 fork 后定制工具白名单、接入内部 MCP、替换默认模型端点；无需等待上游合并。

3. 离线 / air-gapped 环境

本地编译二进制，将 base_url 指向内网推理服务，跳过 api.x.ai，仅使用开源 Harness 编排自有模型。

4. CI 流水线

Headless 模式配合 streaming-json 输出，可将代码审查、架构说明等任务嵌入 GitHub Actions 等流水线。

5. IDE / 平台集成

通过 grok agent stdio 走 ACP，在 Zed、Neovim 或自研客户端中获得 tool call 流式反馈，比纯文本 Headless 输出更适合交互式编辑器场景。

小结¶

xAI 此次开源 Grok Build，实质上是将 编码 Agent 的「操作系统层」——循环调度、工具执行、TUI、扩展加载——完整公开。模型 grok-4.5 仍通过 API 或订阅使用，但 Harness 本身已可在本地编译、对接任意 OpenAI 兼容端点，并通过 ACP / MCP 接入现有开发者工具链。

对于关注 Agent 工程化而非单一模型的开发者，这份 Rust 代码库的价值在于：你可以直接阅读 context 如何组装、tool call 如何 dispatch、MCP 如何挂载——这些细节在闭源 CLI 里通常只能猜测。若你已在用 grok 命令行，不妨对照 xai-org/grok-build 源码，理解每一次文件编辑与 Shell 执行背后的实现路径。