Ubuntu 22.04 LTS 部署宝塔面板与 OpenClaw 实战指导文档

摘要

本文档针对在 Ubuntu 22.04 LTS 上部署 OpenClaw（开源自托管 AI 助手网关）的两种思路进行深度技术分析与实战指导。思路一为先部署宝塔（BT）面板，再在宝塔环境中部署 OpenClaw；思路二为绕过面板，直接以 Docker Compose 或 systemd 原生方式部署 OpenClaw。经过对 OpenClaw 项目架构、三种安装方式、宝塔面板集成路径、安全加固、迁移与运维的系统性研究，本文档得出结论：对于关注"后续迁移与管理便利性"的场景，思路二（Docker Compose 直接部署 + Nginx 反向代理 + systemd 托管）在迁移效率、停机时间、数据完整性、回滚能力和安全隔离方面具有压倒性优势；思路一则更适合服务器上同时运行多个网站、运维团队习惯图形化管理的场景。文档提供两条路径的完整实战命令、配置文件示例、踩坑解决方案及决策树，可直接作为部署执行参考。

一、背景与项目概览

1.1 OpenClaw 项目简介

OpenClaw（前身为 Clawdbot / Moltbot）是一个开源、自托管的个人 AI 助手网关，采用 MIT 协议，由 Peter Steinberger 主导开发，GitHub 仓库位于 https://github.com/openclaw/openclaw。其核心定位是运行在用户自有机器或服务器上的 AI 智能体网关，支持多模型接入（Anthropic Claude、OpenAI GPT、Google Gemini、Kimi、DeepSeek、通义千问、Ollama 本地模型等）、工作流自动化、代码辅助、IM 渠道接入（Telegram、WhatsApp、飞书、钉钉、企业微信等）。截至调研时最新版本约为 2026.7.1。

1.2 核心架构组件

1.3 运行时依赖与系统要求

1.4 安全提示

OpenClaw 仍处于 beta 阶段，其 Tools 层包含 exec（Shell 命令执行）等高权限能力。CVE-2026-25253（CVSS 8.8）影响 v2026.1.29 之前版本，存在跨站 WebSocket 劫持漏洞，可导致远程代码执行。部署时务必升级到 ≥ 2026.1.29 版本，该版本已永久移除 auth: "none" 模式，强制使用 Token 或密码认证。

二、部署前环境准备（通用步骤）

无论选择哪种部署思路，以下基础环境准备工作必须先完成。

2.1 系统更新与基础工具安装

# 更新系统软件源和已安装包
sudo apt update && sudo apt upgrade -y

# 安装基础依赖工具
sudo apt install -y curl wget git net-tools build-essential

2.2 配置 Swap（内存低于 4GB 必做）

OpenClaw 的 npm install 或 Docker 镜像构建过程中可能因内存不足被 OOM Killer 终止（退出码 137），低配服务器必须配置 Swap：

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

2.3 配置防火墙基线

Ubuntu 22.04 默认使用 ufw 防火墙。部署前先放行 SSH 端口，避免后续操作中误锁自己：

sudo ufw allow 22/tcp
sudo ufw enable

后续根据部署思路开放对应端口（详见各方案章节）。

2.4 配置时区与时间同步

sudo timedatectl set-timezone Asia/Shanghai
sudo apt install -y chrony
sudo systemctl enable chrony
sudo systemctl start chrony

三、思路一：先部署宝塔面板，再在宝塔中部署 OpenClaw

3.1 宝塔面板安装

3.1.1 安装命令

Ubuntu 22.04 使用官方推荐的一键安装脚本：

if [ -f /usr/bin/curl ];then curl -sSO https://download.bt.cn/install/install_panel.sh;else wget -O install_panel.sh https://download.bt.cn/install/install_panel.sh;fi;bash install_panel.sh docscenter

安装过程中提示 Do you want to install Bt-Panel to the /www directory now?(y/n) 时输入 y 确认。安装完成后终端会输出面板地址、用户名和密码，务必记录。

3.1.2 安装后关键路径与配置

查看默认登录信息：bt 14；修改密码：bt 5；修改用户名：bt 6；修改端口：bt 8。

3.1.3 宝塔面板安全加固（必做）

宝塔面板默认端口 8888 是高频扫描目标，安装后必须立即加固：

# 修改默认端口（如改为 8881）
bt 8
# 同步放行 ufw 防火墙
ufw allow 8881/tcp
# 删除旧端口规则（如需）
ufw delete allow 8888/tcp

