OpenClaw 生产级 Docker 安装教程：避坑、加固、备份与验证

这篇教程目标很明确：不是“能跑起来就行”，而是在一台干净 Debian/Ubuntu VPS 上，把 OpenClaw 按生产思路装到可以长期维护、可以备份、可以升级、出了问题能定位的状态。

我在写作前查了官方安装、Docker、Linux Server、安全、迁移和更新文档，也看了 GitHub 最新 release。官方文档目前推荐 Node 24 或 Node 22.14+，Docker 部署要求 Docker Engine + Compose v2，并特别提醒 1GB 主机在镜像构建时可能因为 OOM 出现 exit 137；VPS 场景则建议 Gateway 默认保持本机/受控网络访问，不要裸露到公网。本文按这些坑来设计流程。

参考资料：

本文查询时间是 2026-05-30，示例固定使用当前最新 release 2026.5.27。以后安装前先到 release 页面确认最新稳定版本，再替换文中的版本号。

方案选择

本文使用 Docker Compose，而不是直接在宿主机全局 npm install -g openclaw。

原因有四个：

宿主机更干净，OpenClaw 的 Node、依赖、运行目录和工作区都在明确边界内。
生产环境可以用固定镜像版本，避免 latest 引起不可控变化。
Gateway、状态目录、工作区、密钥目录可以统一备份。
防火墙、端口绑定、反代、隧道都能围绕 Compose 文件审计。

最终结构：

Internet
  -> SSH 22/tcp
  -> no direct public OpenClaw port

Admin laptop
  -> SSH tunnel or Tailscale
  -> 127.0.0.1:18789

VPS
  /opt/openclaw/openclaw-src        # 官方仓库，仅放 compose 和脚本
  /opt/openclaw/state               # OpenClaw 状态、配置、会话、凭据
  /opt/openclaw/workspace           # Agent 工作区
  /opt/openclaw/auth-profile-secrets# 模型 OAuth/API 相关密钥
  /opt/openclaw/backups             # 本地备份包

生产前提

推荐配置：

项目	建议
系统	Debian 12/13 或 Ubuntu 22.04/24.04 LTS
内存	最低 2 GB，推荐 4 GB+
磁盘	最低 20 GB，推荐 SSD 40 GB+
CPU	2 vCPU 起步
访问方式	SSH 隧道或 Tailscale，不直接暴露 Gateway
OpenClaw 版本	固定稳定 release，例如 `2026.5.27`
Docker Compose	v2 插件，即 `docker compose`

几个先说清楚的坑：

不要在 1GB 小鸡上本地 build 镜像，官方文档已经点名 pnpm install 可能 OOM。
不要把 18789 直接开到公网。OpenClaw 能执行命令、读写文件、接管浏览器或消息通道，它不是普通网页后台。
不要用一台 Gateway 给互不信任的人共用。官方安全模型默认是单信任边界。
不要只备份 openclaw.json。会话、模型凭据、渠道登录状态都在 state 目录里。
不要默认挂载 Docker socket 给 Agent。需要容器控制能力时再单独设计 socket proxy 或专用节点。

1. 基础系统检查

以 root 登录新机器，先看系统、内存、磁盘和监听端口：

cat /etc/os-release
uname -a
free -h
df -h
ss -lntup
systemctl --failed --no-pager

如果内存小于 2 GB，先加 swap。OpenClaw 自身可以跑，但安装、更新、浏览器依赖和插件安装会吃内存：

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

grep -q '^/swapfile ' /etc/fstab || \
  printf '%s\n' '/swapfile none swap sw 0 0' >> /etc/fstab

free -h

更新系统并安装基础工具：

apt update
apt install -y ca-certificates curl gnupg git lsb-release ufw jq openssl tar

2. 安装 Docker Engine

Debian 推荐使用 Docker 官方仓库：

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

. /etc/os-release
printf '%s\n' \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian ${VERSION_CODENAME} stable" \
  > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Ubuntu 用户把仓库地址里的 debian 改成 ubuntu：

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

. /etc/os-release
printf '%s\n' \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \
  > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

验证：

docker version
docker compose version
docker run --rm hello-world

3. 防火墙先收口

只放行 SSH。OpenClaw Dashboard 后面通过 SSH 隧道访问，不开放公网端口：

ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp
ufw --force enable
ufw status verbose

重要：Docker 发布端口可能绕过普通 ufw 入站规则，所以本文还会在 Compose 里把 OpenClaw 端口绑定到宿主机 127.0.0.1。这是最关键的防线。

