OpenClaw 安装部署完整教程

本教程手把手教您安装部署 OpenClaw，并连接飞书、QQ 等即时通讯平台。

一、什么是 OpenClaw？

OpenClaw 是一个开源的 AI Agent 平台，让你能将 AI 助手接入各种通讯工具（飞书、QQ、Telegram、Discord 等），实现自动化工作流。

核心特性：

多平台支持（飞书、QQ、企业微信、Slack...）
插件化架构（技能系统）
本地运行，数据私有
支持子 Agent 和 ACP 协议

二、环境准备

系统要求

项目	最低要求	推荐配置
操作系统	Ubuntu 20.04+ / Debian 11+ / macOS 11+ / Windows 10+	Ubuntu 22.04 LTS / macOS 12+
CPU	2 核心	4+ 核心
内存	4 GB RAM	8+ GB RAM
硬盘	20 GB 可用空间	50+ GB SSD
GPU	可选（CUDA 11.8+）	NVIDIA GPU 8GB+（用于本地 LLM）

依赖软件（所有平台）

Node.js 20+（需包含 npm）
pnpm（推荐）或 npm
Git
（可选）Docker & Docker Compose
（可选）CUDA 环境（用于 GPU 加速）

二-1. Linux 环境准备（Ubuntu/Debian）

安装 Node.js 20

bash

# 使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

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

安装 pnpm

bash

npm install -g pnpm
pnpm --version

安装 Git

bash

sudo apt-get install -y git
git --version

二-2. macOS 环境准备

安装 Homebrew（如果还没有）

bash

# 官方安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，根据终端提示将 Homebrew 添加到 PATH。

安装 Node.js 20

bash

# 使用 Homebrew
brew install node@20

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

安装 pnpm

bash

npm install -g pnpm
pnpm --version

安装 Git

bash

brew install git
git --version

配置环境变量（如需要）

如果 node 或 pnpm 命令找不到，可能需要添加到 PATH：

bash

# 编辑 ~/.zshrc 或 ~/.bash_profile
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="$HOME/.pnpm/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

二-3. Windows 环境准备

安装 Node.js 20

访问 Node.js 官网
下载 LTS 版本（20.x）
运行安装包，按默认选项安装

验证安装：

powershell

# 打开 PowerShell 或 CMD
node -v  # 应显示 v20.x.x
npm -v

安装 pnpm

powershell

npm install -g pnpm
pnpm --version

安装 Git

访问 Git 官网
下载 Windows 版本
安装时建议选择：
- "Use Git from the Windows Command Prompt"（添加到 PATH）
- "Checkout as-is, commit Unix-style line endings"
验证：
powershell
```
git --version
```

（可选）安装 WSL2（推荐）

对于 Windows 用户，强烈建议使用 WSL2（Windows Subsystem for Linux）：

优势：

完整 Linux 环境，与教程完全兼容
更好的 Docker 支持
避免 Windows 路径问题

安装 WSL2：

powershell

# 以管理员身份运行 PowerShell
wsl --install
# 默认安装 Ubuntu

安装后重启，按提示创建 Linux 用户。后续所有操作都在 WSL2 中进行，与 Linux 章节完全一致。

三-1. Linux 安装 OpenClaw

方式一：全球镜像（推荐）

bash

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

# 2. 安装依赖（使用 pnpm，更快）
pnpm install

# 3. 构建项目
pnpm build

# 4. 启动 OpenClaw
# 开发模式（热重载）
pnpm dev

# 生产模式（后台运行）
pnpm start

方式二：国内镜像（speedup）

bash

# 1. 配置镜像源（可选加速）
pnpm config set registry https://registry.npmmirror.com

# 2. 克隆
git clone https://gitee.com/openclaw/openclaw.git  # 或 GitHub
cd openclaw

# 3. 安装 + 构建
pnpm install --frozen-lockfile
pnpm build

# 4. 运行
pnpm start

首次运行：OpenClaw 会在 ~/.openclaw/ 创建配置目录。

三-2. macOS 安装 OpenClaw

macOS 上的安装与 Linux 几乎完全相同。

步骤

bash

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

# 2. 安装依赖
pnpm install

# 3. 构建
pnpm build

# 4. 启动
# 开发模式
pnpm dev

# 生产模式（会在后台运行，日志输出到控制台）
pnpm start

使用 pm2 管理进程（推荐）

bash

# 安装 pm2（进程管理器）
npm install -g pm2

# 启动 OpenClaw
cd /path/to/openclaw
pm2 start "pnpm start" --name openclaw

# 设置开机自启
pm2 save
pm2 startup
# 按提示执行生成的命令

# 查看日志
pm2 logs openclaw

# 停止/重启
pm2 stop openclaw
pm2 restart openclaw

注意事项

配置文件路径同样是 ~/.openclaw/config.yml
如果需要开放外部访问，修改 host: 127.0.0.1 为 host: 0.0.0.0
macOS 防火墙可能会提示是否允许 node 接收网络连接，点击「允许」

