codex-mcp-bridge

英文版

用于 Claude Desktop 的 MCP server，通过共享的 Codex app-server 将提示词直接发送到现有 Codex 会话。支持 macOS、Windows 和 Linux。

不是使用 codex exec（每次创建新会话）。Bridge 通过 JSON-RPC 与 Codex 的真实 app-server 通信，因此会话会保留完整历史、cwd、模型和 rollout 文件。

架构

Claude Desktop ──stdio──> codex-mcp-bridge ──WebSocket──> codex app-server (ws://127.0.0.1:8791)
                                                                  │
Codex TUI  ──codex --remote ws://127.0.0.1:8791───────────────────┘   (cùng app-server, cùng thread live)

• app-server 是按端口单例运行的。Bridge 探测 http://127.0.0.1:8791/readyz；如果尚未存活，则自动以 detached 方式 spawn（codex app-server --listen ws://127.0.0.1:8791），且该 app-server 在 Bridge 退出后仍会独立继续运行。

• 所有指向同一 URL 的客户端都会使用同一个 app-server → 使用 threadId 调用 thread/resume 会重新加入正在运行的会话，而不是打开新会话。

• Bridge 只维持一个 WebSocket，initialize 只调用一次，并按 threadId 路由通知，因此多个并发会话互不干扰。

Related MCP server: webgpt MCP

工具

send_to_codex_thread 还接受 timeoutSec（默认 240）、cwd、model、effort 和 openInApp（macOS — 发送前在应用中打开会话以实时查看）。超时不会取消 turn —— Bridge 会返回已收集到的内容及 turnId；可以使用 read_codex_thread 继续读取，或使用 interrupt_codex_turn 停止。

安装到 Claude Desktop

npm install
node scripts/install-claude-desktop.mjs

脚本会自动识别 platform，在 config 文件不存在时创建，备份旧版本（*.bak-<ngày>-codexbridge），并保留所有现有 key：

macOS 上的结果：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "/Users/<user>/.local/node/v24.18.0/bin/node",
      "args": ["/Users/<user>/code/codex-mcp-bridge/src/index.mjs"],
      "env": {
        "CODEX_BIN": "/Users/<user>/.local/bin/codex",
        "CODEX_APP_SERVER_URL": "ws://127.0.0.1:8791"
      }
    }
  }
}

安装后重启 Claude Desktop。

解析 codex binary： Claude Desktop（以及 launchd）启动 MCP server 时使用被裁剪的 PATH，因此 codex 通常不在 PATH 中。Bridge 按以下顺序查找 —— CODEX_BIN → 该平台常见的安装位置 → PATH：

在 macOS/Linux 上，codex 是带有 shebang #!/usr/bin/env node 的 Node 脚本，因此 Bridge 还会为子进程重新注入 PATH（当前 node 目录 + /opt/homebrew/bin + /usr/local/bin + 系统目录）——如果缺少这一步，spawn app-server 会在 shebang 处立即失败。

macOS

使用 launchd 将 app-server 作为后台服务运行

node scripts/install-launch-agent.mjs

创建 ~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist（RunAtLoad + 崩溃时 KeepAlive，ThrottleInterval 10 秒），然后运行 launchctl bootstrap gui/$UID。app-server 在登录时就已运行，因此 Bridge 无需自行 spawn，且会话始终处于 live 状态。

launchctl print gui/$UID/com.codex-mcp-bridge.app-server | head -20   # trạng thái
node scripts/install-launch-agent.mjs --uninstall                     # gỡ

日志：~/Library/Logs/codex-mcp-bridge/app-server.{out,err}.log。

在 Codex 桌面应用中直接查看会话

macOS 上的 Codex 桌面应用是 /Applications/ChatGPT.app，并注册了 codex:// scheme。Bridge 使用 codex://threads/<threadId> 打开正确的会话：

open_codex_thread { threadId: "01a0…", background: true }
send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }

这是让任务发起人实时看到 Codex 正在做什么的方式，而不是等任务完成后再去阅读 rollout ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl。

macOS 上的限制

• Codex 桌面应用会通过 stdio 自行运行一个独立的 app-server（ChatGPT.app/Contents/Resources/codex … app-server），并且不接受外部 endpoint。在应用中打开的会话仍然可以通过 Bridge 发送，但机制是从 rollout .jsonl 进行 resume，而不是 live attach。不要向桌面应用中正在运行 turn 的会话发送消息——两个 app-server 同时写入同一个 rollout 可能会损坏历史记录。先用 list_codex_threads 检查 status，仅在 idle/notLoaded 时才发送。

• 位于双系统机器 NTFS 分区上的仓库（/Volumes/...）在 macOS 上只能读取——macOS 以只读方式挂载 NTFS。请在 APFS 卷上保留单独的 checkout（例如 ~/code/codex-mcp-bridge）以运行和修改。

• codex app-server daemon start 使用 unix:// transport，control socket 为 ~/.codex/app-server-control/app-server-control.sock。Bridge 不使用这条路径（其帧协议不同于 WebSocket，且没有公开 API）——始终通过 ws:// 通信。

环境变量

关于 approval： 如果 approval_policy 不是 never，Codex 会请求批准命令/补丁。由于没有人在 Claude Desktop 前点击按钮，Bridge 会根据 CODEX_BRIDGE_APPROVAL 自动回复，并记录到 stderr。默认的 approve 与 ~/.codex/config.toml 中的 approval_policy = "never" + sandbox_mode = "danger-full-access" 配置一致；如果收紧了沙箱，则应考虑改为 deny。

与交互式 Codex 会话共享 app-server

打开 TUI 并指向同一个 endpoint，这样 TUI 中的会话和 Bridge 中的会话就是同一个：

codex --remote ws://127.0.0.1:8791

手动运行 app-server（不依赖 Bridge 的 autostart）：

codex app-server --listen ws://127.0.0.1:8791

测试

npm run check

快速检查：启动 Bridge，必要时自动启动 app-server，列出会话。

npm run smoke

Smoke test 创建一个新会话，连续发送 2 个 turn，并检查 Codex 是否记得上一个 turn 中的 codeword —— 也就是说会话确实是连续的，而不是每次新建会话。

在 Claude 中检查环境：调用工具 codex_bridge_status。