腾讯 LoopForge 安装教程(2026):Windows 用 WSL2 部署实测,免 Key 跑通第一个 SOP
说明:文中 RackNerd 的链接是推广链接,通过它购买价格不变,我会拿到一点佣金。
LoopForge 是腾讯开源的一个自托管平台,11 月在 GitHub 上火了起来:在网页里给"Main Bot"派活,它开一个 Docker 沙箱,调用 Codex、Claude Code、CodeBuddy 这类编程 CLI 去写代码,关键步骤停下来等人审批,最后开 PR。写这篇时 GitHub 上有 5.5k 星。
官方只写了 Linux 和 macOS 的装法。这篇是我在 Windows 11 上实测的:先说原生 Windows 为什么装不上(附真实报错),再用 WSL2 + Ubuntu 从零装好,最后不填任何 API Key 跑通官方演示流程。测试版本是 LoopForge 0.4.0(2026-11-22 的 main 分支)。
先说结论
- Windows 不能直接装,Git Bash 里跑
./start.sh会失败;要走 WSL2 + Ubuntu + Docker Desktop - 装好后一共两个容器(平台 + MySQL),镜像 4.3GB,我这边用了 1 分 43 秒(脚本自动选了南京大学的镜像站)
- 不填 API Key 也能跑官方演示流程(脚本 + 人工审批),真正让 AI 写代码要填你自己的模型 Key
- 默认监听
0.0.0.0:8090,而且它能操作宿主机的 Docker,只在本机用的话建议改成 127.0.0.1
原生 Windows 为什么装不上
我先在 Git Bash 里直接跑了官方命令:
git clone https://github.com/Tencent/LoopForge.git
cd LoopForge
./start.sh第一处报错:
▸ Checking prerequisites
✗ Install Python 3 and curl, then rerun this script; or rerun with LOOPFORGE_YES=1 to accept installation.我电脑上明明装了 Python 3.12。原因是 Windows 自带一个叫 python3 的"应用执行别名",它只是微软商店的占位程序,一运行就提示去商店安装,安装脚本判断为"没有 Python"。
我临时把 python3 指向真正的 Python 再跑,脚本往前走了一步,又报了第二个错:
Created .env with unique local secrets
✗ This installer requires a local Docker socket for sandbox bind mounts. Select a local/rootless Docker context or configure remote workers manually.这个绕不过去:Windows 上的 Docker Desktop 用的是命名管道(npipe://),而 LoopForge 需要把 Linux 的 /var/run/docker.sock 挂进平台容器,才能给每个任务开沙箱。所以 Windows 用户老老实实走 WSL2。
第一步:装 WSL2 和 Ubuntu
在 PowerShell 里:
wsl --install -d Ubuntu-24.04Downloading: Ubuntu 24.04 LTS
Installing: Ubuntu 24.04 LTS
Distribution successfully installed. It can be launched via 'wsl.exe -d Ubuntu-24.04'我的电脑之前已经开过 WSL,所以直接装好了。从没用过 WSL 的电脑,这一步可能需要管理员权限并重启一次(以微软的提示为准)。装好后第一次打开 Ubuntu 会让你设用户名和密码。
第二步:让 Docker Desktop 接管 Ubuntu 里的 Docker
不用在 Ubuntu 里另装 Docker,用 Windows 上的 Docker Desktop 就行:
- 打开 Docker Desktop → Settings → Resources → WSL integration
- 把 Ubuntu-24.04 的开关打开,点 Apply & restart
然后在 Ubuntu 里确认能连上:
docker context inspect --format '{{(index .Endpoints "docker").Host}}'unix:///var/run/docker.sock输出是 unix:///var/run/docker.sock 就对了。如果 which docker 显示的是 /mnt/c/Program Files/Docker/...,说明 Ubuntu 只是借用了 Windows 那边的 docker.exe,集成没开,安装脚本还是会报上面的 socket 错误。
注意:Docker Desktop 必须开着,LoopForge 才能运行。我这台默认不开机自启,重启电脑后要先手动打开它。
第三步:在 Ubuntu 里安装 LoopForge
进 Ubuntu,克隆到 Linux 自己的家目录(我是放在 ~/LoopForge 测的,没试过放在 /mnt/c 下面):
cd ~
git clone https://github.com/Tencent/LoopForge.git
cd LoopForge
./start.shUbuntu 24.04 自带 Python 3、curl 和 git,前置检查直接通过。脚本会先测 ghcr.io 和南京大学镜像站 ghcr.nju.edu.cn 哪个快(官方说明里写了,只有镜像的摘要和官方一致才会用镜像),然后拉镜像、建数据库、导入示例流程。最后几行输出:
▸ Installing the schema extensions and the starter catalog
Installed: run_telemetry.adapter
Installed: run_logs.level
✓ LoopForge is running
LAN: http://192.168.137.255:8090
This machine: http://localhost:8090
No public IP detected. On a cloud host, open http://<public IP>:8090 and allow TCP 8090 in the security group/firewall.
Open it in your browser and create the administrator account.
Default sandboxes reuse the installed runtime image; no second CLI image build is needed.
Stop: ./start.sh stop · Logs: ./start.sh logs · Update images: ./start.sh pull
real 1m43.211s装好后的情况(docker ps 和 docker stats):
loopforge-platform-1 ghcr.io/tencent/loopforge:0.4.0 Up (healthy) 0.0.0.0:8090->8080/tcp
loopforge-mysql-1 mysql:8.4 Up (healthy) 127.0.0.1:33315->3306/tcp
loopforge-mysql-1 MEM=503.1MiB- 平台镜像
ghcr.io/tencent/loopforge:0.4.0有 4.3GB,MySQL 空跑就占 500MB 左右内存,硬盘和内存小的机器要掂量一下 - 输出里的 LAN 地址是 WSL 的内部地址,局域网其他电脑访问不到,本机浏览器打开
http://localhost:8090就行
第四步:创建管理员,不填 Key 跑一次演示
浏览器打开 http://localhost:8090,第一次进来是"创建管理员账号"页面,第一个注册的账号就是管理员,所以装好后尽快自己注册。界面默认是中文。
进去后首页会提示"当前执行器 CodeBuddy 需要先配置 CodeBuddy API Key",先不管它:

官方准备了一个不需要任何 Key 的演示流程:
- 左下角"设置" → "流程模板",能看到「平台验收 · 脚本与审批」(标着"无需 Key 或仓库"),点"打开"
- 右上角点"▶ 运行流程",随便填一句任务输入,点"开始运行"
- 第一个节点是真实执行的脚本(生成一份报告),不到 1 秒跑完,然后停在"人工门禁"等你确认:

这里有三个选项:确认通过、补充信息后重跑当前节点、退回上一步重做。这就是 LoopForge 的核心卖点——AI 干活,关键节点人来拍板。点"确认通过,继续下游",整个流程 3 个节点全部完成,Token 消耗为 0:

第五步:接上模型,让它真正写代码(没实测)
在"设置 → 个人配置 → 个人凭证"里,能看到它支持的执行器:CodeBuddy、Codex、Claude Code、OpenCode、Cursor CLI、Antigravity、Kimi Code、Pi、DeepSeek Harness、ZCode,一共 10 个,外加 GitHub 授权和 Git SSH 密钥。
填好其中一个的 Key 后,就能在首页和 Main Bot 对话、生成文档,或者跑内置的后端 / 前端 / 修 Bug SOP;要改已有仓库并开 PR,还要连上 GitHub。这部分我没有 Key,没实测,以官方文档为准。模型费用要你自己出。
Codex 接第三方模型的思路可以参考 Claude Code / Codex 接入 DeepSeek;Codex 本身连不上网的排查见 codex doctor 网络诊断。
安全:只在本机用就别监听 0.0.0.0
官方部署文档写得很直白:平台容器挂了宿主机的 Docker socket,能访问它就相当于拿到宿主机 root;任何能运行 SOP 的人都能在这台机器的容器里执行代码。另外,绑定的仓库里的 AGENTS.md、CLAUDE.md、.claude/settings.json、.mcp.json 都可能在沙箱里启动命令,只绑你信得过的仓库。
只在自己电脑上用的话,把监听地址改成本机。编辑 ~/LoopForge/.env:
sed -i 's/^LOOPFORGE_BIND=.*/LOOPFORGE_BIND=127.0.0.1/' .env
./start.sh改完再看端口,已经只绑在本机了,Windows 浏览器照样能用 localhost:8090 打开:
loopforge-platform-1 127.0.0.1:8090->8080/tcp要放到服务器上给团队用,官方建议前面加 HTTPS 反向代理,并且在管理员账号建好之前只放行你自己的 IP。
常用命令
都在 ~/LoopForge 目录下执行,stop 和重新启动我都试过:
./start.sh # 启动(重复执行是安全的,会保留 .env 和数据)
./start.sh stop # 停止,数据保留
./start.sh logs # 看平台日志
./start.sh pull # 更新到新版本
./start.sh down # 删除容器,但保留数据卷想彻底删掉,down 之后还要删数据卷(loopforge_mysql-data、loopforge_platform-data)和目录里的 .data,这一步我没做,删之前确认数据不要了。
放到 VPS 上行不行
官方脚本本来就是为 Linux 服务器写的(会自动读云厂商的公网 IP,提示你开安全组端口)。我没在 VPS 上测,只从本机看:镜像 4.3GB、MySQL 常驻约 500MB,每次运行还要再开沙箱容器,我估计 2G 内存的小机器会吃力,4G 内存、40G 以上硬盘比较稳妥(这是估算,不是实测)。正好黑五,RackNerd 4G 套餐年付 $47.98,行情见 2026 黑五 VPS 汇总。
常见问题
报 "Install Python 3 and curl"
在 Windows 的 Git Bash 里跑了,换到 WSL 的 Ubuntu 里跑。Linux 上缺 Python / curl 的话,按提示加 LOOPFORGE_YES=1 让脚本自动装。
报 "requires a local Docker socket"
Docker 连的不是本地 socket:要么在 Windows 原生环境里跑了,要么 WSL 里没开 Docker Desktop 集成(见第二步)。
报 "Port 8090 is already in use"
安装脚本会检查端口,在 .env 里把 AGENTFLOW_HTTP_PORT 改成别的端口再跑(脚本自带的提示,我没遇到)。
重启电脑后打不开
先确认 Docker Desktop 已经启动,再进 Ubuntu 的 ~/LoopForge 执行 ./start.sh。
参考来源
- GitHub 仓库和 README:Tencent/LoopForge
- 部署文档(监听地址、Docker socket 风险):docs/deployment.md
- Docker Desktop 的 WSL 集成:Docker 官方文档