Docker 部署教程 — 龙虾技能库

Docker 镜像获取

OpenClaw 官方提供 Docker 镜像，开箱即用： ``

bash
docker pull openclawai/openclaw:latest



镜像基于 Node.js 运行时，包含 OpenClaw 的所有核心组件。

国内镜像加速

如果拉取速度慢，可以配置 Docker 镜像加速器：

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



docker run 快速启动

最简单的启动方式，一行命令：

bash
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=sk-your-key-here \
  --restart unless-stopped \
  openclawai/openclaw:latest



参数说明：

| 参数 | 说明 |
|------|------|
|

-d

 | 后台运行 |
|

--name openclaw

 | 容器名称 |
|

-p 18789:18789

 | 端口映射（Gateway 默认端口） |
|

-v ~/.openclaw:/root/.openclaw

 | 数据卷挂载（持久化配置和数据） |
|

-e OPENAI_API_KEY=...

 | 设置环境变量 |
|

--restart unless-stopped

 | 自动重启策略 |

启动后访问仪表板：


http://你的服务器IP:18789/



docker-compose 完整配置

生产环境推荐使用 docker-compose，配置更清晰、管理更方便。

创建项目目录

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



编写 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:-}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s



创建 .env 文件

bash
nano /opt/openclaw/.env

env
模型 API Key（至少配置一个）
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

国内模型（可选）
DASHSCOPE_API_KEY=sk-your-qwen-key
DEEPSEEK_API_KEY=sk-your-deepseek-key



启动服务

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



常用管理命令

bash
查看运行状态
docker-compose ps

查看日志
docker-compose logs -f openclaw

重启服务
docker-compose restart

停止服务
docker-compose down

停止并删除数据（谨慎！）
docker-compose down -v



环境变量设置

模型 API Key

至少需要配置一个模型提供商的 API Key：

| 环境变量 | 提供商 | 说明 |
|----------|--------|------|
|

OPENAI_API_KEY

 | OpenAI | GPT-4、GPT-3.5 |
|

ANTHROPIC_API_KEY

 | Anthropic | Claude 系列 |
|

DASHSCOPE_API_KEY

 | 通义千问 | 国内推荐 |
|

DEEPSEEK_API_KEY

 | DeepSeek | 国内推荐，性价比高 |
|

GLM_API_KEY

 | 智谱 AI | GLM 系列 |
|

MOONSHOT_API_KEY

 | Moonshot | Kimi 系列 |

渠道 Token

如果需要连接聊天渠道，配置对应的 Token：

env
Telegram Bot
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Discord Bot
DISCORD_BOT_TOKEN=your-discord-token

WhatsApp（通过二维码配对，不需要 Token）



其他配置

env
时区
TZ=Asia/Shanghai

Gateway 端口（默认 18789）
OPENCLAW_PORT=18789

日志级别
LOG_LEVEL=info



数据持久化

Docker 容器是无状态的，重建容器后数据会丢失。必须通过 volumes 挂载来持久化数据。

需要持久化的目录


~/.openclaw/
├── openclaw.json          # Gateway 配置
├── workspace/             # 智能体工作区（SOUL.md、MEMORY.md 等）
├── sessions/              # 会话记录
├── skills/                # 已安装的技能
└── agents/                # 多智能体配置



docker-compose 中的 volumes 配置

yaml
volumes:
  - ./data:/root/.openclaw          # 所有 OpenClaw 数据



这样所有数据都保存在宿主机的

./data

 目录下，容器重建后数据不会丢失。

备份建议

bash
定期备份数据目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz /opt/openclaw/data/

或者用 rsync 同步到远程
rsync -avz /opt/openclaw/data/ backup-server:/backups/openclaw/



VPS 部署完整流程

从零开始在一台全新的 VPS 上部署 OpenClaw。

第一步：系统初始化

bash
更新系统
sudo apt update && sudo apt upgrade -y

安装基础工具
sudo apt install -y curl wget git nano ufw



第二步：安装 Docker

bash
安装 Docker（官方脚本）
curl -fsSL https://get.docker.com | sh

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

安装 docker-compose
sudo apt install -y docker-compose-plugin

验证安装
docker --version
docker compose version



第三步：配置防火墙

bash
允许 SSH
sudo ufw allow 22

允许 HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

启用防火墙
sudo ufw enable

查看状态
sudo ufw status



注意：不要直接暴露 18789 端口到公网，通过 Nginx 反向代理访问。

第四步：部署 OpenClaw

bash
创建项目目录
mkdir -p /opt/openclaw
cd /opt/openclaw

创建 docker-compose.yml（参考上面的完整配置）
nano docker-compose.yml

创建 .env 文件
nano .env

启动
docker compose up -d

验证运行
docker compose ps
curl http://localhost:18789/



第五步：配置 Nginx 反向代理

