内容
# Grok 构建桥接 Codex 和 Claude Code
中文完整说明：[README.zh-CN.md](README.zh-CN.md) · 打包与发布：[PACKAGING.zh-CN.md](PACKAGING.zh-CN.md)
Grok 构建桥接将 OpenAI Codex 和 Anthropic Claude Code 连接到本地、基于订阅认证的 Grok Build CLI（xAI）。它通过捆绑的 stdio MCP 服务器和共享路由技能，委托审查、有界编码任务、当前网络/X 研究、Grok 4.5 媒体生成和 xAI TTS。Codex 或 Claude Code 仍然是规划、审批、差异审查、验证和最终验收的主要代理；Grok 是一个受控的第二意见和实施渠道，而不是模型交换。
```
Codex / Claude Code → grok-build-delegate 技能 → MCP 工具 → 本地 `grok` CLI / xAI TTS → 主机审查和审批
```
## 项目起源
本仓库是一个本地扩展的派生版本，而不是从零开始的实现。其插件/运行时基础来自 OpenAI 的 Apache-2.0 许可的 [`codex-plugin-cc`](https://github.com/openai/codex-plugin-cc)，Grok Build 适配基于 Artem Matskevych 的公开 [`grok-build-codex-plugin`](https://github.com/Reederey87/grok-build-codex-plugin)。此版本随后被适配用于作者的本地 Codex 和 Claude Code 工作流，包括 Grok 4.5 图像/视频生成、基于订阅的 TTS、中文文档、打包、测试和额外的安装和安全工作。有关此仓库中进行的更改，请参见 Git 历史记录。
## 要求
- Node.js >= 18.18
- Grok Build CLI，已安装并登录：
```bash
curl -fsSL https://x.ai/cli/install.sh | bash
grok login
```
- 至少一个受支持的主机：带有插件支持的 OpenAI Codex CLI 或 Anthropic Claude Code。
## 为 Codex 安装
```bash
npm install
codex plugin marketplace add /path/to/grok-build-codex-plugin
codex plugin add grok-build@grok-build-dev
node scripts/install-codex-config.mjs
```
对于发布 ZIP，请先提取它，然后在提取的目录中运行 `npm ci` 再执行市场命令。发布存档故意排除 `node_modules`；有关端到端演练，请参见中文 [安装指南](README.zh-CN.md#从-zip-安装推荐)。
仓库根目录同时作为市场（`.agents/plugins/marketplace.json`）。在添加之前运行 `npm install` — MCP 服务器在运行时需要 `@modelcontextprotocol/sdk`，并且插件会缓存其 `node_modules`。仍然需要 `codex plugin add` 来注册 `grok-build-delegate` 技能。
最后一步，`node scripts/install-codex-config.mjs`，安装 MCP 服务器本身。在 codex-cli 0.144.1 上，`.mcp.json` 中的 `${PLUGIN_ROOT}` 在 Codex 的会话 cwd 外部不可解析 ([openai/codex#22842](https://github.com/openai/codex/issues/22842))，因此仅依赖 `.mcp.json` 会使服务器无法从其他仓库访问。安装程序会编写一个绝对路径 `[mcp_servers.grok-build]` 条目到 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）— 无论会话 cwd 如何，都可靠。`.mcp.json` 保留在仓库中，以防上游修复解析。运行 `node scripts/install-codex-config.mjs --remove` 来卸载；有关完整的标志引用，请参见 [`dev/README.md`](dev/README.md)。
Codex 有时会使用最小的 PATH 启动插件 MCP 服务器（例如 GUI/launchd 上下文），其中找不到裸 `node` 命令。已安装的配置通过捆绑的启动器 (`mcp-server/bin/grok-build-mcp`) 运行服务器，该启动器在常见安装位置自行定位 node；设置 `GROK_BUILD_NODE=/path/to/node` 以强制使用特定的二进制文件。
## 为 Claude Code 安装
Claude Code 使用相同的 MCP 服务器和共享委托技能，但它不使用 Codex 插件市场。从此仓库的长期检出：
```bash
npm install
claude mcp add --scope user grok-build -- /bin/sh "$PWD/mcp-server/bin/grok-build-mcp"
mkdir -p "$HOME/.claude/skills/grok-build-delegate"
cp skills/grok-build-delegate/SKILL.md "$HOME/.claude/skills/grok-build-delegate/SKILL.md"
claude mcp get grok-build
```
在安装技能后启动新的 Claude Code 会话。安全的默认设置保持仓库写入禁用；仅通过注册 MCP 服务器并设置 `-e GROK_BUILD_ALLOW_WRITE=true` 启用写入，每个写入调用仍必须设置 `write: true`。
根目录 `.mcp.json` 保留用于 Codex 插件打包，并使用 Codex 的 `${PLUGIN_ROOT}` 占位符。对于 Claude Code，支持的设置是上述绝对路径用户范围注册；不要启用仓库的冲突项目范围 `grok-build` 条目。Claude Code 支持当前为 MCP + 技能集成，而不是一键 `.claude-plugin` 包。
## 工具
MCP 服务器暴露十种工具。每个工具都需要一个 `cwd`（目标仓库的绝对路径）。
| 工具 | 用途 |
| --- | --- |
| `grok_build_setup` | 检查本地 Grok CLI、身份验证、模型、备用和状态存储。 |
| `grok_build_prompt` | 在工作区中运行一个前台、严格只读的 Grok 提示。 |
| `grok_build_review` | 收集安全的 Git 上下文并运行只读 Grok 代码审查。 |
| `grok_build_task` | 运行或排队一个有界的 Grok 任务，可选地带有门控工作区写入。 |
| `grok_build_image` | 使用 Grok 4.5 生成图像或编辑本地参考图像。 |
| `grok_build_video` | 使用 Grok 4.5 从源图像或生成的第一帧生成 6 秒或 10 秒的视频。 |
| `grok_build_tts` | 使用现有的本地 Grok Build OIDC 订阅登录，通过 xAI TTS 生成 MP3。 |
| `grok_build_status` | 列出存储库的活动或所有存储的作业，并带有进程存活率。 |
| `grok_build_result` | 返回已完成作业的存储结果和证据。 |
| `grok_build_cancel` | 取消活动作业、终止其进程树并释放其写入锁。 |
`grok_build_task` 默认在前台运行；传递 `background: true` 进行长时间运行，然后轮询 `grok_build_status` 并在作业完成时读取 `grok_build_result`。
## 配置
MCP 服务器读取的环境变量：
| 变量 | 用途 |
| --- | --- |
| `GROK_BUILD_DEFAULT_MODEL` | 传递给 CLI 的默认 Grok 模型。未设置则使用 Grok 自己的默认值。 |
| `GROK_BUILD_PLUGIN_DATA` | 作业状态和审查输入的目录。默认为临时目录。 |
| `GROK_BUILD_API_FALLBACK` | `true` 以全局允许只读 xAI API 备用。默认为 `false`。 |
| `GROK_BUILD_ALLOW_WRITE` | `true` 以允许写入模式任务。默认为关闭。 |
| `XAI_API_KEY` | xAI API 密钥。API 备用需要此密钥。 |
| `GROK_BUILD_XAI_BASE_URL` | xAI API 基本 URL。默认为 `https://api.x.ai/v1`。 |
| `GROK_BUILD_XAI_TIMEOUT_MS` | xAI API 请求超时，单位为毫秒。默认为 `120000`。 |
| `GROK_BUILD_GROK_AUTH_PATH` | 覆盖仅由 TTS 使用的 Grok Build OIDC 存储。默认为 `~/.grok/auth.json`。 |
| `GROK_BUILD_TTS_BASE_URL` | 覆盖 TTS API 基本 URL。默认为 `https://api.x.ai/v1`。 |
| `GROK_BUILD_NODE` | 绝对路径到捆绑启动器要使用的 node 二进制文件，绕过其自己的 PATH 搜索。 |
主机代理的沙盒和审批策略控制应用 Grok 提出的任何补丁。用于 `~/.codex/config.toml` 的每个工具审批片段位于 [`dev/config-snippet.toml`](dev/config-snippet.toml)。安装程序应用相同的策略：只读设置、提示、审查、状态和结果工具自动批准，而具有写入能力的 `grok_build_task`、停止进程的 `grok_build_cancel` 和消耗配额的 `grok_build_image` / `grok_build_video` / `grok_build_tts` 调用保持在 `prompt` 上。此自动策略安装特定于 Codex；Claude Code 遵循其自己的 MCP 权限设置。
## 媒体生成
媒体调用始终使用本地 `grok-4.5` 模型，从不使用 xAI API 备用。它们解析 Grok 的已完成媒体事件并在 `artifact.path` 中返回验证的绝对文件路径。
- `grok_build_image`：文本到图像，或基于参考的编辑，当 `reference_images` 包含一到七个绝对本地路径时。命名真实人物需要一个真正的参考图像。
- `grok_build_video`：动画一个绝对的 `source_image`，或省略它以让 Grok 创建第一帧然后动画。持续时间为 6 秒或 10 秒；分辨率 为 `480p` 或 `720p`。
生成的媒体文件存活在 Grok 的本地会话目录中。两个工具都需要手动 MCP 批准，因为它们创建媒体并且可能消耗订阅配额。
## TTS 生成
`grok_build_tts` 使用存储在 `~/.grok/auth.json` 中的 OIDC 访问令牌调用 xAI 的专用 `/v1/tts` 端点。它不读取或使用 `XAI_API_KEY`，并且从不返回令牌。默认情况下，语音为 `eve`，语言为 `en`，输出为 MP3；对于其他语言，请传递匹配的 ISO 语言代码（例如 `zh`）。内置语音 ID 包括 `ara`、`leo`、`rex` 和 `sal`，并且接受自定义语音 ID。显式 `output_path` 必须是 `cwd` 内的绝对 `.mp3` 路径；如果没有，工具将在 `cwd/grok-build-output/` 下创建一个唯一文件。
桥接要求 Grok CLI 刷新即将过期的登录，并且在 HTTP 401 后重试一次。TTS 仍然需要手动 MCP 批准，因为它写入文件并且可能消耗订阅配额。
## API 备用
默认情况下，所有工作都通过本地的 `grok` CLI 运行。只读 xAI API 备用仅在以下所有条件满足时触发：
- 明确允许 — 调用时 `allow_api_fallback: true` 或 `GROK_BUILD_API_FALLBACK=true`；
- 设置了 `XAI_API_KEY`；
- 本地 `grok` CLI 丢失或未经身份验证；并且
- 请求是只读的。
备用结果标记为 `source: "xai_api_fallback"`。备用从不用于写入模式任务 — 它使用您的 xAI API 积分，因此它是一个明确的只读选择。
## 写入模式
写入模式在 v1 中被禁用，默认情况下关闭。必须满足两个门控：
1. 服务器环境具有 `GROK_BUILD_ALLOW_WRITE=true`，并且
2. 调用在 `grok_build_task` 上设置 `write: true`。
`--always-approve` 从未隐含；`always_approve` 仅在显式请求时对写入任务生效。每个写入作业在运行前后捕获 `git status` 作为证据，以便您可以查看实际更改了什么。应用其他更改仍然通过主机代理的正常编辑/审批流程。
## 试用
启用桥接后，询问 Codex 或 Claude Code：
- “使用 Grok Build 为此仓库运行其设置诊断。”
- “使用 Grok Build 解释此仓库的作用（只读）。”
- “使用 Grok Build 审查我的工作树。”
- “要求 Grok Build 对此分支与 `main` 进行对抗性审查。”
- “使用 Grok 4.5 生成 16:9 的电影式火箭发射图像。”
- “使用 Grok 4.5 创建 6 秒 16:9 的 720p 视频。”
- “使用我的 Grok 订阅将此中文脚本转换为 MP3，语音为 leo。”
`grok-build-delegate` 技能还允许对明确指定、可验证的工作进行选择性隐式路由，例如审查差异、调查聚焦的故障、实施已编写的计划或进行机械编辑。主机代理保留架构、产品判断、差异审查、测试验证和最终验收。写入委托仍然是双重控制的。
## 开发
```bash
npm test # node --test over tests/*.test.mjs
npm run build # tsc type-check (JSDoc types, no emit)
npm run package:plugin # create a clean versioned ZIP and SHA-256 file
```
在没有 Codex 或 Claude Code 的情况下，使用开发运行器或服务器自测试驱动工具：
```bash
node mcp-server/src/dev-runner.mjs setup --cwd "$PWD"
node mcp-server/src/server.mjs --self-test
```
`npm run bump-version` / `npm run check-version` 管理耦合的版本字符串。
## 状态
Grok Build CLI 处于早期测试阶段 — 其标志和 JSON 输出可能会更改。输出解析故意宽容，作业成功从 Grok 的 `stopReason`（`EndTurn` = 干净）读取，而不是退出代码。预计会有粗糙的边缘。
## 许可证
Apache-2.0
