OpenClaw 搭建教程#

概述#

OpenClaw 是一个开源的个人 AI 助理平台，支持多通道（Telegram、WhatsApp、Discord 等）接入，具备技能扩展和自动化能力。

本教程涵盖以下部署方式：

Windows 本地部署（推荐使用 WSL2 或 Docker Desktop）
macOS 本地部署（Apple Silicon 和 Intel 均支持）
Linux (Ubuntu 24.04) 本地部署
Docker Compose 容器化部署（跨平台通用，推荐生产环境）

通用系统要求#

平台	最低要求	推荐配置
Windows	Windows 10 64 位, 8GB RAM, WSL2	Windows 11, 16GB RAM
macOS	macOS 12+, 8GB RAM	macOS 13+, 16GB RAM
Ubuntu 24.04	2GB RAM, 10GB 存储	4GB+ RAM, 20GB+ 存储
Docker	Docker Engine 20.10+	Docker Desktop 4.20+

Docker Compose 容器化部署（推荐）#

适用场景#

生产环境部署
快速体验和测试
多平台统一部署方案
需要环境隔离的场景

安装 Docker#

Windows#

PRTCL // POWERSHELL

1
# 下载 Docker Desktop
2
# 访问 https://www.docker.com/products/docker-desktop/
3

4
# 安装完成后验证
5
docker --version
6
docker-compose --version

macOS#

PRTCL // BASH

1
# 使用 Homebrew 安装
2
brew install --cask docker
3

4
# 启动 Docker Desktop
5
open /Applications/Docker.app
6

7
# 验证安装
8
docker --version
9
docker-compose --version

Ubuntu 24.04#

PRTCL // BASH

1
# 更新软件包索引
2
sudo apt update
3

4
# 安装 Docker Engine
5
sudo apt install -y docker.io docker-compose-v2
6

7
# 启动并启用 Docker
8
sudo systemctl start docker
9
sudo systemctl enable docker
10

11
# 将当前用户添加到 docker 组
12
sudo usermod -aG docker $USER
13
newgrp docker
14

15
# 验证安装
16
docker --version
17
docker compose version

创建项目目录#

PRTCL // BASH

1
# 创建工作目录
2
mkdir -p ~/openclaw/{workspace,data}
3
cd ~/openclaw

创建 docker-compose.yml#

PRTCL // YAML

1
version: '3.8'
2

3
services:
4
  openclaw:
5
    image: openclaw/openclaw:latest
6
    container_name: openclaw
7
    restart: unless-stopped
8
    ports:
9
      - "3000:3000"           # Web UI 端口
10
      - "9229:9229"           # Node.js 调试端口（可选）
11
    volumes:
12
      - ./workspace:/home/node/.openclaw/workspace
13
      - ./data:/home/node/.openclaw/data
14
    environment:
15
      - NODE_ENV=production
16
      - TZ=Asia/Shanghai
17
      - OPENCLAW_HOST=0.0.0.0
18
      - OPENCLAW_PORT=3000
19
    networks:
20
      - openclaw-net
21
    deploy:
22
      resources:
23
        limits:
24
          memory: 2G
25
          cpus: '1.0'
26
        reservations:
27
          memory: 512M
28
          cpus: '0.5'
29

30
  # PostgreSQL 数据库（可选）
31
  postgres:
32
    image: postgres:16-alpine
33
    container_name: openclaw-postgres
34
    restart: unless-stopped
35
    environment:
36
      - POSTGRES_USER=openclaw
37
      - POSTGRES_PASSWORD=your_secure_password_here
38
      - POSTGRES_DB=openclaw
39
    volumes:
40
      - postgres_data:/var/lib/postgresql/data
41
    networks:
42
      - openclaw-net
43

44
  # Redis 缓存（可选）
45
  redis:
46
    image: redis:7-alpine
47
    container_name: openclaw-redis
48
    restart: unless-stopped
49
    command: redis-server --appendonly yes
50
    volumes:
51
      - redis_data:/data
52
    networks:
53
      - openclaw-net
54

55
networks:
56
  openclaw-net:
57
    driver: bridge
58

59
volumes:
60
  postgres_data:
61
  redis_data:

启动服务#

PRTCL // BASH

1
# 启动所有服务
2
docker compose up -d
3

4
# 查看服务状态
5
docker compose ps
6

7
# 查看日志
8
docker compose logs -f openclaw
9

10
# 访问 Web UI
11
# 浏览器打开: http://localhost:3000

