Docker 生产部署

用 Docker Compose 部署 OpenClaw，适合需要环境隔离或可复现部署的场景。

前置条件

• Docker Engine + Docker Compose v2
• 2GB+ 内存（pnpm install 在 1GB 机器上会 OOM）
• 模型 Provider API Key

快速启动

方式一：预构建镜像（推荐）

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 使用官方镜像，跳过本地构建
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# 持久化 /home/node
export OPENCLAW_HOME_VOLUME="openclaw_home"

# 预装常用系统包
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg git curl jq"

# 设置时区
export OPENCLAW_TZ="Asia/Shanghai"

# 运行安装脚本
./docker-setup.sh

验证安装成功：

# 查看容器状态
docker compose ps

# 应该看到 openclaw-gateway 和 openclaw-cli 两个容器
# 状态应该是 "running"

# 检查 Gateway 健康状态
curl http://127.0.0.1:18789/healthz
# 返回 {"ok":true,"status":"live"} 表示成功

方式二：本地构建

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

验证：

docker compose ps
curl http://127.0.0.1:18789/healthz

镜像选择

官方镜像：ghcr.io/openclaw/openclaw

Tag	说明
latest	最新稳定版
main	main 分支最新构建
2026.3.13	指定版本

基础镜像：node:24-bookworm

持久化配置

Docker Compose 默认挂载：

容器路径	宿主机路径	用途
/home/node/.openclaw	~/.openclaw/	配置 + 凭证
/home/node/.openclaw/workspace	~/.openclaw/workspace	工作区

额外挂载（可选）：

# 挂载自定义目录
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/data:/home/node/data:rw"
./docker-setup.sh

健康检查

# 存活探针（无需认证）
curl -fsS http://127.0.0.1:18789/healthz

# 就绪探针
curl -fsS http://127.0.0.1:18789/readyz

# 深度检查（需认证）
docker compose exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Docker 镜像内置 HEALTHCHECK，自动探测 /healthz。连续失败会标记为 unhealthy。

网络配置

# 默认：lan 模式（Docker 内需要）
export OPENCLAW_GATEWAY_BIND=lan

# 如果看到 ws://172.x.x.x:18789 错误：
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan

WARNING

gateway.bind 使用模式值（lan / loopback），不要用 IP 地址（0.0.0.0 / 127.0.0.1）。

Agent Sandbox（可选）

在 Docker Gateway 内启用 agent 沙箱隔离：

export OPENCLAW_SANDBOX=1
./docker-setup.sh

配置：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",           // off | non-main | all
        scope: "agent",             // session | agent | shared
        workspaceAccess: "none",    // none | ro | rw
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          network: "none",          // 默认无网络
          memory: "1g",
          cpus: 1,
          pidsLimit: 256,
          capDrop: ["ALL"],
        }
      }
    }
  }
}

构建沙箱镜像：

scripts/sandbox-setup.sh                 // 基础镜像
scripts/sandbox-common-setup.sh          // 含开发工具
scripts/sandbox-browser-setup.sh         // 含浏览器

权限问题

镜像以 node (uid 1000) 运行。如果遇到 EACCES：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Channel 配置

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "YOUR_TOKEN"

# WhatsApp (QR 配对)
docker compose run --rm openclaw-cli channels login

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "YOUR_TOKEN"

日常管理

# 查看日志
docker compose logs -f openclaw-gateway

# 重启
docker compose restart openclaw-gateway

# 更新
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
docker compose pull
docker compose up -d

# CLI 命令
docker compose run --rm openclaw-cli status
docker compose run --rm openclaw-cli doctor

性能调优

内存限制

# docker-compose.yml
services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

CPU 限制

services:
  openclaw-gateway:
    cpus: 1.0

常见问题

Q: 容器启动后立即退出？

# 查看容器日志
docker compose logs openclaw-gateway

# 检查端口占用
lsof -i :18789

Q: 内存不足 (OOM)？

确保主机有 2GB+ 可用内存，或限制容器内存：

export OPENCLAW_DOCKER_MEMORY="1g"

Q: 如何备份数据？

# 备份配置和工作区
tar -czf openclaw-backup.tar.gz ~/.openclaw/