installation

name	installation
description	OpenClaw 安装与部署
version	1.0.0
author	terminal-skills
tags	["openclaw","installation","deployment","setup"]

OpenClaw 安装与部署

概述

OpenClaw 是一个开源的分布式任务调度和工作流编排平台，本文档涵盖各种环境下的安装部署方法。

环境要求

系统要求

# 检查系统版本
cat /etc/os-release
uname -a

# 最低要求
# - CPU: 2 核心
# - 内存: 4GB
# - 磁盘: 20GB
# - 操作系统: Linux (CentOS 7+, Ubuntu 18.04+, Debian 10+)

# 检查资源
free -h
df -h
nproc

依赖检查

# 检查 Docker
docker --version
docker info

# 检查 Docker Compose
docker-compose --version

# 检查 Java (如需原生安装)
java -version

# 检查 Python
python3 --version
pip3 --version

Docker 方式安装（推荐）

单机部署

# 创建工作目录
mkdir -p /opt/openclaw && cd /opt/openclaw

# 下载 docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -o docker-compose.yml

# 创建必要目录
mkdir -p {data,logs,config}

# 启动服务
docker-compose up -d

# 查看状态
docker-compose ps
docker-compose logs -f

自定义配置

# docker-compose.yml
version: '3.8'

services:
  openclaw-server:
    image: openclaw/openclaw-server:latest
    container_name: openclaw-server
    ports:
      - "8080:8080"
      - "9090:9090"
    environment:
      - OPENCLAW_DB_HOST=openclaw-db
      - OPENCLAW_DB_PORT=3306
      - OPENCLAW_DB_NAME=openclaw
      - OPENCLAW_DB_USER=openclaw
      - OPENCLAW_DB_PASSWORD=${DB_PASSWORD:-openclaw123}
      - OPENCLAW_REDIS_HOST=openclaw-redis
      - OPENCLAW_REDIS_PORT=6379
      - JAVA_OPTS=-Xms1g -Xmx2g
    volumes:
      - ./data:/opt/openclaw/data
      - ./logs:/opt/openclaw/logs
      - ./config:/opt/openclaw/config
    depends_on:
      - openclaw-db
      - openclaw-redis
    restart: unless-stopped

  openclaw-worker:
    image: openclaw/openclaw-worker:latest
    container_name: openclaw-worker
    environment:
      - OPENCLAW_SERVER_HOST=openclaw-server
      - OPENCLAW_SERVER_PORT=9090
      - WORKER_GROUP=default
      - WORKER_THREADS=8
    volumes:
      - ./logs:/opt/openclaw/logs
    depends_on:
      - openclaw-server
    restart: unless-stopped
    deploy:
      replicas: 2

  openclaw-db:
    image: mysql:8.0
    container_name: openclaw-db
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD:-root123}
      - MYSQL_DATABASE=openclaw
      - MYSQL_USER=openclaw
      - MYSQL_PASSWORD=${DB_PASSWORD:-openclaw123}
    volumes:
      - ./data/mysql:/var/lib/mysql
    restart: unless-stopped

  openclaw-redis:
    image: redis:7-alpine
    container_name: openclaw-redis
    command: redis-server --appendonly yes
    volumes:
      - ./data/redis:/data
    restart: unless-stopped

环境变量配置

# 创建 .env 文件
cat > .env << 'EOF'
# 数据库配置
DB_ROOT_PASSWORD=your_root_password
DB_PASSWORD=your_db_password

# 服务配置
OPENCLAW_PORT=8080
OPENCLAW_GRPC_PORT=9090

# 日志级别
LOG_LEVEL=INFO
EOF

# 启动时加载
docker-compose --env-file .env up -d

Kubernetes 部署

Helm 安装

# 添加 Helm 仓库
helm repo add openclaw https://charts.openclaw.io
helm repo update

# 查看可用版本
helm search repo openclaw

# 安装（默认配置）
helm install openclaw openclaw/openclaw -n openclaw --create-namespace

# 安装（自定义配置）
helm install openclaw openclaw/openclaw \
  -n openclaw --create-namespace \
  -f values.yaml

# 查看状态
kubectl get pods -n openclaw
kubectl get svc -n openclaw

values.yaml 示例

# values.yaml
server:
  replicaCount: 2
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "1000m"

worker:
  replicaCount: 3
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

mysql:
  enabled: true
  auth:
    rootPassword: "your_root_password"
    database: openclaw
    username: openclaw
    password: "your_password"
  primary:
    persistence:
      size: 20Gi

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: openclaw.example.com
      paths:
        - path: /
          pathType: Prefix

手动 YAML 部署

# 创建命名空间
kubectl create namespace openclaw

# 应用配置
kubectl apply -f https://raw.githubusercontent.com/openclaw/openclaw/main/deploy/kubernetes/ -n openclaw

