WebCodex 排障实录：Windows + OpenAI Secure MCP Tunnel 独立部署与常见坑
【免费下载链接】webcodexGive cloud AI agents a real development environment on your own machines.项目地址: https://gitcode.com/gh_mirrors/web/webcodex
这是一篇面向新手的WebCodex Windows 部署排障实录：完整记录如何用 WebCodex + OpenAI Secure MCP Tunnel 让 ChatGPT 安全地操作你 Windows 本机项目，并汇总了实测踩过的网络、版本、重启动作三大常见坑。全文按“部署 → 验收 → 排障”顺序展开，照着做即可。
先看懂整体拓扑：两条链路互不干扰
WebCodex 的核心思路是：AI 在云端，代码和工具在你自己的机器上。部署完成后存在两条完全独立的链路：
- ChatGPT → Server：ChatGPT 通过 OpenAI Secure MCP Tunnel 访问本机 Server 的
/mcp端点。这是"AI 入口"。 - Runner → Server：本机 WebCodex Runner 通过 WebSocket 连接 Server，真正负责读写你的项目目录。这是"执行端"。
记住这个边界能帮你避开一半的坑：
- ChatGPT 侧永远不需要看到 WebCodex 的 Bearer 令牌——Tunnel 在本机注入，ChatGPT 里选"无身份验证"即可；
- Tunnel 只解决 AI 到 MCP 的私有传输，不影响Runner 的工作方式；
- Server 只监听
127.0.0.1，不对公网暴露任何端口。
💡 如果只是临时分享一个仓库，直接用
webcodex share --tunnel openai一条命令即可，无需本文的手工拓扑。
部署前的 3 个关键准备
坑 1（提前排掉）：CLI、Server、Runner 必须同版本
这是最容易被忽视的坑。三个组件来自不同版本时，网络问题会伪装成各种诡异现象。先跑三个--version命令确认一致，再开始排网络：
webcodex --version webcodex-server --version webcodex-runner --version创建 Tunnel 与受限 API key
在 OpenAI 平台的Tunnels 页面创建一条 Tunnel 并记录完整 ID，再创建 API key。⚠️ 强烈建议使用Restricted key，只授予 Tunnels 的Read + Use权限，不要给 All 权限：
在 Windows 用户环境中配置两个变量（具体格式见 deploy/webcodex.env.example）：
CONTROL_PLANE_TUNNEL_ID CONTROL_PLANE_API_KEYWebCodex 已内置原生 Rust Tunnel client，无需再安装任何外部 tunnel 二进制。
Windows 前台部署：Server + Runner 两个终端
Windows 当前支持前台 Server runtime——需要保持终端开启。三个终端各跑一个进程：
终端 1 — 初始化并启动 Server（使用独立 env/data 路径，别覆盖已有 runtime）：
webcodex server init --listen 127.0.0.1:18080 --data-dir $dataDir --env-file $envFile --json webcodex server run --env-file $envFile看到下面两行说明本地 MCP 就绪：
Listening on: 127.0.0.1:18080 MCP endpoint: http://localhost:18080/mcp终端 2 — 配对并启动独立 Runner：先用webcodex pairing create生成短期配对码（TTL 600 秒），再在 Runner 侧兑换，同时注册要暴露给 AI 的仓库，并把允许范围限制到真实父目录：
webcodex login http://127.0.0.1:18080 --code <wc_pair_...> --allowed-root C:\src --project C:\src\your-repository --json webcodex runner run --config <login 返回的 runner_config 路径>终端 3 — 启动原生 Tunnel：
webcodex server tunnel --provider openai --env-file $envFile原生 client 会先验证本地/mcp鉴权、再成功完成一次控制面 poll，才会报告就绪。它不再下载外部二进制、不跑 doctor 子进程、也不开放/readyz端口。
验证"两个绿灯"：tunnel_ready ≠ ChatGPT 已连通
⚠️ 这是排障中最容易误判的一点。健康事件里有两个独立指标：
| 指标 | 证明什么 | 不能证明什么 |
|---|---|---|
local_mcp_ready: true | 本机/mcp端点鉴权可用 | Tunnel 控制面健康 |
tunnel_ready: true | 原生 client 完成了一次成功的控制面 poll | ChatGPT Connector 已创建、工具已加载 |
所以"进程启动了""两个绿灯亮了"都不算成功。真正的验收必须走到 ChatGPT 侧。
在 ChatGPT 创建 Connector：三步 + 一个"无身份验证"
- 在 ChatGPT 账户安全设置中开启开发人员模式（界面支持简体中文）：
- 打开插件页面创建新插件：连接方式选隧道 / Tunnel，选择对应的 WebCodex Tunnel，身份验证选无身份验证 / No authentication（因为 Bearer 已由本机 Tunnel client 注入，ChatGPT 不应拿到它），确认风险提示后创建；
- 创建并授权连接后，在插件详情页可以扫到
apply_text_edits等 WebCodex 工具：
- 如果当前对话没出现新工具，先刷新 ChatGPT 窗口再试。
端到端验收清单：别把"进程启动了"当成功
| 层级 | 应看到的证据 |
|---|---|
| Windows Server | loopback 监听正常，/mcp可达 |
| Runner | actual_transport=websocket，Runner online |
| 本地 MCP | local_mcp_ready: true |
| 原生 Tunnel | 成功完成一次 poll 后tunnel_ready: true |
| ChatGPT | Connector 创建成功并 Scan 出工具 |
| Project / Read | login 阶段注册的 Project 可见，能通过 Connector 读取仓库文件 |
| Write | 专用分支写入改动，并用 Git diff 复核 |
最后三项才证明这套 Windows + Tunnel 拓扑真正具备和普通 Server + Runner 一样的开发体验。
排障实录：真实环境踩过的 3 个坑
坑 2：本地 MCP 全绿，Tunnel 却连不上 —— 网络代理问题
实测中遇到的最典型故障：本地/mcp初始化正常、健康检查 200，但 OpenAI 控制面 poll 持续失败。原因是Windows 进程没有继承浏览器的代理路由，api.openai.com的直连 DNS/IPv6 路径不可用。
解决办法——只把控制面路由到代理，本地 MCP 始终绕过代理：
# CLI 方式：给 Tunnel 指定控制面代理 webcodex server tunnel --provider openai --control-plane.http-proxy http://127.0.0.1:7890 ... # 或设置标准 HTTPS_PROXY / NO_PROXY 环境变量如果使用 Desktop，则在设置 → OpenAI Tunnel 网络中选择代理方式，保存后重启 Tunnel 即可：
排障结论沉淀成一条经验：浏览器能上网、本地 MCP 可达，都不能证明控制面 poll 健康——必须看 Tunnel 日志里的 metadata/poll 状态。
坑 3：上次运行状态不确定，Tunnel 拒绝重启
原生 client 有"防重放"设计：若上次运行存在不确定工作（崩溃、未确认的 MCP 交换等），私有的webcodex/tunnel-runs运行标记会阻止重启。
正确处理顺序：先处理之前执行的效果和待处理请求→ 再清除标记或换用新的 Tunnel identity。不要用"换个状态目录绕过标记"的方式硬重启，那违背了 no-replay 契约。详细说明见 crates/webcodex-openai-tunnel/README.md。
常见误区速查
| 误区 | 事实 |
|---|---|
tunnel_ready: true就代表 Connector 可用 | 只证明 poll 成功，ChatGPT 层要单独验证 |
| ChatGPT 需要填写 WebCodex Bearer | Tunnel 模式选No authentication，Bearer 留在本机 |
| Windows 必须用 WSL 或 Windows Service | 前台 Server + 前台 Runner 即可；代价是关终端即停进程 |
share --tunnel openai与手工拓扑是两套东西 | 核心链路相同（本地 MCP + Bearer 注入 + 原生 client），share只是自动管理临时 Server/Runner |
| 把 token 贴进 issue 或截图求帮助 | 严禁泄露 Tunnel ID、API key、Bearer；反馈前先脱敏 |
参考文档
- Windows + OpenAI Secure MCP Tunnel 实操指南（完整命令版）
- Desktop 快速安装与 ChatGPT 连接（普通用户推荐路径）
- Tunnel 原生 client 契约与运行标记说明
- 通用故障排查（分层定位请求是否到达 WebCodex）
- 完整个人部署指南
【免费下载链接】webcodexGive cloud AI agents a real development environment on your own machines.项目地址: https://gitcode.com/gh_mirrors/web/webcodex
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