三-3. Windows 安装 OpenClaw

方式 A：在 WSL2 中安装（强烈推荐）

如果已经安装了 WSL2（见上文），直接在 WSL2 的 Linux 环境中按 Linux 安装步骤操作即可。

优势：

100% 兼容教程
性能好
支持 Docker
路径问题少

方式 B：在 Windows 原生环境中安装

步骤

powershell

# 1. 打开 PowerShell 或 CMD
# 克隆仓库（需要 Git）
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖
pnpm install

# 3. 构建
pnpm build

# 4. 启动
pnpm dev        # 开发模式
pnpm start      # 生产模式

使用 nodemon 自动重启（可选）

powershell

# 全局安装 nodemon
npm install -g nodemon

# 启动（文件变更时自动重启）
nodemon --watch src --exec "pnpm start"

使用 Windows 服务（可选）

可以使用 nssm（Non-Sucking Service Manager）将 OpenClaw 安装为 Windows 服务：

下载 nssm：https://nssm.cc/download

安装并运行：

powershell

nssm install OpenClaw "C:\Program Files\nodejs\node.exe" "C:\path\to\openclaw\dist\index.js"
nssm start OpenClaw

注意事项

配置文件位置：%USERPROFILE%\.openclaw\config.yml
- 通常路径为 C:\Users\YourName\.openclaw\config.yml
端口：默认 3000，确保防火墙允许
路径问题：Windows 路径使用反斜杠 \，但在配置文件中建议使用正斜杠 / 或双反斜杠 \\
权限：需要以普通用户运行，不建议用 Administrator

四、配置 OpenClaw

配置文件位置

