codex-bridge

codex-bridge

为 Claude Code 提供 Codex 任务，即使崩溃、窗口关闭或重启也能继续，并内置 Codex 图像生成功能。 一个无需依赖的 MCP 服务，优先支持 Windows：每次调用都会将任务保存到磁盘，因此你可以关闭 Claude、断电或终止进程，之后再用 codex_resume 继续工作。

分工：Claude Code 负责实现。Codex 负责规划和生成图像。

_{此录制中的服务端调用都是真实的（Codex 的 effort: low，已剪去空闲时间）；claude mcp add 命令是脚本预先写好的。原始录制文件为 docs/demo.cast；使用 asciinema play docs/demo.cast 播放。}

快速开始

你需要 Node.js 20 或更高版本，并安装且登录 Codex CLI。

claude mcp add codex-bridge -- npx -y @xallindrome-labs/codex-bridge

重启 Claude Code，然后提出类似 “在后台让 Codex 制定一份添加速率限制的计划，然后继续工作” 的请求。Claude 会调用 codex_plan 并设置 background: true，之后再获取答复。

其他 MCP 客户端：运行 npx -y @xallindrome-labs/codex-bridge，将其作为 stdio 服务。

平台说明： 本项目在 Windows 11 上开发和测试，并已运行真实的 Codex 任务。CI 会在 Linux、macOS 和 Windows（Node 20 和 22）上检查服务能否启动、使用 MCP 通信，以及从 npm tarball 安装后能否正常工作；还会在 Linux 和 macOS 上使用假的 codex 检查任务能否运行、完成，并在服务被终止后继续。CI 环境没有真实的 Codex CLI，因此尚未在 macOS 和 Linux 上测试真实的 Codex 任务。欢迎提交报告和修复。

工具	功能	沙盒	默认模型 / 努力级别
codex_plan	Codex 编写实现计划、设计评审和第二意见。它会检查 cwd 中的项目。	read-only（始终如此）	你的 Codex 配置默认值
codex_image	Codex 生成或编辑图像。每张图像生成后，桥接程序都会立即将其复制到 output_dir。	read-only（始终如此）	gpt-6-luna / high
codex_result	获取任务结果或进度（wait_seconds 最长为 240），或列出最近的任务。
codex_resume	从中断、超时或失败的位置继续任务。
codex_cancel	停止正在运行的任务。

codex_plan 和 codex_image 接受：

• effort：low、medium、high、xhigh、max 或 ultra（Luna 最高支持 max）。
• model：为此次调用覆盖默认模型。
• background: true：立即返回 job_id，让 Claude 可以继续工作。
• session_id：继续之前的 Codex 对话线程，例如“把图标调暗一些”。

codex_image 还接受 count，用于指定所需图像数量。批量生成时请设置此项：它会启用 k/count 进度，并在恢复任务时只请求缺少的图像。

对比

OpenAI 的 codex-plugin-cc 是从 Claude Code 使用 Codex 的官方方式，在它擅长的方面表现不错：用于审查和恢复的斜杠命令。codex-bridge 则是一个 MCP 服务，侧重点不同：任务不会丢失，以及图像。

该插件的问题跟踪中有多个未解决的问题，都与任务丢失有关；codex-bridge 的设计就是为了避免这些问题。以下结论来自对设计的分析，而非直接对比测试：

codex-plugin-cc 中报告的问题	codex-bridge 的处理方式
工作进程退出后，后台任务永远显示“running”（#704，#699）	状态根据磁盘上的文件、心跳和进程检查来确定。运行器退出后会显示为 interrupted，绝不会显示为“running”；codex_resume 会继续执行该任务。
Windows 上的 cancel 会静默失败（#708）	取消操作会写入一个标记文件；拥有 Codex 进程的运行器会在约 2 秒内发现该文件，并直接调用 taskkill.exe 停止整个进程树，中间不经过 shell。
Windows 上的代理进程泄漏（#718，#782）	不存在共享代理。每次尝试都由一个运行器进程执行，并在 Codex 退出时随之退出。
一个会话结束导致其他会话的任务被终止（#671）	运行器在 Claude 进程树之外启动（Windows 上通过 WMI），因此关闭会话不会终止它们。

该插件具备而本工具没有的功能：斜杠命令，以及审查门控和恢复工作流。另外，本工具较新，用户也少得多。如果该插件适合你，请继续使用。如果你遇到过任务丢失，或希望 Codex 生成的图像在崩溃后仍能保留，可以试试本工具。

重启后任务仍会保留

每次调用都是一个任务，保存在 ~/.codex-bridge/jobs/<job_id>/ 下，包括并非在后台运行的调用。

• **Claude 关闭或崩溃：**任务会继续运行。server.mjs 通过 WMI（Win32_Process.Create）启动 runner.mjs，因此任务不属于 Claude Code 的进程树。关闭 Claude 不会终止任务，之后的任何 Claude 会话都可以通过 codex_result 获取结果。
• 任务本身退出（重启、断电、Codex 崩溃或进程被终止）：任务会标记为 interrupted。下一个 Claude 会话启动时会收到相关通知。codex_resume 会继续执行：
  1. 先取出中断前刚生成的所有图像。
  2. 继续使用同一个 Codex 线程：“已有 N 个完成，只生成剩下的部分。”
  3. 如果尚未启动 Codex 线程，则重新运行原始请求。

