# 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）

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

```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 一致）：

```powershell
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 窗口中检查：

```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`，例如：

```powershell
# 示例：把路径换成你本机实际的 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 配置中添加此服务。**请使用编译后入口文件的绝对路径**，不要写成相对路径。

```json
{
  "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` 中补充：

```json
"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` 表示不限制 |

数据目录结构（默认）：

```text
%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 配置。

## 简短完整使用流程

```powershell
# 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` / 无法启动进程。

处理：

```powershell
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` / 启动任务时，若检测到旧观察进程已不在，会尝试重新打开。
- 手动查看日志是否在写入：

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

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

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

### 3. 日志目录在哪里

默认：

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

PowerShell 打开：

```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 行为没变

```powershell
npm run build
```

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

## 开发和验证

```powershell
npm run typecheck
npm test
npm run build
```

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