在面板设置中进一步配置：绑定域名（仅可通过指定域名访问）、开启面板 SSL、开启 BasicAuth 认证、限制授权 IP。

3.2 在宝塔中部署 OpenClaw

宝塔环境下有三条可行路径，按推荐程度排序。

路径 A：宝塔 Docker 管理器 + Docker Compose 部署（推荐）

此路径将宝塔的可视化管理与 Docker 的环境隔离优势结合，是思路一中的最优选择。

第一步：安装 Docker 管理器

登录宝塔面板 → 软件商店 → 搜索"Docker" → 安装"Docker 管理器"。安装后会自动安装 Docker Engine。

第二步：配置镜像加速器（国内必做）

打开 Docker 管理器 → 设置 → 镜像加速，添加阿里云加速地址：https://registry.cn-hangzhou.aliyuncs.com。

第三步：准备部署目录与配置

mkdir -p /www/wwwroot/openclaw/data/config
mkdir -p /www/wwwroot/openclaw/data/workspace
cd /www/wwwroot/openclaw

创建 docker-compose.yml：

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    environment:
      HOME: /home/node
      TERM: xterm-256color
      TZ: Asia/Shanghai
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "false"
    volumes:
      - ./data/config:/home/node/.openclaw
      - ./data/workspace:/home/node/.openclaw/workspace
    ports:
      - "127.0.0.1:18789:18789"
    init: true
    command: ["node", "dist/index.js", "gateway", "--bind", "loopback", "--port", "18789"]
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    network_mode: "service:openclaw-gateway"
    environment:
      HOME: /home/node
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - ./data/config:/home/node/.openclaw
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
    depends_on:
      - openclaw-gateway

创建 .env 文件：

cat > /www/wwwroot/openclaw/.env << EOF
OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
EOF
cat /www/wwwroot/openclaw/.env  # 记录 Token

第四步：修复数据目录权限

Docker 镜像内运行用户为 node（uid 1000），宿主机目录必须匹配：

chown -R 1000:1000 /www/wwwroot/openclaw/data

第五步：拉取镜像并启动

cd /www/wwwroot/openclaw
docker pull ghcr.io/openclaw/openclaw:latest
# 国内如拉取困难，使用镜像代理：
# docker pull docker.aityp.com/image/ghcr.io/openclaw/openclaw:latest
# docker tag docker.aityp.com/image/ghcr.io/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest

docker compose up -d openclaw-gateway

第六步：执行初始化向导

docker compose run --rm openclaw-cli onboard

向导中选择 Manual 模式（而非 QuickStart，原因见第六章踩坑点），按提示配置模型提供商和 API Key。

第七步：验证

docker compose ps
curl -fsS http://127.0.0.1:18789/healthz
# 获取 Dashboard URL
docker compose run --rm openclaw-cli dashboard --no-open

路径 B：宝塔 Node.js 管理器 + PM2 部署

适合不使用 Docker、希望直接在宿主机运行 OpenClaw 的场景。

第一步：安装 PM2 管理器

宝塔面板 → 软件商店 → 搜索"PM2" → 安装"PM2 管理器"。

第二步：安装 Node.js 22+

打开 PM2 管理器 → Node 版本 → 安装 Node.js 22 LTS（需 22.22.3+）或 Node.js 24 → 设为默认版本。

注意：Ubuntu 22.04 默认 apt 安装的 Node.js 版本为 v12 或 v18，远不满足要求。如未使用宝塔 PM2 管理器，必须通过 NVM 安装：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# 国内如 GitHub 下载失败，使用 Gitee 镜像：
# curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash
nvm install 22
nvm use 22
nvm alias default 22
node -v  # 确认 v22.x.x

第三步：安装 OpenClaw

npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest
source ~/.bashrc
openclaw --version

如出现 openclaw: command not found：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

第四步：初始化

openclaw onboard --install-daemon

第五步：使用宝塔 Supervisor 进程守护

安装 Supervisor 管理器（软件商店 → 搜索"Supervisor"）。添加守护进程：名称 openclaw，启动用户 root，运行目录 /root，启动命令 openclaw gateway start。

注意：宝塔 7.9+ 版本 Supervisor 管理器可能存在 Bug，此时改用"堡塔应用管理器"作为替代。同时需检查 PHP 禁用函数，删除 proc_open 禁用项，否则 Supervisor 启动失败。

