09. Docker 部署指南

课程信息

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

• 个人博客：https://aiking.dev

• 难度等级：🔴 高级

• 阅读时间：30 分钟

• 前置知识：了解 Docker 基础概念、已完成快速开始（03-快速开始指南）

本篇你将学会： 用 Docker 部署 OpenClaw 到服务器、配置 docker-compose、管理数据持久化、设置自动更新

谁需要看这篇？ 如果你只是在自己电脑上用，不需要看这篇。这篇是给想把 OpenClaw 部署到远程服务器（比如云服务器）的人准备的

为什么用 Docker 部署 OpenClaw？

老金在部署课里不会只写一条 docker 命令，因为真正上线后要面对的是升级、日志、回滚和权限。

官方文档：docs.openclaw.ai/install/docker

在聊具体操作之前，先搞清楚一个问题：我直接装不行吗，为什么要折腾 Docker（容器化平台，把应用和环境打包在一起运行）？

Docker 部署的优势

环境一致性 — 本地能跑的，服务器上一定能跑。不会出现"我这里没问题啊"的经典场景。Docker 把 Node.js 版本、系统依赖、配置文件全部打包在一起，消除了环境差异。

一键部署 — 不需要在服务器上手动装 Node.js、配置 npm、处理依赖冲突。一条 docker compose up 搞定一切。

隔离性 — OpenClaw 跑在自己的容器里，不会污染宿主机环境。你可以在同一台机器上跑多个版本的 OpenClaw，互不干扰。

易于迁移 — 想换服务器？把 docker-compose.yml（Docker 的编排工具，用一个配置文件管理多个容器）和数据卷拷过去，几分钟就能恢复。

Agent 沙箱 — Docker 天然适合做 Agent 工具执行的沙箱。通过 agents.defaults.sandbox.mode 配置（默认 "non-main"），非主会话的 Agent 自动在独立 Docker 容器中隔离执行，不会搞坏宿主机。

回滚方便 — 升级出问题？切回上一个镜像（容器的模板，包含了运行所需的一切）版本就行，数据都在 volume（数据卷，让容器重启后数据不丢失）里，不受影响。

什么时候不需要 Docker

• 在自己电脑上开发调试，直接本地安装更快

• 只是临时试用，不需要持久化部署

• 机器资源极其有限（Docker 本身有一定开销）

经验法则：本地开发用原生安装，远程部署用 Docker。

---

Docker 基础环境准备

安装 Docker

Linux（推荐 Ubuntu 22.04+）

# 官方一键安装脚本（最省事）
curl -fsSL https://get.docker.com | sh

# 把当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER

# 重新登录让权限生效
newgrp docker

# 验证安装
docker --version
docker compose version

macOS

# 方法一：Docker Desktop（图形界面）
# 从 https://www.docker.com/products/docker-desktop/ 下载安装

# 方法二：Homebrew
brew install --cask docker

# 安装后启动 Docker Desktop，验证
docker --version
docker compose version

Windows

# 方法一：Docker Desktop（推荐）
# 从 https://www.docker.com/products/docker-desktop/ 下载安装
# 需要开启 WSL2 或 Hyper-V

# 方法二：winget
winget install Docker.DockerDesktop

# 安装后重启，验证
docker --version
docker compose version

系统要求

项目

最低要求

推荐配置

CPU

1 核

2 核+

内存

2 GB

4 GB+

磁盘

10 GB

20 GB+

Docker

24.0+

最新稳定版

Docker Compose

v2.20+

最新稳定版

验证 Docker 环境

docker run --rm hello-world    # 确认 Docker 正常
docker compose version         # 确认 Compose v2（不带横杠）

注意：本文全部使用 docker compose（v2 语法），不是 docker-compose（v1 已弃用）。

---

官方 Docker 镜像使用

拉取官方镜像

docker pull openclaw/openclaw:latest    # 最新稳定版
docker pull openclaw/openclaw:v2026.6.8  # 指定稳定版本
docker images | grep openclaw           # 查看本地镜像

v2026.6.8 发布校验：Docker / npm 生产部署时，优先用官方发布包和固定 tag；自建镜像要保留 package integrity check，不要为了减小镜像随手删 lockfile / shrinkwrap。v2026.6.8 release notes 强化了 release / CI / Docker / E2E / diagnostics 证据链、bounded logs、readiness probes、latest tag parsing 和 rollback snapshots，生产升级时要把这些证据当成升级核对入口。

安全补丁提示：这一轮还包含 protobufjs 8.4.0 安全更新。生产镜像不要长期停在旧 tag；升级镜像后用 openclaw doctor 和容器健康检查确认 Gateway、插件和 channels 都仍能启动。

