WebCodex是一个自托管的工具运行时，让云端 AI Agent（如 ChatGPT、Claude）通过 MCP 协议连接到你机器上的 Runner，直接读写、调试本地代码仓库——全程通过官方 OpenAI Secure Tunnel 安全连接，无需暴露公网 IP，代码也不必上传到任何托管环境。

关键词：WebCodex、ChatGPT 连接本地仓库、OpenAI Secure Tunnel、MCP 插件、云端 AI 开发环境

WebCodex 是什么？3 个核心理解 💡

WebCodex 把ChatGPT、Claude 等 MCP 客户端连接到你已有的仓库、Git 工作区和开发工具。Server 负责认证请求并路由，Runner 负责在代码所在机器上真实执行。对新手来说，记住三个核心优势就够：

• 📦代码留在自己的机器上——不需要把整个仓库上传到聊天服务，只有按请求读取的文件片段才可能返回给 AI 客户端。
• 🔧AI 用的是真实开发环境——文件、Git、编译器、测试和已有工具链直接复用，而不是隔着沙盒"想象"你的项目。
• 👀改动始终可审查——通过 Git diff、Workflow Session 证据和 Runtime Console 检查工作，长时间任务可持续观察，无需一直等待单次回复。

ChatGPT / 其他 AI 客户端 | MCP v WebCodex Server（认证 + 路由） | 经过认证的 Runner 连接 v 你机器上的 Runner +-- 代码仓库 / Git +-- 编译器 / 测试 / 开发工具

想深入原理可以读 架构说明、MCP 文档 与 认证模型。

3 种接入方式：新手应该选哪一条？

本指南以最推荐的 Desktop 路径为主线，其余两种方式放在文末。

第一步：安装 WebCodex Desktop 并添加本地项目

1. 从 Releases 下载与本机架构匹配的安装包（Windows 的 x64/ARM64 安装包，或 macOS 的 Intel / Apple Silicon DMG），安装并打开WebCodex Desktop。
2. 首次启动选择创建主节点——它会在本机同时配置独立的 Server 和本机 Runner；初始项目可以先选也可以跳过，之后再添加。
3. macOS 若被 Gatekeeper 拦截，进入系统设置 → 隐私与安全 → 仍要打开，不要全局关闭 Gatekeeper。
4. 在项目页面添加你的本地代码仓库（建议项目已经在使用版本控制）。

配置完成后，首页会像下面这样显示"准备就绪"状态：

📌 在首页展开"查看运行诊断"，确认三项都为 Ready：Service 运行中、Runner 已连接、Project Ready。

第二步：在 OpenAI 平台创建 Tunnel 和 API key

Tunnel 是官方安全隧道，负责让 ChatGPT 安全地"找到"你本机的 WebCodex：

1. 打开 OpenAI 平台的Tunnels页面，点击Create tunnel创建一个 Tunnel（名称可自定义），并记下完整的 Tunnel ID。
2. 打开API keys页面，创建一把Restricted key，只授予Tunnels: Read和Tunnels: Use权限——不建议使用 All 权限的 key。

⚠️ 不要把真实 API key、WebCodex token 提交到 Git、Issue、截图或聊天记录中。

第三步：在 WebCodex Desktop 保存 Tunnel 配置并启动安全隧道

1. 打开连接页面，新增 ChatGPT connection，填入Tunnel ID和API key，选择Run with WebCodex Server (recommended)，保存配置。
2. 进入连接 → OpenAI Secure Tunnel，点击启动安全隧道。
3. 页面显示"当前状态：已连接"后，说明本地通道已经就绪，可以开始等待 ChatGPT 接入。

一般保持设置 → OpenAI Tunnel 网络 → 自动即可；只有网络环境特殊时才改代理。修改后停止并重新启动 Tunnel 即可，不需要重启 Desktop。

第四步：在 ChatGPT 开启开发者模式

1. 打开 ChatGPT 网页版的账户安全与登录设置页面。
2. 找到开发人员模式并开启——它会允许你添加可能修改本地数据的连接器，开启前请先阅读 ChatGPT 给出的风险提示。

第五步：创建 Tunnel 连接器，让 ChatGPT 连上你的仓库

1. 打开ChatGPT 插件页面，创建新插件。
2. 连接方式选择Tunnel；在 Available tunnels 中选择为 WebCodex 创建的 Tunnel（或点击Use tunnel ID instead直接填完整 Tunnel ID）。
3. Authentication 选择 No authentication——本机 Bearer 由 WebCodex 的 Tunnel client 在本机注入，ChatGPT 不需要也不应该拿到这份凭据。
4. 阅读自定义 MCP 风险提示，信任当前安装后勾选继续，点击Create，再在"添加到 ChatGPT"确认页点击连接。

连接成功后，你可以在插件详情页看到 WebCodex 暴露给 AI 的完整工具列表——读取文件、修改代码（apply_text_edits）、打补丁（apply_patch）、运行命令等，每一项都标注了权限级别：

第六步：端到端验证 + 开始让 AI 干活

验证完整链路——发送这条提示词：

列出 WebCodex 项目，然后列出我刚才选择的项目的顶层文件；如果目录为空，请明确报告为空。

能真实读到文件，才说明 ChatGPT、Tunnel、Server、Runner 和项目权限全部连通。注意：Desktop 显示绿色状态只代表本机就绪，不能替代这一步的真实读取验证。

推荐的渐进式玩法：

1. 先只读：检查这个仓库并总结它的结构。先不要做任何修改。
2. 再小改：修复这个仓库里的一个小问题，并运行相关测试。告诉我具体改了什么。
3. 每次改动先用 Git diff 审查，确认无误再接受。

安全使用 WebCodex 的 5 个建议 🛡️

WebCodex 能在配置的项目范围内读取和修改文件、执行命令，所以请务必：

1. 凭据不落地到 AI：API key、token 不要写进提示词、截图、Git、Issue 或共享日志。
2. 最小授权：Tunnel 用 Restricted key（仅 Tunnels Read + Use）；只注册确实要交给 AI 的项目目录。
3. 改动必经 Git 审查：AI 的写入可以逐 diff 审查，别跳过人工审查直接合并。
4. 注意数据回流：按请求读取的文件内容可能返回给 AI 客户端——不想让 AI 看到的敏感文件，别放进已注册的项目里。
5. 完整安全模型：详见 SECURITY.md。

附录：快速试用与 CLI 接入

不想装 Desktop，只想先试几分钟？进入你的仓库目录，一行命令临时分享（需 Node.js 18+）：

npx --yes @yyjeqhc/webcodex share

看到WebCodex ready后，把打印的 MCP URL 和临时 Credential 填入 ChatGPT 插件即可；按 Ctrl-C 连接即结束。找不到 Bearer 输入框时，改用--auth query-token方式。完整步骤见 快速试用。

需要多设备、自托管或生产部署时，走 CLI 完整路径（webcodex server init→pairing create→webcodex login注册项目 →webcodex runner run），Windows + OpenAI Tunnel 的深入配置见 Windows + OpenAI Secure MCP Tunnel 实操指南，命令全量参考 CLI 文档。遇到问题先查 故障排查。

🎉 到这里，你的 ChatGPT 已经拥有了一个"住在你电脑上"的真实开发环境——理解项目、修改代码、跑测试、查 Git，全部由它自己完成，而你的代码从未离开本机。