保姆级教程从零搭建 WebCodex Server Runner 完整 AI 编码环境【免费下载链接】webcodexGive cloud AI agents a real development environment on your own machines.项目地址: https://gitcode.com/gh_mirrors/web/webcodexWebCodex 是一个自托管的云 AI 编码环境它由部署在你机器上的WebCodex Server和WebCodex Runner组成让 ChatGPT、Claude 等 AI 助手通过 MCP 协议直接读取、修改你本地仓库的代码运行 Git、编译和测试。本教程面向新手带你从零完成 WebCodex Server Runner 的完整 AI 编码环境搭建。一、先搞懂WebCodex 的 3 个组件 搭建之前先花 30 秒理解 WebCodex 的工作方式后面每一步你都会更清楚自己在做什么组件可执行文件职责Serverwebcodex-server认证 AI 客户端、保存共享 runtime 状态、把工作路由给 RunnerRunnerwebcodex-runner运行在你持有代码的机器上真正执行文件读写、Git、测试等任务CLIwebcodex统一命令行工具管理 Server/Runner 生命周期整体链路非常简单ChatGPT / 其他 AI 客户端 | MCP v WebCodex Server v Runner -- 你的项目 / Git / 编译器 / 测试工具两个关键事实Server 从不扫描你的文件系统它只看 Runner 主动注册的项目Runner 才是信任边界请运行在真正持有代码和开发环境的机器上。二、准备工作3 个前置条件 ✅Node.js 18 或更新版本npm 包装器要求Git以及一个可以让 AI 安全查看的代码仓库一台能安装 WebCodex 的机器Linux / macOS / Windows x64 均支持 如果你只想用几分钟临时体验一个仓库可以直接看 快速试用文档 用webcodex share一条命令搞定。本文是完整的长期部署路径。三、第一步安装 WebCodex打开终端执行一条命令完成安装Linux / macOS / Windows 通用npm install -g yyjeqhc/webcodex webcodex --version如果打印出版本号说明webcodex、webcodex-server、webcodex-runner三个可执行文件已就绪。四、第二步初始化并启动 WebCodex Server第一次个人使用推荐前台运行最容易理解和排查问题。Linux / macOSwebcodex server init \ --listen 127.0.0.1:8080 \ --data-dir $HOME/.local/share/webcodex \ --env-file $HOME/.config/webcodex/webcodex.env webcodex server run \ --env-file $HOME/.config/webcodex/webcodex.envWindows PowerShell$envFile Join-Path $HOME .config\webcodex\webcodex.env $dataDir Join-Path $HOME .local\share\webcodex webcodex server init --listen 127.0.0.1:8080 --data-dir $dataDir --env-file $envFile webcodex server run --env-file $envFileserver init会创建数据目录和 bootstrap 管理员 token请记住--env-file指定的路径后面创建登录码要用。保持这个终端运行不要关闭。五、第三步选择 AI 客户端的入口这里其实有两条需要打通的连接Runner → Server同机部署直接用http://127.0.0.1:8080跨机器就用 Runner 能访问到的地址ChatGPT → Server云端 ChatGPT 无法访问你本机的127.0.0.1需要一个可达入口。三种常用方案任选其一方案适用场景说明公网 HTTPS 反向代理有域名 证书仓库自带 Nginx 配置示例 deploy/nginx.webcodex.example.confCloudflare Tunnel无公网 IP在反向代理层做 WebSocket upgradeOpenAI Secure MCP Tunnel主要用 ChatGPTRunner 走本机 loopbackChatGPT 单独走 Tunnel⚠️ 记住一句话Tunnel 只解决网络可达性不改变 WebCodex 的权限模式不需要为了用 Tunnel 而换成临时的share模式。六、第四步创建一次性登录码 回到 Server 机器打开另一个终端创建一个短期 pairing codewebcodex pairing create \ --server-url server-url \ --env-file $HOME/.config/webcodex/webcodex.env \ --username your-name \ --ttl-secs 600输出中会出现一个wc_pair_...开头的一次性登录码。只需把这个码带到 Runner 机器不要复制 Server 的管理员 token 或整个 env 文件。即使 Server 和 Runner 在同一台机器也建议走这条登录流程——日常开发权限与 Server 管理权限保持分离更安全。七、第五步登录并注册项目 在持有代码的机器上运行普通用户身份不要加 sudowebcodex login server-url \ --code wc_pair_... \ --allowed-root /path/to/your/projects \ --project /path/to/your/projects/my-repo \ --print-mcp-config新手只需要记住两个参数--project你现在想让 AI 使用的项目路径--allowed-root以后允许继续添加项目的父目录。--print-mcp-config会在同一次登录成功后打印 ChatGPT 需要的 MCP 连接信息包含用户凭据只应由你本人填入客户端别粘贴到 issue 或聊天记录里。login会自动派生设备名、兑换登录码并生成 Runner 配置全程不需要手工编辑配置文件。以后想再添加一个项目webcodex project register --config login-reported-runner-config /path/to/another-repo八、第六步启动 WebCodex Runnerlogin会打印 Runner 配置路径用它可以前台启动 Runnerwebcodex runner run --config login-reported-runner-config验证没问题后Linux 普通用户推荐直接装成用户级 systemd 服务开机自启、无需 sudowebcodex runner install --scope user --config login-reported-runner-config webcodex runner status --scope user --config login-reported-runner-configRunner 跑起来之后WebCodex 才真正拥有调用本机文件、Git、编译器和测试工具的执行入口。Runner 配置细节可参考 deploy/webcodex-runner.toml.example 与 Runner 文档。九、第七步把 WebCodex 接入 ChatGPT如果你选择普通 HTTPS MCP 接入把上一步login --print-mcp-config打印的配置填入 ChatGPT在 ChatGPT 的Plugins / MCP 设置中创建连接填入 CLI 打印的MCP URL与认证方式Bearer token点击Scan Tools扫描成功即可看到work_on_project、read_files、apply_patch等工具。如果使用 OpenAI Secure MCP Tunnel则按 MCP 文档 中 Tunnel 章节操作ChatGPT 侧选择 Tunnel No authentication凭据由本机 tunnel client 自动注入不要把本地 Bearer 复制给 ChatGPT。十、第八步验证你的 AI 编码环境 用两个循序渐进的 prompt 验证完整体验。1️⃣ 先做只读检查不改任何文件检查这个项目并总结结构。先不要修改文件。能正常得到回答说明 AI 已经能通过 WebCodex 访问你的仓库。2️⃣ 再做一个小修改修复一个小问题运行相关测试并告诉我实际修改了什么。接受结果前用 Git 或审查界面检查实际改动。完成验证后可以在 Runtime 概览页确认 Runner 在线、Job 与项目状态工作过程中的实时任务读文件、跑命令、测试都可以在 Work 面板中逐条追踪十一、日常运维4 个最常用命令 # 查看 Server 状态 webcodex server status --env-file server-env-file # 查看 Runner 状态 / 日志 webcodex runner status --config runner-config webcodex runner logs --config runner-config --lines 100 # 一键体检Server、Runner、项目全链路状态 webcodex ops status --server-url server-url \ --token-file login-reported-webcodex-user-token --strictops status --strict是生产环境推荐的 smoke 检查出现 FAIL 会以非零状态码退出。更多运维命令见 部署指南 与 CLI 参考。十二、新手常见问题排查 ❓现象可能原因与处理pairing code 兑换失败码已过期默认 10 分钟有效或已被使用重新执行webcodex pairing createclient online: noRunner 未启动或配置错误先跑webcodex runner status与runner logsChatGPT 提示FORBIDDEN: ... developer MCPs这是 ChatGPT 会话层准入问题不代表你的 Server/Runner 离线先独立检查 Runner 状态再换允许 Developer MCP 的会话重试AI 看不到某个项目项目未注册用webcodex project register添加且路径必须在--allowed-root之内完整错误码与分层决策树见 故障排查文档。十三、总结你完成了什么 恭喜你已经从零搭好了一个完整的 WebCodex Server Runner AI 编码环境✅ 安装webcodex统一 CLI✅ 初始化并启动了 WebCodex Server✅ 选定了 ChatGPT 可达的网络入口✅ 用一次性登录码完成安全的身份接入✅ 注册项目并启动长期运行的 Runner✅ 通过 MCP 让 AI 助手直接在你机器上读代码、改代码、跑测试。接下来可以继续探索完整使用路径详解docs/PERSONAL_SETUP.zh-CN.md生产部署systemd / Docker / OAuthdocs/DEPLOYMENT.zh-CN.mdMCP 接入与客户端策略docs/MCP.zh-CN.mdRunner 配置、Skill 与 Shell profile 高级项docs/RUNNER.zh-CN.md部署配置模板目录deploy/【免费下载链接】webcodexGive cloud AI agents a real development environment on your own machines.项目地址: https://gitcode.com/gh_mirrors/web/webcodex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考