常用管理命令#

PRTCL // BASH

1
# 停止服务
2
docker compose down
3

4
# 停止并删除数据卷
5
docker compose down -v
6

7
# 重启服务
8
docker compose restart
9

10
# 更新镜像
11
docker compose pull
12
docker compose up -d
13

14
# 进入容器
15
docker exec -it openclaw bash
16

17
# 查看资源使用
18
docker stats openclaw

Windows 本地部署#

方案一：WSL2 + Docker（推荐）#

安装 WSL2#

PRTCL // POWERSHELL

1
# 以管理员身份运行 PowerShell
2

3
# 启用 WSL2 功能
4
wsl --install
5
wsl --set-default-version 2
6

7
# 重启计算机
8

9
# 安装 Ubuntu 发行版
10
wsl --install -d Ubuntu-24.04

在 WSL2 中部署#

PRTCL // BASH

1
# 进入 WSL2 Ubuntu
2
wsl -d Ubuntu-24.04
3

4
# 更新系统
5
sudo apt update && sudo apt upgrade -y
6

7
# 安装 Docker（参考 Ubuntu 部分）
8
sudo apt install -y docker.io docker-compose-v2
9

10
# 添加用户到 docker 组
11
sudo usermod -aG docker $USER
12
newgrp docker
13

14
# 创建项目目录
15
mkdir -p ~/openclaw/{workspace,data}
16
cd ~/openclaw
17

18
# 创建 docker-compose.yml（参考上方配置）
19
# 启动服务
20
docker compose up -d

方案二：Docker Desktop#

安装步骤#

下载 Docker Desktop for Windows
运行安装程序，启用 WSL2 集成
重启计算机
启动 Docker Desktop

部署 OpenClaw#

PRTCL // POWERSHELL

1
# 在 PowerShell 或 CMD 中执行
2

3
# 创建项目目录
4
mkdir C:\Users\%USERNAME%\openclaw
5
cd C:\Users\%USERNAME%\openclaw
6

7
# 创建 docker-compose.yml（参考上方配置）
8

9
# 启动服务
10
docker compose up -d
11

12
# 访问 http://localhost:3000

方案三：原生 Node.js 安装#

安装依赖#

PRTCL // POWERSHELL

1
# 安装 Node.js 20 LTS
2
# 访问 https://nodejs.org/ 下载安装
3

4
# 安装 Git
5
# 访问 https://git-scm.com/ 下载安装
6

7
# 安装 Python 3.11+
8
# 访问 https://www.python.org/ 下载安装，勾选 "Add Python to PATH"
9

10
# 验证安装
11
node --version
12
npm --version
13
git --version
14
python --version

安装 OpenClaw#

PRTCL // POWERSHELL

1
# 创建工作目录
2
mkdir C:\Users\%USERNAME%\.openclaw
3
cd C:\Users\%USERNAME%\.openclaw
4

5
# 克隆仓库
6
git clone https://github.com/openclaw/openclaw.git workspace
7
cd workspace
8

9
# 安装依赖
10
npm install
11

12
# 构建项目
13
npm run build
14

15
# 启动服务
16
npm start
17

18
# 使用 PM2 管理进程（可选）
19
npm install -g pm2
20
pm2 start npm --name "openclaw" -- start
21
pm2 save

macOS 本地部署#

安装 Homebrew#

PRTCL // BASH

1
# 安装 Homebrew（如果未安装）
2
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3

4
# 配置环境变量（Apple Silicon）
5
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
6
eval "$(/opt/homebrew/bin/brew shellenv)"

方案一：Docker Desktop（推荐）#

安装 Docker Desktop#

PRTCL // BASH

1
# 使用 Homebrew 安装
2
brew install --cask docker
3

4
# 启动 Docker Desktop
5
open /Applications/Docker.app
6

7
# 验证安装
8
docker --version
9
docker compose version

部署 OpenClaw#

PRTCL // BASH

1
# 创建项目目录
2
mkdir -p ~/openclaw/{workspace,data}
3
cd ~/openclaw
4

5
# 创建 docker-compose.yml（参考上方配置）
6

7
# 启动服务
8
docker compose up -d
9

10
# 访问 http://localhost:3000

方案二：原生 Node.js 安装#

安装依赖#

PRTCL // BASH

1
# 安装 Node.js 20
2
brew install node@20
3

4
# 链接到系统路径
5
brew link node@20
6

