一、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 的文件系统
