Codex Bridge MCP

让 Claude 或 Codex 负责决策，用一套 MCP 持续、可控地调度 Codex、Claude Code 与支持 ACP 的 Vibe Coding CLI。

Codex Bridge MCP 是连接 任务编排者（Claude Code、Codex 或其他 MCP 客户端）与 编码执行引擎 的本地会话层。它默认原生连接 Codex App Server，也可以驱动 Claude Agent SDK，以及通过 Agent Client Protocol（ACP）接入的 Kimi 等 Vibe Coding CLI。它不是另一个模型，也不是把一条提示词转发给某个 CLI 的脚本；它用统一的 MCP 工具为一项开发任务保留稳定的执行线程、运行状态、审批记录和审阅闭环。

当需求需要多轮补充、代码修改需要审批、任务可能中断、结果还需要审查时，编排者不必为 Codex、Claude Code、Kimi 等工具分别维护一套调用和恢复逻辑，也不必把执行引擎的一句“完成”当作验收结果。

它为谁而做

适合已经使用一种或多种 AI 编码工具，并希望把它们接入真实工程任务的开发者和团队：

• Claude 或 Codex 作为任务编排者，负责理解需求、拆解问题、作出判断和审查结果；

• Codex、Claude Code、Kimi 或其他支持 ACP 的 Vibe Coding 工具作为执行引擎，负责进入仓库、修改文件、执行命令和完成验证；

• 你需要用同一组 MCP 工具选择执行引擎，并让任务状态、审批、恢复和 diff 审阅不随工具切换而断掉。

Claude 是默认、最清晰的协作入口；如果你已经使用 Codex 或其他支持 MCP 的客户端作为上层编排者，也可以通过同一组工具调度一个独立的编码执行引擎。

Related MCP server: claudecode-mcp

解决的问题

一次性调用一个编码工具很容易；难的是让一项复杂任务可靠地走到验收。

一项任务如何流转

你提出目标与约束
        │
        ▼
Claude / Codex / 其他 MCP 客户端  澄清需求、拆解任务、决定审批、审查结果
        │ stdio MCP（兼容入口）
        ▼
Bridge Adapter  自动连接或拉起共享 Core，不持有任务状态
        │ 本地 Streamable HTTP MCP
        ▼
Bridge Core  唯一持有任务、线程、Runtime、审批与恢复状态
        │
        ▼
Engine Adapter  归一化不同执行引擎的协议与能力
        ├─ Codex App Server（原生 WebSocket JSON-RPC，可见 TUI）
        └─ Bridge Engine Host（WebSocket JSON-RPC 边车）
             ├─ Claude Agent SDK
             └─ ACP stdio → Kimi / 其他支持 ACP 的 Vibe Coding CLI

编排者不需要理解每个执行引擎的私有协议。它只在 task_open 时选择 engine，后续仍然使用 task_send、approval_decide、task_status、task_diff 等相同工具。

一次任务通常只有下面几步：

1. 编排者用 task_open 打开项目任务，传入稳定的 orchestrator.kind + orchestrator.sessionId，并用可选的 engine 选择 codex、claude 或已注册的 ACP 引擎（默认 codex）。同一编排会话始终复用该 ID，Bridge 会把它永久绑定到一个 Task 和执行线程；另一个 Claude/Codex/Cursor 会话不能静默接入。相同项目里的独立工作或执行引擎切换使用新的编排会话 ID 和 mode: "new"。

2. 编排者用 task_send 发送补充要求。完整 Task 标题、requirements 和验收条件只在线程创建或恢复时注入；普通 turn 只携带本轮增量 instruction 和检查策略。Bridge 会保持等待直到审批、完成、失败或中断。Codex 引擎还会确认同一线程的可见 TUI；无可见 TUI 的 Claude/ACP 引擎由 Engine Host 无窗口执行。客户端支持 MCP progress 时，等待期间 Bridge 会发送轻量进度心跳；即使 MCP 调用被取消，最终注意力事件也会先持久化，重连后由 task_open、task_send 或 task_status 重放。

3. 执行引擎需要授权时，task_send 会直接返回审批注意力事件；编排者通过 approval_decide 作出决定，并继续等待同一 turn 的下一个注意力事件。

4. 执行引擎完成一轮后，编排者用 task_diff 审查真实改动；不满足验收条件就继续发送下一轮要求。task_status 和 task_events 只用于诊断与审计，不承担正常通知职责。