如何收集图像

Codex 不会写入图像文件。它的图像工具会将生成的每张图像存储在 ~/.codex/generated_images/<thread>/ 中。运行器每 2 秒检查一次该文件夹，并将新图像按生成顺序复制到 output_dir，命名为 <filename>.png、<filename>-2.png 等。任务文件夹中的 copied.json 会记录已复制的文件，因此多次尝试之间不会重复复制图像。

这带来三项好处：

• 图像任务在只读沙箱中运行。
• 崩溃最多只会导致正在生成的一张图像丢失。
• 恢复时能准确统计已完成的数量。

这也避免了一个实际问题：Luna 获准自行保存文件时，会通过几十条 shell 命令将每张图像重新输入为 base64。这种做法很慢，而且保存后的文件与原始文件不再一致。

• **Codex 卡住：**如果 10 分钟没有输出，运行器就会停止本次运行。任务会标记为 timed_out，之后可以恢复。

每次尝试都会保留各自的 prompt.txt、events.jsonl（Codex 事件流）、stderr.txt、心跳和 result.json。已完成的任务会在 14 天后删除。

工作原理

每次尝试都会通过 stdin 传入提示词，运行 codex exec --json（或 codex exec resume <thread>）。不会调用 shell。

每次调用都以只读方式运行。新会话会传入 -s read-only 和 -c sandbox_mode="read-only"；恢复的会话会传入 -c sandbox_mode="read-only"（codex exec resume 不接受 -s）。你的 Codex 配置可能默认使用 danger-full-access，但该默认设置绝不会应用于桥接调用。plan 冒烟测试会检查从恢复的会话中尝试写入是否会失败。

文件	作用
server.mjs	MCP 服务。创建任务、启动运行器、根据磁盘上的文件确定任务状态，并处理恢复和取消。
runner.mjs	运行一次尝试：启动 Codex、记录心跳、监控卡顿或取消、收集图像并写入 result.json。
lib.mjs	共享辅助函数：查找 Codex 二进制文件、构建参数、解析事件、处理图像。

安装选项

# for all your projects
claude mcp add -s user codex-bridge -- npx -y @xallindrome-labs/codex-bridge

# or from a local checkout
claude mcp add codex-bridge -- node /path/to/codex-bridge/server.mjs

使用 claude mcp remove codex-bridge 将其移除（如果安装时使用了 -s user，请添加该参数）。

配置（环境变量）

变量	默认值
CODEX_BIN	自动检测。优先选择与 codex-code-mode-host.exe 位于同一目录的 codex.exe；目前该目录为 ~/.codex/plugins/.plugin-appserver/codex.exe。
CODEX_BRIDGE_HOME	~/.codex-bridge
CODEX_BRIDGE_IDLE_TIMEOUT_MS	600000（Codex 10 分钟没有输出后停止运行）
CODEX_BRIDGE_PLAN_MODEL / CODEX_BRIDGE_PLAN_EFFORT	Codex 配置中的默认值
CODEX_BRIDGE_IMAGE_MODEL / CODEX_BRIDGE_IMAGE_EFFORT	gpt-6-luna / high

测试

node smoke-test.mjs <scratch-dir> [plan|image|jobs|durable|all]

冒烟测试会像 MCP 客户端一样通过 stdio 驱动服务，并且需要已登录的 Codex CLI；测试会消耗少量 Codex 配额。durable 部分会使用 taskkill，因此目前仅支持 Windows。

• plan：运行一项计划，然后尝试从恢复的会话中写入，这一步必须失败。
• image：生成一张图像。
• jobs：测试后台任务、取消和 effort 检查。
• durable：
  1. 在任务运行时终止服务，然后检查新启动的服务是否会收集结果。
  2. 在图像批次运行到一半时强制终止，然后检查新启动的服务是否会将其报告为已中断，以及 codex_resume 是否能完成该任务。

速度

每次调用都有约 4–5 秒的固定开销，更改设置几乎不会影响耗时。其余时间用于 Codex 思考和生成，可能需要几秒到几分钟。若想减少等待时间，请使用 background: true，针对简单问题使用较低的 effort，并在 context 中提供相关代码，让 Codex 少读取一些项目内容。

说明

• 本工具使用 Codex 自带的登录状态和配额，无需单独的 API 密钥。Claude 关闭后仍在运行的任务会持续消耗配额，直到完成。
• 桥接调用以无头方式运行，因此不会显示在 Codex Desktop 侧边栏的对话中。
• 请勿在提示词中发送机密信息。提示词会发送给 OpenAI。

问题反馈与贡献

欢迎在问题跟踪器中提交错误报告和想法。也欢迎提交拉取请求，但审核速度较慢；请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明，私下报告安全问题。

许可证

MIT

---

由 Xallindrome 构建：我们为小型企业构建自动化和 AI 工作流。如果你希望为自己的企业构建类似方案，预约诊断。