一、OpenClaw 是什么？

OpenClaw 是一个自托管的个人AI助手，通过一个本地网关连接你常用的聊天渠道（WhatsApp、Telegram、Slack、Discord、iMessage等），并支持语音交互、实时画布、浏览器控制、设备节点（macOS/iOS/Android）等强大功能。你可以把它想象成一个开源版的“钢铁侠JARVIS”。

官方推荐在 WSL2（Windows Subsystem for Linux） 上运行，以获得最佳体验。本教程以 Ubuntu 22.04（WSL2）为例，同时适用于原生Linux系统。

---

二、准备工作

2.1 系统要求

• 操作系统：Windows 10/11（启用WSL2） 或 Linux（Ubuntu 20.04+）

• 内存：至少4GB（推荐8GB+）

• 磁盘空间：至少2GB（用于代码和依赖）

• 网络：能够访问GitHub和npm registry

2.2 安装WSL2（Windows用户）

以管理员身份打开 PowerShell，执行：

wsl --install

该命令会自动安装默认的 Ubuntu 发行版并启用WSL2。安装完成后重启电脑。

重启后，打开开始菜单找到 Ubuntu 图标，首次启动会提示创建用户名和密码（请记好，后续sudo会用到）。

2.3 更新系统包（WSL2/Linux通用）

在Ubuntu终端中执行：

sudo apt update && sudo apt upgrade -y

2.4 安装nvm（Node版本管理器）

nvm可以让你轻松安装和管理多个Node版本，避免权限问题。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重新加载配置文件：

source ~/.bashrc

验证nvm是否安装成功：

nvm --version

如果显示版本号（如0.39.7），说明成功。

⚠️ 如果 nvm 命令找不到，请关闭当前终端，重新打开一个新终端，或者手动执行 export NVM_DIR="$HOME/.nvm" 和 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" 加载。

2.5 安装Node.js 22

使用nvm安装并设为默认：

nvm install 22
nvm use 22
nvm alias default 22

检查版本：

node --version   # 应输出 v22.x.x
which node       # 应指向 /home/你的用户名/.nvm/...

2.6 安装pnpm

pnpm是高性能的包管理器，OpenClaw项目依赖它。

npm install -g pnpm

验证安装：

pnpm --version

---

三、获取OpenClaw源码

在用户主目录下（或你喜欢的位置）克隆项目：

git clone https://github.com/openclaw/openclaw.git
cd openclaw

---

四、安装依赖

执行pnpm安装，这会根据 pnpm-lock.yaml 下载所有依赖包：

pnpm install

安装过程中可能会看到一些下载警告，属于正常现象。耐心等待，最终应显示类似下面的成功信息：

Progress: resolved 1245, reused 1242, downloaded 0, added 1243, done
... (各种postinstall脚本)
Done in 10.1s using pnpm v10.23.0

可能遇到的警告

Ignored build scripts: @discordjs/opus, @tloncorp/tlon-skill.

如果你需要使用 Discord语音 或 Tlon集成，可以运行以下命令允许它们执行构建脚本：

pnpm approve-builds

然后根据提示选择允许即可。否则可以忽略，不影响核心功能。

---

五、构建项目

pnpm build

构建过程会生成 dist/ 目录，并将TypeScript编译为JavaScript。如果一切顺利，终端最后会显示 build completed 类似信息。

---

六、运行OpenClaw

6.1 运行向导（首次配置，推荐）

pnpm openclaw onboard --install-daemon

向导会帮助你：

• 设置网关（控制平面）

• 配置聊天渠道（如WhatsApp、Telegram）

• 安装后台服务（确保网关常驻）

6.2 直接启动网关（手动模式）

pnpm openclaw gateway --port 18789 --verbose

网关默认监听在 127.0.0.1:18789，打开浏览器访问 http://localhost:18789 即可看到控制界面。

6.3 测试发送消息

打开另一个终端，进入项目目录，发送测试消息（请替换为真实号码）：

pnpm openclaw message send --to +1234567890 --message "Hello from OpenClaw"

如果一切正常，目标号码会收到消息（需要先配置对应渠道）。

---

七、常见问题与解决方案

Q1: 安装pnpm时提示 EACCES: permission denied

原因：系统自带的Node安装在 /usr/local，普通用户无写入权限。
解决：使用nvm安装Node（已在教程中覆盖），全局包会安装在用户目录下，无需sudo。

Q2: 运行 pnpm install 时提示 Node 版本过低

错误示例：

Unsupported engine: wanted: {"node":">=22.12.0"} (current: {"node":"v18.19.1"})

原因：系统Node版本低于22.12.0。
解决：执行 nvm install 22 和 nvm use 22 切换到高版本。

Q3: 构建时出现语法错误 Unexpected token 'with'

错误示例：

SyntaxError: Unexpected token 'with'

原因：Node版本过低（<20），不支持 import ... with {type: 'json'} 语法。
解决：升级Node到22+（步骤见2.5）。

Q4: 下载依赖速度极慢

原因：npm官方源在国内访问较慢。
解决：可以临时使用淘宝镜像：

pnpm config set registry https://registry.npmmirror.com

安装完成后可以恢复官方源：

pnpm config set registry https://registry.npmjs.org

Q5: 运行 openclaw 命令找不到

原因：pnpm的bin目录可能不在PATH中。
解决：使用 pnpm openclaw 而不是直接 openclaw。或者将pnpm bin目录加入PATH：

export PATH="$(pnpm bin):$PATH"

然后就可以直接运行 openclaw 了。

Q6: 安装过程中卡住（长时间无响应）

按 Ctrl + C 终止，然后尝试强制重新安装：

pnpm install --force

或者针对特定包重试：

pnpm rebuild node-llama-cpp

---

八、后续使用与升级

8.1 常用命令

• 启动网关：pnpm openclaw gateway

• 查看帮助：pnpm openclaw --help

• 运行健康检查：pnpm openclaw doctor

• 更新到最新版本：pnpm openclaw update --channel stable

8.2 添加聊天渠道

配置渠道需要修改 ~/.openclaw/openclaw.json 配置文件，或者再次运行向导：

pnpm openclaw onboard

具体渠道的配置参数请参考官方文档：Channels

8.3 启动开发模式（修改代码后自动重载）

pnpm gateway:watch

代码变更后会重新编译并重启网关。

---

九、总结

至此，你已经成功在本地安装了OpenClaw个人AI助手。你可以通过Web界面、命令行或已配置的聊天渠道与它互动。OpenClaw的强大之处在于它的可扩展性——你可以编写自己的“技能”（Skills），让它自动化处理各种任务。

如果在安装过程中遇到其他问题，欢迎查阅官方文档或在GitHub提交Issue。祝玩得开心！

---

附录：WSL2与Windows文件互访

• 在WSL2中，Windows的C盘挂载在 /mnt/c/

• 在Windows资源管理器中，输入 \\wsl$\Ubuntu 即可访问WSL2的文件系统