OpenClaw 最终安装指南：Windows 下用 WSL2 + Ubuntu 跑通源码版

前言

这篇文章不是"照着官方文档抄一遍"，而是一份真正走通过、踩过坑、最后收敛出的最终推荐流程。

这次在 Windows 上安装 OpenClaw 源码版，前后遇到了几类很典型的问题：

Windows 原生环境跑构建脚本不稳定
WSL2 默认占用 C 盘
WSL 不会自动继承 Windows 代理
在 /mnt/d/... 下跑 pnpm install 容易遇到权限和文件锁问题
OpenClaw 安装完成后，还要区分 gateway、tui、dashboard 之间的关系

所以这篇文章的目标不是"记录过程"，而是给出一套以后重装也能直接照做的最终版本。

一、最终推荐思路

如果你想在 Windows 上稳定运行 OpenClaw 源码版，推荐路线是：

Windows 只负责宿主系统
用 WSL2 + Ubuntu 提供 Linux 运行环境
把 Ubuntu 迁移到 D 盘，避免长期吃掉 C 盘
在 Ubuntu 中安装 Node 24 LTS 和 pnpm
把 OpenClaw 仓库同步到 WSL 的 Linux 文件系统
在 WSL 本地目录里执行 pnpm install / build / onboard
日常使用时先启动 gateway，再通过 Dashboard 或 TUI 访问

二、为什么不要直接在 Windows PowerShell 里装

理论上你可以在 Windows 里直接跑：

bash 复制代码

pnpm install
pnpm ui:build
pnpm build

但实际很容易遇到：

脚本依赖 bash
某些依赖在 Windows 原生环境兼容性一般
node_modules 容易被编辑器、索引器、杀毒同时占用
报错形态复杂，比如：
- Command "tsdown" not found
- ERR_PNPM_EACCES
- ECONNRESET

因此最终结论很明确：
不要把 OpenClaw 的源码安装主流程放在 Windows 原生 PowerShell 里。

三、启用 WSL2

管理员 PowerShell 执行：

powershell 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl.exe --set-default-version 2

如果提示重启，就先重启电脑。

如果 wsl --status 提示虚拟化问题，需要进入 BIOS 打开：

Intel：VT-x
AMD：SVM Mode

四、安装 Ubuntu

正常可以先尝试：

powershell 复制代码

wsl --install -d Ubuntu

如果这一步因为联网问题失败，但开始菜单里已经出现 Ubuntu 图标，也可以直接点击图标初始化。

第一次进入 Ubuntu 时，会提示你创建：

Linux 用户名
Linux 密码（这里有保护机制，只管输入后回车就行，不记得了就删除重新输入后回车）

确认安装成功：

powershell 复制代码

wsl --list --verbose

看到类似：

text 复制代码

* Ubuntu    Running    2

就说明 Ubuntu 已经正常跑在 WSL2 上。

五、建议马上把 Ubuntu 迁移到 D 盘

这一点强烈建议不要省略。

WSL 默认会把 Ubuntu 放在 C 盘用户目录下，并创建一个 ext4.vhdx 虚拟磁盘文件。随着后续安装依赖、缓存、构建，它会持续长大。

如果你的 C 盘空间本来就不富余，最好在 Ubuntu 初始化成功后立刻迁移到 D 盘。

执行：

powershell 复制代码

wsl --shutdown
mkdir D:\WSL
wsl --export Ubuntu D:\WSL\ubuntu.tar
wsl --unregister Ubuntu
mkdir D:\WSL\Ubuntu
wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\ubuntu.tar --version 2
wsl -d Ubuntu

如果导入后默认用户变成 root

进入 Ubuntu 后执行：

bash 复制代码

whoami

如果输出是 root，把默认用户改回你自己的普通账户。假设用户名是 xxx：

bash 复制代码

printf "[user]\ndefault=xxx\n" | sudo tee /etc/wsl.conf
exit

然后回到 PowerShell：

powershell 复制代码

wsl --shutdown
wsl -d Ubuntu

再次确认：

bash 复制代码

whoami

如果输出已经是你的普通用户名，说明 Ubuntu 已经成功迁移到 D 盘并修复了默认用户。

六、安装 Ubuntu 里的基础工具

在 Ubuntu 中执行：

bash 复制代码

sudo apt update
sudo apt install -y build-essential curl git unzip rsync

这一步里最值得注意的是 rsync，后面同步仓库会用到。

