Appearance
在云 VM 上部署 OpenClaw 时，所有外部二进制工具必须在构建镜像时安装，否则容器重启后会丢失。按本文示例将 gog、goplaces、wacli 等工具写入 Dockerfile，构建后通过 docker compose exec openclaw-gateway which <工具名> 验证可用性。配置文件和会话状态通过宿主机卷挂载持久化，不会因容器重建清空。
OpenClaw Docker VM 运行时：镜像构建与数据持久化
适用于基于 VM 的 Docker 安装（如 GCP、Hetzner 等 VPS）的通用运行时步骤。
将所需二进制工具内置到镜像
在运行中的容器内安装二进制工具是个陷阱——任何在运行时安装的东西在容器重启后都会丢失。
所有 skills 依赖的外部二进制工具必须在镜像构建时安装。
以下示例仅展示三个常见工具：
gog（来自gogcli）：Gmail 访问goplaces：Google Placeswacli：WhatsApp
这只是示例，不是完整列表。你可以按同样的模式安装任意数量的二进制工具。
如果你后来添加了依赖其他二进制工具的 skills，必须：
- 更新 Dockerfile
- 重新构建镜像
- 重启容器
Dockerfile 示例
dockerfile
FROM node:24-bookworm
RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
# 示例二进制 1：Gmail CLI (gogcli — 安装后为 `gog`)
# 从 https://github.com/steipete/gogcli/releases 复制当前 Linux 版本链接
RUN curl -L https://github.com/steipete/gogcli/releases/latest/download/gogcli_linux_amd64.tar.gz \
| tar -xzO gog > /usr/local/bin/gog; \
chmod +x /usr/local/bin/gog
# 示例二进制 2：Google Places CLI
# 从 https://github.com/steipete/goplaces/releases 复制当前 Linux 版本链接
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_linux_amd64.tar.gz \
| tar -xzO goplaces > /usr/local/bin/goplaces; \
chmod +x /usr/local/bin/goplaces
# 示例二进制 3：WhatsApp CLI
# 从 https://github.com/steipete/wacli/releases 复制当前 Linux 版本链接
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli-linux-amd64.tar.gz \
| tar -xzO wacli > /usr/local/bin/wacli; \
chmod +x /usr/local/bin/wacli
# 按同样的模式在下方添加更多二进制工具
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN corepack enable
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]注意： 上面的下载 URL 适用于 amd64。对于基于 ARM 的 VM（如 Hetzner ARM、GCP Tau T2A），请选择
arm64资产。如需可重现构建，可指定具体版本号的发布 URL。
构建和启动
bash
docker compose build
docker compose up -d openclaw-gateway如果构建时在 pnpm install --frozen-lockfile 阶段因 Killed 或 exit code 137 失败，说明 VM 内存不足，换用更大的机器规格后重试。
验证二进制工具：
bash
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli预期输出：
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli验证 Gateway：
bash
docker compose logs -f openclaw-gateway预期输出：
[gateway] listening on ws://0.0.0.0:18789数据存储位置
OpenClaw 运行在 Docker 中，但 Docker 不是状态的持久化来源。所有长期状态必须能在重启、重建和重启动后保留。
| 组件 | 位置 | 持久化机制 | 说明 |
|---|---|---|---|
| Gateway 配置 | /home/node/.openclaw/ | 宿主机 volume 挂载 | 包含 openclaw.json、.env |
| 模型认证配置 | /home/node/.openclaw/agents/ | 宿主机 volume 挂载 | agents/<agentId>/agent/auth-profiles.json（OAuth、API keys） |
| 认证密钥 | /home/node/.config/openclaw/ | 宿主机 volume 挂载 | OAuth 认证的本地加密密钥 |
| Skill 配置 | /home/node/.openclaw/skills/ | 宿主机 volume 挂载 | Skill 级别的状态 |
| Agent 工作区 | /home/node/.openclaw/workspace/ | 宿主机 volume 挂载 | 代码和 Agent 产物 |
| WhatsApp 会话 | /home/node/.openclaw/ | 宿主机 volume 挂载 | 保留二维码登录状态 |
| Gmail keyring | /home/node/.openclaw/ | 宿主机 volume + 密码 | 需要 GOG_KEYRING_PASSWORD 环境变量 |
| 插件包 | /home/node/.openclaw/npm、/home/node/.openclaw/git | 宿主机 volume 挂载 | 可下载的插件包根目录 |
| 外部二进制工具 | /usr/local/bin/ | Docker 镜像 | 必须在构建时内置 |
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次镜像构建时重建 |
| OS 包 | 容器文件系统 | Docker 镜像 | 不在运行时安装 |
| Docker 容器 | 临时 | 可重启 | 可以安全销毁 |
更新
在 VM 上更新 OpenClaw：
bash
git pull
docker compose build
docker compose up -d相关文档
常见问题
构建时 pnpm install --frozen-lockfile 报 Killed 或 exit code 137 怎么解决？
这是 VM 内存不足的典型表现。换用更大的机器规格（如 2GB RAM 以上），然后重新执行 docker compose build。
容器重启后二进制工具找不到，怎么办？
外部二进制工具必须在镜像构建时安装，不能在容器运行时通过 apt-get 或 curl 临时安装。更新 Dockerfile 添加对应工具，然后重新构建镜像并重启容器即可。
ARM 架构的 VM 怎么配置二进制工具？
将 Dockerfile 中的 amd64 下载链接替换为各工具发布页面上对应的 arm64 资产链接。对于 ARM 架构，使用 node:24-bookworm-slim 或其他支持 ARM64 的基础镜像。