Codex 桥接 ChatGPT 网页端模型：全流程工程落地与避坑手册

本文记录如何利用 miuuyy/codex-chatgpt-web 与 OpenAI 官方安全隧道工具（tunnel-client），打通 ChatGPT 网页端模型（Plus/Pro 订阅免 API 费）到本地 Codex 编辑器的全套链路，使云端模型具备直接读取本地代码仓库、生成补丁文件以及调用本地终端命令的能力。

架构原理与核心组件分工

┌─────────────────────────────────────────────────────────────┐
│                    OpenAI 云端控制台与模型                   │
│  ChatGPT 网页端 (Plus/Pro)  <──>  OpenAI Secure MCP Tunnel   │
└──────────────────────────────┬──────────────────────────────┘
                               │ (TLS 加密出站长连接)
═══════════════════════════════╪═══════════════════════════════
                    Mac 本机环境 (必须开启 TUN 模式)
═══════════════════════════════╪═══════════════════════════════
                               ▼
              OpenAI tunnel-client 守护进程 (PID)
                               │ (标准输入输出 stdio / IPC)
                               ▼
        Codex Web GPT (Bun / cli.js 原生 MCP 服务)
                               │ (UNIX Domain Socket: turn-broker.sock)
                               ▼
                       Codex 本地编辑器
               (工作区文件读写 / 本地终端 Bash 执行)

ChatGPT 网页端：负责核心推理，发起标准化 MCP（Model Context Protocol）工具调用请求。
OpenAI 官方隧道（tunnel-client）：在本地与 OpenAI 网关之间维系一条加密出站长连接，让云端请求穿透内网触达本地。
codex-chatgpt-web 运行时：将本地文件树、文件编辑（Patch）与终端执行接口封装为标准的 MCP Tools。
Codex 编辑器：最终的交互界面，通过本地代理模型选择器调用网页端模型处理编程任务。

阶段一：底层网络环境配置（最关键前置）

OpenAI 官方隧道客户端启动后，会在后台拉起独立的守护进程（Daemon）。该后台进程不继承 macOS 终端的 export http_proxy 环境变量，也不会读取浏览器的系统代理设置。如果直接运行，进程会尝试通过 IPv6 直连 OpenAI 服务器，导致长轮询接口不断抛出 dial tcp [...]:443: i/o timeout，进而引发云端探活返回 404 与 424 错误。

必做操作：开启代理软件的 TUN 虚拟网卡模式

打开本地代理客户端（如 Clash Verge Rev、Surge、Sing-box、v2rayA 等）。
开启 TUN 模式（TUN Mode / 虚拟网卡 / 增强模式）。
规则模式切换为 全局模式（Global） 或确保 api.openai.com 与 *.openai.org 强制走海外代理节点。
验证方式：新建一个没有任何环境变量的终端窗口，执行：

curl -I https://api.openai.com

若 1~2 秒内返回 HTTP/2 403、404 或 200 标头，说明网络层透明代理已生效。开启 TUN 后，终端无需再手动执行 export http_proxy。

二：OpenAI 平台凭据准备

创建隧道入口（Tunnel ID）：

打开 platform.openai.com/settings/organization/tunnels。
点击右上角 Create tunnel，命名任意（例如 test 或 codex）。
复制生成的隧道标识符：格式形如 tunnel_6aafbeb25e5c8191b3aeb9c50a4dc322。

生成 Runtime API Key（常规密钥）：

打开 platform.openai.com/settings/organization/api-keys。
创建一个标准 API Key，以 sk-proj- 或 sk- 开头。用于隧道运行时的数据加密与探活认证。

生成 Admin Key（组织管理密钥）：

打开 platform.openai.com/settings/organization/admin-keys。
创建一个组织管理员密钥，以 sk-admin- 开头。用于本地 runtimes connect --admin-profile default 命令向云端注册运行时实例。

阶段三：系统工具链安装与凭证持久化

1. 安装官方隧道工具

在 Mac 终端中通过 Homebrew 安装：

brew install openai/tools/tunnel-client

验证：运行 tunnel-client version，确认输出版本（例如 0.0.14）[cite: 2]。

2. 下载并安装桌面客户端

前往 miuuyy/codex-chatgpt-web Releases 下载最新版 macOS DMG（如 5.0.8-darwin-arm64.dmg），拖入 Applications 目录并打开。