路径 C：宝塔网站功能配置反向代理 + SSL

无论路径 A 还是路径 B，都建议通过宝塔的网站管理功能配置 Nginx 反向代理，统一 80/443 端口入口。

第一步：创建站点

宝塔面板 → 网站 → 添加站点 → 填写域名（如 openclaw.example.com，域名需已解析到服务器 IP）→ 根目录随意 → PHP 版本选"纯静态"。

第二步：配置反向代理

站点设置 → 反向代理 → 添加反向代理 → 代理名称 openclaw-proxy → 目标 URL http://127.0.0.1:18789（末尾不带斜杠）→ 开启"发送域名"和"发送真实 IP"。

第三步：开启 WebSocket 支持

在反向代理设置中开启 WebSocket 支持，或手动在站点 Nginx 配置中添加：

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;

第四步：配置 SSL 证书

站点设置 → SSL → 选择 Let's Encrypt → 点击申请 → 开启强制 HTTPS。宝塔会通过计划任务自动续签证书。

3.3 宝塔环境的三层防火墙同步

这是思路一中最容易出问题的环节。宝塔环境存在三层独立防火墙，必须同步配置：

注意：OpenClaw 的 18789 端口在反向代理模式下应绑定 127.0.0.1，不需要在防火墙放行。只有在无反向代理、需直接暴露时才放行（不推荐）。

# ufw 配置
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8881/tcp   # 宝塔面板端口（已修改）
ufw allow 22/tcp
ufw reload

3.4 宝塔环境的定时备份

宝塔计划任务 → 添加任务，创建 Shell 脚本类型任务，每日凌晨 2 点执行：

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/www/backup/openclaw"
mkdir -p $BACKUP_DIR
# Docker 部署：备份数据目录
tar -czf $BACKUP_DIR/openclaw_data_$DATE.tar.gz -C /www/wwwroot/openclaw data .env docker-compose.yml
# 保留最近 7 天
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

四、思路二：直接部署 OpenClaw（Docker Compose + systemd + Nginx）

此思路不安装宝塔面板，直接在 Ubuntu 22.04 上以 Docker Compose 部署 OpenClaw，配合 systemd 和 Nginx 实现生产级运维。

4.1 安装 Docker 与 Docker Compose

# 安装 Docker
curl -fsSL https://get.docker.com | bash

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证
docker --version
docker compose version

国内环境配置镜像加速器：

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://registry.cn-hangzhou.aliyuncs.com"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

4.2 创建专用用户与部署目录

# 创建专用用户（非 root 运行，遵循最小权限原则）
sudo adduser openclaw --disabled-password --gecos ""
sudo usermod -aG docker openclaw

# 创建部署目录
sudo mkdir -p /opt/openclaw/data/config
sudo mkdir -p /opt/openclaw/data/workspace
sudo chown -R openclaw:openclaw /opt/openclaw

4.3 编写 Docker Compose 配置

切换到 openclaw 用户并创建配置：

sudo su - openclaw
cd /opt/openclaw

创建 docker-compose.yml（与思路一路径 A 类似，但增加更完整的安全加固）：

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    environment:
      HOME: /home/node
      TERM: xterm-256color
      TZ: Asia/Shanghai
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "false"
      OPENCLAW_SANDBOX: "true"
    volumes:
      - ./data/config:/home/node/.openclaw
      - ./data/workspace:/home/node/.openclaw/workspace
    ports:
      - "127.0.0.1:18789:18789"
    init: true
    command: ["node", "dist/index.js", "gateway", "--bind", "loopback", "--port", "18789"]
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    network_mode: "service:openclaw-gateway"
    environment:
      HOME: /home/node
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - ./data/config:/home/node/.openclaw
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
    depends_on:
      openclaw-gateway:
        condition: service_healthy

创建 .env 文件：

cat > /opt/openclaw/.env << EOF
OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
EOF
chmod 600 /opt/openclaw/.env

修复数据目录权限：

chown -R 1000:1000 /opt/openclaw/data

4.4 拉取镜像并初始化

cd /opt/openclaw
docker pull ghcr.io/openclaw/openclaw:latest
docker compose up -d openclaw-gateway

# 执行初始化向导
docker compose run --rm openclaw-cli onboard

初始化向导关键选择：

4.5 验证部署

# 容器状态
docker compose ps

# 健康检查
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

