在生产环境中使用 Docker 部署 OpenClaw

本文面向已经熟悉 Linux 基础、Docker 与容器化部署的运维/开发人员，演示如何在生产环境中以安全、可扩展的方式部署 OpenClaw（最新稳定版 v2026.3.8）。完整步骤涵盖准备、镜像拉取、目录结构、Docker-Compose 配置、Nginx 反向代理、TLS/防火墙、持久化备份以及后续升级方案。

1️⃣ 前置准备

项目	说明	参考命令
操作系统	64 位 Linux（Debian/Ubuntu/CentOS 均可）	uname -a
Docker	Docker Engine ≥ 20.10，Docker-Compose ≥ 2.0	docker version && docker compose version
域名	用于外网访问（如 openclaw.example.com）	–
TLS 证书	推荐使用 Let’s Encrypt（或自签）	certbot --nginx -d openclaw.example.com
防火墙	只放行 80/443，关闭容器内部 18789 端口对公网的直接访问	ufw allow 80/tcp && ufw allow 443/tcp && ufw deny 18789/tcp
系统用户	建议创建专用系统用户 openclaw（UID/GID 1000）运行容器，避免 root 运行	sudo useradd -r -s /usr/sbin/nologin openclaw

⚠️ 安全提示：生产环境务必使用非 root 用户运行容器，且仅在本机 127.0.0.1 绑定 OpenClaw gateway 端口，外部通过 Nginx 逆向代理访问。

2️⃣ 拉取官方镜像

# 国内网络可使用官方加速源
docker pull docker.1ms.run/alpine/openclaw:v2026.3.8

# 为后续维护打上语义化标签
docker tag docker.1ms.run/alpine/openclaw:v2026.3.8 openclaw:prod-v2026.3.8

如需使用其他镜像源（轩辕镜像、1Panel 镜像等），自行替换 /openclaw: 即可。

3️⃣ 创建部署目录与安全配置

# 创建根目录
sudo mkdir -p /opt/openclaw/{config,logs,data,backups}
sudo chown -R $(whoami):$(whoami) /opt/openclaw
cd /opt/openclaw

