Grok Build 開源後怎麼本地運行：接入 MCP、Skills 和 Plugins 教程

Grok Build 是 xAI 開源的終端 AI 編程代理。它以全屏 TUI 和 grok CLI 運行，可理解代碼庫、編輯文件、執行命令、搜索網頁，也能以無界面模式接入腳本或 CI。開源後，你不僅可以查看其代理運行時、工具調用和擴展系統的實現，也可以在本機用官方發佈版直接接入 MCP、Skills 和 Plugins。

本文以“先安裝官方二進制，再逐項接入擴展”爲主。源碼構建適合想研究或修改 Grok Build 本身的人；普通使用者沒有必要一開始就編譯 Rust 項目。

Quick Answer

最短路徑是：安裝 grok，進入項目目錄運行 grok 完成登錄，再執行 grok inspect 查看它已發現的配置、Skills、Plugins 和 MCP 服務器。隨後用 grok mcp add 添加一個只讀、目錄範圍受限的 MCP 服務進行驗證。

Grok Build 會識別項目中的 .grok/，也兼容 Claude Code 的 Skills、Plugins、MCP、Hooks、CLAUDE.md 和 .claude/rules/。因此已有 Claude Code 工作區時，通常先檢查自動發現結果，不要急着複製一份配置。

Grok Build 開源了什麼

xAI 發佈的倉庫包含 grok CLI/TUI 的 Rust 源碼和代理運行時。公開內容覆蓋代理循環、終端與文件工具、工作區操作、配置、MCP、Markdown 和沙箱等組件；官方說明中也明確列出 Skills、Plugins、Hooks、MCP servers 和 subagents 擴展系統。

這不等於“每個人都應從源碼運行”。官方同時提供 macOS、Linux 和 Windows 的預編譯安裝方式。源碼構建需要 Rust、DotSlash 與 protoc 等依賴，且官方將 Windows 源碼構建標爲 best-effort、未在該源碼樹中測試。日常開發優先安裝發佈版，只有排查實現或貢獻補丁時再構建源碼。

安裝並啓動本地會話

Windows PowerShell

1
2

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

macOS、Linux 或 Git Bash

1
2

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

進入你的倉庫後啓動：

1
2

cd your-project
grok

首次啓動通常會打開瀏覽器進行認證。無法打開瀏覽器的環境可設置 API Key：

1
2

export XAI_API_KEY="xai-..."
grok

Windows PowerShell 對應寫法是：

1
2

$env:XAI_API_KEY = "xai-..."
grok

不要把密鑰寫進倉庫、截圖或 AGENTS.md。若需要長期配置，優先採用系統環境變量或你的密碼管理工具，而不是提交到 Git。

先用 grok inspect 看自動發現結果

在添加任何擴展前，運行：

1

grok inspect

它會顯示當前目錄已加載的配置來源、指令文件、Skills、Plugins、Hooks 和 MCP servers。這一步很重要，因爲 Grok Build 會向上查找項目根目錄，也會讀取用戶目錄下的配置；同名項目級 MCP 配置還會覆蓋用戶級配置。

如果項目已經使用 Claude Code，Grok 會自動讀取 Claude 的 marketplaces、plugins、skills、MCPs、agents、hooks 與 CLAUDE.md、.claude/rules/。先確認 grok inspect 的結果，再決定是否需要新建 .grok/ 目錄，能避免同一服務被重複加載或權限被意外放大。

接入 MCP：先從受限的本地目錄開始

MCP server 會把外部工具暴露給 Grok，工具名稱帶有 <server>__<tool> 命名空間。最簡單的添加方式是 grok mcp add。

下面示例只把一個指定目錄交給 filesystem MCP server；將 /path/to/dir 換成實際目錄，不要直接授權整個用戶目錄或磁盤根目錄：

1

grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

常用管理命令：

1
2
3

grok mcp list
grok mcp doctor filesystem
grok mcp remove filesystem

遠程 MCP 可通過 HTTP 添加。OAuth 型服務首次使用時會進行瀏覽器授權；使用靜態令牌時，應從環境變量讀取，而不是把令牌直接寫進配置：

1
2

grok mcp add --transport http linear https://mcp.linear.app/mcp
grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

需要隨倉庫共享 MCP 聲明時，加上 --scope project，Grok 會在當前目錄寫入 .grok/config.toml：

1

grok mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

項目配置可以提交，密鑰不應提交。團隊成員各自設置 API_TOKEN，再讓 ${API_TOKEN} 在加載配置時展開即可。

MCP 配置文件示例

你也可以直接編輯用戶級配置文件：macOS/Linux 爲 ~/.grok/config.toml，Windows 爲 %USERPROFILE%\.grok\config.toml。