# 获取 Dashboard URL
docker compose run --rm openclaw-cli dashboard --no-open

# 查看日志
docker compose logs -f --tail=100

4.6 配置 systemd 管理 Docker Compose

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

[Unit]
Description=OpenClaw Docker Compose Service
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/openclaw
User=openclaw
Group=openclaw
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target

启用并启动：

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

4.7 配置 Nginx 反向代理 + HTTPS

安装 Nginx 和 certbot：

sudo apt install -y nginx certbot python3-certbot-nginx
sudo systemctl enable nginx
sudo systemctl start nginx

创建 Nginx 配置文件 /etc/nginx/sites-available/openclaw：

server {
    listen 80;
    server_name openclaw.example.com;
    return 301 https://$host$request_uri;
}

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

    ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;

    # 安全响应头
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Basic Auth 认证（双重保护）
    auth_basic "OpenClaw Login";
    auth_basic_user_file /etc/nginx/.htpasswd;

    access_log /var/log/nginx/openclaw-access.log;
    error_log /var/log/nginx/openclaw-error.log;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Authorization "";
        proxy_set_header X-Forwarded-User $remote_user;

        # WebSocket 支持（必需）
        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_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 86400s;
        proxy_buffering off;
    }
}

启用站点并申请 SSL 证书：

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t

# 创建 Basic Auth 密码文件
sudo sh -c 'echo "admin:$(openssl passwd -apr1 YourStrongPassword)" > /etc/nginx/.htpasswd'

# 申请 Let's Encrypt 证书（自动修改 Nginx 配置）
sudo certbot --nginx -d openclaw.example.com
sudo systemctl reload nginx

4.8 配置 OpenClaw trustedProxies

在 OpenClaw 配置文件中设置信任代理，使 Gateway 正确识别经过 Nginx 代理的请求：

docker compose run --rm openclaw-cli config set gateway.trustedProxies '["127.0.0.1"]' --strict-json
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["https://openclaw.example.com"]' --strict-json
docker compose restart openclaw-gateway

4.9 安装 Fail2Ban 防入侵

sudo apt install -y fail2ban
sudo tee /etc/fail2ban/jail.local << 'EOF'
[sshd]
enabled = true
maxretry = 3
bantime = 86400

[nginx-auth]
enabled = true
maxretry = 3
bantime = 86400
EOF
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

4.10 防火墙最终配置

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp
# 注意：18789 端口不对外开放，仅绑定 127.0.0.1
sudo ufw reload
sudo ufw status verbose

五、OpenClaw 安全加固深度配置

无论选择哪种部署思路，以下安全加固配置都必须执行。

5.1 Gateway 认证配置

v2026.1.29 起强制认证，使用 openssl rand -hex 32 生成强 Token：

# 查看当前 Token
docker compose run --rm openclaw-cli config get gateway.auth.token

# 或在配置文件中确认
cat /opt/openclaw/data/config/openclaw.json | grep token

5.2 Tools 与 Skills 权限管控

OpenClaw 的能力分为两层：Tools（25种，底层系统能力）和 Skills（53个，任务方法组合）。安全配置的核心是：exec 工具必须开启审批，Skills 使用白名单模式。

在 ~/.openclaw/openclaw.json（Docker 部署中为 ./data/config/openclaw.json）中配置：

{
  "tools": {
    "allow": [
      "read", "write", "edit", "apply_patch", "exec", "process",
      "web_search", "web_fetch", "browser", "image",
      "memory_search", "memory_get",
      "sessions_list", "sessions_history", "sessions_send",
      "message", "cron", "gateway", "agents_list"
    ],
    "deny": [
      "nodes", "canvas", "llm_task", "lobster"
    ]
  },
  "approvals": {
    "exec": {
      "enabled": true
    }
  },
  "skills": {
    "allowBundled": [
      "gog", "github", "tmux", "session-logs",
      "weather", "summarize", "clawhub",
      "healthcheck", "skill-creator"
    ]
  }
}

关键安全原则：exec 工具开启审批（approvals.exec.enabled: true），防止 AI 执行删库等危险命令；Skills 白名单模式，默认53个全部关闭，仅保留实际使用的；社交消息类 Skills（imsg、slack、discord、wacli）全部关闭；密码类 Skill（1password）禁止开启。

5.3 日志脱敏配置

防止 API Key 泄露到日志中：

{
  "logging": {
    "redactPatterns": ["sk-*", "Bearer *"]
  }
}