从仓库 Dockerfile 构建镜像

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

如果需要自定义镜像（比如加额外系统包）：

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

# 基础构建
docker build -t openclaw:local -f Dockerfile .

# 带额外 apt 包构建
docker build --build-arg OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg imagemagick" \
  -t openclaw:custom -f Dockerfile .

镜像标签说明

标签

说明

适用场景

latest

最新稳定版

生产环境

vYYYY.M.D

指定版本号（如 v2026.6.8）

需要版本锁定

nightly

每日构建

尝鲜新功能

local

本地构建

自定义需求

Gateway ready 与 restart trace

v2026.5.22 对 Gateway 启动路径做了多处性能和诊断优化：插件元数据、channel catalog、startup-idle plugin work、ACPX runtime 会尽量延迟或缓存，Gateway ready 信号不再被未用到的 handler tree 阻塞。

生产部署的健康检查建议区分三件事：

1. 容器进程是否存活。

2. Gateway /readyz 或状态命令是否 ready。

3. channel sidecar、插件服务、meeting notes 等可选能力是否已启动。

如果 restart 变慢或 ready 抖动，先看 restart trace 和 Gateway 日志，不要直接扩大超时时间掩盖问题。

快速启动单容器

不想写 docker-compose.yml？一条命令也能跑：

docker run -d --name openclaw-gateway -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \
  --restart unless-stopped openclaw/openclaw:latest

但对于生产环境，强烈建议用 Docker Compose。

---

docker-compose 完整配置详解

基础版：只跑 Gateway

最简单的配置，适合个人使用：

# docker-compose.yml
version: "3.8"

services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/home/node/.openclaw
      - openclaw-workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:18789/health').then(r => { if (!r.ok) process.exit(1) })"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  openclaw-data:
  openclaw-workspace:

进阶版：Gateway + 数据库 + Redis

适合团队使用，需要持久化存储和缓存：

# docker-compose.yml
version: "3.8"

services:
  # ========== OpenClaw Gateway ==========
  openclaw-gateway:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/home/node/.openclaw
      - openclaw-workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - DATABASE_URL=postgresql://openclaw:${DB_PASSWORD}@postgres:5432/openclaw
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=production
      - LOG_LEVEL=info
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:18789/health').then(r => { if (!r.ok) process.exit(1) })"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
    networks:
      - openclaw-net

  # ========== PostgreSQL 数据库 ==========
  postgres:
    image: postgres:16-alpine
    container_name: openclaw-postgres
    environment:
      - POSTGRES_USER=openclaw
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=openclaw
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U openclaw"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - openclaw-net

  # ========== Redis 缓存 ==========
  redis:
    image: redis:7-alpine
    container_name: openclaw-redis
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - openclaw-net

volumes:
  openclaw-data:
  openclaw-workspace:
  postgres-data:
  redis-data:

networks:
  openclaw-net:
    driver: bridge

启动和管理

docker compose up -d                          # 启动所有服务（后台）
docker compose ps                             # 查看运行状态
docker compose logs -f                        # 实时查看日志
docker compose logs -f openclaw-gateway       # 只看 Gateway 日志
docker compose down                           # 停止所有服务
docker compose down -v                        # 停止并删除数据卷（谨慎！）
docker compose restart openclaw-gateway       # 重启单个服务
docker compose pull && docker compose up -d   # 更新镜像并重启

---

环境变量配置大全

.env 文件模板

在 docker-compose.yml 同目录下创建 .env 文件：

# ========== 核心配置 ==========
# Gateway 访问令牌（必填）
OPENCLAW_GATEWAY_TOKEN=your-secure-token-here

# Gateway 访问密码（可选，与 Token 二选一或同时使用）
OPENCLAW_GATEWAY_PASSWORD=your-secure-password-here

# 运行环境
NODE_ENV=production

# 日志级别：silent, fatal, error, warn, info, debug, trace
LOG_LEVEL=info

# ========== 数据库配置 ==========
DB_PASSWORD=your-strong-db-password

# ========== 模型提供商 API Keys ==========
# OpenAI
OPENAI_API_KEY=sk-proj-xxxxx

# Anthropic
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Google Gemini
GEMINI_API_KEY=AIzaSyxxxxx

# Azure OpenAI
AZURE_OPENAI_API_KEY=xxxxx
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com

# 本地模型（Ollama）
OLLAMA_BASE_URL=http://host.docker.internal:11434

# ========== 聊天平台集成 ==========
# Telegram
TELEGRAM_BOT_TOKEN=your-telegram-bot-token