5. 长任务接近上下文限制时，如果当前引擎支持上下文压缩，编排者可以调用 task_compact；目前该能力仅由 Codex 引擎提供。

核心价值

持续执行，而不是一次转发

orchestrator.kind + orchestrator.sessionId、taskId 与 codexThreadId 形成一一绑定，并持久化在 SQLite。这里的 sessionId 优先使用 Claude、Codex 或 Cursor 自己提供的稳定对话身份；如果客户端没有暴露该值，就在一次对话第一次 task_open 时生成一个，并在该对话内始终复用。临时 stdio/HTTP MCP transport session 会在重连时变化，Bridge 明确不拿它做任务身份。当该 Task 仍是项目当前活跃会话时，同一编排会话再次 task_open 即使标题或需求文本变化，也只会返回原 Task 和 Thread。若另一个会话已用 mode:new 显式换代，旧会话的绑定仍保留，但必须用返回的原 taskId 调用 task_recover 才会显式切回。不同编排会话若碰到已经绑定的活跃 Task 会在 Runtime/TUI 副作用前拒绝；只有新的编排会话显式传入 mode: "new" 才创建隔离线程。旧客户端无法提供稳定编排身份时，仍可用 expectedTaskId 精确复用。

一个 MCP，多个编排者和执行引擎

编排者与执行引擎是两个独立维度。例如：

Claude Code ─┐                         ┌→ Codex App Server
Codex       ─┼→ Codex Bridge MCP ─────┼→ Claude Agent SDK
其他 MCP 客户端 ┘                      └→ Kimi / 其他 ACP CLI

上游 Claude、Codex 或其他 MCP 客户端是任务编排者：它调用 task_open、task_send、task_status 和 task_diff；Bridge 根据 engine 启动或复用一个独立的执行 Runtime 完成实际工作。即使选择与编排者同类的引擎，也不是让同一个会话递归调用自己，因此仍然保留清晰的任务边界、审批链、恢复状态和 diff 审阅链。

审批可控，责任清晰

Bridge 只保存和转发审批请求，不替任务编排者或用户作决定。命令执行、文件修改等需要授权的操作，都要经过明确的 approve 或 deny。审批、完成、失败和中断都会保存为带单调 revision 的 turn 注意力状态；编排者完成对应动作后才写入 ACK。未确认事件会在调用取消或客户端重连后重放，避免只写入后台日志却没有交付给编排者。

中断可恢复，而不是静默重跑

Bridge 会记录 Runtime、线程、turn 和队列状态。Core 重启后通过所选引擎的线程状态接口，将本地活跃 turn 与执行引擎实际状态对账；无法确认已完成的工作会被标记为中断，避免把可能已经生效的修改自动再执行一次。旧 Runtime 连接上的待审批会标记为 orphaned，不会被自动批准、自动拒绝或错误地发送到替代连接。

一个 Core，而不是每个客户端一套运行时

Claude、Codex 或其他 MCP 客户端都连接到同一个本地 Bridge Core。MCP 客户端连接只是临时的协议会话；SQLite、Runtime WebSocket、任务队列和审批请求由 Core 长期持有。关闭或重连一个 MCP 客户端不会触发全库恢复，也不会为同一 Runtime 再创建一条执行引擎连接。

结果可审阅，而不是相信“已完成”

执行引擎的完成事件只是提示编排者进入审查。Bridge 提供工作区 diff、变更文件和可选 patch，让验收基于真实代码，而不是自然语言声明。

上下文更干净

状态、事件和 diff 默认返回可用于继续决策的短摘要：

• 审批请求默认只给出可决策信息；需要原文时再请求完整 payload；

• 事件默认按页返回，并提供游标继续读取；

• diff 默认给出短统计与分页文件列表；只有行级审阅时才请求完整 patch。

这让编排者与执行引擎把上下文留给任务本身，而不是重复的日志和历史数据。

统一调度 Vibe Coding 执行引擎（实验性）

Bridge 的任务/审批/恢复状态机是引擎无关的。除默认的 Codex App Server 外，同一套 MCP 工具可以驱动其他执行引擎——task_open 传入可选的 engine 字段即可（默认 codex）：

例如，选择已注册的 Kimi 引擎时，task_open 的关键参数如下；后续工具调用不需要再区分引擎协议：

{
  "projectRoot": "C:\\absolute\\path\\to\\project",
  "title": "实现并验证登录功能",
  "requirements": ["保持现有 API 兼容"],
  "mode": "new",
  "engine": "kimi"
}

ACP 引擎通过环境变量注册（分号分隔多个，命令按空白切分）：