4. 准备目录和专用数据

mkdir -p /opt/openclaw
mkdir -p /opt/openclaw/state
mkdir -p /opt/openclaw/workspace
mkdir -p /opt/openclaw/auth-profile-secrets
mkdir -p /opt/openclaw/backups
chmod 700 /opt/openclaw/state /opt/openclaw/auth-profile-secrets

OpenClaw 官方 Docker 镜像默认以 uid 1000 的 node 用户运行。宿主机 bind mount 如果是 root 拥有，常见结果就是 EACCES 或插件目录 ownership 异常。先把运行目录给 uid 1000：

chown -R 1000:1000 /opt/openclaw/state
chown -R 1000:1000 /opt/openclaw/workspace
chown -R 1000:1000 /opt/openclaw/auth-profile-secrets

5. 拉取官方仓库并固定版本

安装时不要盲跑 main，也不要直接追 latest。固定 release：

cd /opt/openclaw
git clone https://github.com/openclaw/openclaw.git openclaw-src
cd /opt/openclaw/openclaw-src

git fetch --tags
git checkout v2026.5.27

确认当前版本：

git describe --tags --always

如果你之后看到官方 release 更新，比如 v2026.6.x，先读 release notes，再替换版本号。

6. 写入生产环境变量

生成一个长 token：

OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
printf '%s\n' "$OPENCLAW_GATEWAY_TOKEN"

写入 .env：

cd /opt/openclaw/openclaw-src

nvim .env

内容如下，把 OPENCLAW_GATEWAY_TOKEN 换成刚生成的值：

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.5.27
OPENCLAW_GATEWAY_TOKEN=replace-with-your-random-token
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_MSTEAMS_PORT=3978

OPENCLAW_CONFIG_DIR=/opt/openclaw/state
OPENCLAW_WORKSPACE_DIR=/opt/openclaw/workspace
OPENCLAW_AUTH_PROFILE_SECRET_DIR=/opt/openclaw/auth-profile-secrets
OPENCLAW_HOME_VOLUME=1
OPENCLAW_DISABLE_BONJOUR=1
OPENCLAW_TZ=Asia/Shanghai

这里 OPENCLAW_GATEWAY_BIND=lan 是给容器内部监听用的。真正的公网收口在下一步的端口绑定：只绑定宿主机 127.0.0.1。

7. 写入 Compose 覆盖文件

不要直接改官方 docker-compose.yml，写一个覆盖文件，方便以后更新仓库：

nvim docker-compose.prod.yml

内容：

services:
  openclaw-gateway:
    ports:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "127.0.0.1:${OPENCLAW_BRIDGE_PORT:-18790}:18790"
      - "127.0.0.1:${OPENCLAW_MSTEAMS_PORT:-3978}:3978"
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "5"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true

  openclaw-cli:
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"

解释：

127.0.0.1:18789:18789：宿主机只允许本机访问 Gateway。
restart: unless-stopped：机器重启后自动恢复。
json-file 限制日志大小，避免日志撑爆磁盘。
cap_drop 和 no-new-privileges 保持官方硬化方向。

检查合并后的 Compose：

docker compose -f docker-compose.yml -f docker-compose.prod.yml config >/tmp/openclaw-compose.rendered.yml
grep -n '127.0.0.1' /tmp/openclaw-compose.rendered.yml

应能看到三个端口都绑定到了 127.0.0.1。

8. 拉镜像并启动

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d openclaw-gateway

查看状态：

docker compose -f docker-compose.yml -f docker-compose.prod.yml ps
docker compose -f docker-compose.yml -f docker-compose.prod.yml logs --tail 100 openclaw-gateway
curl -fsS http://127.0.0.1:18789/healthz

如果 pull 提示镜像 tag 不存在，说明 GHCR 还没发布这个 tag 或 tag 命名变化。临时方案是把 .env 改成：

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest

但生产环境建议尽快换回明确版本。

9. 完成首次 onboarding

Docker 文档说明，官方 setup 脚本可以自动跑 onboarding；但在生产 VPS 上，我更建议先把端口和目录都固定好，再通过 CLI 容器执行初始化。

运行：

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli onboard

向导里按这个原则选：