# Discord
DISCORD_BOT_TOKEN=your-discord-bot-token

# Slack
SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
SLACK_APP_TOKEN=xapp-your-slack-app-token

# ========== 可选配置 ==========
# 额外 apt 包（构建时安装）
OPENCLAW_DOCKER_APT_PACKAGES=ffmpeg imagemagick

# 持久化 home 目录
OPENCLAW_HOME_VOLUME=openclaw-home

# 额外挂载路径
OPENCLAW_EXTRA_MOUNTS=/path/to/data:/data

环境变量优先级

Docker Compose 中环境变量优先级（从高到低）：命令行 -e > environment: 直接设置 > env_file: > .env 文件 > 镜像默认值。

敏感信息处理

生产环境不要把密钥直接写在 docker-compose.yml 里。用 ${VARIABLE} 引用 .env 文件中的值，或使用 Docker Secrets（Swarm 模式）。记得把 .env 加入 .gitignore。

---

数据持久化（Volumes 配置）

为什么需要 Volumes

Docker 容器是临时的 — 容器删了，里面的数据就没了。Volumes 把数据存在宿主机上，容器重建后数据还在。

关键数据目录

容器内路径

说明

是否需要持久化

/home/node/.openclaw

OpenClaw 配置和数据

必须

/home/node/.openclaw/workspace

工作空间文件

必须

/var/lib/postgresql/data

PostgreSQL 数据

必须

/data

Redis 持久化数据

推荐

Named Volumes vs Bind Mounts

volumes:
  # Named Volume（推荐）— Docker 管理，性能好
  openclaw-data:/home/node/.openclaw

  # Bind Mount — 直接映射宿主机目录，方便查看文件
  ./local-data:/home/node/.openclaw

Named Volume 性能更好（尤其 macOS/Windows），可移植性高，Docker 自动处理权限。Bind Mount 方便直接查看和编辑文件，但依赖宿主机路径。

查看和管理 Volumes

# 列出所有 volumes
docker volume ls

# 查看 volume 详情
docker volume inspect openclaw-data

# 备份 volume 到 tar 文件
docker run --rm -v openclaw-data:/source:ro -v $(pwd):/backup \
  alpine tar czf /backup/openclaw-data-backup.tar.gz -C /source .

# 从 tar 恢复 volume
docker run --rm -v openclaw-data:/target -v $(pwd):/backup \
  alpine tar xzf /backup/openclaw-data-backup.tar.gz -C /target

# 删除未使用的 volumes（谨慎）
docker volume prune

---

网络配置

端口映射

OpenClaw 使用多个端口提供不同服务：

端口

服务

说明

18789

Gateway

主服务入口

18790

Bridge

内部桥接通信

18791

Browser Control

浏览器控制接口

18793

Canvas Host

画布渲染服务

18800-18899

Browser CDP

Chrome DevTools Protocol 端口池

ports:
  # 格式：宿主机端口:容器端口
  - "18789:18789"              # Gateway 主服务
  - "18790:18790"              # Bridge
  - "18791:18791"              # Browser Control
  - "18793:18793"              # Canvas Host
  - "18800-18899:18800-18899"  # Browser CDP 端口池
  - "127.0.0.1:18789:18789"   # 只监听本地（更安全，替代上面的 18789 映射）

安全提示：生产环境建议绑定 127.0.0.1，通过反向代理暴露服务，不要直接把端口开放到公网。只有 Gateway（18789）需要对外暴露，其他端口仅在需要时映射。

反向代理 Forwarded Headers 安全提示（v2026.4.x+）：OpenClaw 现在会检查转发头（X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto）的一致性。即使请求通过 loopback 到达，如果携带了指向非本地来源的转发头，Gateway 会将该请求视为远程请求，不再享有 loopback 本地信任。反向代理必须覆盖（而非追加）来自客户端的转发头。如果使用 trusted-proxy 认证模式，需要在 gateway.trustedProxies 中配置代理 IP，且不能使用 loopback 地址。详见 10-安全配置指南。

Docker 网络模式

services:
  openclaw-gateway:
    networks:
      - openclaw-net    # bridge 模式（默认，推荐）
    # network_mode: host  # host 模式（性能最好，但没有隔离）

容器间通信

在同一个 Docker 网络中，容器可以通过服务名互相访问：

# Gateway 连接数据库，用服务名 "postgres" 而不是 IP
DATABASE_URL=postgresql://openclaw:password@postgres:5432/openclaw

# Gateway 连接 Redis
REDIS_URL=redis://redis:6379/0