3. 持久化系统环境变量

打开终端，将 API Key 与 Admin Key 写入 zsh 配置文件，避免每次开关终端重新配置：

echo 'export OPENAI_API_KEY="sk-你的常规APIKey"' >> ~/.zshrc
echo 'export OPENAI_ADMIN_KEY="sk-admin-你的管理APIKey"' >> ~/.zshrc
echo 'export CONTROL_PLANE_API_KEY="sk-你的常规APIKey"' >> ~/.zshrc
source ~/.zshrc

验证：执行 echo $OPENAI_ADMIN_KEY，确保能打印出 sk-admin-... 字符串，且两端无多余空格。

阶段四：清理冲突状态与启动本地运行时

由于此前可能尝试过异常启动，必须彻底清理僵尸进程和旧的通信套接字，防止端口与锁冲突[cite: 4, 5]。

1. 彻底杀死残留进程与清除管道锁

在终端中执行：

# 强制结束所有残留的 bun、tunnel-client 和 tmux 进程
killall -9 bun tunnel-client tmux 2>/dev/null

# 清理未正常释放的 UNIX Socket 文件
rm -f /Users/$USER/.codex-chatgpt-web/runtime/*.sock

2. 初始化桌面端通信管道

打开 Codex Web GPT 桌面应用。
进入第 2 步 “连接本地 Harness” 界面。
依次填入 Tunnel ID（tunnel_...）与 API key（填标准 Key，勿填 Admin key）。
保持桌面端打开，它会在后台自动生成通信文件 /Users/$USER/.codex-chatgpt-web/runtime/turn-broker.sock。

3. 测试本地 MCP 脚本健康状态

在终端执行一行探活测试，验证 Bun 解释器与本地 CLI 是否能正常工作：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /Users/$USER/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/runtime/bun /Users/$USER/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/app/cli.js mcp --contract native --broker-socket /Users/$USER/.codex-chatgpt-web/runtime/turn-broker.sock

正确回显：终端立即输出 {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"codex-native","version":"5.0.8"}},"jsonrpc":"2.0","id":1}。
若出现 No such file or directory，请重启桌面客户端直至生成 .sock 文件。

4. 建立官方安全隧道托管

在终端中执行完整的桥接命令（将本地路径映射到云端隧道）[cite: 4, 5]：

tunnel-client runtimes connect \
  --alias codex-chatgpt-web \
  --admin-profile default \
  --profile codex-chatgpt-web \
  --profile-dir "/Users/$USER/.codex-chatgpt-web/tunnel/profiles" \
  --mcp-command "'/Users/$USER/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/runtime/bun' '/Users/$USER/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/app/cli.js' 'mcp' '--contract' 'native' '--broker-socket' '/Users/$USER/.codex-chatgpt-web/runtime/turn-broker.sock'"

正确回显：输出 Connected codex-chatgpt-web using process mode。

5. 校验隧道运行状态

在终端中查看当前隧道的健康检查：

tunnel-client runtimes status codex-chatgpt-web

就绪指标：终端输出包含 codex-chatgpt-web ready tunnel_...。
日志核对：执行 tunnel-client runtimes status codex-chatgpt-web --json 时，log.tail 内绝不能出现 i/o timeout 或 connection refused。此时桌面端界面前两步全部显示绿色勾号[cite: 8]。

阶段五：ChatGPT 网页端连接器配置

1. 开启开发者模式

登录 ChatGPT 网页端。
点击左下角头像 -> 设置项（Settings）[cite: 7]。
找到 开发者模式（Developer Mode） 并切换为开启状态[cite: 8]。

2. 添加 MCP 连接器

在浏览器中访问连接器管理面板：https://chatgpt.com/#settings/Connectors。
点击 “创建连接器”（新建插件），精确填写以下表单：

名称：必须精确填写为 Codex Native2（严格注意空格与首字母大写，不要重命名为其他字符）[cite: 7, 8]。
描述：选填，如 test。
连接：选择隧道（切换到隧道选项卡）。
可用隧道：下拉选择刚才创建的隧道（显示为你设置的名字和 tunnel_... ID）。
身份验证：选择 无身份验证。
勾选底部的 “我了解并希望继续”。

点击右下角 “创建” 按钮。

此时云端网关会通过后台长连接向本地发送一次 SSE 握手请求。由于本地处于 ready 状态且 TUN 代理正常，握手瞬间通过，弹窗自动关闭。

3. 配置高权限（关键防拦截设置）

连接器创建完成后：

在连接器列表中点击刚刚创建的 Codex Native2。
权限策略选择 “允许所有操作”（Allow all actions）[cite: 8]。

注意：若选择“允许低风险操作”，ChatGPT 在尝试给本地文件打补丁或执行 bash 命令时，会被安全策略直接拦截阻断[cite: 8]。

阶段六：全链路验证与日常使用流程

1. 桌面客户端终检

回到 Codex Web GPT 桌面应用第三步界面，点击右下角 “验证运行时”[cite: 8]。

界面 3 个步骤全部点亮绿色打勾图标，提示服务完全就绪[cite: 8]。

2. 在 Codex 中调用网页端模型

启动 Codex 编辑器客户端。
在底部的模型选择下拉框（Model Picker）中，选择通过本插件注入的 ChatGPT 网页端模型（如 GPT-4o (Web)、o1 (Web)、o3-mini (Web) 等）。
发起指令测试：

“请查看当前工作区根目录下的 package.json，并在根目录下创建一个 verify_test.txt 文件，内容写入‘MCP 桥接成功’。”

预期动作：

网页端模型推理后触发 MCP 工具调用。
桌面端捕获指令，自动在本地读写文件并保存。
Codex 编辑器内同步呈现文件修改对比树。

避坑与报错速查表（全场景复盘）

报错信息 / 异常现象	核心根因分析	根治方案
`zsh: no such file or directory: 你的 Tunnel_ID` 或 `<tunnel_...>`[cite: 2]	终端将文档示例中的 `< >` 占位符识别为 Shell 输入重定向控制符[cite: 2]	命令中直接填入字符串，坚决不要加外层的尖括号 `< >`[cite: 2]。
`unknown flag: --tunnel-id`[cite: 3]	`tunnel-client` 0.0.14 版本参数重构，移除了单层 `--tunnel-id` 选项[cite: 2, 3]	单行命令使用 `--control-plane.tunnel-id`，管理命令使用 `runtimes connect`。

| | process XXXXX did not exit after SIGTERM[cite: 4, 5] | 进程异常中断后，旧的守护进程卡死，持续占用系统锁与 socket 文件[cite: 4, 5] | 执行 kill -9 <PID>，并运行 killall -9 bun tunnel-client tmux 2>/dev/null，清除 .sock[cite: 4, 5]。 | | environment variable OPENAI_ADMIN_KEY is not set | 执行带 --admin-profile 的命令时未提供组织管理密钥 | 前往 OpenAI 后台生成 sk-admin-... 密钥，并在终端中 export OPENAI_ADMIN_KEY。 | | MCP SSE probe returned 404 from openai.org / HTTP 424 Failed Dependency
| 隧道后台进程无法直连云端，轮询请求持续 i/o timeout，导致云端探测不到本地实例

| 核心病根：必须开启代理客户端的 TUN 模式（虚拟网卡）+ 全局模式，使后台守护进程的网络走代理。

| | 网页端点击创建连接器报 Something went wrong
| 网页端未开启开发者模式，或隧道名称与插件配置不一致（要求严格匹配）[cite: 7, 8] | 在 ChatGPT 设置中开启“开发者模式”[cite: 8]；连接器名称**必须严格填写为 Codex Native2**[cite: 7, 8]。 |

附：日常重启维护命令清单

电脑重启或需要重新唤醒服务时，无需重新走全流程，依次执行以下三步即可：

确认代理：确保代理客户端已开启 TUN 模式。
打开桌面端：启动 Codex Web GPT 应用。
唤醒隧道：打开终端，执行一行命令恢复后台托管连接：

tunnel-client runtimes connect \
  --alias codex-chatgpt-web \
  --admin-profile default \
  --profile codex-chatgpt-web \
  --profile-dir "$HOME/.codex-chatgpt-web/tunnel/profiles" \
  --mcp-command "'$HOME/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/runtime/bun' '$HOME/.codex-chatgpt-web/versions/5.0.8-darwin-arm64/app/cli.js' 'mcp' '--contract' 'native' '--broker-socket' '$HOME/.codex-chatgpt-web/runtime/turn-broker.sock'"