项目	建议
Gateway auth	token，使用 `.env` 里的长 token
Gateway bind	容器内 `lan`，宿主机仍只绑定 `127.0.0.1`
模型	选你已有账号/API key 的主力模型
渠道	先跳过或只配一个测试渠道
插件/技能	先最小化，跑通后再加
daemon	Docker Compose 已托管，不需要宿主机 systemd user daemon

向导结束后重启一次：

docker compose -f docker-compose.yml -f docker-compose.prod.yml restart openclaw-gateway

10. 用 SSH 隧道打开 Dashboard

在你的电脑上执行：

ssh -L 18789:127.0.0.1:18789 root@your-vps-ip

保持这个 SSH 窗口打开，然后浏览器访问：

http://127.0.0.1:18789/

输入 .env 里的 OPENCLAW_GATEWAY_TOKEN。

如果需要重新获取 Dashboard 链接：

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli dashboard --no-open

如果提示设备未授权，列出并批准设备：

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli devices list
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli devices approve <requestId>

11. 安全审计与健康检查

初始化后立即跑：

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli doctor
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli security audit

如果审计提示 DM、Group、exec、plugin、browser control 或 Gateway exposure 风险，先处理这些，再接渠道。

生产底线：

Gateway 不公网暴露。
DM 使用 pairing 或 allowlist，不要随便 open。
群聊必须 mention gate 或严格 allowlist。
Agent 默认工具最小化，不给不必要的 shell、文件、浏览器和 cron 能力。
插件只装可信来源，装完再跑 security audit。

再从宿主机确认端口没有公网监听：

ss -lntp | grep -E '18789|18790|3978' || true

应该看到类似：

127.0.0.1:18789
127.0.0.1:18790
127.0.0.1:3978

从你本地电脑直接访问 http://your-vps-ip:18789/ 应该失败。只有 SSH 隧道后的 http://127.0.0.1:18789/ 能打开。

12. 添加 Telegram 渠道示例

先在 BotFather 创建 bot，拿到 token。然后执行：

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli \
  channels add --channel telegram --token "123456:replace-with-token"

添加后跑：

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli doctor
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli security audit

第一次有人私聊 bot 时，如果使用 pairing 策略，按提示 approve，不要为了省事把所有 DM 打开。

13. 备份

备份 OpenClaw 时，重点不是源码仓库，而是 state、workspace 和密钥目录。

创建备份脚本：

nvim /opt/openclaw/backup-openclaw.sh

内容：

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/opt/openclaw/backups"
STAMP="$(date +%Y%m%d-%H%M%S)"
OUT="${BACKUP_DIR}/openclaw-${STAMP}.tgz"

mkdir -p "$BACKUP_DIR"

cd /opt/openclaw/openclaw-src
docker compose -f docker-compose.yml -f docker-compose.prod.yml stop openclaw-gateway

tar -czf "$OUT" \
  -C /opt/openclaw state workspace auth-profile-secrets \
  -C /opt/openclaw/openclaw-src .env docker-compose.prod.yml

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d openclaw-gateway

chmod 600 "$OUT"
find "$BACKUP_DIR" -type f -name 'openclaw-*.tgz' -mtime +30 -delete

printf 'backup created: %s\n' "$OUT"

授权并试跑：

chmod 700 /opt/openclaw/backup-openclaw.sh
/opt/openclaw/backup-openclaw.sh
ls -lh /opt/openclaw/backups

加入 cron，每天凌晨 3 点备份：

crontab -e

加入：

0 3 * * * /opt/openclaw/backup-openclaw.sh >> /opt/openclaw/backups/backup.log 2>&1

更稳妥的生产做法是再把 /opt/openclaw/backups 加密同步到另一台机器或对象存储。state 里有模型凭据、渠道登录态和会话记录，不要明文丢到公开网盘。

14. 升级流程

升级不要直接 docker compose pull && up -d。先备份，再读 release，再切 tag。

示例从 2026.5.27 升到 2026.x.y：

cd /opt/openclaw/openclaw-src

/opt/openclaw/backup-openclaw.sh

git fetch --tags
git checkout v2026.x.y

nvim .env

把镜像改成：

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.x.y

拉取并重启：

docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli doctor
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli security audit
curl -fsS http://127.0.0.1:18789/healthz

如果升级后异常，回滚：

cd /opt/openclaw/openclaw-src

git checkout v2026.5.27
nvim .env

把镜像改回：

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.5.27

然后：

docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

如果 state 已被新版迁移且无法回退，就停服务后从备份恢复。

15. 常见坑和处理

`exit 137` 或安装中断