连接宿主机服务

如果 Ollama 跑在宿主机上，容器里用 host.docker.internal 访问：

environment:
  - OLLAMA_BASE_URL=http://host.docker.internal:11434
extra_hosts:
  - "host.docker.internal:host-gateway"   # Linux 需要这行

---

生产环境部署最佳实践

Nginx 反向代理配置

生产环境不要直接暴露 OpenClaw 端口，用 Nginx 做反向代理：

# /etc/nginx/sites-available/openclaw.conf
server {
    listen 80;
    server_name openclaw.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

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

    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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 $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/openclaw.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL/TLS 证书配置

Let's Encrypt（免费）：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d openclaw.yourdomain.com
sudo certbot renew --dry-run   # 验证自动续期

Caddy（更简单，自动 HTTPS）：

# /etc/caddy/Caddyfile
openclaw.yourdomain.com {
    reverse_proxy 127.0.0.1:18789
}

Caddy 自动申请和续期证书，比 Nginx + certbot 省事得多。

日志管理

Docker 日志驱动配置

services:
  openclaw-gateway:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"     # 单个日志文件最大 10MB
        max-file: "5"       # 最多保留 5 个文件
        compress: "true"    # 压缩旧日志

查看和分析日志

docker compose logs -f openclaw-gateway          # 实时查看
docker compose logs --tail 100 openclaw-gateway   # 最近 100 行
docker compose logs --since "2024-01-01" openclaw-gateway  # 按时间过滤

集中式日志（生产推荐）

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

多节点部署建议用 Loki + Grafana 或 ELK 收集日志，通过 fluentd 日志驱动转发。

健康检查

services:
  openclaw-gateway:
    healthcheck:
      # 检查 Gateway 是否响应（注意：OpenClaw 镜像中没有 curl，使用 Node.js fetch）
      test: ["CMD", "node", "-e", "fetch('http://localhost:18789/health').then(r => { if (!r.ok) process.exit(1) })"]
      interval: 30s       # 每 30 秒检查一次
      timeout: 10s        # 超时时间
      retries: 3          # 连续失败 3 次标记为 unhealthy
      start_period: 15s   # 启动后等 15 秒再开始检查

配合监控告警，可以写一个简单的 cron 脚本检查 docker inspect --format='{{.State.Health.Status}}' openclaw-gateway 的输出，unhealthy 时发邮件并自动重启。

生产上线工坊：从空 VPS 到可维护服务

下面是一条适合个人、小团队和开源项目维护者的生产部署路径。它的目标不是"把容器跑起来"，而是让你以后能更新、排错、恢复。

假设服务器是 Ubuntu，域名是 openclaw.example.com，部署目录是 /opt/openclaw。

第一步，创建专用目录：

sudo mkdir -p /opt/openclaw
sudo chown -R $USER:$USER /opt/openclaw
cd /opt/openclaw

第二步，准备 .env：

umask 077
touch .env

写入最小配置：

NODE_ENV=production
OPENCLAW_GATEWAY_HOST=127.0.0.1
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_GATEWAY_TOKEN=replace-with-long-random-token

OPENAI_API_KEY=${OPENAI_API_KEY}
ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

OPENCLAW_GATEWAY_HOST=127.0.0.1 很重要。生产环境让 Nginx/Caddy 对外服务，Gateway 自己只监听本机，减少直接暴露面。

第三步，准备 docker-compose.yml：

services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    env_file:
      - .env
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - openclaw-home:/home/node/.openclaw
      - ./logs:/var/log/openclaw
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:18789/health').then(r => { if (!r.ok) process.exit(1) })"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

volumes:
  openclaw-home:

第四步，启动：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail 100 openclaw-gateway

第五步，本机探测：

curl -i http://127.0.0.1:18789/health

第六步，再配置反向代理和 TLS。确认反代能访问后，再尝试外部访问域名。不要在 Gateway 没有 token、没有 TLS、没有反代限制时把 18789 直接暴露到公网。

上线后的目录布局

一个容易维护的部署目录可以这样组织：

/opt/openclaw/
├── docker-compose.yml
├── .env
├── logs/
├── backups/
│   ├── 2026-06-09T030000+0800/
│   └── ...
├── scripts/
│   ├── backup.sh
│   ├── restore.sh
│   ├── update.sh
│   └── health.sh
└── README.ops.md

README.ops.md 不是给用户看的文档，而是给未来的你看的操作笔记。建议记录：

# OpenClaw 运维笔记

## 服务器

- 域名：openclaw.example.com
- 部署目录：/opt/openclaw
- Gateway 内部端口：127.0.0.1:18789
- 反向代理：Nginx

## 常用命令

- 启动：docker compose up -d
- 日志：docker compose logs -f openclaw-gateway
- 更新：bash scripts/update.sh
- 备份：bash scripts/backup.sh

## 注意

- 不直接开放 18789 到公网。
- 更新前先备份 volume 和 .env。
- 恢复后必须重建/确认记忆索引。

有了这个文件，新成员或一个月后的你都不会靠记忆操作生产服务。

---

云平台部署

AWS 部署

EC2 + Docker Compose

# 推荐 t3.medium: 2 vCPU, 4GB RAM
ssh -i your-key.pem [email protected]
curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker ubuntu
git clone https://github.com/openclaw/openclaw.git && cd openclaw
cp .env.example .env   # 编辑 .env 填入配置
docker compose up -d

AWS ECS（容器服务）

适合需要自动扩缩容的场景。在 AWS 控制台创建 ECS 任务定义，指定镜像 openclaw/openclaw:latest，端口映射 18789:18789，分配 2048MB 内存和 1024 CPU 单位。详细配置参考 AWS ECS 文档。

GCP 部署

Cloud Run（Serverless）

# 构建并推送镜像到 GCR
gcloud builds submit --tag gcr.io/your-project/openclaw

# 部署到 Cloud Run
gcloud run deploy openclaw \
  --image gcr.io/your-project/openclaw \
  --port 18789 \
  --memory 2Gi \
  --cpu 2 \
  --set-env-vars "NODE_ENV=production" \
  --allow-unauthenticated

GCE（虚拟机）

创建 e2-medium 实例，SSH 连接后安装 Docker 并部署（流程同 EC2）。

Azure 部署

Azure Container Instances

# 创建资源组
az group create --name openclaw-rg --location eastus

# 部署容器
az container create \
  --resource-group openclaw-rg \
  --name openclaw \
  --image openclaw/openclaw:latest \
  --ports 18789 \
  --cpu 2 \
  --memory 4 \
  --environment-variables NODE_ENV=production

阿里云部署

ECS + Docker

# 1. 创建 ECS 实例（推荐 ecs.c6.large: 2 vCPU, 4GB）
# 2. SSH 连接后安装 Docker
ssh root@your-ecs-ip
curl -fsSL https://get.docker.com | sh

# 配置阿里云镜像加速器
sudo tee /etc/docker/daemon.json <<-'EOF'
{ "registry-mirrors": ["https://your-id.mirror.aliyuncs.com"] }
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

# 部署
git clone https://github.com/openclaw/openclaw.git
cd openclaw && docker compose up -d

VPS 部署（Hetzner / Vultr / DigitalOcean）

性价比最高的方案，适合个人和小团队（约 $5-10/月）：

ssh root@your-vps-ip
curl -fsSL https://get.docker.com | sh
git clone https://github.com/openclaw/openclaw.git
cd openclaw && ./docker-setup.sh

远程访问方案

Gateway 默认绑定 127.0.0.1，外部无法直接访问。三种方案：

方案一：SSH 隧道（最简单）

# 在本地机器上
ssh -L 18789:127.0.0.1:18789 root@your-vps-ip
# 然后本地浏览器访问 http://127.0.0.1:18789/

方案二：Tailscale（推荐长期使用）

# VPS 和本地都安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
# 通过 Tailscale IP 访问：http://100.x.x.x:18789/

方案三：反向代理 + HTTPS（对外服务）

参考上面的 Nginx 或 Caddy 配置。

---

Agent 沙箱（Docker 隔离）

Docker 在 OpenClaw 中扮演双重角色：一是容器化部署 Gateway 本身，二是为 Agent 工具执行提供沙箱隔离。这两者是独立的概念：

• Gateway 容器化 — 整个 OpenClaw 跑在 Docker 里

• Agent 沙箱 — Gateway 跑在主机上（或容器里），但 Agent 的工具执行在独立的 Docker 容器中

沙箱的核心价值：Agent 执行的代码（shell 命令、脚本等）被限制在隔离容器中，即使代码有破坏性操作也不会影响宿主机。

沙箱模式

OpenClaw 的沙箱通过 agents.defaults.sandbox.mode 控制。配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式）：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        // "non-main" — 非主会话在 Docker 沙箱中运行（推荐）
        // "all"      — 所有会话都在沙箱中运行
        // "off"      — 关闭沙箱
        "mode": "non-main",
        "image": "openclaw:sandbox"
      }
    }
  }
}