7
# 安装 Python 3.11+
8
brew install python@3.11
9

10
# 验证安装
11
node --version
12
npm --version
13
python3 --version

安装 OpenClaw#

PRTCL // BASH

1
# 创建工作目录
2
mkdir -p ~/.openclaw/workspace
3
cd ~/.openclaw/workspace
4

5
# 克隆仓库
6
git clone https://github.com/openclaw/openclaw.git .
7
# 或下载发布版本
8
curl -L https://github.com/openclaw/openclaw/archive/refs/heads/main.tar.gz | tar -xz --strip-components=1
9

10
# 安装依赖
11
npm install
12

13
# 构建项目
14
npm run build
15

16
# 启动服务
17
npm start
18

19
# 创建 LaunchAgent 服务（开机自启）
20
cat > ~/Library/LaunchAgents/com.user.openclaw.plist << 'EOF'
21
<?xml version="1.0" encoding="UTF-8"?>
22
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
23
<plist version="1.0">
24
<dict>
25
    <key>Label</key>
26
    <string>com.user.openclaw</string>
27
    <key>ProgramArguments</key>
28
    <array>
29
        <string>/opt/homebrew/bin/node</string>
30
        <string>/Users/$(whoami)/.openclaw/workspace/index.js</string>
31
    </array>
32
    <key>RunAtLoad</key>
33
    <true/>
34
    <key>KeepAlive</key>
35
    <true/>
36
    <key>WorkingDirectory</key>
37
    <string>/Users/$(whoami)/.openclaw/workspace</string>
38
    <key>StandardOutPath</key>
39
    <string>/tmp/openclaw.log</string>
40
    <key>StandardErrorPath</key>
41
    <string>/tmp/openclaw.error.log</string>
42
</dict>
43
</plist>
44
EOF
45

46
# 加载服务
47
launchctl load ~/Library/LaunchAgents/com.user.openclaw.plist

Ubuntu 24.04 本地部署#

方案一：Docker Compose（推荐）#

安装 Docker#

PRTCL // BASH

1
#!/bin/bash
2
# 更新软件包索引
3
sudo apt update
4

5
# 安装必要的依赖
6
sudo apt install -y ca-certificates curl gnupg
7

8
# 添加 Docker 官方 GPG 密钥
9
sudo install -m 0755 -d /etc/apt/keyrings
10
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
11
sudo chmod a+r /etc/apt/keyrings/docker.gpg
12

13
# 设置 Docker 仓库
14
echo \
15
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
16
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
17
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
18

19
# 安装 Docker Engine
20
sudo apt update
21
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
22

23
# 启动并启用 Docker
24
sudo systemctl start docker
25
sudo systemctl enable docker
26

27
# 将当前用户添加到 docker 组
28
sudo usermod -aG docker $USER
29
newgrp docker
30

31
# 验证安装
32
docker --version
33
docker compose version

部署 OpenClaw#

PRTCL // BASH

1
# 创建项目目录
2
mkdir -p ~/openclaw/{workspace,data}
3
cd ~/openclaw
4

5
# 创建 docker-compose.yml（参考上方配置）
6

7
# 启动服务
8
docker compose up -d
9

10
# 设置开机自启
11
docker compose enable
12

13
# 访问 http://localhost:3000

方案二：原生 Node.js 安装#

安装系统依赖#

PRTCL // BASH

1
#!/bin/bash
2
set -e
3

4
# 更新系统
5
sudo apt update && sudo apt upgrade -y
6

7
# 安装系统依赖
8
sudo apt install -y \
9
    git curl wget \
10
    build-essential \
11
    python3 python3-pip python3-venv \
12
    libssl-dev libcurl4-openssl-dev \
13
    pkg-config
14

15
# 安装 Node.js 20（使用 NodeSource 仓库）
16
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
17
sudo apt install -y nodejs
18

19
# 验证安装
20
node --version
21
npm --version
22
python3 --version

安装 OpenClaw#

PRTCL // BASH

1
#!/bin/bash
2
set -e
3

4
# 创建工作目录
5
mkdir -p ~/.openclaw/workspace
6
cd ~/.openclaw/workspace
7

8
# 克隆仓库
9
git clone https://github.com/openclaw/openclaw.git .
10

11
# 安装 Node.js 依赖
12
npm install
13

14
# 构建项目
15
npm run build
16

17
# 创建 systemd 服务
18
sudo tee /etc/systemd/system/openclaw.service << 'EOF'
19
[Unit]
20
Description=OpenClaw AI Assistant
21
After=network.target
22