1
2
3
4
5
6
7
8
9

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
startup_timeout_sec = 30
tool_timeout_sec = 6000

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { "x-mcp-session-id" = "{{session_id}}" }

配置後再次運行 grok inspect，並用 grok mcp doctor <名稱> 檢查連通性。首次運行的 npx server 可能需要下載依賴；如果它啓動超時，再謹慎提高 startup_timeout_sec，不要把超時問題誤判爲權限問題。

Skills：放入項目或用戶目錄

Skills 是包含 Markdown 指令、腳本和資源的可複用文件夾。Grok 會從以下位置發現它們：

• 項目中的 ./.grok/skills/，並向上查找至倉庫根目錄；
• 用戶目錄中的 ~/.grok/skills/；
• 已啓用 Plugin 的 skills/ 目錄；
• ~/.grok/config.toml 的 [skills] paths 額外路徑。

項目專用 Skill 可以使用類似結構：

1
2
3
4
5
6

.grok/
└── skills/
    └── release-check/
        ├── SKILL.md
        └── scripts/
            └── check.sh

SKILL.md 應清楚說明觸發條件、允許使用的工具、輸入輸出和安全邊界。用戶可調用的 Skill 會顯示爲 /<skill-name> 斜槓命令；自動觸發的 Skill 則應避免過於寬泛的描述，以免每個任務都被錯誤加載。

Plugins：把多個擴展打包管理

Plugin 可以打包 Skills、agents、hooks、MCP servers 和 LSP servers，適合團隊共享一組固定工作流。Grok 會從項目 .grok/plugins/、用戶 ~/.grok/plugins/、marketplace 安裝目錄，以及 config.toml 的 [plugins] paths 發現它們；也可以通過 --plugin-dir <PATH> 臨時指定路徑。

在 TUI 中輸入 /plugins、/skills、/hooks 或 /mcps，會打開同一個擴展管理界面。先安裝或啓用最小的一組擴展，再逐個驗證，尤其不要一開始就把能執行 shell、寫 Git、訪問雲服務的插件全打開。

如果團隊已有 Claude Code 插件市場，Grok 的兼容層可直接讀取它們。只有在需要 Grok 獨有配置、或希望與 Claude 配置隔離時，才單獨建立 .grok/plugins/。

本地模型與無界面模式

Grok Build 支持在用戶級 config.toml 中加入自定義模型，例如 OpenAI-compatible endpoint 或本地推理服務：

1
2
3
4
5
6
7
8

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

配置後可選擇該模型：

1
2

grok inspect
grok -p "Explain this codebase" -m my-model

grok -p 是無界面模式，適合腳本、CI 或其他應用集成；需要機器可讀輸出時可加 --output-format streaming-json。在 CI 中使用時應單獨創建低權限令牌、限制工作目錄，並明確禁止自動執行不可逆的 Git 或部署操作。

常見問題與安全邊界

爲什麼擴展沒有生效？

依次檢查：

1. 在預期項目目錄中執行 grok inspect；
2. 用 grok mcp list 確認 server 是否已註冊；
3. 用 grok mcp doctor <名稱> 查看配置和網絡診斷；
4. 檢查項目級 .grok/config.toml 是否覆蓋了同名用戶級 server；
5. 檢查環境變量是否在啓動 grok 的同一終端會話中可見。

能否把 Codex 或 Claude Code 的配置直接複用？

Claude Code 的大部分擴展和指令文件可被 Grok 自動發現，但“能夠被讀取”不等於每個第三方擴展都應直接信任。先在測試倉庫執行 grok inspect，覈對擴展來源、權限和啓動命令，再決定是否用於真實項目。

源碼編譯失敗怎麼辦？

如果你的目標只是使用 Grok Build，改用官方預編譯安裝包通常更快。確實需要編譯源碼時，按倉庫 README 準備 Rust、DotSlash 和 protoc，並優先在官方標註爲支持的 macOS 或 Linux 主機上構建。Windows 上的源碼構建目前不應作爲生產環境的默認路徑。

官方參考

• xAI：Grok Build 開源公告
• xAI：Grok Build 入門與本地模型配置
• xAI：Skills、Plugins 與 Marketplaces
• xAI：MCP Servers 配置
• xAI 官方開源倉庫

Related Posts

• Grok 4.5 API 怎麼接入：Responses API、價格、EU 可用性與 prompt cache 設置
• Grok Automations 是什麼：與 ChatGPT Tasks、Claude 定時任務有什麼區別
• Archify 怎麼安裝到 Codex/Claude Code：從倉庫生成架構圖、流程圖與 SVG