【OpenClaw】WSL2 源码安装 OpenClaw 完整指南 (20260313 版本)

WSL2 源码安装 OpenClaw 完整指南

1. 环境准备

1.1 前提条件

Windows 10/11 已安装 WSL2
WSL2 发行版（推荐 Ubuntu 22.04+）
网络连接正常

1.2 启用 WSL2 Systemd 支持

必须步骤：OpenClaw 依赖 systemd 用户服务

bash 复制代码

# 创建/编辑 wsl.conf
sudo tee /etc/wsl.conf << 'EOF'
[boot]
systemd=true
EOF

# 验证配置
cat /etc/wsl.conf

重启 WSL2 使配置生效：

powershell
# 在 Windows PowerShell 中执行
wsl --shutdown
然后重新打开 WSL2 终端。

1.3 验证 Systemd

bash 复制代码

# 检查 systemd 是否作为 PID 1
ps -p 1 -o comm=
# 预期输出: systemd

# 检查 systemd 用户服务
systemctl --user status
注意：如果显示 Failed to connect to bus，参考 问题3 解决。

2. 安装步骤

2.1 安装 Node.js 22+ 和 pnpm

bash 复制代码

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

# 加载 nvm
source ~/.bashrc

# 安装 Node 22 LTS
nvm install 22
nvm use 22
nvm alias default 22

# 验证
node -v  # 应显示 v22.x.x
npm -v

# 安装 pnpm
npm install -g pnpm
pnpm -v

2.2 克隆 OpenClaw 源码

bash 复制代码

# 创建工作目录
mkdir -p ~/06_openclaw && cd ~/06_openclaw

# 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 查看分支/标签（可选）
git branch -l
git tag -l

2.3 安装依赖

bash 复制代码

# 根目录依赖
pnpm install

# UI 子目录依赖（关键！容易遗漏）
cd ui && pnpm install && cd ..

2.4 构建项目

bash 复制代码

# 构建 UI（关键步骤）
pnpm ui:build

# 注意：构建输出在 dist/control-ui/，不是 ui/dist/
# 验证构建结果
ls -la dist/control-ui/index.html