"non-main" 是推荐的默认值：主会话直接在宿主环境执行以保证交互性能，而 Agent 派生的子会话自动在 Docker 容器中隔离运行，防止工具执行影响宿主机。

沙箱镜像类型

镜像

说明

大小

Dockerfile.sandbox

基础沙箱，最小化

~200MB

Dockerfile.sandbox-browser

带浏览器（Playwright）

~800MB

Dockerfile.sandbox-common

通用沙箱，常用工具齐全

~500MB

构建沙箱镜像

# 基础沙箱
docker build -t openclaw:sandbox -f Dockerfile.sandbox .

# 带浏览器的沙箱
docker build -t openclaw:sandbox-browser -f Dockerfile.sandbox-browser .

Podman Rootless 替代方案

如果你的环境不允许使用 Docker 或需要无 root 权限运行容器，OpenClaw 官方支持 Podman rootless 部署。

核心区别： Podman 以当前用户身份运行容器（--userns=keep-id），不需要 Docker 守护进程，也不需要 root 权限。

快速开始：

# 一键初始化（构建镜像 + 创建配置 + 启动 Gateway）
./scripts/podman/setup.sh

# 使用 CLI 管理容器化的 Gateway
openclaw --container <容器名> gateway status

SELinux 环境： Podman 启动脚本会自动检测 SELinux 状态，在 enforcing/permissive 模式下自动为挂载目录追加 :Z 选项，无需手动配置。

