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 → ServerChatGPT 通过 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.exampleCONTROL_PLANE_TUNNEL_ID CONTROL_PLANE_API_KEYWebCodex 已内置原生 Rust Tunnel client无需再安装任何外部 tunnel 二进制。Windows 前台部署Server Runner 两个终端Windows 当前支持前台 Server runtime——需要保持终端开启。三个终端各跑一个进程终端 1 — 初始化并启动 Server使用独立 env/data 路径别覆盖已有 runtimewebcodex 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 — 启动原生 Tunnelwebcodex 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 完成了一次成功的控制面 pollChatGPT Connector 已创建、工具已加载所以进程启动了两个绿灯亮了都不算成功。真正的验收必须走到 ChatGPT 侧。在 ChatGPT 创建 Connector三步 一个无身份验证在 ChatGPT 账户安全设置中开启开发人员模式界面支持简体中文打开插件页面创建新插件连接方式选隧道 / Tunnel选择对应的 WebCodex Tunnel身份验证选无身份验证 / No authentication因为 Bearer 已由本机 Tunnel client 注入ChatGPT 不应拿到它确认风险提示后创建创建并授权连接后在插件详情页可以扫到apply_text_edits等 WebCodex 工具如果当前对话没出现新工具先刷新 ChatGPT 窗口再试。端到端验收清单别把进程启动了当成功层级应看到的证据Windows Serverloopback 监听正常/mcp可达Runneractual_transportwebsocketRunner online本地 MCPlocal_mcp_ready: true原生 Tunnel成功完成一次 poll 后tunnel_ready: trueChatGPTConnector 创建成功并 Scan 出工具Project / Readlogin 阶段注册的 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 BearerTunnel 模式选No authenticationBearer 留在本机Windows 必须用 WSL 或 Windows Service前台 Server 前台 Runner 即可代价是关终端即停进程share --tunnel openai与手工拓扑是两套东西核心链路相同本地 MCP Bearer 注入 原生 clientshare只是自动管理临时 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），仅供参考