Skip to main content
Glama

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 负责具体执行;工具说明和返回结果定义其余流程。

Related MCP server: grok-subagent

功能

  • 每个 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"
  1. 已认证:本仓库不负责 Grok 账号登录流程。请先按 Grok CLI 官方方式完成认证;若认证无效,会话连接或任务执行会失败,错误会出现在观察窗口或 %USERPROFILE%\.grok-to-codex\logs\ 下的日志中。

  2. 可从终端调用:在普通 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。

Available Tools

6 tools
grok_session_closeC

当 Grok 会话已经闲置且不再需要后台进程时调用。它会关闭工作进程,但保留会话映射,之后仍可尝试恢复。

Inputs: project_root (required), codex_task_id (required), branch, working_directory.

grok_session_ensureA

当任务涉及代码项目时,先调用此工具连接或创建当前 Codex 任务、项目路径和 Git 分支对应的 Grok 会话。它只建立会话,不会让 Grok 开始编码。

Inputs: project_root (required), codex_task_id (required), branch, open_observer, +1 more.

grok_session_switchB

当项目路径、工作目录或 Git 分支发生变化时调用,为新的上下文切换到独立的 Grok 会话,避免复用不相关的旧上下文。

Inputs: project_root (required), codex_task_id (required), branch, open_observer, +1 more.

grok_task_cancelA

当用户要求停止当前 Grok 工作,或确认任务已经失去响应时调用。它会取消任务并结束对应的 Grok 进程树。

Inputs: project_root (required), codex_task_id (required), branch, working_directory.

grok_task_startA

当 Codex 完成需求分析并需要具体修改代码、执行命令或运行测试时,使用此工具把明确任务交给 Grok。此调用会一直等待,直到 Grok 完成、失败、阻塞或被取消;等待期间不要并行执行其他项目工作。架构规划、需求判断和最终审查仍由 Codex 负责。

Inputs: mode (required), objective (required), project_root (required), codex_task_id (required), +8 more.

grok_task_statusA

在用户要求查看进度、排查异常或确认 Grok 状态时调用。返回简短状态,不返回完整实时日志;不需要主动每隔几分钟轮询。

Inputs: project_root (required), codex_task_id (required), branch, working_directory.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: session creation, task start, status check, cancel, session switch, and close. No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent 'grok_verb_noun' pattern (e.g., grok_session_ensure, grok_task_start), making it predictable.

    Tool Count5/5

    With 6 tools, the server is well-scoped, covering the full lifecycle of session and task management without unnecessary duplication.

    Completeness5/5

    The tool set covers all essential operations for managing Grok sessions and tasks: creation, starting, status, cancellation, context switching, and cleanup. No obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Codex to use Grok Build CLI as a controlled subagent via MCP tools for independent investigation, review, and isolated implementation tasks.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects OpenAI Codex and Claude Code to the local Grok Build CLI for second-opinion code reviews, bounded coding tasks, web research, media generation, and TTS.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Grok Build to orchestrate the local Codex CLI for code reviews, adversarial reviews, task rescue, session transfer, and background job management through MCP tools.
      1
      Apache 2.0