OpenClaw Docker 容器化部署全教程（进阶版）

一、镜像拉取与国内加速

1. 官方镜像

OpenClaw 提供官方预构建镜像，基于 Node.js 运行时，集成全部核心组件：

bash

运行

docker pull openclawai/openclaw:latest

2. Docker 国内镜像加速

国内服务器直接拉取 Docker Hub 速度慢、易超时，先配置镜像加速器：

bash

运行

# 编辑 Docker 守护进程配置
sudo nano /etc/docker/daemon.json

写入以下内容：

json

{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://registry.docker-cn.com"
  ]
}

保存后重启 Docker 生效：

bash

运行

sudo systemctl restart docker

二、单行命令快速启动（临时 / 测试场景）

适合快速体验、临时运行，一条命令完成部署：

bash

运行

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=sk-你的密钥 \
  --restart unless-stopped \
  openclawai/openclaw:latest

参数说明

表格

参数	作用
`-d`	后台守护进程运行
`--name openclaw`	自定义容器名称
`-p 18789:18789`	端口映射，网关默认端口
`-v ~/.openclaw:/root/.openclaw`	数据卷挂载，持久化配置、会话、技能
`-e`	注入环境变量，配置模型密钥等
`--restart unless-stopped`	容器异常自动重启，手动停止则不重启

启动完成后，浏览器访问面板：

plaintext

http://服务器IP:18789/

三、docker-compose 生产级部署（推荐）

正式服务器、长期运维优先使用 docker-compose，配置结构化、管理便捷、支持健康检查与环境文件。

1. 创建部署目录

bash

运行

mkdir -p /opt/openclaw
cd /opt/openclaw

2. 编写编排文件 `docker-compose.yml`

yaml

version: '3.8'

services:
  openclaw:
    image: openclawai/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/root/.openclaw
    environment:
      - TZ=Asia/Shanghai
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY:-}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:-}
    # 健康检查，监控服务状态
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

3. 编写环境变量文件 `.env`

统一管理各类密钥、参数，避免硬编码：

bash

运行

nano /opt/openclaw/.env

内容示例（按需填写，至少配置一个模型密钥）：

env

# 大模型 API Key
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
# 国内模型（推荐）
DASHSCOPE_API_KEY=sk-通义千问密钥
DEEPSEEK_API_KEY=sk-DeepSeek密钥
GLM_API_KEY=sk-智谱密钥
MOONSHOT_API_KEY=sk-月之暗面密钥

# 聊天渠道 Token（按需开启）
TELEGRAM_BOT_TOKEN=123456:ABCDEF
DISCORD_BOT_TOKEN=xxx

# 基础配置
TZ=Asia/Shanghai
OPENCLAW_PORT=18789
LOG_LEVEL=info

4. 启动与基础管理

bash

运行

# 后台启动服务
docker compose up -d

# 查看运行状态
docker compose ps

# 实时查看日志
docker compose logs -f openclaw

# 重启服务
docker compose restart

# 停止服务（保留数据）
docker compose down

# 停止并删除数据卷（谨慎使用，数据会丢失）
docker compose down -v

四、常用环境变量对照表

1. 大模型密钥（必填项，任选其一或多选）

表格

环境变量	模型厂商
`OPENAI_API_KEY`	OpenAI GPT 系列
`ANTHROPIC_API_KEY`	Anthropic Claude 系列
`DASHSCOPE_API_KEY`	阿里通义千问（国内优选）
`DEEPSEEK_API_KEY`	DeepSeek 深度求索（国内优选）
`GLM_API_KEY`	智谱 AI GLM
`MOONSHOT_API_KEY`	月之暗面 Kimi

2. 聊天渠道配置

env

# Telegram 机器人
TELEGRAM_BOT_TOKEN=xxx
# Discord 机器人
DISCORD_BOT_TOKEN=xxx

3. 通用基础配置

env