Systemd 集成（Quadlet）： 使用 --quadlet 标志可生成 systemd 用户服务，支持开机自启和 systemctl --user 管理。需要 loginctl enable-linger 以支持 SSH/无头环境下的持久运行。

端口绑定： 默认只绑定 127.0.0.1（Gateway 18789，Bridge 18790），可通过 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 等环境变量覆盖。

详细的 Podman 部署文档见 docs.openclaw.ai/install/podman。

---

自动更新和 CI/CD

Watchtower 自动更新

Watchtower 会自动检测镜像更新并重启容器：

# 添加到 docker-compose.yml
services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=86400   # 每 24 小时检查一次
      - WATCHTOWER_INCLUDE_STOPPED=false
    restart: unless-stopped

GitHub Actions CI/CD

# .github/workflows/deploy.yml
name: Deploy OpenClaw
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /opt/openclaw
            docker compose pull && docker compose up -d
            docker image prune -f

手动更新流程

docker compose pull                    # 拉取最新镜像
docker compose up -d                   # 重启服务
docker image prune -f                  # 清理旧镜像

更新与回滚工坊

不要把更新理解成三条命令。生产环境更新应该包含“记录当前版本、备份、更新、观察、必要时回滚”。

先记录当前镜像：

cd /opt/openclaw
docker compose images
docker inspect openclaw-gateway --format '{{.Image}}'

更新前备份：

bash scripts/backup.sh

拉取新镜像但先不清理旧镜像：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail 200 openclaw-gateway

观察这几件事：

curl -i http://127.0.0.1:18789/health
docker inspect openclaw-gateway --format='{{.State.Health.Status}}'
docker compose logs --since "10m" openclaw-gateway

如果新版本异常，先不要 docker image prune。改回固定 tag 或旧 digest：

services:
  openclaw-gateway:
    image: openclaw/openclaw:<previous-tag>

然后重启：

docker compose up -d
docker compose logs --tail 100 openclaw-gateway

如果数据结构已经被新版本迁移，回滚镜像未必够用，需要恢复备份。这就是更新前备份必须存在的原因。

可以把更新流程写成脚本，但脚本里不要自动删除旧镜像：

#!/usr/bin/env bash
set -euo pipefail

cd /opt/openclaw
echo "[1/5] backup"
bash scripts/backup.sh

echo "[2/5] current image"
docker inspect openclaw-gateway --format '{{.Image}}' || true

echo "[3/5] pull"
docker compose pull

echo "[4/5] restart"
docker compose up -d

echo "[5/5] health"
sleep 10
docker compose ps
curl -i http://127.0.0.1:18789/health

更新成功并观察一段时间后，再清理：

docker image prune -f

---

性能调优和资源限制

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

容器资源限制

防止单个容器吃光服务器资源：

services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G
        reservations:
          cpus: "0.5"
          memory: 512M
  postgres:
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 2G
  redis:
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

Docker 守护进程优化

编辑 /etc/docker/daemon.json，配置日志轮转、overlay2 存储驱动、文件描述符限制：

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "storage-driver": "overlay2",
  "default-ulimits": {
    "nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 }
  }
}

监控资源使用

⏭️ 小白可跳过 — 这部分面向运维专家，单机部署不需要