5.4 会话隔离配置

防止跨用户信息泄露：

{
  "dmScope": "per-channel-peer"
}

per-channel-peer 模式下，每个发送者与渠道对独立隔离会话，是推荐配置。main 模式下所有 DM 共享一个会话，存在跨用户泄露风险。

5.5 文件权限加固

chmod 600 /opt/openclaw/data/config/openclaw.json
chmod 700 /opt/openclaw/data/config
chmod 600 /opt/openclaw/.env

5.6 运行安全审计

# 基本审计
docker compose run --rm openclaw-cli security audit

# 深度审计（含 Gateway 实时探测）
docker compose run --rm openclaw-cli security audit --deep

# 自动修复安全配置
docker compose run --rm openclaw-cli security audit --fix

5.7 安全加固完整清单

必须完成的项：升级到最新版本（≥ 2026.1.29）、启用 Token 认证、exec 工具开启审批、Skills 使用白名单、Docker 沙箱隔离、Gateway 绑定 loopback、配置日志脱敏、设置 dmScope: "per-channel-peer"、文件权限加固、API 密钥设置最小权限和额度限制、运行安全审计。

严禁的项：在 0.0.0.0 上暴露未认证的 Gateway、--privileged 特权模式启动容器、将 API 密钥硬编码在配置文件中、在主力工作机（含个人隐私数据）上直接安装。

六、常见踩坑点与解决方案

6.1 Node.js 版本不满足要求（最高频，约 60% 安装失败）

问题：Ubuntu 22.04 默认 apt 安装的 Node.js 版本为 v12 或 v18，远低于 OpenClaw 要求的 22.22.3+。表现为 npm install 时报语法错误或运行时报 node:sqlite 相关错误。

解决：使用 NVM 安装正确版本。国内网络下 NVM 安装脚本可能从 GitHub 下载失败，改用 Gitee 镜像：

curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

6.2 npm EACCES 权限错误

问题：全局安装时报 EACCES: permission denied。

解决：配置用户级 npm 全局目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

或使用 NVM 管理的 Node.js（自动避免权限问题）。

6.3 QuickStart 模式中断导致 Dashboard 无法访问

问题：初始化向导选择 QuickStart 模式后中途意外退出，Gateway 未完成初始化，后续无法进入 Dashboard。

解决：选择 Manual 模式重新初始化，Manual 模式优先保证 Gateway 初始化完成。如仍无法修复，完全重装：

docker compose down
mv ./data/config ./data/config-backup
mkdir -p ./data/config
chown -R 1000:1000 ./data/config
docker compose up -d openclaw-gateway
docker compose run --rm openclaw-cli onboard

6.4 Docker 容器权限问题

问题：容器启动后无法读写挂载目录，报 EACCES 或 permission denied。

解决：OpenClaw Docker 镜像内运行用户为 node（uid 1000），宿主机挂载目录必须匹配：

chown -R 1000:1000 /opt/openclaw/data
# 或宝塔路径
chown -R 1000:1000 /www/wwwroot/openclaw/data

6.5 ghcr.io 镜像拉取失败

问题：国内网络拉取 GitHub Container Registry 镜像超时。

解决：使用镜像代理：

docker pull docker.aityp.com/image/ghcr.io/openclaw/openclaw:latest
docker tag docker.aityp.com/image/ghcr.io/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest

6.6 反向代理 502 Bad Gateway

问题：通过域名访问返回 502。

排查顺序：检查 OpenClaw 容器是否运行（docker compose ps）、检查 18789 端口是否监听（curl http://127.0.0.1:18789/healthz）、检查 Nginx 配置中目标 URL 是否正确（末尾不带斜杠）、检查防火墙是否放行。

6.7 Web UI 无法远程访问

推荐使用 SSH 隧道方式访问，不直接暴露端口：

# 在本地机器执行
ssh -N -L 18789:127.0.0.1:18789 user@server_ip
# 然后本地浏览器访问 http://localhost:18789/#token=YOUR_TOKEN

如服务器重装后 SSH 连接报 Host key verification failed：

ssh-keygen -R <server_ip>

6.8 宝塔与 ufw 防火墙冲突

问题：宝塔面板开了端口，但 ufw 未放行，导致外部无法访问。宝塔防火墙与系统 ufw 是两层独立防线。

解决：同步配置三层防火墙（云安全组 + ufw + 宝塔防火墙），详见第 3.3 节。