平台	配置目录	配置文件路径
Linux	`~/.openclaw/`	`~/.openclaw/config.yml`
macOS	`~/.openclaw/`	`~/.openclaw/config.yml`
Windows	`%USERPROFILE%\.openclaw\`	`C:\Users\YourName\.openclaw\config.yml`

通用结构：

.openclaw/
├── config.yml              # 主配置
├── credentials/            # 凭证目录（不提交到 Git）
│   ├── feishu/
│   ├── qqbot/
│   └── wecom/
├── workspace/              # 工作区
│   ├── skills/             # 已安装技能
│   ├── memory/             # 记忆数据
│   └── logs/               # 日志（如果配置了）
└── logs/                  # 日志目录（如果配置了）

基础配置示例

编辑 ~/.openclaw/config.yml：

yaml

# OpenClaw 配置文件
version: 1

# 服务器设置
server:
  port: 3000               # 控制台端口
  host: 127.0.0.1          # 绑定地址（生产环境建议用反向代理）
  ssl:
    enable: false          # 启用 HTTPS（需证书）
    cert: /path/to/cert.pem
    key: /path/to/key.pem

# 日志设置
logging:
  level: info              # debug/info/warn/error
  file: ~/.openclaw/logs/openclaw.log
  maxSize: 10m
  maxFiles: 7

# AI 模型配置
models:
  default: openrouter/anthropic/claude-3.5-sonnet
  # 可用提供商：
  # - openrouter（推荐，多模型）
  # - openai
  # - anthropic
  # - ollama（本地）
  # - localai（本地）
  # - azure
  # - groq（高速）
  
# 频道配置（按需开启）
channels:
  feishu:
    enable: false
  qqbot:
    enable: false
  discord:
    enable: false
  telegram:
    enable: false
  wecom:
    enable: false

# 技能配置
skills:
  auto_install: true       # 自动安装推荐技能
  hub: https://clawhub.com # 技能仓库

五、连接飞书（ Lark / 飞书）

⚠️ 平台通用说明：飞书应用配置在所有平台上完全一致，唯一区别是本地 OpenClaw 的配置文件路径（见上表）。

步骤 1：创建飞书应用

访问飞书开放平台
登录后点击「创建应用」
选择「自建应用」→「机器人」
填写信息：
- 应用名称：OpenClaw 助手
- 应用图标：上传任意图标
- 描述：AI 助手机器人

步骤 2：配置权限

在「权限管理」页面，申请以下权限：

基础权限

im:read - 读取消息
im:write - 发送消息
im:message:send - 发送消息（V2 版本）

高级权限（需要审核）

contact:read - 读取通讯录（可选，用于 @提及）
contact:read_only - 只读通讯录

步骤 3：获取凭证

在「应用基本信息」页面：

复制 App ID（app_id）
点击「在飞书开放平台生成」按钮获取 App Secret
保存这两个值

步骤 4：配置事件订阅

进入「事件订阅」页面
开启「开启加密密钥」（随机生成，复制）
设置请求地址（稍后填写）
订阅事件：
- im.message.message_read_v1（已读回执）
- im.message.reaction.created_v1（ reacted）
- 主要勾选：im.message.receive_v1（接收消息）

请求地址格式：

https://你的域名或 IP:端口/api/v1/feishu/events

例如：https://openclaw.example.com/api/v1/feishu/events

⚠️ 暂勿保存，先完成下一步配置 OpenClaw

步骤 5：配置 OpenClaw 飞书插件

编辑 ~/.openclaw/workspace/feishu/credentials.json（如果不存在则创建）：

json

{
  "app_id": "your_app_id_here",
  "app_secret": "your_app_secret_here",
  "encryption_key": "your_verification_token_or_encryption_key",
  "verification_token": "随机生成的加密密钥（如果开启）",
  "webhook_url": "/api/v1/feishu/events",
  "enable_webhook": true,
  "allowed_chat_types": ["p2p", "group"]
}

字段说明：

app_id / app_secret：从飞书应用基本信息获取
encryption_key / verification_token：事件订阅中的加密密钥（可选）
webhook_url：飞书事件的回调路径
allowed_chat_types：允许的对话类型（p2p 单聊，group 群聊）

步骤 6：配置 URL 校验（完成飞书侧）

飞书需要验证你提供的 URL 是否有效。

确保 OpenClaw 正在运行（pnpm start）
确保服务器可公网访问（域名或 IP）
如果有防火墙，开放端口（默认 3000）
回到飞书「事件订阅」页面，点击「保存」
飞书会发送验证请求到你的 webhook URL
OpenClaw 会自动响应验证（返回 challenge 参数）

验证通过后，事件订阅即激活。

步骤 7：启用飞书频道

编辑 ~/.openclaw/config.yml：

yaml

channels:
  feishu:
    enable: true
    credentials_path: ~/.openclaw/workspace/feishu/credentials.json

重启 OpenClaw：

bash

# 如果使用 pnpm start（生产模式）
pkill -f "node.*openclaw"  # 停止旧进程
pnpm start &

# 或使用 systemd 服务（推荐）
sudo systemctl restart openclaw

步骤 8：邀请机器人入群

在飞书应用页面，获取「机器人 URL」
选择要邀请的群组
点击「添加机器人」→「从应用列表选择」→ 找到 OpenClaw 助手
设置欢迎语（可选）
完成

现在机器人会在群里响应 @OpenClaw 的消息了！

六、连接 QQ 机器人

⚠️ 平台注意事项：
Linux/macOS：使用 go-cqhttp 或 Morax 的对应平台版本
Windows：使用 go-cqhttp 的 windows-amd64 版本，或在 WSL2 中运行 Linux 版本
配置文件路径：根据 OpenClaw 平台不同，credentials.json 路径见上文表格

QQ 机器人需要 Morax 或 Lagrange 等底层协议支持。OpenClaw 通过 go-cqhttp 协议接入。

方式一：使用 go-cqhttp（推荐新手）

步骤 1：下载 go-cqhttp

Linux：

bash

# 下载最新版本（Linux AMD64）
wget https://github.com/Mrs4s/go-cqhttp/releases/latest/download/go-cqhttp-linux-amd64.tar.gz
tar -zxvf go-cqhttp-linux-amd64.tar.gz
chmod +x go-cqhttp

macOS：

bash

# 下载 macOS 版本（amd64 或 arm64，根据芯片）
# arm64 (Apple Silicon M1/M2/M3)
wget https://github.com/Mrs4s/go-cqhttp/releases/latest/download/go-cqhttp-darwin-arm64.tar.gz
# amd64 (Intel Mac)
wget https://github.com/Mrs4s/go-cqhttp/releases/latest/download/go-cqhttp-darwin-amd64.tar.gz

tar -zxvf go-cqhttp-*.tar.gz
chmod +x go-cqhttp

Windows：

访问 go-cqhttp 发布页
下载 go-cqhttp-windows-amd64.tar.gz
用 7-Zip 或 WinRAR 解压
重命名 go-cqhttp.exe 为 go-cqhttp.exe（已经是 exe）

Windows WSL2：在 WSL2 中按 Linux 步骤操作。

步骤 2：登录 QQ

首次运行会提示扫码登录：

Linux/macOS：

bash

cd ~/.openclaw/qqbot
./go-cqhttp

Windows：

powershell

cd C:\path\to\qqbot
.\go-cqhttp.exe

屏幕上会显示二维码，用手机 QQ 扫码登录（建议小号，避免封号）。

登录后，go-cqhttp 会生成：

device.json（设备信息）
session.token（登录态）
config.yml（配置文件）

步骤 3：配置 go-cqhttp

修改 config.yml：

yaml

message:
  # 收到消息后转发给 OpenClaw（HTTP）
  post-format: string
  # 不直接响应，交由 OpenClaw 处理

servers:
  - http:
      address: 127.0.0.1:5700  # 监听端口，OpenClaw 连接这里
      middlewares:
        - access_log
        - gzip

重要：确保 address 是 OpenClaw 可以访问的地址（默认 127.0.0.1:5700）。

启动 go-cqhttp（后台）：

Linux/macOS：

bash

nohup ./go-cqhttp > cqhttp.log 2>&1 &
# 或使用 pm2
pm2 start ./go-cqhttp --name qqbot

Windows：

powershell

# 新开一个 PowerShell 窗口，运行
cd C:\path\to\qqbot
.\go-cqhttp.exe
# 保持该窗口开启，或使用 Windows 计划任务/NSSM 作为服务

使用 NSSM 安装为 Windows 服务：

powershell

nssm install OpenClawQQ "C:\path\to\qqbot\go-cqhttp.exe"
nssm start OpenClawQQ

验证运行：

bash

curl http://127.0.0.1:5700/get_login_info

应返回 QQ 号码和昵称。

方式二：使用 Morax（更稳定）

Morax 是基于 OneBot 标准实现，兼容性好。

bash

# 下载 Morax
wget https://github.com/Morsorus/Morax/releases/latest/download/morax-linux-amd64.tar.gz
tar -zxvf morax-linux-amd64.tar.gz
chmod +x morax

配置 config.yml：

yaml

servers:
  - http:
      address: 127.0.0.1:8080

登录方式同 go-cqhttp。

步骤 4：配置 OpenClaw QQ 插件

创建 credentials.json 文件，路径根据平台选择：

平台	推荐路径
Linux	`~/.openclaw/workspace/qqbot/credentials.json`
macOS	`~/.openclaw/workspace/qqbot/credentials.json`
Windows	`C:\Users\YourName\.openclaw\workspace\qqbot\credentials.json`

内容：

json

{
  "base_url": "http://127.0.0.1:5700",
  "access_token": "",  // 如果 go-cqhttp 设置了 access_token 则填写
  "secret": "",        // 如果启用了加密
  "self_id": 0,        // 机器人 QQ 号，留空自动获取
  "enable_group": true,
  "enable_private": true,
  "command_prefix": ["!", "！"]  // 命令前缀（可选）
}

步骤 5：启用 QQ 频道

编辑 ~/.openclaw/config.yml：

yaml

channels:
  qqbot:
    enable: true
    credentials_path: ~/.openclaw/workspace/qqbot/credentials.json

步骤 6：重启 OpenClaw

bash

# 如果使用 systemd
sudo systemctl restart openclaw

# 或直接运行
cd /path/to/openclaw
pnpm start

现在 QQ 机器人已就绪，可以：

在好友私聊中发送消息
在群里 @机器人 发送指令
通过 !命令（如果设置了前缀）

七、连接企业微信（WeCom）

步骤 1：创建企业微信应用

登录企业微信管理后台
进入「应用管理」→「自建」
点击「创建应用」
填写：
- 应用名称：OpenClaw 助手
- 可见范围：选择需要使用的部门/成员
创建后记录：
- CorpID（企业 ID）
- AgentId（应用 ID）
- Secret（应用密钥）

步骤 2：配置消息接收

在应用详情页：

找到「接收消息」配置
设置「API 接收消息」为开启
填写 URL：

https://你的域名/api/v1/wecom/events

填写 Token 和 EncodingAESKey（随机生成，记下来）
保存

步骤 3：配置 OpenClaw

编辑 ~/.openclaw/workspace/wecom/credentials.json：

json

{
  "corp_id": "your_corp_id",
  "agent_id": 123456,
  "secret": "your_app_secret",
  "token": "your_verification_token",
  "encoding_aes_key": "your_encoding_aes_key",
  "webhook_url": "/api/v1/wecom/events"
}

配置文件中启用：

yaml

channels:
  wecom:
    enable: true
    credentials_path: ~/.openclaw/workspace/wecom/credentials.json

步骤 4：在企业微信中测试

在企业微信中找到该应用
发送消息给应用（单聊或群聊 @应用）
应收到 OpenClaw 回复

八、进阶配置

配置反向代理（Nginx）

生产环境建议用 Nginx 反向代理 OpenClaw：

nginx

# /etc/nginx/sites-available/openclaw
server {
    listen 80;
    server_name openclaw.example.com;

    # 重定向到 HTTPS（如果启用了 SSL）
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name openclaw.example.com;

    # SSL 证书
    ssl_certificate /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # 健康检查
    location /health {
        proxy_pass http://127.0.0.1:3000/health;
        access_log off;
    }
}

启用并重启：

bash

sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

配置 Systemd 服务

创建 /etc/systemd/system/openclaw.service：

ini

[Unit]
Description=OpenClaw AI Agent
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/path/to/openclaw
Environment=NODE_ENV=production
ExecStart=/usr/bin/pnpm start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

启用并启动：

bash

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

查看日志：

bash

sudo journalctl -u openclaw -f

配置 Windows 服务（NSSM）

对于 Windows 用户，推荐使用 NSSM（Non-Sucking Service Manager）将 OpenClaw 安装为系统服务。

前提：OpenClaw 已安装在非 WSL2 的 Windows 环境（如 C:\openclaw）

步骤

下载 NSSM：https://nssm.cc/download
- 选择 nssm-2.24.zip（或最新版）
- 解压到 C:\nssm
以管理员身份打开 PowerShell 或 CMD

安装服务：

powershell

# 设置路径
$nssmPath = "C:\nssm\nssm.exe"
$openclawDir = "C:\openclaw"
$nodePath = "C:\Program Files\nodejs\node.exe"
$openclawScript = "C:\openclaw\dist\index.js"

# 安装服务
& $nssmPath install OpenClaw $nodePath $openclawScript

# 设置工作目录
& $nssmPath set OpenClaw AppDirectory $openclawDir

# 设置环境变量（可选）
& $nssmPath set OpenClaw Environment NODE_ENV=production

# 启动服务
& $nssmPath start OpenClaw

验证服务状态：

powershell

# 查看服务
Get-Service OpenClaw

# 查看日志
& $nssmPath status OpenClaw

设置开机自启：

powershell

Set-Service OpenClaw -StartupType Automatic

管理命令

操作	命令
启动	`nssm start OpenClaw`
停止	`nssm stop OpenClaw`
重启	`nssm restart OpenClaw`
查看日志	`nssm log OpenClaw`
移除服务	`nssm remove OpenClaw`

使用 pm2 跨平台进程管理（推荐开发环境）

pm2 是 Node.js 的进程管理器，支持 Linux/macOS/Windows。

bash

# 全局安装 pm2
npm install -g pm2

# 启动 OpenClaw（在项目根目录）
cd /path/to/openclaw
pm2 start "pnpm start" --name openclaw

# 查看状态
pm2 status

# 查看日志
pm2 logs openclaw

# 停止/重启
pm2 stop openclaw
pm2 restart openclaw

# 开机自启（Linux）
pm2 save
pm2 startup

# 开机自启（macOS）
pm2 save
pm2 startup launchd

# 开机自启（Windows）
pm2 save
pm2 startup windows

九、常见问题排查

Q1: 飞书事件订阅验证失败

现象：飞书提示「请求地址验证失败」

排查：

确认 OpenClaw 正在运行且端口可达
确认防火墙开放了端口（sudo ufw status）
确认 URL 路径正确：https://your-domain/api/v1/feishu/events

查看 OpenClaw 日志：

bash

sudo journalctl -u openclaw -f
# 或
tail -f ~/.openclaw/logs/openclaw.log

Q2: QQ 机器人无法接收消息

排查：

go-cqhttp 是否正常运行？

bash

ps aux | grep go-cqhttp
curl http://127.0.0.1:5700/get_login_info

登录态是否过期？重新扫码登录
检查 go-cqhttp 日志：tail -f ~/.openclaw/qqbot/cqhttp.log
是否开启了「 góc」或「禁止机器人」等限制

Q3: 消息重复发送

原因：多个平台同时监听或 Webhook 重复触发。

解决：

确保只有一个 OpenClaw 实例在运行
检查是否有多个 webhook 配置指向同一实例
查看 config.yml 的 duplication_prevention 配置

Q4: 配置修改不生效

解决：

编辑正确配置文件（~/.openclaw/config.yml 或项目根目录的）
重启服务：sudo systemctl restart openclaw
查看日志确认加载：grep "config loaded" ~/.openclaw/logs/openclaw.log

Q5: 端口被占用

bash

# 查看端口占用
sudo lsof -i :3000
# 或
netstat -tulpn | grep 3000

# 修改 config.yml 使用其他端口
server:
  port: 3001

Q6: 消息重复发送

原因：多个平台同时监听或 Webhook 重复触发。

解决：

确保只有一个 OpenClaw 实例在运行
检查是否有多个 webhook 配置指向同一实例
查看 config.yml 的 duplication_prevention 配置

Q7: macOS 权限问题

如果遇到权限错误：

bash

# 1. 确保 Node.js 有权限
# 如果 Homebrew 安装的，通常没问题

# 2. 清理 npm 缓存
npm cache clean --force

# 3. 删除 node_modules 重装
rm -rf node_modules
pnpm install

# 4. macOS 防火墙：系统偏好设置 → 安全性与隐私 → 防火墙
# 添加 "node" 或 "bash" 到允许列表

Q8: WSL2 网络访问问题

WSL2 与 Windows 共享网络，但 IP 可能不同：

bash

# 在 WSL2 中查看 IP
ip addr

# 如果 Windows 无法访问 WSL2，在 WSL2 中绑定到 0.0.0.0
# config.yml
server:
  host: 0.0.0.0

# 在 Windows 访问时用 WSL2 的 IP 或 localhost（如果配置正确）

十、技能生态系统

OpenClaw 的强大在于 技能系统（Skills）—— 可复用的功能模块。

查看已安装技能

bash

# 通过命令行
cd /path/to/openclaw
pnpm skills:list

# 或访问管理界面（如果启用）
http://localhost:3000/admin/skills

安装新技能

1. 从技能仓库搜索

bash

# 搜索技能
pnpm skillhub search "weather"

# 安装技能
pnpm skillhub install openclaw/skill-weather

2. 手动安装

bash

# 下载技能到 ~/.openclaw/workspace/skills/
cd ~/.openclaw/workspace/skills
git clone https://github.com/openclaw/skill-example.git weather

# 在 OpenClaw 中启用
# 编辑 config.yml
skills:
  enabled:
    - weather

常用技能推荐

技能名	功能	安装命令
`skill-weather`	天气查询	`pnpm skillhub install openclaw/skill-weather`
`skill-reminder`	定时提醒	`pnpm skillhub install openclaw/skill-cron`
`skill-websearch`	网页搜索	`pnpm skillhub install openclaw/skill-search`
`skill-dalle`	图像生成	`pnpm skillhub install openclaw/skill-dalle`
`skill-calendar`	日历集成	`pnpm skillhub install openclaw/skill-calendar`

十一、备份与迁移

备份重要数据

Linux/macOS：

bash

# 备份整个 ~/.openclaw 目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

# 单独备份
- ~/.openclaw/credentials/    # 凭证（最重要）
- ~/.openclaw/workspace/skills/  # 已安装技能
- ~/.openclaw/workspace/memory/  # 记忆数据
- ~/.openclaw/config.yml      # 配置文件

Windows：

powershell

# 压缩备份（需要 7-Zip 或 PowerShell 5+）
Compress-Archive -Path "$env:USERPROFILE\.openclaw\*" -DestinationPath "openclaw-backup-$(Get-Date -Format yyyyMMdd).zip"

# 或手动复制
xcopy "%USERPROFILE%\.openclaw" "C:\backup\openclaw\" /E /I /H

WSL2（从 Windows 访问）：

powershell

# 在 PowerShell 中
wsl -d Ubuntu -- tar -czf /mnt/c/backup/openclaw-backup-$(date +%Y%m%d).tar.gz -C /home/youruser .openclaw

迁移到新服务器

在新服务器安装 OpenClaw（见前三节）

复制备份文件到新服务器：

bash

scp openclaw-backup.tar.gz user@newserver:~/
ssh user@newserver "tar -xzf openclaw-backup.tar.gz -C ~/"

恢复权限：

bash

chmod 700 ~/.openclaw/credentials
chmod 600 ~/.openclaw/credentials/*.json

启动服务

十二、安全建议

1. 凭证安全

永远不要将 credentials.json 提交到 Git
使用环境变量或密钥管理工具
定期轮换 API keys

2. 网络隔离

OpenClaw 只监听本地（127.0.0.1:3000），通过 Nginx 暴露
使用防火墙限制访问 IP
启用 HTTPS（Let's Encrypt 免费证书）

3. 最小权限原则

飞书/QQ 机器人使用小号，避免主号被封
飞书应用权限只申请必要的
文件系统权限设为最小必要

4. 监控日志

定期检查：

bash

# 错误日志
grep -i error ~/.openclaw/logs/openclaw.log | tail -20

# 异常登录
grep "login" ~/.openclaw/workspace/qqbot/cqhttp.log

十三、性能调优

模型选择

OpenClaw 默认使用 OpenRouter（付费），如需降低成本：

使用本地模型（Ollama）

安装 Ollama：

bash

curl -fsSL https://ollama.ai/install.sh | sh

下载模型：

bash

ollama pull llama2:7b-chat
ollama pull codellama:7b-instruct

配置 OpenClaw：

yaml

models:
  default: ollama/llama2:7b-chat
providers:
  ollama:
    endpoint: http://127.0.0.1:11434

使用高速推理（Groq）

Groq 提供 LPU 架构，速度极快（数千 tokens/s）：

yaml

models:
  default: groq/llama3-8b-8192
providers:
  groq:
    api_key: your_groq_api_key

申请 API Key：https://console.groq.com

十四、完整快速安装脚本

为了方便，这里提供一键安装脚本：

bash

#!/bin/bash
# openclaw-quick-install.sh

set -e

echo "=== OpenClaw 快速安装脚本 ==="

# 1. 检查 Node.js
if ! command -v node &> /dev/null; then
    echo "安装 Node.js 20..."
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs
fi

echo "Node.js 版本: $(node -v)"
echo "npm 版本: $(npm -v)"

# 2. 安装 pnpm
echo "安装 pnpm..."
npm install -g pnpm

# 3. 下载 OpenClaw
if [ ! -d "openclaw" ]; then
    git clone https://github.com/openclaw/openclaw.git
fi
cd openclaw

# 4. 安装依赖
echo "安装依赖（可能需要几分钟）..."
pnpm install --frozen-lockfile

# 5. 构建
echo "构建项目..."
pnpm build

# 6. 创建配置目录
mkdir -p ~/.openclaw/{logs,workspace/{skills,memory},credentials}

# 7. 复制默认配置
if [ ! -f ~/.openclaw/config.yml ]; then
    cp configs/default.yml ~/.openclaw/config.yml
    echo "请编辑 ~/.openclaw/config.yml 配置您需要的频道"
fi

# 8. 安装基础技能
echo "安装推荐技能..."
pnpm skillhub install openclaw/skill-weather &
pnpm skillhub install openclaw/skill-reminder &
wait

echo ""
echo "=== 安装完成 ==="
echo ""
echo "下一步："
echo "1. 编辑 ~/.openclaw/config.yml，启用 feishu/qqbot 等频道"
echo "2. 配置对应平台的凭证（参考教程）"
echo "3. 启动：pnpm start 或 sudo systemctl start openclaw"
echo ""
echo "详细教程：https://docs.openclaw.ai/"

使用：

bash

chmod +x openclaw-quick-install.sh
./openclaw-quick-install.sh

十五、平台安装对比总结

项目	Linux	macOS	Windows (原生)	Windows (WSL2)
推荐度	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
安装难度	简单	简单	中等	简单
性能	优秀	优秀	一般	优秀
Docker 支持	✅	✅	⚠️ 有限	✅
生产部署	✅ Systemd	✅ pm2/launchd	⚠️ NSSM	✅ Linux 方式
开发体验	优秀	优秀	一般	优秀
建议用途	所有场景	所有场景	仅测试	所有场景（最佳）

平台选择建议

如果你在 Windows 上：

✅ 首选：安装 WSL2，然后在 Ubuntu 中部署（与 Linux 教程完全一致）
⚠️ 次选：原生 Windows + NSSM 服务（路径和权限问题较多）
❌ 避免：在 C 盘根目录或带空格路径安装

如果你在 macOS 上：

✅ 直接按 Linux 步骤操作，几乎所有命令都相同
✅ 使用 Homebrew 管理依赖
✅ 使用 pm2 管理进程（生产环境）

如果你在 Linux 上：

✅ 最简单，直接按教程操作
✅ 推荐使用 Systemd + Nginx + 反向代理

十六、快速检查清单

安装完成后，用此清单验证配置：

[ ] Node.js 20+ 已安装，node -v 显示正确版本
[ ] pnpm 已安装，pnpm --version 可执行
[ ] Git 已安装，可克隆仓库
[ ] OpenClaw 已克隆到本地
[ ] pnpm install 成功（无错误）
[ ] pnpm build 成功（生成 dist/ 目录）
[ ] 配置文件 ~/.openclaw/config.yml 存在
[ ] 尝试 pnpm start，看到 "Server listening on port 3000"
[ ] 浏览器访问 http://localhost:3000，看到 OpenClaw 界面
[ ] （可选）配置了 Nginx 反向代理，https://your-domain 可访问
[ ] 需要飞书/QQ：已配置对应 credentials.json
[ ] 需要 QQ：go-cqhttp/Morax 已运行，curl http://127.0.0.1:5700/get_login_info 返回数据
[ ] 日志无错误：tail -f ~/.openclaw/logs/openclaw.log

全部 ✅ 后，你的 OpenClaw 就可以正式使用了！

十七、获取帮助

官方文档：https://docs.openclaw.ai/
GitHub：https://github.com/openclaw/openclaw
Community：https://discord.com/invite/clawd
中文社区：https://clawhub.com
问题反馈：https://github.com/openclaw/openclaw/issues

总结

OpenClaw 跨平台安装部署总结：

✅ 环境准备：Node.js 20+ + pnpm + Git（各平台命令略有不同）
✅ 克隆+构建：git clone → pnpm install → pnpm build
✅ 配置：编辑 ~/.openclaw/config.yml，启用需要的频道
✅ 平台配置：飞书（应用配置）、QQ（go-cqhttp）、企微（应用配置）
✅ 启动服务：Linux（systemd）、macOS（pm2）、Windows（NSSM 或 WSL2）
✅ 验证：浏览器访问、发送测试消息

无论你用 Linux、macOS 还是 Windows，现在都能轻松部署 OpenClaw 了！

OpenClaw 安装部署完整教程 ​

一、什么是 OpenClaw？ ​

二、环境准备 ​

系统要求 ​

依赖软件（所有平台） ​

二-1. Linux 环境准备（Ubuntu/Debian） ​

安装 Node.js 20 ​

安装 pnpm ​

安装 Git ​

二-2. macOS 环境准备 ​

安装 Homebrew（如果还没有） ​

安装 Node.js 20 ​

安装 pnpm ​

安装 Git ​

配置环境变量（如需要） ​

二-3. Windows 环境准备 ​

安装 Node.js 20 ​

安装 pnpm ​

安装 Git ​

（可选）安装 WSL2（推荐） ​

三-1. Linux 安装 OpenClaw ​

方式一：全球镜像（推荐） ​

方式二：国内镜像（speedup） ​

三-2. macOS 安装 OpenClaw ​

步骤 ​

使用 pm2 管理进程（推荐） ​

注意事项 ​

三-3. Windows 安装 OpenClaw ​

方式 A：在 WSL2 中安装（强烈推荐） ​

方式 B：在 Windows 原生环境中安装 ​

步骤 ​

使用 nodemon 自动重启（可选） ​

使用 Windows 服务（可选） ​

注意事项 ​

四、配置 OpenClaw ​

配置文件位置 ​

基础配置示例 ​

五、连接飞书（ Lark / 飞书） ​

步骤 1：创建飞书应用 ​

步骤 2：配置权限 ​

基础权限 ​

高级权限（需要审核） ​

步骤 3：获取凭证 ​

步骤 4：配置事件订阅 ​

步骤 5：配置 OpenClaw 飞书插件 ​

步骤 6：配置 URL 校验（完成飞书侧） ​

步骤 7：启用飞书频道 ​

步骤 8：邀请机器人入群 ​

六、连接 QQ 机器人 ​

方式一：使用 go-cqhttp（推荐新手） ​

步骤 1：下载 go-cqhttp ​

步骤 2：登录 QQ ​

步骤 3：配置 go-cqhttp ​

方式二：使用 Morax（更稳定） ​

步骤 4：配置 OpenClaw QQ 插件 ​

步骤 5：启用 QQ 频道 ​

步骤 6：重启 OpenClaw ​

七、连接企业微信（WeCom） ​

步骤 1：创建企业微信应用 ​

步骤 2：配置消息接收 ​

步骤 3：配置 OpenClaw ​

步骤 4：在企业微信中测试 ​

八、进阶配置 ​

配置反向代理（Nginx） ​

配置 Systemd 服务 ​

配置 Windows 服务（NSSM） ​

步骤 ​

管理命令 ​

使用 pm2 跨平台进程管理（推荐开发环境） ​

九、常见问题排查 ​

Q1: 飞书事件订阅验证失败 ​

Q2: QQ 机器人无法接收消息 ​

Q3: 消息重复发送 ​

Q4: 配置修改不生效 ​

Q5: 端口被占用 ​

Q6: 消息重复发送 ​

Q7: macOS 权限问题 ​

Q8: WSL2 网络访问问题 ​

十、技能生态系统 ​

查看已安装技能 ​

OpenClaw 安装部署完整教程

一、什么是 OpenClaw？

二、环境准备

系统要求

依赖软件（所有平台）

二-1. Linux 环境准备（Ubuntu/Debian）

安装 Node.js 20

安装 pnpm

安装 Git

二-2. macOS 环境准备

安装 Homebrew（如果还没有）

安装 Node.js 20

安装 pnpm

安装 Git

配置环境变量（如需要）

二-3. Windows 环境准备

安装 Node.js 20

安装 pnpm

安装 Git

（可选）安装 WSL2（推荐）

三-1. Linux 安装 OpenClaw

方式一：全球镜像（推荐）

方式二：国内镜像（speedup）

三-2. macOS 安装 OpenClaw

步骤

使用 pm2 管理进程（推荐）

注意事项

三-3. Windows 安装 OpenClaw

方式 A：在 WSL2 中安装（强烈推荐）

方式 B：在 Windows 原生环境中安装

步骤

使用 nodemon 自动重启（可选）

使用 Windows 服务（可选）

注意事项

四、配置 OpenClaw

配置文件位置

基础配置示例

五、连接飞书（ Lark / 飞书）

步骤 1：创建飞书应用

步骤 2：配置权限

基础权限

高级权限（需要审核）

步骤 3：获取凭证

步骤 4：配置事件订阅

步骤 5：配置 OpenClaw 飞书插件

步骤 6：配置 URL 校验（完成飞书侧）

步骤 7：启用飞书频道

步骤 8：邀请机器人入群

六、连接 QQ 机器人

方式一：使用 go-cqhttp（推荐新手）

步骤 1：下载 go-cqhttp

步骤 2：登录 QQ

步骤 3：配置 go-cqhttp

方式二：使用 Morax（更稳定）

步骤 4：配置 OpenClaw QQ 插件

步骤 5：启用 QQ 频道

步骤 6：重启 OpenClaw

七、连接企业微信（WeCom）

步骤 1：创建企业微信应用

步骤 2：配置消息接收

步骤 3：配置 OpenClaw

步骤 4：在企业微信中测试

八、进阶配置

配置反向代理（Nginx）

配置 Systemd 服务

配置 Windows 服务（NSSM）

步骤

管理命令

使用 pm2 跨平台进程管理（推荐开发环境）

九、常见问题排查

Q1: 飞书事件订阅验证失败

Q2: QQ 机器人无法接收消息

Q3: 消息重复发送

Q4: 配置修改不生效

Q5: 端口被占用

Q6: 消息重复发送

Q7: macOS 权限问题

Q8: WSL2 网络访问问题

十、技能生态系统

查看已安装技能