Grok-Codex Bridge

这是一个 MCP（模型上下文协议）工具，可以让 Codex 把具体的编码任务交给 Grok Build CLI 执行。经过测试，Grok 4.5 的编码处理速度远超其他模型，而且在有明确要求或方案的情况下能力完全不差。由于 GPT 5.6 的正常任务处理速度偏慢，所以需要用一个编码智能体来协助 Codex 干脏活累活。

协作分工

• Codex：负责需求理解、架构设计、项目规划、代码审查和最终决策。
• Grok：负责具体的代码查找、文件修改、命令执行和测试。
• 桥接程序：让任务调用一直等待到 Grok 完成；同时把实时过程写入本地日志，并显示在独立的观察窗口中。

下载安装 MCP 后，可以使用这段自定义提示词来要求 Codex 使用该工具：

当任务涉及代码项目时，先调用 grok_session_ensure 连接当前项目对应的 Grok 会话。当完成需求分析并需要进行具体的代码修改、命令执行或测试时，优先使用 Grok-Codex MCP 工具。Codex 负责规划、架构和审查，Grok 负责具体执行；工具说明和返回结果定义其余流程。

功能

• 每个 Codex 任务、项目路径和 Git 分支对应一个 Grok 会话。
• 通过 ACP（代理客户端协议）的标准输入输出通道控制 Grok Build CLI。
• 通过 --always-approve 自动批准 Grok 的普通工具权限请求。
• 每五分钟进行一次内部健康检查；健康检查与最大运行时间分开配置。
• 不把 Grok 的连续过程逐条发送到 Codex 上下文。
• 提供可见的 PowerShell 观察窗口，显示任务阶段、工具、文件、测试、错误和健康检查结果；如果旧窗口已经关闭，会自动重新打开。
• 校验项目路径和工作目录。
• 在 Windows 上取消任务时结束完整的进程树（父进程及其子进程）。

环境要求

• Node.js 20 或更高版本。
• Git（用于从 GitHub 克隆仓库）。
• 已安装并完成认证的 Grok CLI。
• grok 已加入 PATH 环境变量，或者设置 GROK_EXECUTABLE 指向 Grok 可执行文件。

从 GitHub 克隆并安装（Windows PowerShell）

下面的命令可直接复制；请按需把本地路径改成你自己的目录。

# 1. 进入你希望存放仓库的目录
cd $env:USERPROFILE\Desktop

# 2. 克隆公开仓库
git clone https://github.com/Nurkic4/grok-to-codex.git
cd grok-to-codex

# 3. 确认 Node.js 版本（需要 >= 20）
node -v

# 4. 安装依赖
npm install

# 5. 编译 TypeScript 到 dist/
npm run build

安装完成后，应能看到：

• node_modules\：依赖
• dist\index.js：MCP 服务入口
• dist\observer.js：观察窗口入口

命令说明与完整验证流程

