## 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配置 #龙虾技能库