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