ChatGPT Codex Bridge

简体中文 | 安全 | 贡献指南

一个本地优先的 MCP 桥接器，让 ChatGPT 可以检查已注册的 Codex 项目、读取 Codex 会话历史，并将已确认的任务派发给本地 Codex CLI。

[!IMPORTANT] 这是一个独立的社区项目。它不是 OpenAI 的官方产品，与 OpenAI 无关联，也未获得 OpenAI 的认可。ChatGPT、Codex 和 OpenAI 均为其各自所有者的商标。

功能

• 发现已在 Codex Desktop 中注册的项目，无需授予对整个主目录的访问权限。

• 在 Codex 只读沙箱中运行分析和规划。

• 在工作区写入前要求提供短期、一次性使用的确认令牌。

• 以游标分页和脱敏方式列出并读取可见的 Codex 会话。

• 构建有界项目历史上下文，而不会将数 GB 的历史记录加载到内存中。

• 通过本地 Codex 应用服务器协议创建和继续持久化 Codex Desktop 会话。

• 将 ChatGPT 提供的上下文作为不可信参考文本交给 Codex，并带有秘密检测。

• 使用后台任务，使长时间运行的 Codex 任务不会占用 MCP 隧道请求。

该桥接器不暴露任意 shell 工具，也不监听公共端口。远程访问由官方 OpenAI Secure MCP Tunnel 客户端 提供。

架构

flowchart LR
    A[ChatGPT] -->|MCP connector| B[OpenAI Secure MCP Tunnel]
    B -->|outbound tunnel| C[tunnel-client on your machine]
    C -->|stdio MCP| D[ChatGPT Codex Bridge]
    D -->|sandboxed commands| E[Codex CLI]
    D -->|read-only indexes| F[Codex projects and sessions]
    D -. optional local IPC .-> G[Codex Desktop sidebar refresh]

可选的侧边栏刷新路径依赖于一个私有的、不受支持的 Codex Desktop 扩展，不包含在本仓库中。核心桥接器无需它即可工作；新建的持久化会话可能需要重启 Codex Desktop 后才会出现在侧边栏中。

环境要求

• 装有 Python 3.11+ 的 macOS 或 Linux

• 可用的 codex CLI 安装和登录

• 用于自动项目发现和会话历史功能的 Codex Desktop

• 用于文档所述 Tunnel 安装路径的 Homebrew

• 具有 Secure MCP Tunnels 访问权限的 OpenAI 组织

本项目目前已在 macOS 上测试。不支持 Windows，因为可选的桌面通知路径使用 Unix 套接字。

快速开始

git clone https://github.com/AaAndrew233/chatgpt-codex-bridge.git
cd chatgpt-codex-bridge
./scripts/bootstrap.sh

bootstrap.sh 会创建本地虚拟环境，安装经过审查的依赖锁文件，并生成不受跟踪的 config.json 和 .mcp.json 文件。它绝不会覆盖现有配置。

打开 config.json 并选择一种授权来源：

{
  "codex_command": "codex",
  "model": null,
  "codex_project_catalog": "~/.codex/.codex-global-state.json",
  "allowed_roots": []
}

• 将 model 保留为 null 以继承当前的 Codex 配置。

• 将 allowed_roots 留空，仅使用已在 Codex Desktop 中注册的项目。

• 仅在自动发现不可用时，才将狭窄的项目目录添加到 allowed_roots。

• 切勿授权 / 或您的主目录。桥接器会拒绝这两者。

运行本地检查：

./scripts/check_public_release.py
.venv/bin/python -m unittest discover -s tests -v

通过 Secure MCP Tunnel 连接

安装官方客户端：

brew install openai/tools/tunnel-client
tunnel-client --version
tunnel-client help quickstart

将运行时密钥存储在本仓库之外的文件中，并限制其权限：

chmod 600 /ABSOLUTE/PATH/TO/runtime-key

创建托管的后台运行时。替换所有占位值：

tunnel-client runtimes connect \
  --alias codex-bridge \
  --profile codex-bridge \
  --tunnel-id '<YOUR_TUNNEL_ID>' \
  --runtime-api-key 'file:/ABSOLUTE/PATH/TO/runtime-key' \
  --mcp-command '/ABSOLUTE/PATH/TO/chatgpt-codex-bridge/scripts/run_server.sh'

验证托管运行时正在运行、健康且就绪：

tunnel-client runtimes status codex-bridge --json

然后在 ChatGPT 连接器设置 中创建或刷新连接器。官方 Tunnel 入门指南是组织角色、隧道 ID、运行时密钥和当前命令的权威来源：openai/tunnel-client/docs/onboarding.md。

不要使用管理员密钥作为长期运行的运行时。不要提交运行时密钥、隧道 ID、生成的配置文件、config.json 或 .mcp.json。

在 ChatGPT 中进行首次测试

在启用连接器的情况下开始一个新的 ChatGPT 对话，并询问：

Call codex_status. Show only whether the bridge is healthy, the available tool names,
and the registered project names. Do not modify files.

然后测试一个只读任务：

Use codex_analyze on <PROJECT_PATH> to summarize the project structure and identify
the three highest-risk areas. Poll the job until it finishes and retrieve every output page.
Do not modify files.

对于写入操作，ChatGPT 必须首先调用 codex_prepare_apply，向您展示确切的计划，获得您的明确确认，然后才能使用返回的令牌调用 codex_apply。

MCP 工具

安全模型

信任边界刻意保持狭窄：

• 项目访问仅限于经过验证的 Codex 项目根目录或显式的狭窄根目录。

• 敏感目录（如 .ssh、.aws、.gnupg、.kube、.config 和 Library）在自动发现期间会被拒绝。

• Codex 子进程接收最小化环境，并以显式沙箱模式运行。

• 写入令牌会过期、一次性使用，并绑定到确切的项目和请求。

• 会话输出在离开机器前会过滤为仅用户可见消息并进行脱敏。

• 请求、输出、扫描、并发、保留和超时限制均有界。

• ChatGPT 上下文被视为不可信输入，不能覆盖本地策略。

在将桥接器暴露给团队之前，请阅读 docs/security-model.md。漏洞报告应遵循 SECURITY.md。

运行限制

默认限制记录在 config.example.json 中，并在启动时强制执行。重要默认值包括两个并发任务、30 分钟已完成任务保留期、120,000 字符请求上限、分页的 100,000 字符任务输出，以及项目历史的有界流式扫描。

scan_complete 表示配置的源扫描是否完成。context_complete 单独表示所有扫描文本是否都适合返回的上下文预算。扫描完成不等于无界导出。

开发

./scripts/bootstrap.sh
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q \
  bridge_core.py conversation_catalog.py desktop_assignment.py \
  desktop_sessions.py project_context.py server.py

有关贡献规则，请参阅 CONTRIBUTING.md；有关模块边界，请参阅 docs/architecture.md。

许可证

Apache License 2.0。请参阅 LICENSE。