标题

在 WSL2 上从源码安装 OpenClaw（2026 年最新版）完整实录：踩坑 + 解决方案

摘要（约 100 字）

在 WSL2 (Ubuntu 20.04) 上从 GitHub 源码编译安装 OpenClaw 个人 AI 助手（2026.1.30 版），过程中遇到 Node 版本过低、pnpm 未安装、node-llama-cpp 编译失败（CMake 版本不足）、gateway 默认只绑 loopback、Control UI 安全策略（secure context 要求 HTTPS 或 localhost）等多个问题。通过升级 Node 到 24、使用 nvm 管理、安装新版 CMake、手动调整 gateway bind 为 lan、启用 allowInsecureAuth 等方式最终成功部署，并通过内网 IP 访问 Control UI。适合想深度自定义或在 Linux 环境自建 OpenClaw 的开发者参考。

正文

1. 环境与准备

操作系统：WSL2 + Ubuntu 20.04.6 LTS
内核：6.6.87.2-microsoft-standard-WSL2
目标：从源码编译运行最新版 OpenClaw（仓库：https://github.com/openclaw/openclaw）

工作目录：

cd /mnt/d/sourceCode/ai_tools
mkdir openclaw && cd openclaw
git clone https://github.com/openclaw/openclaw.git
cd openclaw

2. 主要踩坑与解决路径

问题 1：pnpm & Node 版本过旧

现象：pnpm install 提示 command not found；apt 安装的 nodejs 只有 v10.19。

解决：

• 先装一个临时的 nodejs（用来装 nvm 和 pnpm）
• 安装 nvm（v0.40.3）
• 用 nvm 安装 Node 24（当时最新 LTS 系列）
• 全局安装 pnpm

关键命令：

sudo apt install nodejs
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
. "$HOME/.nvm/nvm.sh"
nvm install 24
npm install -g pnpm
pnpm -v   # 应看到 10.23.0 或更高

问题 2：pnpm install 时 node-llama-cpp 编译失败

现象：postinstall 脚本报 CMake 3.19+ 要求，但系统只有 3.16；多次 fallback 失败，最终 exit code 1。

解决：

pip3 install --user cmake
# 安装后得到 cmake 4.2.1（满足要求）
pnpm install   # 再次执行，这次编译通过（耗时约 8 分钟）

注意：node-llama-cpp 会尝试构建 CUDA / Vulkan / CPU 三种版本，最终 fallback 到 CPU 版成功。

问题 3：构建与基本启动

pnpm ui:build          # 构建 Control UI（vite）
pnpm build             # 完整构建（包括 canvas-a2ui 等）

问题 4：onboard 完成后 Web UI 连接被拒绝（ERR_CONNECTION_REFUSED）

现象：浏览器访问 http://127.0.0.1:18789/?token=xxx 失败，gateway 未监听端口。

解决路径（最有效）：

• 先手动在前台启动看日志：

  pnpm openclaw gateway --port 18789 --verbose
  

• 确认启动成功后再考虑 daemon。

问题 5：内网 IP（172.17.45.80）访问失败 / 只绑 loopback

现象：ss -ltnp | grep 18789 只看到 127.0.0.1；内网其他设备 connection refused。

解决：
OpenClaw gateway --bind 只支持预设模式：loopback / lan / tailnet / auto / custom

推荐命令（内网访问）：

pnpm openclaw gateway --port 18789 --bind lan --verbose

如果提示 Refusing to bind non-loopback without auth，则需先配置 token（持久化方式）：

// 编辑 ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "5144da0a0931c0a8aeedd7733401942cbf94630cc6e242d1"
    }
  }
}

问题 6：Control UI 报错 disconnected (1008): requires HTTPS or localhost (secure context)

现象：用 http://172.17.45.80:18789/overview 访问时 WebSocket 断开，浏览器阻止 device identity。

原因：现代浏览器对非 localhost + 非 HTTPS 的页面有严格安全限制（secure context）。

解决（三种选其一，按推荐顺序）：

1. 最推荐：SSH 端口转发（零改动、安全）
   本地电脑运行：

   ssh -L 18789:127.0.0.1:18789 用户名@172.17.45.80
   

   浏览器访问：http://localhost:18789/?token=xxx

2. 临时降级：允许不安全认证（token-only 模式）
   在 ~/.openclaw/openclaw.json 补充：

   {
     "gateway": {
       "controlUi": {
         "allowInsecureAuth": true
       }
     }
   }
   

   重启 gateway 后即可用 http + 内网 IP + token 访问（但安全性降低）。

3. 长期推荐：Tailscale Serve 做 HTTPS 代理（官方偏好方案）

3. 最终启动方式总结

• 开发调试：pnpm openclaw gateway --bind lan --verbose
• 生产建议：调整 config 后用 systemd daemon 运行

  pnpm openclaw onboard --install-daemon   # 初次
  systemctl --user restart openclaw-gateway
  

4. 小结与建议

从源码安装 OpenClaw 在 WSL2 上可行，但对 Node/CMake/构建工具链要求较高，建议：

• 优先用 nvm 管理 Node ≥22
• 遇到 llama.cpp 编译问题先升级 cmake
• 远程访问强烈推荐 SSH 转发 或 Tailscale（避免直接暴露 + 解决 secure context 问题）
• 安全第一：工具开启后 agent 可能执行任意代码，建议先用最小权限模式

如果你也准备在 VPS / WSL 上自建 OpenClaw，欢迎留言分享你的配置或新坑～ 🦞