Codex Local Bridge

在 ChatGPT 网页端规划，在自己的 Ubuntu 上让 Codex 修改、测试并交付代码。

快速开始 · 使用效果 · 项目授权 · 工具列表 · 故障排查 · English

它解决什么问题

你在 ChatGPT 里讨论代码，但文件、测试环境和 VS Code 都在本机。Bridge 将两端接起来：网页端可以读取授权文件、委派编码任务、拿回真实测试结果，再继续同一个 Codex 会话。

已有 VS Code Codex 插件可以继续使用。Bridge 使用独立 CODEX_HOME，不会接管 IDE 对话。

Related MCP server: ChatGPT MCP Bridge

费用与平台权限：先确认这两件事

1. Codex 执行权限：使用已有 ChatGPT 账号登录官方 Codex App Server，不用按 Token 计费的 API Key。仍受套餐额度限制；额度不足会真实报错，不会自动购买额度或切到付费 API。官方说明

2. ChatGPT 网页 MCP 权限：Codex 订阅权限与“网页能否连接自定义 MCP、调用写工具”是两回事。维护者环境已经跑通，不代表任意 Plus 账号都有同样入口。发布时官方将完整自定义 MCP 支持列在 Business、Enterprise/Edu 范围内；请先查看自己账号/工作区的实际权限和最新官方文档。本项目无法解锁平台权限，也不会默认要求你付费升级。

本项目不需要云服务器或付费第三方中转。HTTPS 优先使用 Tailscale Funnel，免费个人方案的资格、地区与使用限制以 Tailscale 当前政策 为准。若账号不能使用远程 MCP，可先运行本机 stdio；这不能替代网页端连接。

工作方式

flowchart LR
    Web[ChatGPT 网页] -->|HTTPS MCP + OAuth| Bridge[Python Local Bridge]
    Bridge --> Files[授权文件工具]
    Bridge -->|App Server / ChatGPT 登录| Codex[本地 Codex]
    Codex --> Snapshot[结构化修改 / Git 快照]
    Snapshot --> Tests[Bubblewrap 隔离测试]
    Tests --> Review{权限 + 风险 + 基线检查}
    Review -->|普通修改且测试通过| Apply[备份 / 写回 / 审计]
    Review -->|需要人工判断| Approval[本机单独审批]
    Bridge <--> DB[(SQLite 任务与会话)]

模型的原生 Shell、直接主机文件写入、联网工具和提权请求被禁用。测试由 Bridge 使用固定 argv 执行，快照只读、网络隔离。文件工具直接修改文本，不会自行运行测试。

快速开始

1. 安装到一个固定目录

已实测 Ubuntu 22.04 / Python 3.10。需要 Git、Python venv、bubblewrap，以及可正常登录的官方 Codex CLI。

sudo apt update
sudo apt install python3-venv git bubblewrap

git clone https://github.com/yiwancibeishang123/codex-local-bridge.git
cd codex-local-bridge

# 可选：安装已验证的官方 CLI 0.162.1 到用户私有目录，不需要 npm/root。
# 若已有兼容 CLI，可跳过；安装器也会探测 VS Code 扩展内的 Codex。
python3 scripts/install-engine.py
bash scripts/install.sh

~/.local/bin/codex-local-bridge login
~/.local/bin/codex-local-bridge doctor
systemctl --user enable --now codex-local-bridge

安装脚本创建 .venv、运行默认回归、生成私有配置和 systemd 用户服务，并初始化独立 demo。不会自动开公网入口、复制 IDE 凭证或提升项目写权限。已有配置和 unit 会保留；已有 unit 指向其他安装目录时，应先核对 systemctl --user cat codex-local-bridge，避免启动旧源码。

配置在 ~/.config/codex-local-bridge/config.json，状态在 ~/.local/share/codex-local-bridge/。配置权限必须为 600。源码目录需保留在安装位置。

2. 建立 HTTPS 入口

先安装并登录 Tailscale，完成其要求的 HTTPS/Funnel 权限设置。不要覆盖设备上已有的其他映射。

sudo tailscale login --qr --timeout=60s
sudo tailscale set --operator="$USER"
tailscale funnel status
tailscale funnel --bg 8767

将 Funnel 输出的实际 HTTPS origin 写入配置 public_url，然后：

systemctl --user restart codex-local-bridge

snap 版 CLI 自带 socket 参数，不要重复加 --socket。没有弹出浏览器时，打开终端给出的登录链接。HTTPS/Funnel 设置详见官方文档。

3. 在 ChatGPT 添加 MCP 连接

在当前账号提供的自定义 MCP/插件入口，填写：

回调必须与连接界面给出的地址完全一致；不同则在本机调整 redirect_uris 后重启，不能允许任意回调。

授权页会显示一条含真实请求 ID的命令。在 Ubuntu 执行该命令并输入 AUTHORIZE，再刷新授权页面：

~/.local/bin/codex-local-bridge auth-requests
~/.local/bin/codex-local-bridge approve-auth 页面显示的真实请求ID

成功后应发现 10 个工具。新开聊天、选择该连接，再请求：“列出授权项目，读取 demo 的 calculator.py，暂不修改文件。”

直接在浏览器打开 /mcp 得到 401 Authentication required 是正常现象；MCP 客户端会携带 OAuth token。服务升级后需要刷新/重新发现工具；旧对话可能保留旧 Schema。平台自身也可能对工具操作弹出确认，本机项目授权不会覆盖这些平台规则。

项目授权：一次明确同意，随时撤销

