codex-mcp-bridge

在 ChatGPT 与官方本地 Codex MCP 服务器之间提供一个小型策略层。

ChatGPT
  -> OpenAI Secure MCP Tunnel
  -> codex-mcp-bridge (loopback HTTP)
  -> codex mcp-server (stdio)
  -> one explicitly allowed repository

官方 Codex MCP 服务器已经提供 codex 和 codex-reply。该桥接层刻意只增加 ChatGPT 日常更安全使用所需的控制项：

• bridge_status：检查当前生效的策略。

• codex_read：强制使用只读 Codex 会话。

• codex_run：启动受策略限制的读取或写入会话。

• codex_reply：仅继续通过此桥接层创建的线程。

• codex_job_status：获取长时间运行任务的结果。

安全默认值

• 绑定到 127.0.0.1。

• 除非显式配置根目录，否则只允许一个当前工作目录。

• 使用 read-only Codex 沙盒。

• 使用 on-request 审批策略。

• 决不暴露 danger-full-access。

• 除非桥接层所有者启动写入配置，否则阻止工作区写入。

• 拒绝配置的真实路径根目录之外的路径。

• 拒绝包含常见机密文件名的仓库，除非所有者显式禁用预检查。

• 限制提示长度和并发 Codex 任务数。

• 抑制上游 Codex stderr，除非启用本地调试日志。

这些控制是策略层，不是 OS 级隔离。若需要强隔离，请使用暂存副本、容器、虚拟机或独立的 OS 用户。

Related MCP server: mcp-governance-proxy

先决条件

• Node.js 20 或更高版本；推荐 Node.js 22。

• 已安装并完成认证的 Codex CLI，且提供 codex mcp-server。

• ChatGPT 访问需要 tunnel-client 和 OpenAI Secure MCP Tunnel。

官方参考：

• 以 MCP 服务器方式运行 Codex

• Secure MCP Tunnel

安装

npm ci
npm run check

本地冒烟测试

本地模式不会创建公共端点：

npm run bridge:local -- --root /absolute/path/to/repository

MCP 端点是 http://127.0.0.1:8876/mcp，健康检查端点是 http://127.0.0.1:8876/healthz。

Secure MCP Tunnel

在 OpenAI Platform 中创建隧道，然后在本仓库之外提供其运行时凭据：

export CONTROL_PLANE_API_KEY="<runtime-key>"
export CONTROL_PLANE_TUNNEL_ID="tunnel_..."

npm run bridge:secure -- --root /absolute/path/to/repository

启动器会构建桥接层，在环回地址上启动它，初始化 tunnel 配置文件，运行 tunnel-client doctor，并保持 tunnel 客户端运行。

对于有意的写入会话：

npm run bridge:secure -- --root /absolute/path/to/repository --write

不需要写入配置时，不要让它一直运行。

macOS Keychain

security add-generic-password -a "$USER" -s "codex-mcp-bridge:control-plane-api-key" -w "<runtime-key>" -U
security add-generic-password -a "$USER" -s "codex-mcp-bridge:control-plane-tunnel-id" -w "tunnel_..." -U

CODEX_MCP_BRIDGE_ROOT=/absolute/path/to/repository npm run bridge:secure:keychain

仅在有意进行写入会话时使用 bridge:secure:write:keychain。

配置

为兼容上游，暂时接受旧的 CODEX_GPT_BRIDGE_* 变量前缀。

ChatGPT 配置

参见 docs/chatgpt-setup.md。

上游

本仓库在 MIT License 下衍生自 DeepCogNeural/codex-gpt-bridge。本 fork 的范围参见 UPSTREAM.md。