如何使用Docker运行OpenClaw：容器化部署超详细教程

相比直接在系统上安装，用 Docker 运行 OpenClaw 有三个无可替代的优势：安全隔离（恶意技能或提示注入攻击的影响被限制在容器内）、环境一致（同一镜像在任何机器上运行效果相同）、易于维护（更新只需拉新镜像，回滚只需切换标签）。

对于需要长期稳定运行 OpenClaw 的用户——尤其是在 VPS、家用 NAS 或云服务器上部署的场景——Docker 是目前最推荐的方式。本文带你完整走一遍 Docker 容器化部署流程。

准备工作：你需要什么

• Docker Engine（Linux）或 Docker Desktop（macOS/Windows）
• Docker Compose v2（Docker Desktop 已内置）
• 至少 2GB RAM（镜像构建时内存不足会导致进程被系统杀死，报错 exit 137）
• 大模型 API Key（Anthropic Claude 或 OpenAI 均可）

验证 Docker 是否安装成功：

docker --version
docker compose version

两条命令都能输出版本号即可开始。

方式一：官方一键安装脚本（最简单）

OpenClaw 官方仓库提供了完整的 Docker 安装脚本，会自动完成镜像构建、引导配置和启动：

# 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 运行官方 Docker 安装脚本
./scripts/docker/setup.sh

如果不想从源码构建镜像，可以使用官方预构建镜像：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

脚本执行过程中会：

• 自动创建 ~/.openclaw/（配置目录）和 ~/openclaw/workspace/（工作区目录）并挂载为容器卷
• 启动引导向导，提示输入 API Key 并选择模型
• 生成 Gateway Token 并写入 .env 文件
• 通过 Docker Compose 启动 Gateway 容器

方式二：手动编写 docker-compose.yml（推荐生产环境）

对于需要精细控制配置的用户，手动编写 docker-compose.yml 是更好的选择。

第一步：创建项目目录

mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

第二步：创建环境变量文件 .env

在项目目录中创建 .env 文件，存放所有敏感信息：

# .env 文件内容
ANTHROPIC_API_KEY=sk-ant-你的密钥
OPENAI_API_KEY=sk-你的密钥        # 可选
DEEPSEEK_API_KEY=sk-你的密钥      # 可选
TELEGRAM_BOT_TOKEN=你的BotToken   # 可选
TZ=Asia/Shanghai                   # 时区设置

⚠️ 安全提示：.env 文件包含敏感 API Key，务必将其添加到 .gitignore，永远不要上传到 GitHub 或任何公开仓库。

第三步：编写 docker-compose.yml

version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest   # 官方预构建镜像
    container_name: openclaw
    restart: unless-stopped            # 崩溃自动重启，手动停止不重启
    ports:
      - "127.0.0.1:18789:18789"       # 仅绑定本机，不暴露公网
    volumes:
      - ~/.openclaw:/home/node/.openclaw          # 配置和记忆持久化
      - ~/openclaw/workspace:/home/node/workspace  # 工作区持久化
    environment:
      - NODE_ENV=production
      - TZ=${TZ}
    env_file:
      - .env                           # 从 .env 文件加载 API Key
    deploy:
      resources:
        limits:
          memory: 2G                   # 内存上限
        reservations:
          memory: 512M                 # 保留最低内存
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18789/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s               # 容器启动后等待60秒再开始健康检查

💡 关键说明：容器内部 gateway.host 需要设为 0.0.0.0（监听所有接口），这样 Docker 的端口映射才能正常工作——但在 ports 配置中用 127.0.0.1:18789:18789 限制宿主机只在本地监听，保证外部无法直接访问。这是 Docker 部署与裸机部署在网络配置上最容易混淆的地方。

第四步：启动容器

# 后台启动
docker compose up -d

# 查看启动日志
docker compose logs -f

等待日志中出现 “Gateway listening on port 18789” 类似信息，说明容器已成功启动。

第五步：运行引导向导完成初始配置

容器启动后，进入容器运行引导向导：

docker compose exec openclaw openclaw onboard

按提示选择大模型提供商、输入 API Key、配置通讯平台。向导完成后，Gateway Token 会显示在终端，立即复制保存。

在 Docker 中运行 CLI 命令

部署完成后，所有 openclaw CLI 命令都需要在容器内执行：