# 或本地文件
kubectl apply -f openclaw-deployment.yaml -n openclaw

# 查看部署状态
kubectl get all -n openclaw
kubectl describe deployment openclaw-server -n openclaw

原生安装

下载安装包

# 下载最新版本
OPENCLAW_VERSION=$(curl -s https://api.github.com/repos/openclaw/openclaw/releases/latest | grep tag_name | cut -d '"' -f 4)
wget https://github.com/openclaw/openclaw/releases/download/${OPENCLAW_VERSION}/openclaw-${OPENCLAW_VERSION}.tar.gz

# 解压
tar -xzf openclaw-${OPENCLAW_VERSION}.tar.gz -C /opt/
mv /opt/openclaw-${OPENCLAW_VERSION} /opt/openclaw
cd /opt/openclaw

初始化数据库

# 创建数据库
mysql -u root -p << 'EOF'
CREATE DATABASE IF NOT EXISTS openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'openclaw'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'%';
FLUSH PRIVILEGES;
EOF

# 导入初始数据
mysql -u openclaw -p openclaw < /opt/openclaw/sql/init.sql

配置并启动

# 编辑配置
vim /opt/openclaw/conf/application.yml

# 启动服务
/opt/openclaw/bin/openclaw-server.sh start
/opt/openclaw/bin/openclaw-worker.sh start

# 查看状态
/opt/openclaw/bin/openclaw-server.sh status
/opt/openclaw/bin/openclaw-worker.sh status

# 查看日志
tail -f /opt/openclaw/logs/openclaw-server.log

Systemd 服务

# 创建 Server 服务
cat > /etc/systemd/system/openclaw-server.service << 'EOF'
[Unit]
Description=OpenClaw Server
After=network.target mysql.service redis.service

[Service]
Type=forking
User=openclaw
Group=openclaw
Environment=JAVA_HOME=/usr/lib/jvm/java-11
ExecStart=/opt/openclaw/bin/openclaw-server.sh start
ExecStop=/opt/openclaw/bin/openclaw-server.sh stop
ExecReload=/opt/openclaw/bin/openclaw-server.sh restart
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 创建 Worker 服务
cat > /etc/systemd/system/openclaw-worker.service << 'EOF'
[Unit]
Description=OpenClaw Worker
After=network.target openclaw-server.service

[Service]
Type=forking
User=openclaw
Group=openclaw
Environment=JAVA_HOME=/usr/lib/jvm/java-11
ExecStart=/opt/openclaw/bin/openclaw-worker.sh start
ExecStop=/opt/openclaw/bin/openclaw-worker.sh stop
ExecReload=/opt/openclaw/bin/openclaw-worker.sh restart
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动
systemctl daemon-reload
systemctl enable openclaw-server openclaw-worker
systemctl start openclaw-server openclaw-worker
systemctl status openclaw-server openclaw-worker

安装验证

健康检查

# API 健康检查
curl -s http://localhost:8080/api/health | jq .

# 组件状态
curl -s http://localhost:8080/api/status | jq .

# 集群信息
curl -s http://localhost:8080/api/cluster/info | jq .

访问 Web UI

# 默认访问地址
# http://localhost:8080

# 默认管理员账号
# 用户名: admin
# 密码: admin123 (首次登录后请修改)

# 测试登录
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

升级指南

Docker 升级

# 备份数据
docker-compose exec openclaw-db mysqldump -u openclaw -p openclaw > backup.sql

# 拉取新版本
docker-compose pull

# 重启服务
docker-compose down
docker-compose up -d

# 验证
docker-compose ps
curl -s http://localhost:8080/api/health

Kubernetes 升级

# Helm 升级
helm upgrade openclaw openclaw/openclaw -n openclaw

# 查看升级状态
kubectl rollout status deployment/openclaw-server -n openclaw

# 回滚（如需要）
helm rollback openclaw -n openclaw

卸载

Docker 卸载

# 停止并删除容器
docker-compose down

# 删除数据（谨慎）
docker-compose down -v
rm -rf /opt/openclaw

# 删除镜像
docker rmi $(docker images openclaw/* -q)

Kubernetes 卸载

# Helm 卸载
helm uninstall openclaw -n openclaw

# 删除命名空间
kubectl delete namespace openclaw

# 清理 PVC（谨慎）
kubectl delete pvc --all -n openclaw

安装问题排查

问题	可能原因	解决方法
端口被占用	其他服务占用	netstat -tlnp | grep 8080
数据库连接失败	配置错误/网络问题	检查连接配置和网络
内存不足	JVM 配置过大	调整 JAVA_OPTS
权限问题	目录权限不足	chown -R openclaw:openclaw /opt/openclaw
Worker 无法注册	Server 未启动/网络问题	检查 Server 状态和网络连通性