錄：Windows + OpenAI Secure MCP Tunnel 獨(dú)立部署與常見坑)
WebCodex 排障實(shí)錄Windows OpenAI Secure MCP Tunnel 獨(dú)立部署與常見坑【免費(fèi)下載鏈接】webcodexGive cloud AI agents a real development environment on your own machines.項(xiàng)目地址: https://gitcode.com/gh_mirrors/web/webcodex這是一篇面向新手的WebCodex Windows 部署排障實(shí)錄完整記錄如何用 WebCodex OpenAI Secure MCP Tunnel 讓 ChatGPT 安全地操作你 Windows 本機(jī)項(xiàng)目并匯總了實(shí)測(cè)踩過的網(wǎng)絡(luò)、版本、重啟動(dòng)作三大常見坑。全文按“部署 → 驗(yàn)收 → 排障”順序展開照著做即可。先看懂整體拓?fù)鋬蓷l鏈路互不干擾WebCodex 的核心思路是AI 在云端代碼和工具在你自己的機(jī)器上。部署完成后存在兩條完全獨(dú)立的鏈路ChatGPT → ServerChatGPT 通過 OpenAI Secure MCP Tunnel 訪問本機(jī) Server 的/mcp端點(diǎn)。這是AI 入口。Runner → Server本機(jī) WebCodex Runner 通過 WebSocket 連接 Server真正負(fù)責(zé)讀寫你的項(xiàng)目目錄。這是執(zhí)行端。記住這個(gè)邊界能幫你避開一半的坑ChatGPT 側(cè)永遠(yuǎn)不需要看到 WebCodex 的 Bearer 令牌——Tunnel 在本機(jī)注入ChatGPT 里選無身份驗(yàn)證即可Tunnel 只解決 AI 到 MCP 的私有傳輸不影響Runner 的工作方式Server 只監(jiān)聽127.0.0.1不對(duì)公網(wǎng)暴露任何端口。 如果只是臨時(shí)分享一個(gè)倉庫直接用webcodex share --tunnel openai一條命令即可無需本文的手工拓?fù)?。部署前?3 個(gè)關(guān)鍵準(zhǔn)備坑 1提前排掉CLI、Server、Runner 必須同版本這是最容易被忽視的坑。三個(gè)組件來自不同版本時(shí)網(wǎng)絡(luò)問題會(huì)偽裝成各種詭異現(xiàn)象。先跑三個(gè)--version命令確認(rèn)一致再開始排網(wǎng)絡(luò)webcodex --version webcodex-server --version webcodex-runner --version創(chuàng)建 Tunnel 與受限 API key在 OpenAI 平臺(tái)的Tunnels 頁面創(chuàng)建一條 Tunnel 并記錄完整 ID再創(chuàng)建 API key。?? 強(qiáng)烈建議使用Restricted key只授予 Tunnels 的Read Use權(quán)限不要給 All 權(quán)限在 Windows 用戶環(huán)境中配置兩個(gè)變量具體格式見 deploy/webcodex.env.exampleCONTROL_PLANE_TUNNEL_ID CONTROL_PLANE_API_KEYWebCodex 已內(nèi)置原生 Rust Tunnel client無需再安裝任何外部 tunnel 二進(jìn)制。Windows 前臺(tái)部署Server Runner 兩個(gè)終端Windows 當(dāng)前支持前臺(tái) Server runtime——需要保持終端開啟。三個(gè)終端各跑一個(gè)進(jìn)程終端 1 — 初始化并啟動(dòng) Server使用獨(dú)立 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 — 配對(duì)并啟動(dòng)獨(dú)立 Runner先用webcodex pairing create生成短期配對(duì)碼TTL 600 秒再在 Runner 側(cè)兌換同時(shí)注冊(cè)要暴露給 AI 的倉庫并把允許范圍限制到真實(shí)父目錄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 — 啟動(dòng)原生 Tunnelwebcodex server tunnel --provider openai --env-file $envFile原生 client 會(huì)先驗(yàn)證本地/mcp鑒權(quán)、再成功完成一次控制面 poll才會(huì)報(bào)告就緒。它不再下載外部二進(jìn)制、不跑 doctor 子進(jìn)程、也不開放/readyz端口。驗(yàn)證兩個(gè)綠燈tunnel_ready ≠ ChatGPT 已連通?? 這是排障中最容易誤判的一點(diǎn)。健康事件里有兩個(gè)獨(dú)立指標(biāo)指標(biāo)證明什么不能證明什么local_mcp_ready: true本機(jī)/mcp端點(diǎn)鑒權(quán)可用Tunnel 控制面健康tunnel_ready: true原生 client 完成了一次成功的控制面 pollChatGPT Connector 已創(chuàng)建、工具已加載所以進(jìn)程啟動(dòng)了兩個(gè)綠燈亮了都不算成功。真正的驗(yàn)收必須走到 ChatGPT 側(cè)。在 ChatGPT 創(chuàng)建 Connector三步 一個(gè)無身份驗(yàn)證在 ChatGPT 賬戶安全設(shè)置中開啟開發(fā)人員模式界面支持簡(jiǎn)體中文打開插件頁面創(chuàng)建新插件連接方式選隧道 / Tunnel選擇對(duì)應(yīng)的 WebCodex Tunnel身份驗(yàn)證選無身份驗(yàn)證 / No authentication因?yàn)?Bearer 已由本機(jī) Tunnel client 注入ChatGPT 不應(yīng)拿到它確認(rèn)風(fēng)險(xiǎn)提示后創(chuàng)建創(chuàng)建并授權(quán)連接后在插件詳情頁可以掃到apply_text_edits等 WebCodex 工具如果當(dāng)前對(duì)話沒出現(xiàn)新工具先刷新 ChatGPT 窗口再試。端到端驗(yàn)收清單別把進(jìn)程啟動(dòng)了當(dāng)成功層級(jí)應(yīng)看到的證據(jù)Windows Serverloopback 監(jiān)聽正常/mcp可達(dá)Runneractual_transportwebsocketRunner online本地 MCPlocal_mcp_ready: true原生 Tunnel成功完成一次 poll 后tunnel_ready: trueChatGPTConnector 創(chuàng)建成功并 Scan 出工具Project / Readlogin 階段注冊(cè)的 Project 可見能通過 Connector 讀取倉庫文件Write專用分支寫入改動(dòng)并用 Git diff 復(fù)核最后三項(xiàng)才證明這套 Windows Tunnel 拓?fù)湔嬲邆浜推胀?Server Runner 一樣的開發(fā)體驗(yàn)。排障實(shí)錄真實(shí)環(huán)境踩過的 3 個(gè)坑坑 2本地 MCP 全綠Tunnel 卻連不上 —— 網(wǎng)絡(luò)代理問題實(shí)測(cè)中遇到的最典型故障本地/mcp初始化正常、健康檢查 200但 OpenAI 控制面 poll 持續(xù)失敗。原因是Windows 進(jìn)程沒有繼承瀏覽器的代理路由api.openai.com的直連 DNS/IPv6 路徑不可用。解決辦法——只把控制面路由到代理本地 MCP 始終繞過代理# CLI 方式給 Tunnel 指定控制面代理 webcodex server tunnel --provider openai --control-plane.http-proxy http://127.0.0.1:7890 ... # 或設(shè)置標(biāo)準(zhǔn) HTTPS_PROXY / NO_PROXY 環(huán)境變量如果使用 Desktop則在設(shè)置 → OpenAI Tunnel 網(wǎng)絡(luò)中選擇代理方式保存后重啟 Tunnel 即可排障結(jié)論沉淀成一條經(jīng)驗(yàn)瀏覽器能上網(wǎng)、本地 MCP 可達(dá)都不能證明控制面 poll 健康——必須看 Tunnel 日志里的 metadata/poll 狀態(tài)?？?3上次運(yùn)行狀態(tài)不確定Tunnel 拒絕重啟原生 client 有防重放設(shè)計(jì)若上次運(yùn)行存在不確定工作崩潰、未確認(rèn)的 MCP 交換等私有的webcodex/tunnel-runs運(yùn)行標(biāo)記會(huì)阻止重啟。正確處理順序先處理之前執(zhí)行的效果和待處理請(qǐng)求→ 再清除標(biāo)記或換用新的 Tunnel identity。不要用換個(gè)狀態(tài)目錄繞過標(biāo)記的方式硬重啟那違背了 no-replay 契約。詳細(xì)說明見 crates/webcodex-openai-tunnel/README.md。常見誤區(qū)速查誤區(qū)事實(shí)tunnel_ready: true就代表 Connector 可用只證明 poll 成功ChatGPT 層要單獨(dú)驗(yàn)證ChatGPT 需要填寫 WebCodex BearerTunnel 模式選No authenticationBearer 留在本機(jī)Windows 必須用 WSL 或 Windows Service前臺(tái) Server 前臺(tái) Runner 即可代價(jià)是關(guān)終端即停進(jìn)程share --tunnel openai與手工拓?fù)涫莾商讝|西核心鏈路相同本地 MCP Bearer 注入 原生 clientshare只是自動(dòng)管理臨時(shí) Server/Runner把 token 貼進(jìn) issue 或截圖求幫助嚴(yán)禁泄露 Tunnel ID、API key、Bearer反饋前先脫敏參考文檔Windows OpenAI Secure MCP Tunnel 實(shí)操指南完整命令版Desktop 快速安裝與 ChatGPT 連接普通用戶推薦路徑Tunnel 原生 client 契約與運(yùn)行標(biāo)記說明通用故障排查分層定位請(qǐng)求是否到達(dá) WebCodex完整個(gè)人部署指南【免費(fèi)下載鏈接】webcodexGive cloud AI agents a real development environment on your own machines.項(xiàng)目地址: https://gitcode.com/gh_mirrors/web/webcodex創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 WebCodex 排障實(shí)錄：Windows + OpenAI Secure MCP Tunnel 獨(dú)立部署與常見坑
WebCodex 排障實(shí)錄Windows OpenAI Secure MCP Tunnel 獨(dú)立部署與常見坑【免費(fèi)下載鏈接】webcodexGive cloud AI agents a real development environment on your own machines.項(xiàng)目地址: https://gitcode.com/gh_mirrors/web/webcodex這是一篇面向新手的WebCodex Windows 部署排障實(shí)錄完整記錄如何用 WebCodex OpenAI Secure MCP Tunnel 讓 ChatGPT 安全地操作你 Windows 本機(jī)項(xiàng)目并匯總了實(shí)測(cè)踩過的網(wǎng)絡(luò)、版本、重啟動(dòng)作三大常見坑。全文按“部署 → 驗(yàn)收 → 排障”順序展開照著做即可。先看懂整體拓?fù)鋬蓷l鏈路互不干擾WebCodex 的核心思路是AI 在云端代碼和工具在你自己的機(jī)器上。部署完成后存在兩條完全獨(dú)立的鏈路ChatGPT → ServerChatGPT 通過 OpenAI Secure MCP Tunnel 訪問本機(jī) Server 的/mcp端點(diǎn)。這是AI 入口。Runner → Server本機(jī) WebCodex Runner 通過 WebSocket 連接 Server真正負(fù)責(zé)讀寫你的項(xiàng)目目錄。這是執(zhí)行端。記住這個(gè)邊界能幫你避開一半的坑ChatGPT 側(cè)永遠(yuǎn)不需要看到 WebCodex 的 Bearer 令牌——Tunnel 在本機(jī)注入ChatGPT 里選無身份驗(yàn)證即可Tunnel 只解決 AI 到 MCP 的私有傳輸不影響Runner 的工作方式Server 只監(jiān)聽127.0.0.1不對(duì)公網(wǎng)暴露任何端口。 如果只是臨時(shí)分享一個(gè)倉庫直接用webcodex share --tunnel openai一條命令即可無需本文的手工拓?fù)?。部署前?3 個(gè)關(guān)鍵準(zhǔn)備坑 1提前排掉CLI、Server、Runner 必須同版本這是最容易被忽視的坑。三個(gè)組件來自不同版本時(shí)網(wǎng)絡(luò)問題會(huì)偽裝成各種詭異現(xiàn)象。先跑三個(gè)--version命令確認(rèn)一致再開始排網(wǎng)絡(luò)webcodex --version webcodex-server --version webcodex-runner --version創(chuàng)建 Tunnel 與受限 API key在 OpenAI 平臺(tái)的Tunnels 頁面創(chuàng)建一條 Tunnel 并記錄完整 ID再創(chuàng)建 API key。?? 強(qiáng)烈建議使用Restricted key只授予 Tunnels 的Read Use權(quán)限不要給 All 權(quán)限在 Windows 用戶環(huán)境中配置兩個(gè)變量具體格式見 deploy/webcodex.env.exampleCONTROL_PLANE_TUNNEL_ID CONTROL_PLANE_API_KEYWebCodex 已內(nèi)置原生 Rust Tunnel client無需再安裝任何外部 tunnel 二進(jìn)制。Windows 前臺(tái)部署Server Runner 兩個(gè)終端Windows 當(dāng)前支持前臺(tái) Server runtime——需要保持終端開啟。三個(gè)終端各跑一個(gè)進(jìn)程終端 1 — 初始化并啟動(dòng) Server使用獨(dú)立 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 — 配對(duì)并啟動(dòng)獨(dú)立 Runner先用webcodex pairing create生成短期配對(duì)碼TTL 600 秒再在 Runner 側(cè)兌換同時(shí)注冊(cè)要暴露給 AI 的倉庫并把允許范圍限制到真實(shí)父目錄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 — 啟動(dòng)原生 Tunnelwebcodex server tunnel --provider openai --env-file $envFile原生 client 會(huì)先驗(yàn)證本地/mcp鑒權(quán)、再成功完成一次控制面 poll才會(huì)報(bào)告就緒。它不再下載外部二進(jìn)制、不跑 doctor 子進(jìn)程、也不開放/readyz端口。驗(yàn)證兩個(gè)綠燈tunnel_ready ≠ ChatGPT 已連通?? 這是排障中最容易誤判的一點(diǎn)。健康事件里有兩個(gè)獨(dú)立指標(biāo)指標(biāo)證明什么不能證明什么local_mcp_ready: true本機(jī)/mcp端點(diǎn)鑒權(quán)可用Tunnel 控制面健康tunnel_ready: true原生 client 完成了一次成功的控制面 pollChatGPT Connector 已創(chuàng)建、工具已加載所以進(jìn)程啟動(dòng)了兩個(gè)綠燈亮了都不算成功。真正的驗(yàn)收必須走到 ChatGPT 側(cè)。在 ChatGPT 創(chuàng)建 Connector三步 一個(gè)無身份驗(yàn)證在 ChatGPT 賬戶安全設(shè)置中開啟開發(fā)人員模式界面支持簡(jiǎn)體中文打開插件頁面創(chuàng)建新插件連接方式選隧道 / Tunnel選擇對(duì)應(yīng)的 WebCodex Tunnel身份驗(yàn)證選無身份驗(yàn)證 / No authentication因?yàn)?Bearer 已由本機(jī) Tunnel client 注入ChatGPT 不應(yīng)拿到它確認(rèn)風(fēng)險(xiǎn)提示后創(chuàng)建創(chuàng)建并授權(quán)連接后在插件詳情頁可以掃到apply_text_edits等 WebCodex 工具如果當(dāng)前對(duì)話沒出現(xiàn)新工具先刷新 ChatGPT 窗口再試。端到端驗(yàn)收清單別把進(jìn)程啟動(dòng)了當(dāng)成功層級(jí)應(yīng)看到的證據(jù)Windows Serverloopback 監(jiān)聽正常/mcp可達(dá)Runneractual_transportwebsocketRunner online本地 MCPlocal_mcp_ready: true原生 Tunnel成功完成一次 poll 后tunnel_ready: trueChatGPTConnector 創(chuàng)建成功并 Scan 出工具Project / Readlogin 階段注冊(cè)的 Project 可見能通過 Connector 讀取倉庫文件Write專用分支寫入改動(dòng)并用 Git diff 復(fù)核最后三項(xiàng)才證明這套 Windows Tunnel 拓?fù)湔嬲邆浜推胀?Server Runner 一樣的開發(fā)體驗(yàn)。排障實(shí)錄真實(shí)環(huán)境踩過的 3 個(gè)坑坑 2本地 MCP 全綠Tunnel 卻連不上 —— 網(wǎng)絡(luò)代理問題實(shí)測(cè)中遇到的最典型故障本地/mcp初始化正常、健康檢查 200但 OpenAI 控制面 poll 持續(xù)失敗。原因是Windows 進(jìn)程沒有繼承瀏覽器的代理路由api.openai.com的直連 DNS/IPv6 路徑不可用。解決辦法——只把控制面路由到代理本地 MCP 始終繞過代理# CLI 方式給 Tunnel 指定控制面代理 webcodex server tunnel --provider openai --control-plane.http-proxy http://127.0.0.1:7890 ... # 或設(shè)置標(biāo)準(zhǔn) HTTPS_PROXY / NO_PROXY 環(huán)境變量如果使用 Desktop則在設(shè)置 → OpenAI Tunnel 網(wǎng)絡(luò)中選擇代理方式保存后重啟 Tunnel 即可排障結(jié)論沉淀成一條經(jīng)驗(yàn)瀏覽器能上網(wǎng)、本地 MCP 可達(dá)都不能證明控制面 poll 健康——必須看 Tunnel 日志里的 metadata/poll 狀態(tài)?？?3上次運(yùn)行狀態(tài)不確定Tunnel 拒絕重啟原生 client 有防重放設(shè)計(jì)若上次運(yùn)行存在不確定工作崩潰、未確認(rèn)的 MCP 交換等私有的webcodex/tunnel-runs運(yùn)行標(biāo)記會(huì)阻止重啟。正確處理順序先處理之前執(zhí)行的效果和待處理請(qǐng)求→ 再清除標(biāo)記或換用新的 Tunnel identity。不要用換個(gè)狀態(tài)目錄繞過標(biāo)記的方式硬重啟那違背了 no-replay 契約。詳細(xì)說明見 crates/webcodex-openai-tunnel/README.md。常見誤區(qū)速查誤區(qū)事實(shí)tunnel_ready: true就代表 Connector 可用只證明 poll 成功ChatGPT 層要單獨(dú)驗(yàn)證ChatGPT 需要填寫 WebCodex BearerTunnel 模式選No authenticationBearer 留在本機(jī)Windows 必須用 WSL 或 Windows Service前臺(tái) Server 前臺(tái) Runner 即可代價(jià)是關(guān)終端即停進(jìn)程share --tunnel openai與手工拓?fù)涫莾商讝|西核心鏈路相同本地 MCP Bearer 注入 原生 clientshare只是自動(dòng)管理臨時(shí) Server/Runner把 token 貼進(jìn) issue 或截圖求幫助嚴(yán)禁泄露 Tunnel ID、API key、Bearer反饋前先脫敏參考文檔Windows OpenAI Secure MCP Tunnel 實(shí)操指南完整命令版Desktop 快速安裝與 ChatGPT 連接普通用戶推薦路徑Tunnel 原生 client 契約與運(yùn)行標(biāo)記說明通用故障排查分層定位請(qǐng)求是否到達(dá) WebCodex完整個(gè)人部署指南【免費(fèi)下載鏈接】webcodexGive cloud AI agents a real development environment on your own machines.項(xiàng)目地址: https://gitcode.com/gh_mirrors/web/webcodex創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考