七、安装 Node 24 LTS

这次实际安装过程中，nvm 因为访问 GitHub Raw 失败不稳定，所以最终最稳的方案是用 NodeSource：

bash 复制代码

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v

仓库只要求：

json 复制代码

"engines": {
  "node": ">=22.12.0"
}

因此 Node 24 LTS 完全满足要求。

八、安装 pnpm

最省事的方式：

bash 复制代码

sudo npm install -g pnpm@10
pnpm -v

实际安装中，拿到 pnpm 10.32.0 也可以正常继续使用，不必强行纠结一定要和锁文件版本完全一致。

九、不要在 /mnt/d 目录里直接安装依赖

这是整个安装过程中最关键的一条经验。

如果你在下面这种路径直接跑：

bash 复制代码

cd /mnt/d/studyspace/OpenClaw_git/openclaw
pnpm install

很容易遇到：

text 复制代码

ERR_PNPM_EACCES: permission denied, rename ...

根本原因通常不是简单的"没权限"，而是：

项目在 Windows 文件系统里
pnpm 在 WSL 中安装依赖
编辑器、杀毒、索引器、Windows 文件锁可能同时干扰

因此最终推荐做法是：

Windows 上保留源码副本，真正安装和构建时，把仓库同步到 WSL 自己的 Linux 文件系统中。

十、把 Windows 上的仓库同步到 WSL 工作目录

如果 Windows 上已经有仓库，不需要再 git clone 一遍，直接同步：

bash 复制代码

mkdir -p ~/workspace/openclaw
rsync -a --delete \
  --exclude node_modules \
  --exclude ui/node_modules \
  /mnt/d/studyspace/OpenClaw_git/openclaw/ \
  ~/workspace/openclaw/
cd ~/workspace/openclaw

这样做有两个好处：

避开 GitHub clone 网络不稳定的问题
避免把 Windows 侧残缺或损坏的 node_modules 一起带过来

十一、WSL 里的代理必须单独配置

这一点也非常重要。

很多人会发现：

Windows 浏览器可以正常访问外网
代理软件一直开着
但 WSL 里的 curl、git、pnpm 还是访问 GitHub 失败

原因在于：
WSL 不会自动继承 Windows GUI 代理。

如果你的代理软件本地提供：

socks: 10800
http: 10801

那么在 Ubuntu 中应优先配置 HTTP 代理。

先获取 Windows 主机在 WSL 中的地址：

bash 复制代码

HOST_IP=$(awk '/nameserver/ {print $2; exit}' /etc/resolv.conf)
echo $HOST_IP

然后设置代理：

bash 复制代码

export http_proxy=http://$HOST_IP:10801
export https_proxy=http://$HOST_IP:10801
export HTTP_PROXY=http://$HOST_IP:10801
export HTTPS_PROXY=http://$HOST_IP:10801

测试：

bash 复制代码

curl -I https://github.com
curl -I https://codeload.github.com

如果还不通

大概率要去 Windows 代理软件里打开：

Allow LAN
允许局域网连接

否则 WSL 访问不到宿主机的代理端口。

十二、正式安装 OpenClaw

在以下前提都满足后：

Ubuntu 已迁移到 D 盘
Node 和 pnpm 已安装
仓库已同步到 ~/workspace/openclaw
代理已验证可访问 GitHub 和 codeload

执行：

bash 复制代码

cd ~/workspace/openclaw
pnpm install
pnpm ui:build
pnpm build

完成后运行引导：

bash 复制代码

pnpm openclaw onboard --install-daemon

十三、Onboarding 推荐选择

第一次安装，建议尽量走最简路线。

推荐选择如下：

安全确认：Yes
模式：QuickStart
默认模型：Keep current (qwen-portal/coder-model)
聊天渠道：Skip for now
搜索提供商：Skip for now
Skills：No
Hooks：Skip for now

这样最适合第一次先跑通系统，而不是一上来把所有能力全配完。

十四、安装完成后怎么启动

安装完成后，很多人会误以为 tui、Dashboard 或 CLI 自己就能直接工作。

实际上，OpenClaw 的日常使用方式应该分成两层：

1. 先启动 gateway （18789 是我这边代理的端口，根据自己代理端口自行调整）

进入仓库：

bash 复制代码

cd ~/workspace/openclaw
pnpm openclaw gateway --port 18789 --verbose