$env:CODEX_BRIDGE_ACP_ENGINES = "kimi=kimi acp;gemini=gemini --experimental-acp"

说明：

• 只有实现 ACP 的 CLI/Agent 才能通过该入口接入；配置一个普通、非 ACP 命令不会自动获得 Bridge 能力；

• 配置格式为 id=command arg1 arg2;id2=command2 arg1，当前按空白切分参数，不解析 shell 引号；codex 与 claude 是保留的内置 id；

• 非 Codex 引擎由 Runtime Host Manager 启动一个 node engineHostMain.js 边车进程（与 codex app-server 走完全相同的端口分配、健康检查、DEAD 重建与恢复流程），因此需要先 npm run build；

• 一个 projectRoot 每个引擎各有一个 Runtime Host；项目的活跃会话仍然全局唯一，跨引擎切换需 mode: "new"；

• 无可见 TUI 的引擎自动无窗口执行，不受 CODEX_BRIDGE_CODEX_TUI_MODE 影响；

• Claude 引擎复用本机已登录的 Claude 凭据（Agent SDK 自带运行时，不依赖已安装的 claude CLI）；Kimi 引擎要求已完成 kimi login；

• Task 和 Runtime 会持久化其 engine，task_status 与 task_list 也会返回该字段。为兼容既有 MCP schema，响应中的 codexThreadId 当前仍作为通用的执行线程/会话 ID 使用。

产品边界

Codex Bridge MCP 的职责是可靠地连接任务编排者与编码执行引擎，不替代任何一方：

• 不是新的模型：不会替任务编排者规划，也不会替所选执行引擎编写实现；

• 不是云端代理：Bridge 本身运行在本机，不增加额外的云端中转；

• 不会自动批准操作：审批权始终属于任务编排者和用户；

• 不会把任意 CLI 自动变成执行引擎：除内置 Codex 和 Claude 外，CLI 必须提供 Bridge 当前支持的 ACP 接口；

• 不会用 TUI 传递任务：正常任务通过执行引擎协议进入线程。可见 TUI 仅由 Codex 引擎提供，用于观察或人工交互。

当前 Runtime Host 与可见 Codex TUI 的启动流程主要面向 Windows + PowerShell 验证。

快速开始

前置条件

• Windows 与 PowerShell；

• Node.js >= 20.11.0；

• 支持 stdio MCP 的客户端，例如 Claude Code 或 Codex；也可以直接连接 Streamable HTTP MCP。

• 至少准备一个执行引擎：支持 codex app-server 且已认证的 Codex CLI、本机已认证的 Claude 凭据，或一个已安装并登录且支持 ACP 的 Vibe Coding CLI。

安装与构建

git clone https://github.com/luojiateng/codex-bridge-mcp.git
cd codex-bridge-mcp
npm install
npm run build

构建完成后，dist/index.js 是稳定的 stdio MCP 入口。它会自动连接或拉起一个只监听 127.0.0.1 的共享 Bridge Core，不需要另开终端管理 Core。运行脚本生成配置片段：

.\scripts\install-mcp.ps1

Codex 的配置形态如下：

[mcp_servers.codex_bridge]
command = "node"
args = ["C:\\absolute\\path\\codex-bridge-mcp\\dist\\index.js"]
cwd = "C:\\absolute\\path\\codex-bridge-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 600

Claude Code 使用同一个 node dist/index.js stdio 命令即可。多个 MCP 客户端只会创建各自的轻量 Adapter；所有 Adapter 都连接同一个 Core，因此客户端退出不会关闭正在执行的 turn，也不会重新执行全库恢复。

每次 npm run build 都会生成新的 Bridge build ID。stdio Adapter 发现端口上仍是旧 build 的 Core 时会明确报告 PID 和版本不兼容，不会静默复用旧代码或自动终止正在运行的任务；确认没有活跃任务后再重启该 Core。进度心跳默认每 15 秒发送一次，可用 CODEX_BRIDGE_ATTENTION_HEARTBEAT_MS 调整。

对 Codex 引擎，可见 TUI 默认采用 CODEX_BRIDGE_CODEX_TUI_AUTO_RELAUNCH=active-turn：正在执行或等待审批时，窗口意外退出会按 0s / 2s / 5s 在原会话上最多重拉 3 次；空闲时不主动弹窗，由下一次 task_send 惰性恢复。连续失败会打开 60 秒熔断，带原稳定编排身份的 task_open(mode=reuse)（旧客户端则加 expectedTaskId）可执行一次明确的人工重试并重置计数。也可以设为 active-session（活跃项目会话即主动恢复）或 off（完全关闭自动恢复，窗口退出后必须显式恢复已知 Task）。task_status.codexTui 会返回当前 PID、状态、重试次数、下次重试时间和最近错误。