23
[Service]
24
Type=simple
25
User=$(whoami)
26
WorkingDirectory=/home/$(whoami)/.openclaw/workspace
27
Environment=NODE_ENV=production
28
Environment=TZ=Asia/Shanghai
29
ExecStart=/usr/bin/node index.js
30
Restart=always
31
RestartSec=10
32
StandardOutput=journal
33
StandardError=journal
34

35
[Install]
36
WantedBy=multi-user.target
37
EOF
38

39
# 重载 systemd 配置
40
sudo systemctl daemon-reload
41

42
# 启用并启动服务
43
sudo systemctl enable openclaw.service
44
sudo systemctl start openclaw.service
45

46
# 查看服务状态
47
sudo systemctl status openclaw.service
48

49
# 查看日志
50
sudo journalctl -u openclaw.service -f
51

52
echo "安装完成！"
53
echo "访问地址: http://localhost:3000"
54
echo "查看日志: sudo journalctl -u openclaw.service -f"

初始配置#

访问 Web UI#

启动服务后，打开浏览器访问：http://localhost:3000

创建管理员账户#

首次访问需要设置管理员账户和密码。

配置通道#

Telegram 通道#

PRTCL // YAML

1
channels:
2
  telegram:
3
    enabled: true
4
    token: "YOUR_BOT_TOKEN"  # 从 @BotFather 获取
5
    allowFrom:
6
      - "YOUR_TELEGRAM_USER_ID"

WhatsApp 通道#

PRTCL // YAML

1
channels:
2
  whatsapp:
3
    enabled: true
4
    sessionPath: "/home/node/.openclaw/data/whatsapp-session"

配置技能#

PRTCL // YAML

1
skills:
2
  baidu-search:
3
    enabled: true
4
    apiKey: "YOUR_BAIDU_API_KEY"
5

6
  weather:
7
    enabled: true
8
    provider: "wttr.in"

配置定时任务#

PRTCL // YAML

1
jobs:
2
  - name: "每日天气推送"
3
    schedule: "0 8 * * *"  # 每天 8:00
4
    task: "获取今日天气并推送"
5
    channel: "telegram"
6

7
  - name: "科技热点日报"
8
    schedule: "0 7 * * *"  # 每天 7:00
9
    task: "收集科技新闻并分析"
10
    channel: "telegram"

数据备份与恢复#

Docker 部署备份#

PRTCL // BASH

1
#!/bin/bash
2
BACKUP_DIR="/backup/openclaw"
3
DATE=$(date +%Y%m%d_%H%M%S)
4

5
# 创建备份目录
6
mkdir -p "$BACKUP_DIR"
7

8
echo "=== OpenClaw 备份 ($DATE) ==="
9

10
# 备份工作空间
11
echo "备份工作空间..."
12
tar -czf "$BACKUP_DIR/workspace_$DATE.tar.gz" -C ~/openclaw workspace
13

14
# 备份数据目录
15
echo "备份数据目录..."
16
tar -czf "$BACKUP_DIR/data_$DATE.tar.gz" -C ~/openclaw data
17

18
# 备份数据库（如果使用）
19
if docker compose ps | grep -q postgres; then
20
    echo "备份 PostgreSQL 数据库..."
21
    docker compose exec -T postgres pg_dump -U openclaw openclaw > "$BACKUP_DIR/db_$DATE.sql"
22
fi
23

24
# 清理旧备份（保留 7 天）
25
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete
26
find "$BACKUP_DIR" -name "*.sql" -mtime +7 -delete
27

28
echo "备份完成: $BACKUP_DIR"

原生部署备份#

PRTCL // BASH

1
#!/bin/bash
2
BACKUP_DIR="/backup/openclaw"
3
DATE=$(date +%Y%m%d_%H%M%S)
4

5
# 创建备份目录
6
mkdir -p "$BACKUP_DIR"
7

8
echo "=== OpenClaw 备份 ($DATE) ==="
9

10
# 备份工作空间
11
tar -czf "$BACKUP_DIR/workspace_$DATE.tar.gz" -C ~/.openclaw workspace
12

13
# 备份数据目录
14
tar -czf "$BACKUP_DIR/data_$DATE.tar.gz" -C ~/.openclaw data
15

16
echo "备份完成: $BACKUP_DIR"

常见问题排查#

Docker 相关问题#

端口冲突#

PRTCL // BASH