见下一节。

Nginx 反向代理配置

Nginx 作为反向代理，提供域名访问、SSL 加密和 WebSocket 支持。

安装 Nginx

bash
sudo apt install -y nginx



配置文件

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

nginx
server {
    listen 80;
    server_name your-domain.com;

    # HTTP 重定向到 HTTPS（配置 SSL 后启用）
    # return 301 https://$server_name$request_uri;

    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";

        # 传递真实 IP
        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;

        # 超时设置（WebSocket 需要较长超时）
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}



启用配置

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



WebSocket 支持说明

OpenClaw 的 WebChat 和部分渠道使用 WebSocket 通信。Nginx 配置中的这两行是关键：

nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";



如果缺少这两行，WebChat 将无法正常工作。

SSL 证书配置

使用 Let's Encrypt 免费 SSL 证书。

安装 Certbot

bash
sudo apt install -y certbot python3-certbot-nginx



申请证书

bash
sudo certbot --nginx -d your-domain.com



Certbot 会自动：
1. 验证域名所有权
2. 申请 SSL 证书
3. 修改 Nginx 配置添加 HTTPS
4. 设置自动续期

验证自动续期

bash
测试续期
sudo certbot renew --dry-run

查看证书状态
sudo certbot certificates



手动配置 HTTPS

如果 Certbot 自动配置不生效，手动修改 Nginx 配置：

nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    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;
    }
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}



国内服务器注意事项

镜像加速

国内服务器拉取 Docker Hub 镜像可能很慢，务必配置镜像加速器（参考本文开头的配置方法）。

域名备案

如果使用国内服务器（阿里云、腾讯云等）并绑定域名：

- 必须完成 ICP 备案，否则域名会被封禁
- 备案周期通常 7-20 个工作日
- 备案期间可以用 IP 直接访问（不绑定域名）
- 备案完成前不要配置 SSL 证书

端口限制

部分云服务商默认只开放 22、80、443 端口，其他端口需要在安全组中手动开放。

如果使用 Nginx 反向代理（推荐），只需要开放 80 和 443 即可。

网络访问

OpenClaw 需要访问模型 API（OpenAI、Anthropic 等），国内服务器可能无法直接访问：

- 推荐方案：使用国内模型提供商（通义千问、DeepSeek、智谱 GLM）
- 备选方案：配置代理访问国外 API
- 混合方案：国内模型为主，国外模型作为故障转移备选

时区设置

确保容器时区正确：

yaml
environment:
  - TZ=Asia/Shanghai



更新和维护

更新 OpenClaw

bash
cd /opt/openclaw

拉取最新镜像
docker compose pull

重建容器（数据不会丢失，因为挂载了 volumes）
docker compose up -d

查看新版本
docker compose logs openclaw | head -20



查看日志

bash
实时日志
docker compose logs -f openclaw

最近 100 行
docker compose logs --tail 100 openclaw



监控容器状态

bash
查看资源使用
docker stats openclaw

查看容器详情
docker inspect openclaw



常见问题排查

容器启动失败：

bash
查看启动日志
docker compose logs openclaw

常见原因：
1. 端口被占用 → 修改端口映射
2. 环境变量缺失 → 检查 .env 文件
3. 数据目录权限 → chmod -R 755 ./data



无法访问仪表板：

bash
检查容器是否运行
docker compose ps

检查端口监听
ss -tlnp | grep 18789

检查防火墙
sudo ufw status



WebSocket 连接失败：

bash
检查 Nginx 配置是否包含 WebSocket 支持
sudo nginx -t
sudo cat /etc/nginx/sites-enabled/openclaw | grep -i upgrade



完整部署检查清单

部署完成后，逐项检查：

- [ ] Docker 容器正常运行（

docker compose ps

）
- [ ] Gateway 可访问（

curl http://localhost:18789/

）
- [ ] Nginx 反向代理正常（通过域名访问）
- [ ] SSL 证书有效（浏览器显示锁图标）
- [ ] WebSocket 正常（WebChat 可以对话）
- [ ] 数据持久化正常（重启容器后数据还在）
- [ ] 自动重启正常（

docker compose restart

 后服务恢复）
- [ ] 日志可查看（

docker compose logs

）
- [ ] 备份策略已配置

小结

Docker 部署 OpenClaw 的核心步骤：

1. 拉取镜像，编写 docker-compose.yml
2. 配置环境变量（API Key、渠道 Token）
3. 挂载数据卷实现持久化
4. 配置 Nginx 反向代理（注意 WebSocket 支持）
5. 申请 SSL 证书
6. 国内服务器注意镜像加速和备案

数据安全靠 volumes 挂载，更新靠

docker compose pull && up -d`，简单可靠。 --- #Docker部署 #VPS部署 #服务器运维 #Nginx配置 #龙虾技能库