Docker OpenClaw 生产环境部署指南（单机架构版）
OpenClaw 项目介绍
2026年爆火的OpenClaw AI执行引擎（曾用名Clawdbot、Moltbot），由奥地利开发者、PSPDFKit创始人Peter Steinberger主导开发，于2026年1月完成品牌定名与全生态统一，是2026年全球开源领域增速最快的项目之一，截至2026年2月，其GitHub仓库星标数已突破18.6万，社区贡献者与插件生态持续高速扩张。与传统对话式AI工具截然不同，OpenClaw的核心定位是“本地运行、可自托管的AI执行引擎”，主打“从给建议到做事情”的能力跃迁——它并非被动响应的聊天机器人，而是能通过自然语言指令，自主规划并完成全流程任务的“数字员工”。项目以本地优先为核心设计理念，所有用户数据默认存储于用户自有设备，彻底实现数据主权与隐私安全自主；同时支持接入Claude、GPT、Ollama等几乎所有主流大模型，兼容Telegram、WhatsApp、钉钉、飞书、QQ等十余种主流通讯渠道，可通过可插拔的技能插件无限扩展能力边界，覆盖办公自动化、文件管理、邮件处理、日程运维、代码辅助、跨应用协同等全场景任务执行，项目基于MIT开源协议开放全部代码，支持用户免费使用、自由修改、二次开发与私有化部署。
环境准备
Docker 环境安装
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
国内轩辕镜像拉取
# 拉取指定版本镜像（生产推荐）
docker pull docker.xuanyuan.run/alpine/openclaw:2026.2.22-beta.1
# 可选：为镜像添加本地别名，便于后续使用
docker tag docker.xuanyuan.run/alpine/openclaw:2026.2.22-beta.1 openclaw:prod-2026.2.22
- 轩辕镜像官方链接：https://xuanyuan.cloud/r/alpine/openclaw
- 版本说明：生产环境必须使用具体版本号（如 2026.2.22-beta.1），禁止使用 latest 标签。
生产环境部署
步骤 1：准备目录与配置文件
# 创建生产环境目录
mkdir -p /opt/openclaw/{config,logs,data}
cd /opt/openclaw
# 创建 .gitignore 文件，避免提交敏感信息
cat > .gitignore << EOF
.env
*.log
config/*
data/*
EOF
# 创建 .env 文件，存储敏感配置（务必设置权限）
cat > .env << EOF
OPENCLAW_TOKEN=$(openssl rand -hex 32) # 使用 openssl 生成随机令牌
OPENCLAW_IMAGE=docker.xuanyuan.run/alpine/openclaw:2026.2.22-beta.1
EOF
# 设置 .env 文件权限（关键：防止凭据泄露）
chmod 600 .env
步骤 2：编写生产级 Docker Compose 文件
创建 docker-compose.prod.yml，包含资源限制、健康检查、重启策略等核心配置：
version: '3.8'
volumes:
openclaw_home: # 持久化 home 目录
driver: local
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE}
container_name: openclaw-gateway-prod
restart: unless-stopped # 生产级重启策略：除非手动停止，否则自动重启
environment:
- NODE_ENV=production
- OPENCLAW_TOKEN=${OPENCLAW_TOKEN}
volumes:
- openclaw_home:/home/node
- ./config:/home/node/config:ro
- ./logs:/home/node/logs:rw
# 按需挂载主机目录（生产环境建议严格限制权限）
# - /data/openclaw/files:/home/node/files:rw
ports:
- "127.0.0.1:18789:18789" # 仅绑定本地回环地址，禁止直接暴露公网
# 资源限制（普通 docker compose 模式下生效）
mem_limit: 2g
cpus: 2
# 健康检查（使用 wget，避免依赖 curl）
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://localhost:18789/health || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 60s
logging: # 日志配置（便于集中管理）
driver: "json-file"
options:
max-size: "100m"
max-file: "5"
compress: "true"
user: "1000:1000" # 非 root 用户运行（提升安全性）
# 可选：沙箱容器（生产环境建议独立部署）
openclaw-sandbox:
image: openclaw-sandbox:bookworm-slim
container_name: openclaw-sandbox-prod
restart: "no" # 沙箱按需启动，不自动重启
network_mode: none # 禁用网络（提升安全性，注意：会导致网络相关操作失败）
mem_limit: 1g
cpus: 0.5
user: "1000:1000"
volumes:
- ./sandbox-data:/home/node/sandbox:rw
说明：若使用 Docker Swarm 模式，可将资源限制配置在 deploy.resources 下。
步骤 3：配置 Nginx 反向代理（HTTPS + 公网访问）
生产环境禁止直接暴露 Gateway 端口，需通过 Nginx 做反向代理并配置 HTTPS。
# /etc/nginx/conf.d/openclaw.conf
server {
listen 443 ssl http2;
server_name openclaw.your-domain.com; # 替换为你的域名
# HTTPS 完整配置（生产环境必须）
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers on;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
# 强制 HSTS（提升安全性）
add_header Strict-Transport-Security "max-age=31536000" always;
# 限制访问（可选：仅允许指定 IP）
# allow 192.168.1.0/24;
# deny all;
# 反向代理配置
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;
# 超时配置（适配 LLM 长响应）
proxy_connect_timeout 60s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
# 健康检查接口
location /health {
proxy_pass http://127.0.0.1:18789/health;
access_log off;
}
}
# 重定向 HTTP 到 HTTPS
server {
listen 80;
server_name openclaw.your-domain.com;
return 301 https://$host$request_uri;
}
步骤 4：配置防火墙（生产必须）
生产服务器需关闭 18789 端口对公网的暴露，仅开放 443 端口。以 ufw 为例（Ubuntu/Debian）：
ufw allow 443/tcp
ufw deny 18789/tcp
ufw enable
步骤 5：Docker Daemon 安全建议（企业环境）
# 1. 开启 live-restore（容器在 daemon 重启时保持运行）
# 编辑 /etc/docker/daemon.json，添加：
{
"live-restore": true
}
# 2. 限制 docker.sock 权限（默认已为 root:docker 660，请勿放宽）
chmod 660 /var/run/docker.sock
# 3. 生产环境禁止将 docker.sock 挂载进容器（沙箱场景需谨慎评估）
步骤 6：启动生产环境服务
# 启动 Gateway 服务
docker compose -f docker-compose.prod.yml up -d
# 初始化配置（生成令牌/配置渠道）
docker compose -f docker-compose.prod.yml run --rm openclaw-gateway onboard
# 检查服务状态
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f openclaw-gateway
步骤 7：生产环境升级策略
# 1. 升级前备份数据卷
docker run --rm -v openclaw_home:/source -v /backup/openclaw:/dest alpine tar -czf /dest/openclaw_home_$(date +%Y%m%d).tar.gz /source
# 2. 拉取新版本镜像
docker compose -f docker-compose.prod.yml pull
# 3. 重启服务
docker compose -f docker-compose.prod.yml up -d
# 4. 验证服务状态
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f openclaw-gateway
步骤 8：日志长期策略（企业级建议）
# 方案 1：使用 journald driver（便于系统日志管理）
# 在 docker-compose.prod.yml 中修改 logging 配置：
logging:
driver: "journald"
options:
tag: "openclaw-gateway"
# 方案 2：接入 Loki/ELK（集中日志管理）
# 参考 Loki 官方文档配置 Docker logging driver 为 loki
实用配置
1. 额外挂载主机目录
- 测试环境：可灵活挂载，支持读写权限
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
- 生产环境：仅挂载必要目录，严格限制权限
# 在 docker-compose.prod.yml 中添加
volumes:
- /data/openclaw/files:/home/node/files:ro # 生产环境优先只读
2. 安装额外 APT 包
- 测试环境：动态配置（不可复现，仅测试用）
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
- 生产环境：固定版本构建（推荐）创建自定义 Dockerfile：
FROM docker.xuanyuan.run/alpine/openclaw:2026.2.22-beta.1
# 固定 Debian 包版本，确保构建可复现
RUN apt-get update && \
apt-get install -y --no-install-recommends \
ffmpeg=7:5.1.5-0+deb12u1 \
build-essential=12.9 \
wget=1.21.3-1+b2 \ # 确保 wget 存在（用于健康检查）
&& apt-get clean && \
rm -rf /var/lib/apt/lists/*
USER node
构建命令：
docker build -t openclaw:prod-custom -f Dockerfile.prod .
3. 渠道配置
# WhatsApp（扫码登录）
docker compose -f docker-compose.prod.yml run --rm openclaw-gateway channels login
# Telegram（输入 bot token）
docker compose -f docker-compose.prod.yml run --rm openclaw-gateway channels add --channel telegram --token "<token>"
# Discord（输入 bot token）
docker compose -f docker-compose.prod.yml run --rm openclaw-gateway channels add --channel discord --token "<token>"
4. 沙箱隔离（生产级配置）
生产环境沙箱需平衡安全性与可用性，核心配置如下：
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main", // 仅沙箱非主会话（默认推荐）
"scope": "agent", // 每个智能体一个容器
"workspaceAccess": "none", // 不允许访问智能体工作区
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"network": "bridge", // 生产环境如需网络，使用 bridge（而非 none）
"user": "1000:1000",
"memory": "1g", // 限制容器内存
"cpuQuota": 50000, // 限制 CPU 使用率（50%）
"ulimits": {
"nproc": 1024,
"nofile": 4096
}
}
}
}
}
}
沙箱网络说明：
network: none：最高安全级别，但会导致网络相关操作（如 pip install、API 调用）失败；
network: bridge：允许基础网络访问，可通过防火墙限制出站流量，平衡安全与可用。
常见问题排查
1. 镜像拉取失败
确认使用国内轩辕镜像，生产环境固定版本标签；
检查 Docker 服务状态：systemctl status docker（Linux）；
配置国内 Docker 镜像源（如阿里云、网易）。
2. 访问 127.0.0.1:18789 提示未授权
重新生成令牌：docker compose -f docker-compose.prod.yml run --rm openclaw-gateway dashboard --no-open；
检查 .env 文件权限：ls -l .env（需为 -rw-------）；
生产环境检查 Nginx 反向代理配置是否正确。
3. 沙箱启动失败
检查沙箱镜像是否构建：scripts/sandbox-setup.sh；
若使用 network: none，确认沙箱内无网络依赖操作；
检查容器资源限制是否过低：适当调高 memory/cpus 配置。
4. 生产环境服务自动退出
查看容器日志：docker compose -f docker-compose.prod.yml logs openclaw-gateway；
检查资源限制是否不足：调高 memory/cpus 配置；
确认 restart 策略为 unless-stopped。
5. 权限错误（EACCES）
修改挂载目录权限：sudo chown -R 1000:1000 /opt/openclaw/data；
生产环境确保容器以 non-root 用户（1000:1000）运行。
总结
核心关键点
版本管理：Docker 镜像无自动更新，生产环境必须固定版本标签（如 2026.2.22-beta.1），禁止使用 latest/beta；
资源限制：普通 docker compose 模式下使用 mem_limit/cpus，Swarm 模式可使用 deploy.resources；
安全配置：
测试环境：默认配置可直接使用，仅绑定 127.0.0.1；
生产环境：必须配置反向代理 + HTTPS、防火墙、资源限制、非 root 运行、健康检查、重启策略；
健康检查：使用 wget 替代 curl，确保在 Debian slim 镜像中可用；
令牌生成：使用 openssl rand -hex 32 替代 uuidgen，更通用；
沙箱隔离：平衡安全性与可用性，生产环境推荐使用 bridge 网络 + 防火墙限制，而非完全禁用网络。
部署选型建议
个人测试：选择快速启动流程，使用 beta 版本镜像，无需复杂配置；
企业生产：严格遵循生产环境部署流程，补充 Nginx 反向代理、HTTPS、防火墙、日志管理、定期备份等配置，确保服务稳定安全。
本文来自博客园，作者：leepandar，转载请注明原文链接：https://www.cnblogs.com/leepandar/p/19748871
浙公网安备 33010602011771号