# .gitignore（防止敏感信息被误提交）
cat > .gitignore <<'EOF'
.env
*.log
config/*
data/*
backups/*
EOF

# 生成高强度网关令牌
OPENCLAW_TOKEN=$(openssl rand -hex 32)

# 写入 .env
cat > .env <<EOF
OPENCLAW_TOKEN=$OPENCLAW_TOKEN
OPENCLAW_IMAGE=openclaw:prod-v2026.3.8
EOF

chmod 600 .env   # 仅 owner 可读写

4️⃣ Docker-Compose（生产版）docker-compose.prod.yml

version: '3.8'

volumes:
  openclaw_home: {}

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    container_name: openclaw-gateway-prod
    restart: unless-stopped
    environment:
      NODE_ENV: production
      OPENCLAW_GATEWAY_TOKEN: $OPENCLAW_TOKEN
    volumes:
      - openclaw_home:/home/node   # 持久化全部数据
      - ./config:/home/node/config:ro
      - ./logs:/home/node/logs:rw
    ports:
      - "127.0.0.1:18789:18789"    # 仅本机可访问，外部通过 Nginx 代理
    mem_limit: 2g
    cpus: 2
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:18789/healthz", "||", "exit", "1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s
    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "5"
        compress: "true"
    user: "1000:1000"

关键点说明

• openclaw_home 卷负责持久化配置、技能、记忆、工作区等核心数据
• ports 只绑定到 127.0.0.1，防止公网直接访问
• user: "1000:1000" 强制容器以内非 root 用户运行
• healthcheck 用于 Docker 自动监测网关健康状态

5️⃣ Nginx 反向代理（HTTPS）

在 /etc/nginx/sites-available/openclaw.conf 中创建：

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;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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 300s;
        proxy_read_timeout 300s;
    }

    location /health {
        proxy_pass http://127.0.0.1:18789/healthz;
        access_log off;
    }
}

# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name openclaw.example.com;
    return 301 https://$host$request_uri;
}

启用并重载：

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

TLS：若尚未拥有证书，可使用 certbot --nginx -d openclaw.example.com 自动申请 & 配置。

6️⃣ 启动容器 & 初始化

# 拉起容器（后台运行）
docker compose -f docker-compose.prod.yml up -d

# 检查容器状态
docker compose -f docker-compose.prod.yml ps

# 实时查看日志，确认无错误
docker compose -f docker-compose.prod.yml logs -f openclaw-gateway

首次运行需要完成 onboard 向导（配置模型提供商、渠道等）：

docker compose -f docker-compose.prod.yml run --rm openclaw-gateway onboard

向导会在终端交互式询问模型 API Key、渠道 Token 等信息，完成后会写入 ~/.openclaw/openclaw.json（已挂载至 ./config），后续可直接通过 UI 或 CLI 管理。

7️⃣ 重要日常运维

任务	命令	备注
创建备份（首次部署）	docker exec openclaw-gateway-prod openclaw backup create --name init-$(date +%F)	备份会保存至容器内部 ~/.openclaw/backups，建议同步到宿主机 ./backups
验证备份	docker exec openclaw-gateway-prod openclaw backup verify --name init-$(date +%F)	确认备份完整性
导出本地备份	docker cp openclaw-gateway-prod:/home/node/.openclaw/backups/<file> ./backups/	长期保存到离线介质
升级前备份	docker exec openclaw-gateway-prod openclaw backup create --name pre-upgrade-$(date +%F)	防止升级失误
拉取新镜像 & 重启	docker pull docker.1ms.run/alpine/openclaw:v2026.3.9 && sed -i 's/prod-v2026.3.8/prod-v2026.3.9/' .env && docker compose -f docker-compose.prod.yml pull && docker compose -f docker-compose.prod.yml up -d	自动完成滚动升级
查看健康	curl -s http://127.0.0.1:18789/healthz	返回 200 OK 表示网关正常
日志轮转	已在 docker-compose 中配置 max-size 100m 与 max-file 5	防止日志磁盘爆满

8️⃣ 常见问题排查

症状	可能原因	解决方案
容器启动失败，日志中出现 EACCES	主机目录权限不足	确保 openclaw 用户拥有 ./config、./logs、./backups 的读写权限（chown -R 1000:1000 ./config）
Nginx 404	代理目标端口未映射或网关未运行	验证 docker ps 中 openclaw-gateway-prod 已监听 18789；检查 Nginx proxy_pass 地址是否为 127.0.0.1:18789
API 调用返回 401	OPENCLAW_GATEWAY_TOKEN 不匹配	在 .env 中重新生成 token 并重新启动容器；使用相同 token 登录 UI
模型提供商认证失败	API Key 输入错误或配额耗尽	重新在 onboard 向导或 openclaw models auth login 中更新正确的密钥
容器 OOM	内存限制过低	增大 mem_limit（如 4g）或检查容器内部进程占用

9️⃣ 生产环境最佳实践小结

1. 最小权限：容器仅在 127.0.0.1 绑定端口，外部只能通过 Nginx HTTPS 访问
2. 持久化卷：openclaw_home 卷保证所有配置、记忆、技能、工作区在容器重建后不丢失
3. 定期备份：建议使用 cron 每日自动执行 openclaw backup create，并把备份同步到异地存储（如对象存储）
4. 滚动升级：升级前务必创建 pre-upgrade 备份，使用 docker compose pull && up -d 完成无停机切换
5. 监控报警：结合 Prometheus / Grafana 监控容器 cpu/memory/health，通过 alertmanager 推送到企业微信/飞书告警

🔟 结束语

完成以上步骤后，您将拥有一个 安全、可扩展、易维护 的 OpenClaw 生产实例。后续可通过 OpenClaw Dashboard（http://openclaw.example.com）管理渠道、插件、模型，亦可在容器内部直接执行 openclaw 子命令完成高级配置。

若有任何部署细节或后续功能需求（如多租户、插件定制、远程调试等），欢迎随时向我提问，我会第一时间给出对应方案。

祝部署顺利，AI 助手跑通！ 🐉🚀