默认 demo 只读。需要自动修改时，只对你选择的项目在本机配置以下权限：

{
  "id": "demo",
  "name": "Python acceptance demo",
  "root": "/home/YOUR_USER/codex-bridge-demo",
  "include": ["*.py", "*.md"],
  "allowed_modes": ["read", "write_test"],
  "file_write_enabled": true,
  "project_authorization": true,
  "tests": [["/usr/bin/python3", "-m", "unittest", "discover", "-v"]]
}

默认 systemd 仅允许状态目录写入。若项目位于其他目录，还需给该项目添加精确可写路径：

mkdir -p ~/.config/systemd/user/codex-local-bridge.service.d
~/.local/bin/codex-local-bridge project-systemd demo \
  > ~/.config/systemd/user/codex-local-bridge.service.d/demo.conf
systemctl --user daemon-reload
systemctl --user restart codex-local-bridge

~/.local/bin/codex-local-bridge grant-project demo
# 核对范围，在交互终端输入 AUTHORIZE demo
~/.local/bin/codex-local-bridge project-policy demo

省略有效期表示持续有效；可以用 grant-project demo --hours 24 限时授权。撤销不需要重启：

~/.local/bin/codex-local-bridge revoke-project demo

源码后缀和风险分类是保守规则，不是完整 DLP。自动测试仅放行配置中的安全 unittest argv；其他测试框架暂时保留单次审批。完整规则、撤销边界与恢复办法见项目授权说明。

使用效果

以下流程来自独立验收项目的真实执行记录，展示值已去掉账号、域名、任务 ID 和私有项目内容；不是截图，也不是模拟网页成功。

示例 A：修复 → 测试 → 继续同一会话

在已授权的 demo 中向 ChatGPT 发出：

修复 calculator.py 的 add(a, b)，让它返回 a + b。保留原测试，使用 write_test，并返回实际测试结果和是否写回。

随后：

继续上一个任务，保留 add 修复，增加 multiply(a, b) 和 multiply(3, 4) == 12 的单元测试。

观察到的结果：

示例 B：读取 → SHA 精确编辑

文件工具返回平铺对象，同时提供 JSON 文本和 structuredContent：

{
  "project_id": "demo",
  "path": "calculator.py",
  "sha256": "e1a894022d1a082987b87adecb623438c9e386d86b2b621cff4a5fe7fdf7edc8",
  "bytes": 32,
  "content": "def add(a, b):\n    return a - b\n",
  "redacted": false
}

此 SHA 对应示例中的原文件字节，不是修复后的内容。修改前先读取最新 SHA；request_edit_file 只替换唯一匹配片段。旧 SHA 会被拒绝，不能覆盖你在 VS Code 中刚做的修改。新文件使用 expected_sha256="ABSENT"。

判断完成状态要看四个字段：

更多真实验证范围、未覆盖项目和复现命令见验收报告。

十个 MCP 工具

授权、审批、撤销、精确 Diff 应用和部署命令只在本机提供，不暴露为网络工具。

用网页维护 Bridge 自身

~/.local/bin/codex-local-bridge register-maintenance
systemctl --user restart codex-local-bridge
~/.local/bin/codex-local-bridge grant-project bridge_maintenance

之后以 project_id=bridge_maintenance 委派。维护项目是独立 Git 源码副本，普通授权修改不会直接覆盖运行服务。其默认测试是语法/清单烟测，不等于完整 pytest；正式部署前必须审查 Diff、备份、跑全量回归，再单独发布与重启。

测试、升级与贡献

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m pytest -q

# 可选：需本机已有 Bridge 配置和 ChatGPT Codex 登录；使用现有订阅额度。
BRIDGE_LIVE_CODEX=1 .venv/bin/python -m pytest tests/test_live_codex.py -q -s

提供可启用的 GitHub Actions 模板，默认不持有凭证，也不调用付费 API。当前发布凭证没有 workflow scope，因此云端 CI 尚未启用；上方测试徽章记录本地真实测试成绩。部分测试使用明确标注的确定性协议 fixture；这类通过结果不能冒充真实模型或 ChatGPT 浏览器端到端成功。

升级前查看 CHANGELOG，备份配置和状态目录，再按贡献与发布约定进行。GitHub 源码更新不会自动替你部署本机服务；不要对已运行的服务目录盲目 git pull 后直接重启。

• 只看到 5 个工具 / 文件返回 {}：确认服务已升级，重新扫描工具并启动新对话。新版五个文件工具有显式 outputSchema 和 structuredContent。运行 scripts/check-connection.py 检查实际 HTTPS 返回。

• awaiting_approval：核对项目本机开关、有效 grant、测试 argv 和风险类型；OAuth 同意不代表项目自动写权限。

• 测试通过但未写回：检查 changes_applied、apply_error；空差异、风险修改、撤销、SHA 冲突或 systemd 只读都可能阻止写回。

• Codex 额度不足：等待当前套餐额度恢复；Bridge 不购买额度，也不会切换 API Key。

• bwrap 失败：运行 doctor，检查主机的用户命名空间策略；不要跳过沙箱。

• 服务重启后中断：保留任务与 thread，显式重试/续接；不静默重放写入。

完整排查见 TROUBLESHOOTING。

文档与许可

权限策略 · 安全边界 · 真实验收 · 贡献指南 · 更新记录

MIT License。独立社区项目，与 OpenAI、ChatGPT 或 Tailscale 无官方隶属关系。官方 Codex CLI 与 MCP SDK 通过原渠道安装，遵循各自许可证；本仓库不捆绑其二进制或任何登录凭证。