# 容器时区
TZ=Asia/Shanghai
# 网关端口
OPENCLAW_PORT=18789
# 日志级别：debug/info/warn/error
LOG_LEVEL=info

五、数据持久化与备份

1. 持久化原理

容器默认无状态，删除 / 重建容器会丢失所有数据，必须通过数据卷挂载。

OpenClaw 核心数据目录：

plaintext

/root/.openclaw/
├── openclaw.json      # 网关主配置
├── workspace/         # 智能体人设、规则、长期记忆
├── sessions/          # 会话记录
├── skills/            # 已安装技能
└── agents/            # 多智能体配置

在 docker-compose 中通过 - ./data:/root/.openclaw 将数据落地到宿主机 ./data 目录。

2. 数据备份方案

本地打包备份

bash

运行

# 按日期打包备份
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz /opt/openclaw/data/

远程同步备份

bash

运行

# 增量同步至备份服务器
rsync -avz /opt/openclaw/data/ 备份服务器IP:/backups/openclaw/

六、全新 VPS 从零部署流程

1. 系统初始化（Ubuntu/Debian）

bash

运行

# 更新系统包
sudo apt update && sudo apt upgrade -y
# 安装基础工具
sudo apt install -y curl wget git nano ufw

2. 安装 Docker & Compose

bash

运行

# 一键安装 Docker
curl -fsSL https://get.docker.com | sh
# 将当前用户加入 docker 组，免 sudo 执行
sudo usermod -aG docker $USER
# 安装 compose 插件
sudo apt install -y docker-compose-plugin

# 验证版本
docker --version
docker compose version

重新登录终端，用户组权限方可生效。

3. 防火墙配置

只开放必要端口，提升安全性：

bash

运行

# 允许远程 SSH
sudo ufw allow 22
# 允许网站 80/443
sudo ufw allow 80
sudo ufw allow 443
# 启用防火墙
sudo ufw enable
# 查看规则
sudo ufw status

生产环境不建议直接对外暴露 18789 端口，统一使用 Nginx 反向代理。

4. 部署 OpenClaw

bash

运行

cd /opt/openclaw
# 编写 compose、.env 文件（参考上文）
# 启动服务
docker compose up -d
# 验证服务可用性
curl http://localhost:18789/

七、Nginx 反向代理配置（生产必备）

实现域名访问、SSL 加密、WebSocket 兼容，隐藏内网端口。

1. 安装 Nginx

bash

运行

sudo apt install -y nginx

2. 创建站点配置

bash

运行

sudo nano /etc/nginx/sites-available/openclaw

基础配置（支持 WebSocket）：

nginx