需要调试或让支持 Streamable HTTP 的客户端直接连接时，可以显式启动 Core：

npm start

默认地址是 http://127.0.0.1:43110/mcp，本地令牌保存在 data/mcp-token。这是可选的直连方式；普通 stdio 安装不需要手工读取或配置令牌。

Core 生命周期与升级

Bridge Core 默认采用按需启动，不是 Windows 开机自启服务：第一次由 MCP 客户端建立连接时，stdio Adapter 会在本机没有可用 Core 的情况下拉起共享 Bridge Core；任务需要执行环境时，再由 Core 的 Runtime Host Manager 为对应项目和引擎启动 codex app-server 或 Bridge Engine Host。关闭单个客户端不会停止 Core，也不会中断已经提交的 turn。日常使用不需要每次手工执行 npm start；该命令主要用于前台诊断。

每次构建都会生成新的 Bridge build ID。Adapter 发现 43110 上运行的是旧构建时，会先通过本地 Bearer Token 请求安全升级：Core 检查运行中的 turn、队列命令、审批、Project Session 创建/恢复和 Runtime 迁移状态；全部为空时，旧 Core 自动进入 DRAINING、关闭连接并退出，Adapter 随即拉起新 Core，再完成本次 MCP 连接。这个过程不会重建 Task 或执行线程，也不需要手工查找和停止 PID。

如果仍有活跃操作，Core 会返回具体 blocker，并保持旧 Core 继续运行，不会为了升级中断任务；只要 Bridge protocol 兼容，本次 /mcp 仍会连接旧 Core，让当前任务继续使用。操作结束后再次执行 /mcp 即可自动切换到新构建。健康信息仍可用于诊断：

$health = Invoke-RestMethod http://127.0.0.1:43110/healthz
$health

若安全升级被阻止，错误中会列出 activeTurns、runningCommands、queuedCommands、activeApprovals、transitionalProjectSessions 或 transitionalRuntimes 中的非零项。若需要查看启动阶段的直接错误，再在项目目录运行 npm start 进行前台诊断。

不要在任务执行中或存在待审批操作时直接停止 Core。Bridge 会持久化可恢复状态，但不会假装未确认的外部操作一定没有发生。

常用能力

完整工具 schema 请见 src/mcp/schemas.ts。产品约束、阶段计划和验收矩阵请见 docs/phase-development.md。

本地数据与隐私

Bridge 在本机保存任务、线程、语义事件、审批、队列和上下文快照，以实现恢复与审阅。默认数据目录位于 Bridge 安装目录下的 data/，其中可能包含任务内容、命令、审批原因和 diff 信息；data/mcp-token 是本地 HTTP 访问令牌。

这些本地运行数据、日志和 .env 已被项目 .gitignore 排除。请像管理本地开发日志一样管理它们，并不要把真实凭据写入任务说明、环境示例或仓库文件。

执行引擎的逐 token / delta 输出不会写入 SQLite 事件表；Bridge 只持久化审批、turn 完成/中断、上下文阈值和错误等可恢复的语义事实，从源头减少编排者读取噪音历史时的 Token 消耗。

开发验证

npm run typecheck
npm run build
npm run check:forbidden
npm run smoke:protocol
npm run smoke:context
npm run smoke:queue
npm run smoke:recovery
npm run smoke:runtime-interruption
npm run smoke:project-session
npm run smoke:attention
npm run smoke:hosted-engine
npm run smoke:diff
npm run smoke:mcp

真实端到端验证按执行引擎分别运行：

npm run e2e:real                         # Codex App Server
npx tsx scripts/e2e-claude-engine.ts    # Claude Agent SDK
npx tsx scripts/probe-acp-kimi.ts       # Kimi ACP

这些命令会启动或复用真实的本地执行 Runtime，并可能消耗对应模型额度，因此只应在已完成认证且允许启动相关引擎的环境中执行。

Codex Bridge MCP 不只是让 Claude 或 Codex 调用一次编码工具，而是让编排者通过一套 MCP 在 Codex、Claude Code 与支持 ACP 的 Vibe Coding CLI 之间选择执行引擎，并可靠地把一项开发任务从目标推进到验收。