命令	作用	会不会生成 dist/
npm install	安装 package.json 中的依赖	否
npm run typecheck	只做 TypeScript 类型检查（tsc --noEmit），不写出编译产物	否
npm test	运行 tests/*.test.ts 单元测试	否
npm run build	编译 TypeScript，生成 dist/ 下的 JS 产物	是

推荐的完整验证顺序（与仓库 CI 一致）：

cd C:\Users\你的用户名\Desktop\grok-to-codex

npm run typecheck
npm test
npm run build

说明：

• typecheck：尽早发现类型错误，适合开发过程中频繁执行。
• test：验证会话键、路径边界、任务提示词、默认终端配置、观察窗口存活判断等逻辑。
• build：生成 Codex MCP 实际要启动的 dist/index.js 与观察窗口用的 dist/observer.js。
• 修改源码后，若要在发布模式下使用，需要重新执行 npm run build。

构建产物用途

产物	用途
dist/index.js	MCP 服务主入口。Codex 通过 node 启动它，从而暴露 grok_* 系列工具。
dist/observer.js	独立观察窗口入口。桥接程序在需要时用 node dist/observer.js --file <jsonl日志> 打开，实时读取 JSONL 日志并打印任务过程。

相关 npm 脚本：

脚本	含义
npm start	以发布模式启动 MCP：node dist/index.js
npm run dev	以开发模式直接运行源码：tsx src/index.ts
npm run observer	以开发模式运行观察窗口源码（仍需自行提供 --file 日志路径）

确认 Grok CLI 已安装、可调用

桥接程序默认执行 PATH 中的 grok；也可通过 GROK_EXECUTABLE 指定绝对路径。

在 新的 PowerShell 窗口中检查：

# 是否能在 PATH 中找到 grok
Get-Command grok -ErrorAction SilentlyContinue

# 查看可执行文件位置
where.exe grok

# 确认命令能被启动（以你本机 Grok CLI 实际支持的帮助/版本参数为准）
grok --help

判断标准：

1. 已安装且在 PATH 中：Get-Command grok 能返回命令信息，where.exe grok 能打印路径。
2. 不在 PATH 中：为 MCP 配置设置 GROK_EXECUTABLE，例如：

# 示例：把路径换成你本机实际的 grok.exe 位置
$env:GROK_EXECUTABLE = "C:\Users\你的用户名\AppData\Local\Programs\grok\grok.exe"

3. 已认证：本仓库不负责 Grok 账号登录流程。请先按 Grok CLI 官方方式完成认证；若认证无效，会话连接或任务执行会失败，错误会出现在观察窗口或 %USERPROFILE%\.grok-to-codex\logs\ 下的日志中。
4. 可从终端调用：在普通 PowerShell 里能运行 grok，并且没有 “无法识别命令” 一类错误。Codex 启动 MCP 时继承的环境变量也需要能找到同一可执行文件。

Codex MCP 配置（Windows 绝对路径示例）

在 Codex 使用的 MCP 配置中添加此服务。请使用编译后入口文件的绝对路径，不要写成相对路径。

{
  "mcpServers": {
    "grok-to-codex": {
      "command": "node",
      "args": [
        "C:\\Users\\你的用户名\\Desktop\\grok-to-codex\\dist\\index.js"
      ],
      "env": {
        "GROK_MODEL": "grok-4.5",
        "GROK_ALWAYS_APPROVE": "true",
        "GROK_OPEN_OBSERVER": "true"
      }
    }
  }
}

可选：当 grok 不在 PATH 中时，在 env 中补充：

"GROK_EXECUTABLE": "C:\\Users\\你的用户名\\AppData\\Local\\Programs\\grok\\grok.exe"

注意：

• JSON 里的 Windows 路径请使用双反斜杠 \\，或改用正斜杠 /。
• MCP 协议数据只写入标准输出；诊断信息写入标准错误。
• 观察窗口是独立的控制台窗口，通过读取桥接程序数据目录中的 JSONL（每行一个 JSON 对象）日志显示 Grok 的工作过程。
• 修改配置或重新 npm run build 后，通常需要重启 Codex / 重新加载 MCP，才会生效。

提供的工具

• grok_session_ensure：创建或恢复当前任务对应的 Grok 会话。
• grok_task_start：执行一项编码、测试或检查任务，并等待任务结束后返回结果。
• grok_task_status：返回当前任务的简要状态。
• grok_task_cancel：取消当前任务并结束 Grok 的进程树。
• grok_session_switch：切换到另一个项目或分支对应的独立上下文。
• grok_session_close：关闭闲置的 Grok 工作进程，同时保留会话映射。

每个任务都应该提供目标、允许修改的路径、限制条件、验收标准和验证命令。

grok_task_start 支持的模式：

• implement：实现/修改代码
• test：运行或补充测试
• inspect：只读检查、排查

该调用会一直等待，直到 Grok 完成、失败、阻塞、被取消，或触发可选的最大运行时间限制。

运行配置

环境变量	默认值	说明
GROK_CODEX_BRIDGE_HOME	%USERPROFILE%\.grok-to-codex	会话注册表和日志目录
GROK_EXECUTABLE	grok	Grok 可执行文件
GROK_MODEL	grok-4.5	传给 Grok 的模型名称
GROK_TERMINAL_SHELL	Windows 使用 powershell.exe，Unix 使用系统默认 shell	Grok 通过 ACP 创建终端时使用的 shell
GROK_ALWAYS_APPROVE	true	启动 Grok 时跳过普通权限询问
GROK_OPEN_OBSERVER	true	是否打开可见观察窗口
GROK_HEALTH_INTERVAL_MS	300000	内部健康检查间隔，默认五分钟
GROK_MAX_RUNTIME_MS	0	可选的最大运行时间（毫秒），0 表示不限制

数据目录结构（默认）：

%USERPROFILE%\.grok-to-codex\
  sessions.json          # 会话映射
  logs\
    <会话键>.jsonl       # 观察窗口读取的实时日志

健康检查与任务等待（重要）

• 五分钟健康检查不是任务超时时间。
• 默认每隔约 5 分钟（GROK_HEALTH_INTERVAL_MS=300000）检查一次 Grok 进程与 ACP 通道是否仍然可用。
• 只要 Grok 正常运行，grok_task_start 可以一直等待到任务结束。
• 桥接程序会持续读取 ACP 事件，因此 Grok 完成后会立即返回结果。
• 若需要限制单次任务最长运行时间，请单独设置 GROK_MAX_RUNTIME_MS，或在 grok_task_start 中传入 max_runtime_ms；0 表示不限制。

权限说明

--always-approve 会取消 Grok 普通工具调用的人工确认，不代表获得 Windows 管理员权限。Grok 的拒绝规则、钩子（工具执行前后的自动检查）或管理员策略仍然可能阻止操作。

开发模式与发布模式

模式	如何启动	适用场景
开发模式	npm run dev（内部是 tsx src/index.ts）	本地改源码、调试 MCP 逻辑；直接跑 TypeScript，不依赖最新 dist/
发布 / Codex 使用模式	先 npm run build，再由 Codex 启动 node ...\dist\index.js，或执行 npm start	日常把任务交给 Grok；MCP 配置应指向编译后的 dist/index.js

补充说明：

• 观察窗口在运行时会启动同目录下的 observer.js。发布模式下对应 dist/observer.js。
• 开发模式下改动 src/ 后，重启 npm run dev 即可；发布模式下必须重新 npm run build，再重启 MCP。
• Codex 集成请使用发布模式产物，避免把 tsx 开发链路写进 MCP 配置。

简短完整使用流程

# A. 准备本仓库
cd C:\Users\你的用户名\Desktop
git clone https://github.com/Nurkic4/grok-to-codex.git
cd grok-to-codex
npm install
npm run typecheck
npm test
npm run build

# B. 确认 Grok 可用
Get-Command grok
grok --help

# C. 在 Codex MCP 配置中加入 dist\index.js 的绝对路径与环境变量
# D. 重启 / 重新加载 Codex 的 MCP
# E. 在 Codex 中先 grok_session_ensure，再在需要落地改代码时 grok_task_start
# F. 查看弹出的观察窗口，或打开：
#    $env:USERPROFILE\.grok-to-codex\logs\

推荐提示词（可放进 Codex 自定义说明）：

当任务涉及代码项目时，先调用 grok_session_ensure 连接当前项目对应的 Grok 会话。当完成需求分析并需要进行具体的代码修改、命令执行或测试时，优先使用 Grok-Codex MCP 工具。Codex 负责规划、架构和审查，Grok 负责具体执行。

常见问题排查

1. grok 不在 PATH

现象：MCP 启动会话失败，日志或标准错误提示找不到 grok / 无法启动进程。

处理：

Get-Command grok -ErrorAction SilentlyContinue
where.exe grok

• 若找不到：把 Grok 安装目录加入用户或系统 PATH，新开 PowerShell / 重启 Codex 后再试。
• 或者在 MCP env 中设置 GROK_EXECUTABLE 为 grok.exe 的绝对路径。

2. 观察窗口不显示

可能原因与处理：

• GROK_OPEN_OBSERVER 被设为 false / 0 / off / no：改回 true 或删除该变量以使用默认值。
• 尚未成功建立会话：先调用 grok_session_ensure；观察窗口通常在会话就绪时打开。
• 旧窗口已关闭：再次 ensure / 启动任务时，若检测到旧观察进程已不在，会尝试重新打开。
• 手动查看日志是否在写入：

Get-ChildItem "$env:USERPROFILE\.grok-to-codex\logs"
Get-Content "$env:USERPROFILE\.grok-to-codex\logs\*.jsonl" -Tail 20

• 也可手动打开观察窗口（把日志文件路径换成实际文件）：

node C:\Users\你的用户名\Desktop\grok-to-codex\dist\observer.js --file C:\Users\你的用户名\.grok-to-codex\logs\某个会话.jsonl

3. 日志目录在哪里

默认：

%USERPROFILE%\.grok-to-codex\logs\

PowerShell 打开：

explorer "$env:USERPROFILE\.grok-to-codex\logs"

若设置了 GROK_CODEX_BRIDGE_HOME，则日志位于该目录下的 logs\。会话注册表是同级的 sessions.json。

4. 五分钟健康检查是什么意思

• 它是运行中的存活/连通性检查，默认约每 5 分钟一次。
• 不是“任务最多跑五分钟就会超时”。
• 任务真正的可选超时由 GROK_MAX_RUNTIME_MS 或工具参数 max_runtime_ms 控制；默认为 0（不限制）。
• 健康检查失败时，会写入观察日志，并可能关闭异常的 Grok 进程；这与“正常完成任务后立即返回”是两回事。

5. grok_task_start 为什么一直不返回

• 正常现象：该工具会阻塞等待 Grok 做完当前任务。
• 请看观察窗口或 JSONL 日志中的阶段、工具调用和错误。
• 需要中止时，调用 grok_task_cancel。
• 不要把五分钟健康检查误判为超时；除非你显式配置了最大运行时间，否则任务可以一直跑到结束。

6. 改了代码但 Codex 行为没变

npm run build

然后重启 / 重新加载 Codex 的 MCP，确认配置仍指向最新的 dist\index.js。

开发和验证

npm run typecheck
npm test
npm run build

CI（.github/workflows/ci.yml）在 Node.js 20 上执行同样的顺序：npm ci → typecheck → test → build。