server {
    listen 80;
    server_name 你的域名.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        # WebSocket 核心配置，缺一不可
        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_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

3. 启用配置并重载

bash

运行

# 建立软链接启用站点
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
# 可选：删除默认站点
sudo rm /etc/nginx/sites-enabled/default
# 检查配置语法
sudo nginx -t
# 重载 Nginx
sudo systemctl reload nginx

八、HTTPS SSL 证书配置

使用 Let’s Encrypt 免费证书，实现全站加密。

1. 安装 Certbot

bash

运行

sudo apt install -y certbot python3-certbot-nginx

2. 自动申请并配置证书

bash

运行

sudo certbot --nginx -d 你的域名.com

工具会自动完成：域名验证、证书签发、Nginx 配置改写、自动续期定时任务。

3. 续期测试

bash

运行

# 模拟续期，检查是否正常
sudo certbot renew --dry-run

4. 手动 HTTPS 配置（自动配置失败时使用）

nginx

server {
    listen 443 ssl http2;
    server_name 你的域名.com;

    ssl_certificate /etc/letsencrypt/live/你的域名.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/你的域名.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    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 $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

# 80 端口强制跳转 HTTPS
server {
    listen 80;
    server_name 你的域名.com;
    return 301 https://$server_name$request_uri;
}

修改后重载 Nginx：sudo systemctl reload nginx

九、国内服务器专属注意事项

镜像加速 必须配置 Docker 镜像加速器，否则拉取镜像极易超时。
域名备案 国内云服务器绑定域名，必须完成 ICP 备案；备案前可临时使用 IP 访问。
端口策略 云服务商安全组仅默认开放 22/80/443，自定义端口需手动放行；推荐只用反向代理，不暴露原生端口。
模型网络 优先选用通义千问、DeepSeek、智谱等国内大模型；如需使用境外模型，需配置网络代理。
时区容器内务必配置 TZ=Asia/Shanghai，避免日志、定时任务时间错乱。

十、版本更新与日常维护

1. 升级 OpenClaw

bash

运行

cd /opt/openclaw
# 拉取最新镜像
docker compose pull
# 重建容器（数据由卷挂载保留，不会丢失）
docker compose up -d

2. 状态与资源监控

bash

运行

# 查看容器资源占用
docker stats openclaw
# 查看容器详细信息
docker inspect openclaw

3. 常见故障排查

容器启动失败

bash

运行

# 查看详细报错日志
docker compose logs openclaw

常见原因：端口冲突、.env 密钥缺失、数据目录权限不足。

修复权限：

bash

运行

chmod -R 755 /opt/openclaw/data

面板无法访问

检查容器状态：docker compose ps
检查端口监听：ss -tlnp | grep 18789
检查防火墙：sudo ufw status

WebSocket 连接异常

核对 Nginx 配置，确保存在以下两行：

nginx

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

执行 sudo nginx -t 校验配置并重载。

十一、部署完成自检清单

Docker 容器正常运行
本地 127.0.0.1:18789 可正常访问面板
域名 + HTTPS 访问正常，浏览器安全锁标识正常
Web 对话 WebSocket 长连接无断开
重启容器后，配置、会话、技能数据不丢失
容器自动重启策略生效
已配置定期数据备份

十二、总结

测试用 docker run 快速启动，生产环境统一使用 docker-compose；
数据卷挂载是核心，保证容器重建后数据不丢失；
公网部署务必搭配 Nginx 反向代理 + SSL，兼顾安全与体验；
国内服务器优先配置镜像加速、选用本土大模型、遵守备案规则；
日常更新使用 docker compose pull && up -d，操作简单平滑。

OpenClaw Docker 容器化部署全教程（进阶版）

一、镜像拉取与国内加速

1. 官方镜像

2. Docker 国内镜像加速

二、单行命令快速启动（临时 / 测试场景）

参数说明

三、docker-compose 生产级部署（推荐）

1. 创建部署目录

2. 编写编排文件 docker-compose.yml

3. 编写环境变量文件 .env

4. 启动与基础管理

四、常用环境变量对照表

1. 大模型密钥（必填项，任选其一或多选）

2. 聊天渠道配置

3. 通用基础配置

五、数据持久化与备份

1. 持久化原理

2. 数据备份方案

本地打包备份

远程同步备份

六、全新 VPS 从零部署流程

1. 系统初始化（Ubuntu/Debian）

2. 安装 Docker & Compose

3. 防火墙配置

4. 部署 OpenClaw

七、Nginx 反向代理配置（生产必备）

1. 安装 Nginx

2. 创建站点配置

3. 启用配置并重载

八、HTTPS SSL 证书配置

1. 安装 Certbot

2. 自动申请并配置证书

3. 续期测试

4. 手动 HTTPS 配置（自动配置失败时使用）

九、国内服务器专属注意事项

十、版本更新与日常维护

1. 升级 OpenClaw

2. 状态与资源监控

3. 常见故障排查

容器启动失败

面板无法访问

WebSocket 连接异常

十一、部署完成自检清单

十二、总结

2. 编写编排文件 `docker-compose.yml`

3. 编写环境变量文件 `.env`