6.9 低配 VPS 安装 OOM（退出码 137）

问题：1GB RAM 的 VPS 上 npm install 或 Docker 构建被 OOM Killer 终止。

解决：配置 Swap（见第 2.2 节），或降低构建堆内存：

export NODE_OPTIONS=--max-old-space-size=4096

6.10 终端渲染"卡住"

问题：TUI 界面看起来卡住不动。

解决：这并非程序卡死，滚动鼠标滚轮即可刷新终端显示。

七、迁移方案深度对比

7.1 两种思路迁移能力对比

7.2 思路一迁移流程

# 1. 停止服务
cd /www/wwwroot/openclaw && docker compose down

# 2. 打包配置和数据
tar -czf openclaw-backup.tar.gz -C /www/wwwroot/openclaw data .env docker-compose.yml

# 3. 使用宝塔一键迁移工具迁移网站/数据库配置
#    （OpenClaw 数据需手动处理）

# 4. 新服务器安装宝塔面板
curl -sSO https://download.bt.cn/install/install_panel.sh && bash install_panel.sh docscenter

# 5. 安装 Docker 管理器（软件商店）

# 6. 恢复 OpenClaw 数据
cd /www/wwwroot/openclaw
tar -xzf openclaw-backup.tar.gz
chown -R 1000:1000 data

# 7. 拉取镜像并启动
docker pull ghcr.io/openclaw/openclaw:latest
docker compose up -d openclaw-gateway

# 8. 验证
curl -fsS http://127.0.0.1:18789/healthz

7.3 思路二迁移流程

# 1. 停止服务
cd /opt/openclaw && docker compose down

# 2. 备份数据
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz data .env docker-compose.yml

# 3. 传输到新服务器
scp openclaw-backup-*.tar.gz docker-compose.yml user@new-server:~/

# 4. 新服务器安装 Docker
curl -fsSL https://get.docker.com | bash
sudo systemctl enable docker

# 5. 拉取镜像
docker pull ghcr.io/openclaw/openclaw:latest

# 6. 恢复数据
mkdir -p /opt/openclaw && cd /opt/openclaw
tar -xzf ~/openclaw-backup-*.tar.gz
chown -R 1000:1000 data

# 7. 启动
docker compose up -d openclaw-gateway

# 8. 验证
docker compose ps
curl -fsS http://127.0.0.1:18789/healthz

7.4 回滚策略对比

思路二的 Docker 部署具有显著回滚优势：

# 升级前先标记当前版本
docker tag ghcr.io/openclaw/openclaw:latest openclaw:backup-$(date +%Y%m%d)

# 升级
docker compose pull
docker compose up -d

# 如出问题，秒级回滚
docker compose down
# 修改 docker-compose.yml 中 image 为 openclaw:backup-YYYYMMDD
docker compose up -d

思路一的 npm 安装方式回滚：

npm install -g openclaw@<旧版本号>
openclaw doctor
openclaw gateway restart

八、长期运维最佳实践

8.1 日志管理

日志轮转配置（/etc/logrotate.d/openclaw）：

/opt/openclaw/data/config/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

8.2 监控

进程存活监控脚本（配合 crontab 每 5 分钟执行）：

#!/bin/bash
# /opt/openclaw/scripts/check-openclaw.sh
if ! docker compose -f /opt/openclaw/docker-compose.yml ps | grep -q "Up"; then
    docker compose -f /opt/openclaw/docker-compose.yml up -d openclaw-gateway
    echo "$(date): OpenClaw restarted" >> /var/log/openclaw-monitor.log
fi

# crontab
*/5 * * * * /opt/openclaw/scripts/check-openclaw.sh

OpenClaw 内置健康检查端点：/healthz（存活检查）、/readyz（就绪检查）、/api/diagnostics/prometheus（Prometheus 指标），可集成到 Prometheus + Grafana 监控体系。

8.3 版本升级流程

升级前必做：

docker compose run --rm openclaw-cli --version
docker compose run --rm openclaw-cli status
# 备份当前数据
tar -czf /opt/openclaw/backup/pre-upgrade-$(date +%Y%m%d).tar.gz data

升级执行：

cd /opt/openclaw
docker compose pull
docker compose up -d

升级后必做：

docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli security audit --deep
curl -fsS http://127.0.0.1:18789/healthz

8.4 数据备份策略