这是 OOM 高发信号。处理：

free -h
dmesg -T | grep -i -E 'killed process|out of memory|oom'

解决：

用预构建镜像，不在小机器上 build。
至少 2 GB 内存，最好 4 GB。
加 2 GB swap。

`EACCES` 或插件目录 ownership 异常

修目录所有权：

chown -R 1000:1000 /opt/openclaw/state
chown -R 1000:1000 /opt/openclaw/workspace
chown -R 1000:1000 /opt/openclaw/auth-profile-secrets

docker compose -f docker-compose.yml -f docker-compose.prod.yml restart openclaw-gateway

Dashboard 显示未授权或需要 pairing

重新生成链接并批准设备：

docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli dashboard --no-open
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli devices list
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli devices approve <requestId>

CLI 容器 DNS 偶发 `EAI_AGAIN`

官方 Docker 文档提到，在某些 Docker Desktop 环境里，openclaw-cli 共享 gateway 网络并 drop 掉 NET_RAW 后，npm 类命令可能出现 DNS 问题。Linux VPS 上不常见。真遇到时，不要长期放宽 gateway，只给一次性 CLI 命令用临时 override：

nvim docker-compose.cli-dns.local.yml

内容：

services:
  openclaw-cli:
    cap_drop: !reset []

只在需要安装插件的这一次使用：

docker compose \
  -f docker-compose.yml \
  -f docker-compose.prod.yml \
  -f docker-compose.cli-dns.local.yml \
  run --rm openclaw-cli plugins install <package>

用完不要把这个文件加入日常启动命令。

`openclaw` 看起来启动了，但公网能访问

立刻停服务：

cd /opt/openclaw/openclaw-src
docker compose -f docker-compose.yml -f docker-compose.prod.yml stop openclaw-gateway

检查 docker-compose.prod.yml 端口是否是 127.0.0.1:18789:18789，不要写成 18789:18789。修完再启动：

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d openclaw-gateway
ss -lntp | grep 18789

只复制配置后迁移，新机器上会话和渠道全没了

迁移必须复制整个 state 目录和 workspace。官方迁移文档也明确说，模型 auth profiles、channel credentials、sessions 都不只在 openclaw.json 里。

正确迁移：

cd /opt/openclaw/openclaw-src
docker compose -f docker-compose.yml -f docker-compose.prod.yml stop openclaw-gateway

tar -czf /root/openclaw-migrate.tgz \
  -C /opt/openclaw state workspace auth-profile-secrets \
  -C /opt/openclaw/openclaw-src .env docker-compose.prod.yml

新机器恢复后：

chown -R 1000:1000 /opt/openclaw/state
chown -R 1000:1000 /opt/openclaw/workspace
chown -R 1000:1000 /opt/openclaw/auth-profile-secrets

cd /opt/openclaw/openclaw-src
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli doctor

16. 最终验收清单

cd /opt/openclaw/openclaw-src

docker compose -f docker-compose.yml -f docker-compose.prod.yml ps
curl -fsS http://127.0.0.1:18789/healthz
ss -lntp | grep -E '18789|18790|3978'
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli doctor
docker compose -f docker-compose.yml -f docker-compose.prod.yml run --rm openclaw-cli security audit
/opt/openclaw/backup-openclaw.sh

验收标准：

healthz 返回正常。
18789/18790/3978 只监听 127.0.0.1。
本地电脑必须通过 SSH 隧道才能访问 Dashboard。
doctor 没有阻塞性错误。
security audit 没有公网暴露、开放 DM、危险 debug flag、权限过宽等高风险项。
备份包能生成，权限是 600。
重启 VPS 后服务能自动恢复：

reboot

重连后：

cd /opt/openclaw/openclaw-src
docker compose -f docker-compose.yml -f docker-compose.prod.yml ps
curl -fsS http://127.0.0.1:18789/healthz

结论

生产安装 OpenClaw，真正难的不是执行安装命令，而是边界控制：谁能访问 Gateway、谁能给 bot 发消息、Agent 能调用哪些工具、状态目录怎么备份、升级失败怎么退回。

按本文这套方式，OpenClaw 的入口默认只在 VPS 本机，管理走 SSH 隧道；运行状态全部落在 /opt/openclaw 下；版本、Compose 覆盖、日志、备份和审计都有固定动作。这样后面无论是加 Telegram、接 Slack、配本地节点，还是升级到新 release，都不会变成一次靠运气的安装。