OpenClaw 部署指南

📋 目录

• 项目简介
• 安装方式对比
• Windows WSL2 完整部署流程
• 常见问题解决
• 启动和使用

---

项目简介

OpenClaw 是一个可以运行在你自己设备上的个人 AI 助手。

核心功能

• 多渠道消息整合 - 支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、Matrix、WebChat 等
• 语音交互 - macOS/iOS/Android 支持语音唤醒和对话模式
• 本地网关 - 单一控制平面管理所有会话、渠道、工具和事件
• 多代理路由 - 不同渠道/账户路由到隔离的代理工作区
• Live Canvas - 代理驱动的可视化工作空间
• 配套应用 - macOS 菜单栏应用 + iOS/Android 节点应用

系统要求

• Node.js ≥ 22
• macOS、Linux 或 Windows (强烈推荐 WSL2)
• pnpm（从源码构建时需要）

---

安装方式对比

安装方式	适用人群	难度	可修改性	隔离性	执行方式
npm 全局安装	普通用户	⭐	❌	❌	运行编译后的 dist/
源码构建	开发者	⭐⭐	✅	❌	tsx 直接运行 TypeScript
Docker 部署	运维/服务器	⭐⭐	❌	✅	容器化运行

1. npm 全局安装（最简单）

npm install -g openclaw@latest
openclaw onboard --install-daemon

特点：

• ✅ 一行命令完成
• ✅ 安装已编译的产物
• ❌ 无法修改源码
• ❌ 只能使用发布版本

2. 源码构建（开发者推荐）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

特点：

• ✅ 可修改源码和调试
• ✅ 可用最新 dev 分支
• ✅ 支持热重载：pnpm gateway:watch
• ✅ 可运行测试：pnpm test

3. Docker 部署

./docker-setup.sh

特点：

• ✅ 完全隔离的容器环境
• ✅ 适合服务器/VPS
• ❌ 需要 Docker 环境

---

Windows WSL2 完整部署流程

重要提示： Windows 原生支持不完善，强烈推荐使用 WSL2！

步骤 1：安装 WSL2

1.1 安装 WSL 和 Ubuntu

# PowerShell 管理员模式运行
wsl --install -d Ubuntu

1.2 切换 WSL 网络为镜像模式（解决代理问题）

创建配置文件 %USERPROFILE%\.wslconfig：

Set-Content -Path "$env:USERPROFILE\.wslconfig" -Value "[wsl2]`nnetworkingMode=mirrored"

重启 WSL：

wsl --shutdown

1.3 移动 WSL 到其他盘（可选，节省 C 盘空间）

# 创建目标目录
New-Item -Path "F:\WSL" -ItemType Directory -Force

# 导出 Ubuntu
wsl --export Ubuntu F:\WSL\ubuntu.tar

# 注销原发行版
wsl --unregister Ubuntu

# 导入到新位置
wsl --import Ubuntu F:\WSL\Ubuntu F:\WSL\ubuntu.tar

# 删除临时文件
Remove-Item F:\WSL\ubuntu.tar

验证：

wsl -d Ubuntu -e bash -c "pwd"

---

步骤 2：配置 WSL 环境

2.1 进入 WSL

wsl -d Ubuntu

以下命令在 WSL Ubuntu 内部执行：

2.2 配置清华镜像源（加速 apt）

# 备份原文件
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 写入清华源
sudo tee /etc/apt/sources.list > /dev/null << 'EOF'
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
EOF

# 清理缓存并更新
sudo rm -rf /var/lib/apt/lists/*
sudo apt update

2.3 安装 Node.js 22（使用 nvm + 淘宝镜像）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 加载 nvm
export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"

# 使用淘宝镜像安装 Node.js 22
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install 22

# 验证
node --version
npm --version

2.4 配置永久环境变量

cat >> ~/.bashrc << 'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
EOF

source ~/.bashrc

2.5 创建全局符号链接（让 bash 脚本能找到 node）

NODE_PATH=$(which node)
NPM_PATH=$(which npm)
sudo ln -sf $NODE_PATH /usr/local/bin/node
sudo ln -sf $NPM_PATH /usr/local/bin/npm

2.6 安装 pnpm

npm install -g pnpm

# 配置淘宝镜像
pnpm config set registry https://registry.npmmirror.com

---

步骤 3：克隆项目并构建

3.1 克隆仓库

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

如果需要配置代理：

export http_proxy=http://127.0.0.1:33210
export https_proxy=http://127.0.0.1:33210
git clone https://github.com/openclaw/openclaw.git

3.2 安装依赖

pnpm install

3.3 构建 UI

pnpm ui:build

3.4 构建项目

pnpm build

---

步骤 4：运行引导向导

pnpm openclaw onboard --install-daemon

向导会配置：

• 模型认证（Anthropic/OpenAI）
• 网关设置
• 消息渠道（WhatsApp/Telegram 等）
• 后台服务安装

---

启动和使用

检查网关状态

pnpm openclaw gateway status

手动启动网关（前台）

pnpm openclaw gateway --port 18789 --verbose

访问控制面板

浏览器打开：http://127.0.0.1:18789/

发送测试消息

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

与 AI 助手对话

pnpm openclaw agent --message "你好" --thinking high

开发模式（热重载）

pnpm gateway:watch

---

常见问题解决

1. 构建时找不到 node 命令

原因： bash 非交互模式不加载 .bashrc

解决： 创建全局符号链接

NODE_PATH=$(which node)
sudo ln -sf $NODE_PATH /usr/local/bin/node

2. npm 下载速度慢

解决： 配置淘宝镜像

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

3. WSL 无法访问 Windows 代理

解决： 切换到镜像网络模式（见步骤 1.2）

4. rolldown 找不到原生绑定

原因： Windows node_modules 缺少 Linux 原生模块

解决： 在 WSL 内部重新 pnpm install

5. Canvas A2UI bundling 失败

临时方案： 创建空占位文件

touch src/canvas-host/a2ui/a2ui.bundle.js
touch src/canvas-host/a2ui/.bundle.hash

完整方案： 在 WSL 内完整构建

---

快速验证

# 检查状态
pnpm openclaw status

# 健康检查
pnpm openclaw health

# 安全审计
pnpm openclaw security audit --deep

---

开发命令速查

命令	说明
pnpm openclaw ...	运行 CLI 命令
pnpm build	TypeScript 编译
pnpm gateway:watch	热重载开发模式
pnpm test	运行测试
pnpm lint	代码检查
pnpm format	格式化代码

---

相关文档

• 官网：https://openclaw.ai
• 文档：https://docs.openclaw.ai
• GitHub：https://github.com/openclaw/openclaw
• Discord：https://discord.gg/clawd