前言¶
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 命令、檢索網頁，並管理長時任務。使用形態有三種：
- 交互式 TUI：全屏、支持鼠標的終端界面；
- Headless 模式：腳本、CI/CD 中通過
-p非交互執行； - ACP 集成：通過 Agent Client Protocol，嵌入 IDE 或自定義應用。
本次開源的是 Harness 與 TUI 的 Rust 源碼，並非 Grok 4.5 模型權重。官方明確，倉庫涵蓋以下模塊：
| 模塊 | 說明 |
|---|---|
| Agent 循環 | 上下文組裝、模型響應解析、工具調用分發 |
| 工具層 | 讀/寫/搜索代碼、運行終端命令等 |
| 終端 TUI | 渲染、輸入、計劃審查、行內 diff 查看器 |
| 擴展系統 | Skills、Plugins、Hooks、MCP Servers、Subagents |
倉庫從 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 分層，便於按需閱讀源碼：
| 路徑 | 內容 |
|---|---|
crates/codegen/xai-grok-pager-bin |
組合根，構建 xai-grok-pager 二進制 |
crates/codegen/xai-grok-pager |
TUI：滾動區、提示符、模態框、渲染 |
crates/codegen/xai-grok-shell |
Agent 運行時，含 leader/stdio/headless 入口 |
crates/codegen/xai-grok-tools |
工具實現：終端、文件編輯、搜索等 |
crates/codegen/xai-grok-workspace |
宿主文件系統、VCS、執行、檢查點 |
crates/codegen/... |
配置、MCP、Markdown、沙箱等其餘 CLI crate |
third_party/ |
vendored 上游（如 Mermaid 圖表棧） |
若你想審計「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 文檔）：
- 發送
initialize，協商協議版本與客戶端能力； - 根據返回的
authMethods選擇認證方式（如cached_token或xai.api_key），發送authenticate； - 調用
session/new創建會話，再通過session/prompt下發任務； - 助手文本與工具生命週期事件以
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 的橫向對比¶
| 項目 | 協議 | 可 Fork | 模型選擇 | 外部 PR |
|---|---|---|---|---|
| Grok Build | Apache 2.0 | 允許 | 任意（config.toml） |
不接受 |
| Codex CLI | Apache 2.0 | 允許 | OpenAI 模型 | 開放 |
| OpenCode | MIT | 允許 | 75+ Provider | 社區維護 |
| Claude Code | 專有 | 不可 | Anthropic 模型 | — |
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 執行背後的實現路徑。