# 创建正确的目录结构（Gateway 查找路径）
mkdir -p packages/ui/dist
cp -r dist/control-ui/* packages/ui/dist/

# 验证
ls packages/ui/dist/index.html

# 构建 CLI
pnpm build

2.5 创建全局命令

bash 复制代码

# 确保入口文件可执行
chmod +x openclaw.mjs

# 方法1：使用 pnpm link（推荐）
pnpm link --global

# 如果失败，手动创建软链接
ln -sf ~/06_openclaw/openclaw/openclaw.mjs ~/.local/share/pnpm/openclaw

# 或者使用 nvm 的 bin 目录
ln -sf ~/06_openclaw/openclaw/openclaw.mjs /home/$USER/.nvm/versions/node/v22.22.1/bin/openclaw

# 验证
which openclaw
openclaw --version
2.6 启动 Gateway
bash
# 前台运行（推荐，方便查看日志）
openclaw gateway run

# 后台运行
nohup openclaw gateway run > /tmp/openclaw.log 2>&1 &
注意：openclaw gateway start 需要 systemd 服务，如果 systemd 用户服务不可用，使用 run 命令。

3. 问题汇总与解决方案

问题1：Node 版本过低

现象：

text 复制代码

SyntaxError: Unexpected reserved word
await installProcessWarningFilter();

原因：系统默认 Node 版本过低（如 v12.22.9），不支持顶层 await。

解决：

bash 复制代码

# 检查当前 Node
which node      # 可能显示 /usr/bin/node
node -v         # 可能显示 v12.x.x

# 切换到 nvm 的 Node
nvm use 22

# 确保 PATH 优先使用 nvm
export PATH="/home/$USER/.nvm/versions/node/v22.22.1/bin:$PATH"

# 验证
node -v  # 应显示 v22.22.1

问题2：pnpm 全局命令找不到

现象：

text 复制代码

pnpm link --global
ERR_PNPM_NO_GLOBAL_BIN_DIR Unable to find the global bin directory
原因：pnpm 全局 bin 目录未设置或不在 PATH 中。

解决：

bash
# 方法1：设置 pnpm
pnpm setup
source ~/.bashrc

# 方法2：手动设置
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# 方法3：直接使用 nvm 的 bin 目录
ln -sf ~/06_openclaw/openclaw/openclaw.mjs /home/$USER/.nvm/versions/node/v22.22.1/bin/openclaw

问题3：Systemd 用户服务连接失败

现象：

bash 复制代码

$ systemctl --user status
Failed to connect to bus: No such file or directory

原因：WSL2 中 D-Bus 用户会话未启动，或 XDG_RUNTIME_DIR 设置错误。

解决：

bash 复制代码

# 检查当前用户 ID
id -u  # 应显示 1000

# 设置环境变量
export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus

# 创建目录
sudo mkdir -p /run/user/$(id -u)
sudo chown $(id -un):$(id -gn) /run/user/$(id -u)

# 验证
systemctl --user status
永久修复（添加到 ~/.bashrc）：

bash
cat >> ~/.bashrc << 'EOF'

# Fix WSL2 systemd user services
USER_ID=$(id -u)
export XDG_RUNTIME_DIR=/run/user/$USER_ID
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$USER_ID/bus
EOF

source ~/.bashrc

问题4：UI 构建失败或资源找不到

现象：

text 复制代码

Control UI assets missing; building (ui:build, auto-installs UI deps)...
ls: cannot access 'packages/ui/dist/index.html': No such file or directory

原因：

Vite 构建输出到 dist/control-ui/，不是 packages/ui/dist/

Gateway 查找 UI 资源的路径是 packages/ui/dist/

解决：

bash 复制代码

cd ~/06_openclaw/openclaw
# 确保 UI 依赖安装
cd ui && pnpm install && cd ..

# 构建 UI
pnpm ui:build

# 创建正确的目录结构
mkdir -p packages/ui/dist
cp -r dist/control-ui/* packages/ui/dist/

# 或者创建软链接
mkdir -p dist
ln -sf ../packages/ui/dist dist/control-ui

# 验证
ls packages/ui/dist/index.html

问题5：Gateway 提示服务禁用

现象：

text 复制代码

Gateway service disabled.
Start with: openclaw gateway install
Start with: systemctl --user start openclaw-gateway.service

原因：openclaw gateway start 需要 systemd 服务，但 WSL2 中 systemd 用户服务可能不可用。

解决：

bash 复制代码

# 使用 run 命令前台运行（推荐）
openclaw gateway run

# 或使用 nohup 后台运行
nohup openclaw gateway run > /tmp/openclaw.log 2>&1 &

问题6：软链接指向错误

现象：

bash 复制代码

ln -sf ~/06_openclaw/openclaw/dist/cli.js ~/.local/share/pnpm/openclaw
chmod: cannot operate on dangling symlink

原因：dist/cli.js 不存在，实际入口是 openclaw.mjs。

解决：

bash 复制代码

# 检查 package.json 的 bin 字段
cat package.json | grep -A3 '"bin"'
# 输出: "openclaw": "openclaw.mjs"

# 使用正确的入口文件
ln -sf ~/06_openclaw/openclaw/openclaw.mjs ~/.local/share/pnpm/openclaw
chmod +x ~/06_openclaw/openclaw/openclaw.mjs

问题7：npm 损坏

现象：

bash 复制代码

sudo npm uninstall -g openclaw
Error: Cannot find module 'semver'

原因：npm 自身损坏，模块缺失。

解决：

bash 复制代码

# 方法1：使用 nvm 重装 Node
nvm uninstall 22
nvm install 22
nvm use 22

# 方法2：绕过 npm，直接使用 pnpm
cd ~/06_openclaw/openclaw
pnpm exec openclaw gateway run
4. 验证安装
4.1 检查 Gateway 状态
bash
# 在另一个终端执行
openclaw status
预期输出：

text
Gateway │ local · ws://127.0.0.1:18789 · reachable ✅

4.2 访问 Web UI

bash 复制代码

# 自动打开浏览器（带令牌）
openclaw dashboard

# 或获取 URL
openclaw dashboard --no-open
手动访问：

http://127.0.0.1:18789/

Chat: http://127.0.0.1:18789/chat?session=main

4.3 健康检查

bash 复制代码

openclaw doctor
openclaw gateway probe

5. 常用命令

命令说明

复制代码

openclaw gateway run	前台启动 Gateway
openclaw gateway start	通过 systemd 启动（需要服务安装）
openclaw gateway stop	停止 Gateway
openclaw status	查看整体状态
openclaw doctor	诊断配置问题
openclaw dashboard	打开 Web UI
openclaw logs gateway --follow	查看实时日志
openclaw config get gateway.token	获取访问令牌

参考链接

OpenClaw 官方文档: https://docs.openclaw.ai
GitHub 仓库: https://github.com/openclaw/openclaw
WSL2 Systemd 支持: https://learn.microsoft.com/en-us/windows/wsl/wsl-config