> ## Content Index
> Fetch the complete content index at: https://tbbbk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 腾讯 LoopForge 安装教程（2026）：Windows 用 WSL2 部署实测，免 Key 跑通第一个 SOP
- URL: https://tbbbk.com/tencent-loopforge-install-wsl2-guide/
- Published: 2026-11-22T05:12:44.000Z
- Updated: 2026-11-22T05:12:44.000Z
- Description: 腾讯 LoopForge 在 Windows 上怎么装？原生 Git Bash 会报错，WSL2 + Docker Desktop 实测 1 分 43 秒装好，不填 Key 跑通官方演示流程。
- Author: TuBaiBai
- Tags: AI 编程工具

*说明：文中 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](https://tbbbk.com/content/images/2026/11/loopforge-home.jpg)

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

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

![LoopForge 运行停在人工审批节点](https://tbbbk.com/content/images/2026/11/loopforge-gate.jpg)

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

![LoopForge 演示流程 3 个节点全部完成](https://tbbbk.com/content/images/2026/11/loopforge-done.jpg)

## 第五步：接上模型，让它真正写代码（没实测）

在"设置 → 个人配置 → 个人凭证"里，能看到它支持的执行器：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](https://tbbbk.com/claude-code-codex-deepseek-flash-setup/)；Codex 本身连不上网的排查见 [codex doctor 网络诊断](https://tbbbk.com/codex-doctor-network-troubleshooting/)。

## 安全：只在本机用就别监听 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 套餐](https://my.racknerd.com/aff.php?aff=19073&pid=970)年付 $47.98，行情见 [2026 黑五 VPS 汇总](https://tbbbk.com/black-friday-vps-deals-2026/)。

## 常见问题

### 报 "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](https://github.com/Tencent/LoopForge)
- 部署文档（监听地址、Docker socket 风险）：[docs/deployment.md](https://github.com/Tencent/LoopForge/blob/main/docs/deployment.md)
- Docker Desktop 的 WSL 集成：[Docker 官方文档](https://docs.docker.com/desktop/features/wsl/)