docker stats                          # 实时查看所有容器资源
docker stats openclaw-gateway         # 查看特定容器
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"  # 格式化输出

---

备份和恢复

全量备份脚本

#!/bin/bash
# backup.sh — OpenClaw 全量备份
BACKUP_DIR="/opt/backups/openclaw"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "${BACKUP_DIR}/${DATE}"

# 备份配置文件
cp docker-compose.yml .env "${BACKUP_DIR}/${DATE}/"

# 备份 OpenClaw 数据卷
docker run --rm \
  -v openclaw-data:/source:ro \
  -v "${BACKUP_DIR}/${DATE}":/backup \
  alpine tar czf /backup/openclaw-data.tar.gz -C /source .

# 备份 PostgreSQL
docker compose exec -T postgres \
  pg_dump -U openclaw openclaw | gzip > "${BACKUP_DIR}/${DATE}/db-backup.sql.gz"

# 备份 Redis
docker run --rm \
  -v redis-data:/source:ro \
  -v "${BACKUP_DIR}/${DATE}":/backup \
  alpine tar czf /backup/redis-data.tar.gz -C /source .

# 清理 30 天前的备份
find "${BACKUP_DIR}" -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;
echo "Backup completed: ${BACKUP_DIR}/${DATE}"

v2026.5.22 备份命名：新版更倾向使用 local-time backup archive names。生产脚本里建议保留时区信息或在备份目录旁写入 date -Is 输出，方便跨服务器恢复时判断备份先后。

恢复流程

#!/bin/bash
# restore.sh — 从备份恢复
BACKUP_PATH=$1
[ -z "$BACKUP_PATH" ] && echo "Usage: ./restore.sh /opt/backups/openclaw/20240101_120000" && exit 1

# 停止服务
docker compose down

# 恢复配置
cp "${BACKUP_PATH}/docker-compose.yml" "${BACKUP_PATH}/.env" .

# 恢复数据卷
docker volume create openclaw-data
docker run --rm -v openclaw-data:/target -v "${BACKUP_PATH}":/backup \
  alpine tar xzf /backup/openclaw-data.tar.gz -C /target

# 恢复数据库
docker compose up -d postgres && sleep 5
gunzip -c "${BACKUP_PATH}/db-backup.sql.gz" | \
  docker compose exec -T postgres psql -U openclaw openclaw

# 恢复 Redis
docker volume create redis-data
docker run --rm -v redis-data:/target -v "${BACKUP_PATH}":/backup \
  alpine tar xzf /backup/redis-data.tar.gz -C /target

# 启动所有服务
docker compose up -d
echo "Restore completed from: ${BACKUP_PATH}"

定时备份（Cron）

# 每天凌晨 3 点自动备份
echo "0 3 * * * cd /opt/openclaw && bash backup.sh >> /var/log/openclaw-backup.log 2>&1" | crontab -

恢复演练：备份不是存下来就结束

很多部署事故不是没有备份，而是从来没恢复过。建议在非生产目录做一次恢复演练。

创建演练目录：

mkdir -p /opt/openclaw-restore-drill
cd /opt/openclaw-restore-drill

复制 compose 和备份：

cp /opt/openclaw/docker-compose.yml .
cp /opt/openclaw/.env .

把端口改成演练端口，避免碰到生产实例：

ports:
  - "127.0.0.1:28789:18789"

恢复到新的 volume 名称，避免覆盖生产 volume：

volumes:
  openclaw-home-drill:

运行恢复脚本前，确认脚本里的 volume 名称也指向演练 volume。恢复完成后：

docker compose up -d
curl -i http://127.0.0.1:28789/health
docker compose logs --tail 100 openclaw-gateway

然后进入容器或通过 OpenClaw 命令确认关键数据存在：

docker compose exec openclaw-gateway ls -la /home/node/.openclaw

演练结束后清理：

docker compose down
docker volume rm openclaw-restore-drill_openclaw-home-drill

恢复演练每月做一次就够。关键是确认三个东西：备份文件能解压、volume 能挂载、Gateway 能启动。

Volume 安全：不要让数据跟容器一起消失

容器可以随时删除，数据不应该。OpenClaw 的配置、记忆、会话、认证资料都应该放在 volume 或 bind mount 中。

危险做法：

services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"

这个配置没有持久化挂载。容器重建后，你可能丢失工作空间。

稳妥做法：

services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    volumes:
      - openclaw-home:/home/node/.openclaw

volumes:
  openclaw-home:

如果你选择 bind mount，也要明确宿主机路径和权限：