备份脚本（crontab 每日凌晨 2 点执行）：

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/opt/openclaw/backup"
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/openclaw_$DATE.tar.gz -C /opt/openclaw data .env docker-compose.yml
find $BACKUP_DIR -name "openclaw_*.tar.gz" -mtime +30 -delete

九、两种部署思路综合决策分析

9.1 对比总表

9.2 适用场景与推荐

思路一（宝塔 + OpenClaw）适合：

服务器上同时运行多个网站或服务、运维团队习惯图形化管理界面、不需要频繁迁移、对宝塔生态（数据库管理、文件管理、计划任务）有明确需求。此方案下推荐使用宝塔 Docker 管理器 + Docker Compose 部署 OpenClaw（路径 A），再配合宝塔网站功能配置反向代理和 SSL，兼顾图形化便利与 Docker 隔离。

思路二（直接 Docker 部署）适合：

专注于 OpenClaw 部署、需要频繁迁移或弹性扩展、对安全性和可控性要求高、需要快速回滚和版本管理、有一定 Linux/Docker 技术能力。此方案在迁移便利性、停机时间、数据完整性、回滚能力方面具有压倒性优势。

9.3 最终推荐

针对用户明确提出的"方便后续迁移与管理"需求，本文档推荐思路二（Docker Compose 直接部署 + systemd 托管 + Nginx 反向代理 + Let's Encrypt SSL）作为首选方案。理由如下：

第一，迁移效率。Docker 镜像加数据卷的迁移方式只需 3-4 步、5-15 分钟停机时间，远优于宝塔环境下需要重建 Node.js 环境和手动处理非标准网站配置的 30 分钟至 2 小时；

第二，环境一致性。Docker 镜像保证跨平台运行环境完全一致，消除"在我机器上能跑"的问题。目标服务器只需安装 Docker，无需匹配 Node.js 版本、npm 全局包等依赖；

第三，回滚能力。Docker 部署可通过保留旧镜像实现秒级回滚，而宝塔环境下的 npm 安装方式回滚需要重新安装指定版本并运行 doctor 修复配置；

第四，安全隔离。Docker 容器配合 cap_drop: ALL、no-new-privileges: true、--bind loopback 提供最彻底的安全隔离，不引入宝塔面板本身的攻击面（面板端口暴露、默认弱密码等）；

第五，Ubuntu 22.04 LTS 原生优势。systemd 是 Ubuntu 22.04 的原生服务管理器，Nginx 和 certbot 均可通过 apt 直接安装，无需额外面板即可实现完整的生产级运维；

如用户服务器上还有其他网站或服务需要管理，可在思路二基础上额外安装宝塔面板仅用于管理其他站点，OpenClaw 独立通过 Docker Compose 运行，两者互不干扰；

十、诊断命令速查表

References

1. OpenClaw GitHub Repository
2. OpenClaw 官方安装脚本
3. OpenClaw 官方文档（中文）
4. OpenClaw Docker 部署文档
5. Ubuntu下openclaw部署全流程 - 博客园
6. openclaw新手部署详细教程——适用于ubuntu22.04 - CSDN
7. Ubuntu 22.04安装部署OpenClaw完整教程 - CSDN
8. 关于OpenClaw部署在Ubuntu上的经验小结 - 博客园
9. Ubuntu上docker安装OpenClaw - 腾讯云
10. Ubuntu 部署 OpenClaw 终极指南 - CSDN
11. Ubuntu 云服务部署 OpenClaw 并接入飞书机器人 - 博客园
12. 全网最详细安装部署教程 - GitHub Pages
13. OpenClaw 完全部署指南：从入门到安全加固 - 知乎
14. VMWare虚拟机OpenClaw部署踩坑实录 - 博客园
15. OpenClaw安全部署使用完全指南｜25类Tools与53个Skills - 阿里云
16. 手把手本地部署OpenClaw安全篇 - CSDN
17. OpenClaw公网部署：全链路安全加固 - 腾讯云
18. OpenClaw Docker容器化部署生命周期管理 - 阿里云
19. 宝塔面板官方安装文档
20. 宝塔Linux面板命令大全
21. 宝塔面板 Node.js PM2 部署教程
22. 宝塔面板整机迁移教程
23. OpenClaw中文文档：升级、迁移与卸载 - 博客园
24. 在Linux上用systemd运行OpenClaw守护进程 - OpenClaw中文站
25. OpenClaw生产环境稳定性清单 - 鲲鹏AI