这个终端要保持开着，因为它就是后台服务。

2. 再打开访问入口

你有两个常见入口：

浏览器 Dashboard

在 Windows 浏览器打开：

text 复制代码

http://localhost:18789/

如果需要 token，就用 onboarding 给出的完整链接。

终端 UI

新开一个 Ubuntu 终端，执行：

bash 复制代码

cd ~/workspace/openclaw
pnpm openclaw tui

如果你先开 tui，但 gateway 没启动，就会看到：

text 复制代码

not connected to gateway - message not sent

这不是安装失败，只是顺序错了。

十五、为什么 `openclaw --help` 会提示 command not found

因为你现在跑的是源码仓库模式，不是全局 npm 安装模式。

所以优先使用：

bash 复制代码

pnpm openclaw --help

而不是直接执行：

bash 复制代码

openclaw --help

十六、为什么 `pnpm openclaw agent --message ...` 会失败

这是另一个很容易误解的点。

如果你直接执行：

bash 复制代码

pnpm openclaw agent --message "你好"

它可能会报要你传：

--to
--session-id
--agent

这不是环境有问题，而是 agent 命令本身需要你明确指定会话目标。

第一次上手时，不建议从 agent CLI 裸命令开始，更推荐：

先用 Dashboard
或者用 pnpm openclaw tui

十七、Dashboard 出现 `500 Request rate increased too quickly` 是什么问题

这通常不是 OpenClaw 自己挂了，而更像是你当前模型提供商的限流提示，比如 Qwen 侧请求过快。

出现这种情况时建议：

关闭多余测试窗口
不要连续刷新和重试
等几十秒再发一条短消息

这类问题一般属于模型侧限流，不是本地 gateway 安装失败。

十八、最终推荐的最短复现流程

如果你以后要在另一台 Windows 机器上重装，照下面这套最短流程就行。

Windows 管理员 PowerShell

powershell 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl.exe --set-default-version 2

Ubuntu 初始化成功后迁移到 D 盘

powershell 复制代码

wsl --shutdown
mkdir D:\WSL
wsl --export Ubuntu D:\WSL\ubuntu.tar
wsl --unregister Ubuntu
mkdir D:\WSL\Ubuntu
wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\ubuntu.tar --version 2
wsl -d Ubuntu

Ubuntu 中安装基础环境

bash 复制代码

sudo apt update
sudo apt install -y build-essential curl git unzip rsync
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pnpm@10

同步仓库到 WSL 本地目录

bash 复制代码

mkdir -p ~/workspace/openclaw
rsync -a --delete \
  --exclude node_modules \
  --exclude ui/node_modules \
  /mnt/d/studyspace/OpenClaw_git/openclaw/ \
  ~/workspace/openclaw/
cd ~/workspace/openclaw

配代理

bash 复制代码

HOST_IP=$(awk '/nameserver/ {print $2; exit}' /etc/resolv.conf)
export http_proxy=http://$HOST_IP:10801
export https_proxy=http://$HOST_IP:10801
export HTTP_PROXY=http://$HOST_IP:10801
export HTTPS_PROXY=http://$HOST_IP:10801

安装和构建 OpenClaw

bash 复制代码

pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

日常启动

如果你当前在 Windows 桌面环境里，建议先打开 Windows PowerShell，然后进入 Ubuntu：

powershell 复制代码

wsl -d Ubuntu

进入 Ubuntu 后，再启动 OpenClaw gateway：

bash 复制代码

cd ~/workspace/openclaw
pnpm openclaw gateway --port 18789 --verbose

最后回到 Windows 浏览器访问：

text 复制代码

http://localhost:18789/

十九、这次安装最重要的三个结论

最后把最关键的经验再压缩成三句：

OpenClaw 源码版在 Windows 上最稳的跑法是 WSL，不是原生 PowerShell
不要在 /mnt/d 下直接跑 pnpm install，要把项目放到 WSL 本地目录
Windows 开代理不等于 WSL 自动能用，WSL 必须单独配置代理

二十、总结

如果你只想记住一句话，那就是：

Windows 提供系统，WSL 提供 Linux 环境，OpenClaw 项目放在 WSL 本地目录里，代理单独配，日常先起 gateway，再开 Dashboard。

按这套流程走，基本就能避开这次安装中遇到的大多数坑。

OpenClaw 最终安装指南：Windows 下用 WSL2 + Ubuntu 跑通源码版