1
# 检查端口占用
2
sudo netstat -tlnp | grep :3000
3

4
# 修改 docker-compose.yml 中的端口映射
5
ports:
6
  - "3001:3000"

权限问题#

PRTCL // BASH

1
# 修复目录权限
2
sudo chown -R $USER:$USER ~/openclaw
3
sudo chmod -R 755 ~/openclaw/workspace

内存不足#

PRTCL // YAML

1
# 在 docker-compose.yml 中调整资源限制
2
deploy:
3
  resources:
4
    limits:
5
      memory: 1G

原生部署问题#

Node.js 版本不匹配#

PRTCL // BASH

1
# 使用 nvm 管理 Node.js 版本
2
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
3
source ~/.bashrc
4
nvm install 20
5
nvm use 20

系统服务启动失败#

PRTCL // BASH

1
# 查看服务状态
2
sudo systemctl status openclaw.service
3

4
# 查看详细日志
5
sudo journalctl -u openclaw.service -n 50
6

7
# 重启服务
8
sudo systemctl restart openclaw.service

网络连接问题#

PRTCL // BASH

1
# 测试网络连接
2
curl -I https://github.com
3
curl -I https://hub.docker.com
4

5
# 配置代理（如果需要）
6
export http_proxy=http://proxy.example.com:8080
7
export https_proxy=http://proxy.example.com:8080

性能优化#

Docker 部署优化#

PRTCL // YAML

1
# docker-compose.yml 优化配置
2
services:
3
  openclaw:
4
    # ... 其他配置
5
    # 优化 Node.js 内存
6
    command: ["node", "--max-old-space-size=1536", "index.js"]
7

8
    # 资源限制
9
    deploy:
10
      resources:
11
        limits:
12
          memory: 2G
13
          cpus: '2'
14
        reservations:
15
          memory: 512M
16
          cpus: '0.5'

原生部署优化#

PRTCL // BASH

1
# 使用 PM2 进程管理
2
npm install -g pm2
3
pm2 start npm --name "openclaw" -- start
4
pm2 startup
5
pm2 save
6

7
# 优化 Node.js 内存
8
export NODE_OPTIONS="--max-old-space-size=2048"

部署方案对比#

特性	Docker Compose	Windows 原生	macOS 原生	Ubuntu 原生
安装速度	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
环境隔离	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐⭐
系统资源	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
调试难度	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
生产推荐	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
跨平台	⭐⭐⭐⭐⭐	⭐	⭐⭐⭐	⭐⭐⭐

使用场景	推荐方案
快速体验	Docker Compose
开发调试	各平台原生安装
生产部署	Docker Compose
资源受限	Ubuntu 原生

OpenClaw 搭建教程#

概述#

通用系统要求#

Docker Compose 容器化部署（推荐）#

适用场景#

安装 Docker#

Windows#

macOS#

Ubuntu 24.04#

创建项目目录#

创建 docker-compose.yml#

启动服务#

常用管理命令#

Windows 本地部署#

方案一：WSL2 + Docker（推荐）#

安装 WSL2#

在 WSL2 中部署#

方案二：Docker Desktop#

安装步骤#

部署 OpenClaw#

方案三：原生 Node.js 安装#

安装依赖#

安装 OpenClaw#

macOS 本地部署#

安装 Homebrew#

方案一：Docker Desktop（推荐）#

安装 Docker Desktop#

部署 OpenClaw#

方案二：原生 Node.js 安装#

安装依赖#

安装 OpenClaw#

Ubuntu 24.04 本地部署#

方案一：Docker Compose（推荐）#

安装 Docker#

部署 OpenClaw#

方案二：原生 Node.js 安装#

安装系统依赖#

安装 OpenClaw#

初始配置#

访问 Web UI#

创建管理员账户#

配置通道#

Telegram 通道#

WhatsApp 通道#

配置技能#

配置定时任务#

数据备份与恢复#

Docker 部署备份#

原生部署备份#

常见问题排查#

Docker 相关问题#

端口冲突#

权限问题#

内存不足#

原生部署问题#

Node.js 版本不匹配#

系统服务启动失败#

网络连接问题#

性能优化#

Docker 部署优化#

原生部署优化#

部署方案对比#

推荐选择#

相关资源#

OpenClaw搭建教程

阿里云 OpenClaw 一键部署教程

OpenClaw保姆级部署教程

CoPaw快速入门教程

OpenClaw接入各种频道

评论