services:
  openclaw-gateway:
    volumes:
      - ./data/openclaw:/home/node/.openclaw

设置权限：

mkdir -p /opt/openclaw/data/openclaw
sudo chown -R 1000:1000 /opt/openclaw/data/openclaw
chmod 700 /opt/openclaw/data/openclaw

Named volume 管理省心，bind mount 方便备份和人工查看。生产中二者都可以，关键是不要无挂载运行。

---

常见 Docker 问题排查

镜像构建失败

docker build --no-cache -t openclaw:local -f Dockerfile .   # 清理缓存重建
docker build --progress=plain -t openclaw:local -f Dockerfile .  # 详细输出
docker system prune -a   # 磁盘空间不足时清理

容器无法启动

# 查看容器日志
docker compose logs openclaw-gateway

# 查看退出原因
docker inspect openclaw-gateway --format='{{.State.ExitCode}} {{.State.Error}}'

# 进入容器调试（运行中）
docker compose exec openclaw-gateway /bin/bash

# 容器已停止时用 run
docker compose run --rm openclaw-gateway /bin/bash

端口冲突

lsof -i :18789          # 检查端口占用
ss -tlnp | grep 18789   # 或者用 ss
# 解决方案：在 docker-compose.yml 中改为 "28789:18789"

权限问题

docker compose exec openclaw-gateway ls -la /home/node/.openclaw   # 检查权限
docker compose exec openclaw-gateway chown -R node:node /home/node/.openclaw  # 修复

内存不足（OOM Killed）

docker inspect openclaw-gateway --format='{{.State.OOMKilled}}'  # 检查 OOM
docker stats openclaw-gateway --no-stream                         # 查看内存使用
# 解决方案：增加 deploy.resources.limits.memory 或升级服务器

网络连接问题

# 检查容器网络
docker network inspect openclaw-net

# 容器间连通性测试
docker compose exec openclaw-gateway ping postgres

数据卷挂载问题

docker inspect openclaw-gateway | grep -A 10 Mounts   # 检查挂载
docker run --rm -v openclaw-data:/data alpine ls -la /data  # 查看 volume 内容

Docker Compose 版本问题

确认使用 v2 语法（docker compose，不带横杠）。v1 的 docker-compose 已弃用，v2 内置在 Docker Engine 中。

反向代理后登录或 WebSocket 异常

如果页面能打开，但聊天一直断开、WebChat 没有响应，优先检查反代是否保留了升级头：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;

如果日志里的来源 IP 全是 127.0.0.1，检查 X-Forwarded-For：

proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;

不要把客户端传来的 X-Forwarded-For 直接追加进信任链。生产安全配置里应该由反向代理覆盖这些头。

更新后模型或消息平台不可用

按环境变量、容器、应用三层查：

# 1. 宿主机 .env 是否还在
ls -la /opt/openclaw/.env

# 2. 容器是否拿到环境变量
docker compose exec openclaw-gateway env | grep -E "OPENAI|ANTHROPIC|TELEGRAM|DISCORD"

# 3. OpenClaw 自身状态
docker compose logs --tail 200 openclaw-gateway

如果 .env 没问题但容器里没有变量，检查 env_file 是否写在正确 service 下。如果容器有变量但平台仍失败，检查平台 token 是否过期或 webhook 地址是否变更。

磁盘空间突然打满

先看 Docker 占用：

docker system df
docker ps -a --size

再看日志：

du -sh /var/lib/docker/containers/* 2>/dev/null | sort -h | tail
du -sh /opt/openclaw/logs

处理顺序：

1. 确认备份存在。

2. 清理停止容器和未使用镜像。

3. 调整 logging max-size/max-file。

4. 不要直接删除 volume，除非你确认里面不是 OpenClaw 数据。

docker container prune
docker image prune

---

快速参考卡片

常用命令速查

操作

命令

启动服务

docker compose up -d

停止服务

docker compose down

查看状态

docker compose ps

查看日志

docker compose logs -f

重启服务

docker compose restart

更新镜像

docker compose pull && docker compose up -d

进入容器

docker compose exec openclaw-gateway /bin/bash

资源监控

docker stats

清理空间

docker system prune -a

部署方案对比

方案

成本

难度

适用场景

VPS + Docker Compose

$5-10/月

低

个人/小团队

AWS EC2

$15-50/月

中

中小团队

AWS ECS

$20-100/月

高

需要自动扩缩容

GCP Cloud Run

按用量计费

中

Serverless 场景

阿里云 ECS

¥50-200/月

低

国内用户

---

下一步

Docker 部署搞定了！去 10. 安全配置指南 加固你的 AI 助手。