阅读时间 9 分钟

腾讯 LoopForge 安装教程(2026):Windows 用 WSL2 部署实测,免 Key 跑通第一个 SOP

腾讯 LoopForge 在 Windows 上怎么装?原生 Git Bash 会报错,WSL2 + Docker Desktop 实测 1 分 43 秒装好,不填 Key 跑通官方演示流程。

说明:文中 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.04
Downloading: 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 就行:

  1. 打开 Docker Desktop → Settings → Resources → WSL integration
  2. 把 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.sh

Ubuntu 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",先不管它:

LoopForge 首页,提示需要配置 CodeBuddy API Key

官方准备了一个不需要任何 Key 的演示流程:

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

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

LoopForge 演示流程 3 个节点全部完成

第五步:接上模型,让它真正写代码(没实测)

在"设置 → 个人配置 → 个人凭证"里,能看到它支持的执行器: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。

参考来源