Codex Bridge MCP

让 Claude 或 Codex 负责决策，让 Codex 在同一个任务中持续、可控地完成执行。

Codex Bridge MCP 是连接 任务编排者（Claude Code 或 Codex）与 Codex App Server 的本地 MCP。它不是另一个模型，也不是把一条提示词转发给 Codex 的脚本；它为一项开发任务保留稳定的执行线程、运行状态、审批记录和审阅闭环。

当需求需要多轮补充、代码修改需要审批、任务可能中断、结果还需要审查时，Claude 不必每次重新解释上下文，也不必把 Codex 的一句“完成”当作验收结果。

它为谁而做

适合已经同时使用 Claude 与 Codex，并希望把它们用在真实工程任务中的开发者和团队：

• Claude 擅长理解需求、拆解问题、作出判断和审查结果；

• Codex 擅长进入仓库、修改文件、执行命令和完成验证；

• 你需要的是一条不会在多轮协作中断掉的执行链。

Claude 是默认、最清晰的协作入口；如果你已经使用 Codex 作为上层编排者，也可以让 Codex 通过同一组 MCP 工具调度一个独立的 Codex Runtime。

Related MCP server: claudecode-mcp

解决的问题

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

一项任务如何流转

你提出目标与约束
        │
        ▼
Claude / Codex  澄清需求、拆解任务、决定审批、审查结果
        │ stdio MCP（兼容入口）
        ▼
Bridge Adapter  自动连接或拉起共享 Core，不持有任务状态
        │ 本地 Streamable HTTP MCP
        ▼
Bridge Core  唯一持有任务、线程、Runtime、TUI、审批与恢复状态
        │ WebSocket JSON-RPC
        ▼
Codex   在真实仓库中修改代码、执行命令、完成验证

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

1. Claude 用 task_open 打开项目任务，并传入 orchestrator: { kind: "claude", sessionId: "<Claude 对话的稳定 ID>" }。同一 Claude 对话始终复用该 ID，Bridge 会把它永久绑定到一个 Task 和 Codex Thread；另一个 Claude/Codex/Cursor 会话不能静默接入。相同项目里的独立工作使用新的编排会话 ID 和 mode: "new"。

2. Claude 用 task_send 发送补充要求。完整 Task 标题、requirements 和验收条件只在线程创建或恢复时作为 developer instructions 注入；普通 turn/start 只携带本轮增量 instruction 和检查策略，既保持任务边界，也避免每轮重复消耗 Token。Bridge 会先确认同一线程的可见 TUI 仍在运行，再启动 Codex turn，并保持等待直到审批、完成、失败或中断。如果窗口在空闲阶段退出，下一次 task_send 会先在原 Project Session、Runtime 和 Thread 上恢复 TUI，再调用 turn/start；恢复失败会阻止该 turn，不会静默转入无窗口后台执行。客户端支持 MCP progress 时，等待期间 Bridge 会发送轻量进度心跳；即使 MCP 调用被取消，最终注意力事件也会先持久化，重连后由 task_open、task_send 或 task_status 重放。只有显式配置 CODEX_BRIDGE_CODEX_TUI_MODE=off 才允许无窗口执行。

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

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

5. 长任务接近上下文限制时，Claude 可以调用 task_compact，在原线程中压缩上下文。

核心价值

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

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 精确复用。

Codex 也可以调度 Codex

Bridge 支持两种编排方式：

Claude Code → Codex Bridge MCP → Codex Runtime
Codex      → Codex Bridge MCP → 独立 Codex Runtime

在第二种方式中，上游 Codex 是任务编排者：它调用 task_open、task_send、task_status 和 task_diff，Bridge 则启动或复用一个独立的 Codex App Server Runtime 执行实际工作。它不是让同一个 Codex 会话递归调用自己，因此仍然保留清晰的任务边界、审批链、恢复状态和 diff 审阅链。

审批可控，责任清晰

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

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

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

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

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

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

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

上下文更干净

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

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

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

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

这让 Claude 与 Codex 把上下文留给任务本身，而不是重复的日志和历史数据。

产品边界

Codex Bridge MCP 的职责是可靠地协同 Claude 与 Codex，不替代任何一方：

• 不是新的模型：不会替任务编排者规划，也不会替 Codex 编写实现；

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

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

• 不会用 TUI 传递任务：正常任务通过 App Server 的 turn/start 进入 Codex。可见 TUI 仅用于观察或人工交互。

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

快速开始

前置条件

• Windows 与 PowerShell；

• Node.js >= 20.11.0；

• 已安装并完成认证的 Codex CLI，且支持 codex app-server；

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

安装与构建

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 命令即可。多个 Codex/Claude 客户端只会创建各自的轻量 Adapter；所有 Adapter 都连接同一个 Core，因此客户端退出不会关闭正在执行的 Codex turn，也不会重新执行全库恢复。

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

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

每次构建都会生成新的 Bridge build ID。Adapter 发现 43110 上运行的是旧构建时，会先通过本地 Bearer Token 请求安全升级：Core 检查运行中的 turn、队列命令、审批、Project Session 创建/恢复和 Runtime 迁移状态；全部为空时，旧 Core 自动进入 DRAINING、关闭连接并退出，Adapter 随即拉起新 Core，再完成本次 MCP 连接。这个过程不会重建 Task 或 Codex Thread，也不需要手工查找和停止 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 排除。请像管理本地开发日志一样管理它们，并不要把真实凭据写入任务说明、环境示例或仓库文件。

App Server 的逐 token / delta 输出不会写入 SQLite 事件表；Bridge 只持久化审批、turn 完成/中断、上下文阈值和错误等可恢复的语义事实，从源头减少 Claude 与 Codex 读取噪音历史时的 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:diff
npm run smoke:mcp

真实端到端验证使用 npm run e2e:real。它会启动或复用真实的 Codex App Server，因此应只在允许本机 Codex Runtime 运行的环境中执行。

Codex Bridge MCP 不只是让 Claude 或 Codex 调用一次 Codex，而是让编排者能可靠地把一项开发任务从目标推进到验收。