# 检查运行状态
docker exec openclaw openclaw doctor

# 查看 Gateway 状态
docker exec openclaw openclaw gateway status

# 查看技能列表
docker exec openclaw openclaw skills list

# 添加定时任务
docker exec openclaw openclaw cron add \
  --name "morning-brief" \
  --cron "0 9 * * *" \
  --message "总结今日邮件和日程"

# 进入容器 shell（排查问题时使用）
docker exec -it openclaw bash

注意：在 Docker 中运行 openclaw doctor --fix 时，需要加 -it 参数以支持交互式输入：

docker exec -it openclaw openclaw doctor --fix

连接通讯平台：以 Telegram 为例

# 方式一：通过 CLI 连接
docker exec openclaw openclaw channels add \
  --channel telegram \
  --token 你的BotToken

# 方式二：通过控制面板连接
# 建立 SSH 隧道后在浏览器访问控制面板
ssh -L 18789:127.0.0.1:18789 用户名@服务器IP
# 然后浏览器访问 http://127.0.0.1:18789

连接 Telegram 后，发送第一条消息，系统会返回配对码，在控制面板或 CLI 中确认：

docker exec openclaw openclaw pairing approve telegram 配对码

日常运维命令速查

# 启动容器
docker compose up -d

# 停止容器
docker compose stop

# 重启容器（修改配置后）
docker compose restart

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

# 查看资源占用（CPU、内存）
docker stats openclaw

# 更新到最新版本
docker compose pull
docker compose up -d

# 清理旧镜像
docker image prune -f

数据持久化：永远不要丢失你的记忆

OpenClaw 的所有重要数据都通过 Volume 挂载持久化到宿主机：

• ~/.openclaw/：配置文件、API Key、Agent 记忆、会话历史
• ~/openclaw/workspace/：工作区文件、技能、SOUL.md 等

注意：运行 docker compose down -v 会删除所有 Volume 数据（包括你的记忆和配置）！日常停止服务只用 docker compose stop 或 docker compose down（不加 -v）。

建议定期备份这两个目录：

# 手动备份
tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz \
  ~/.openclaw ~/openclaw/workspace

# 设置每日自动备份（crontab）
# 编辑 crontab：crontab -e
# 添加以下行（每天凌晨2点备份）
0 2 * * * tar -czf ~/backups/openclaw-$(date +\%Y\%m\%d).tar.gz ~/.openclaw ~/openclaw/workspace

常见问题排查

Q：容器启动后立即退出，日志显示 exit 137 怎么办？
这是内存不足的信号（OOM Kill）。检查宿主机可用内存是否至少有 2GB，或增加 swap 空间：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Q：控制面板显示”连接失败”怎么办？
确认容器正在运行（docker ps），端口映射正确（docker port openclaw），然后在本地建立 SSH 隧道后访问。

Q：更新容器后配置丢失了怎么办？
确认 docker-compose.yml 中的 volumes 配置正确，数据目录挂载指向宿主机路径。容器本身是无状态的，所有数据应持久化到挂载卷中。

Q：在 VPS 上 Docker 防火墙策略需要注意什么？
Docker 会自动修改 iptables 规则，有时会绕过 UFW 防火墙直接暴露端口。务必在 ports 中使用 127.0.0.1:18789:18789（绑定本机 IP），而不是 18789:18789（暴露所有接口）。

进阶：添加 Nginx 反向代理（可选）

如果需要通过域名访问控制面板，可以在 docker-compose.yml 中添加 Nginx 服务：

services:
  openclaw:
    # ... 已有配置 ...

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - /path/to/ssl:/etc/ssl

nginx.conf 配置（注意 WebSocket 头部，OpenClaw 实时通信依赖它）：

server {
    listen 443 ssl;
    server_name openclaw.你的域名.com;
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    location / {
        proxy_pass http://openclaw:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Docker 部署 vs 裸机安装：如何选择？

想了解更多 Docker 部署细节，访问 OpenClaw官网中文版（通过浏览器翻译访问 openclaw.ai）或官方 Docker 文档 docs.openclaw.ai/install/docker。

本文内容基于 OpenClaw 官方文档、lumadock.com、openclaws.io、oepnclaw.com 等公开资料整理，信息截至2026年3月28日。