ChatGPT Codex Bridge

简体中文 | Security | Contributing

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

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

功能简介

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

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

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

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

• 支持对 Codex Desktop 的"最近"部分中单个无项目会话进行限时、经用户确认的访问。

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

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

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

• 使用后台任务，使长时间运行的 Codex 任务不会保持 MCP 隧道请求处于打开状态。

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

Related MCP server: ChatGPT MCP Bridge

架构

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 后才会出现在侧边栏中。

环境要求

• macOS 或 Linux，Python 3.11+

• 可正常工作的 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": [],
  "session_access_ttl_seconds": 3600
}

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

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

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

• session_access_ttl_seconds 控制已批准的无项目会话授权的内存生命周期，且不能超过 24 小时。

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

运行本地检查：

./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。

对于"最近"下的无项目会话，ChatGPT 首先调用 codex_list_sessions(include_unassigned=true)。结果仅暴露脱敏的侧边栏元数据。然后它必须调用 codex_prepare_session_access，向您展示会话标题、规范工作目录、访问模式以及适用时的确切写入请求，并等待明确批准。返回的访问令牌仅激活该会话的内存授权。工作区写入还需要同一准备调用返回的精确请求确认令牌。

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。