Docker VM 运行时

在配置好虚拟机并安装 Docker 后，使用此运行时流程。提供商指南（如 GCP 和 Hetzner）负责虚拟机创建、防火墙规则、SSH 访问以及返回笔记本电脑的隧道。本页面负责这些主机共用的 Docker 设置。

开始之前¶

你需要：

• 一台安装了 Docker Engine 和 Docker Compose v2 的 Debian 或 Ubuntu 虚拟机
• 构建源码镜像至少需要 6 GB 内存；较小的主机应使用下方官方预构建镜像
• 虚拟机上的 OpenClaw 源码检出
• 用于 onboarding 的提供商和模型凭据
• 仅限 SSH 或以其他方式受限的提供商防火墙；不要将 Gateway 端口直接暴露到公共互联网

在虚拟机中执行：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker --version
docker compose version

准备持久化主机状态¶

维护好的设置脚本默认将状态放在当前虚拟机用户的主目录下：

export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"
export OPENCLAW_AUTH_PROFILE_SECRET_DIR="$HOME/.openclaw-auth-profile-secrets"

如果你的虚拟机使用专用数据盘，请在设置前覆盖这些路径。将这三个目录都保留在备份中。当前 OAuth token 材料以明文形式存储在 OPENCLAW_CONFIG_DIR 下的 SQLite 中，包括 access、refresh 和 ID-token 值。请将配置目录及其备份或副本视为凭据。

auth-profile 密钥目录仅包含用于恢复旧版加密的 OAuth sidecar 凭据的本地密钥。它必须在该恢复路径中持续存在，并且与 OPENCLAW_CONFIG_DIR 保持分离，但它不会加密当前的 SQLite 行，也不会保护仅状态的备份或副本。

运行维护好的 Docker 设置¶

./scripts/docker/setup.sh

该脚本会创建主机目录、构建 openclaw:local、运行 onboarding 流程、生成 Gateway token、同步 .env，并通过仓库的 docker-compose.yml 启动 Gateway。Compose 文件将容器侧状态固定到 /home/node/.openclaw，同时使用上述主机路径作为绑定挂载源。

要使用官方预构建镜像而不是从源码构建：

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

对于无人值守设置、提供商 SecretRefs、额外挂载、沙箱设置以及所有受支持的环境变量，请使用完整的 Docker 指南。

将必需的二进制文件烘焙到镜像中¶

在运行中的容器内安装二进制文件是一个陷阱：运行时安装的任何内容都会在容器重新创建时丢失。在构建时将技能所需的每个外部二进制文件烘焙到镜像中。

下面的示例仅按字母顺序涵盖三个二进制文件：

• gog（来自 gogcli）用于 Gmail 访问
• goplaces 用于 Google Places
• wacli 用于 WhatsApp

这些只是示例，不是完整列表。Docker Compose 构建仓库根目录下的 Dockerfile，因此请扩展该文件，而不是创建独立示例或替换其内容。仓库的 Dockerfile 包含必需的 manifest 提取、构建、生产依赖、运行时资产和最终运行时阶段。构建和生产安装共享相同的 manifests 和 lockfile，包括 packages/* 和选定的插件工作区。

对于 Debian 软件包，建议使用现有的构建参数：

export OPENCLAW_IMAGE_APT_PACKAGES="socat"

对于下载的发布二进制文件（如 gog、goplaces 或 wacli），请将下载和安装命令添加到仓库根目录 Dockerfile 的最终运行时阶段，位于其软件包安装块之后、USER node 之前。保留现有的非 root uid 1000 设置、tini 入口点、健康检查和 openclaw 符号链接。

在不重复 onboarding 的情况下重新构建自定义镜像：

OPENCLAW_SKIP_ONBOARDING=1 ./scripts/docker/setup.sh

如果在依赖安装或打包过程中构建失败并显示 Killed 或退出代码 137，说明虚拟机内存不足。请在重试前调整其大小。

验证烘焙的二进制文件：

docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli

验证并管理 Gateway¶

docker compose ps
docker compose logs --tail=100 openclaw-gateway
curl -fsS http://127.0.0.1:18789/healthz
docker compose run --rm openclaw-cli dashboard --no-open

/healthz 返回 200 响应，确认 Gateway 进程正在监听。镜像的 HEALTHCHECK 会轮询同一端点。如果 Control UI 需要设备批准：

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

哪些状态持久化在哪里¶

OpenClaw 在 Docker 中运行，但容器文件系统并不是权威数据源。长期状态必须能在重启、重建和重新启动后继续存在。

常见陷阱：切勿将 openclaw.json 作为文件绑定¶

将网关状态挂载为目录，切勿作为单个文件挂载。仓库中的 docker-compose.yml 已经这样做了：

# Supported: whole state directory.
- "${OPENCLAW_CONFIG_DIR:-${HOME:-/tmp}/.openclaw}:/home/node/.openclaw"

# Unsupported: single-file bind. Do not use this.
# - "./openclaw.json:/home/node/.openclaw/openclaw.json"

单个文件绑定会一直附着在被挂载的文件上。常规的 OpenClaw 配置保存会替换 openclaw.json。如果容器启动后，主机侧的保存操作替换了单个文件绑定的源文件，容器可能会继续读取旧文件，而主机路径已指向新文件。主机侧的保存可能成功，但容器看到的内容不会更新。原地写入同一文件的编辑不会导致这种不一致。

解决办法：保留 Compose 中的目录挂载。在主机上编辑该目录内的 openclaw.json。

更新 OpenClaw¶

对于源码构建的镜像：

git pull --ff-only
OPENCLAW_SKIP_ONBOARDING=1 ./scripts/docker/setup.sh
docker compose run --rm openclaw-cli doctor --json

对于固定版本或预构建的镜像，请在重新运行安装脚本前将 OPENCLAW_IMAGE 更新为目标标签或摘要。常规镜像升级会对挂载状态执行启动安全的迁移；当迁移无法自动完成时，请参阅 升级容器镜像 进行恢复。

相关¶

• Docker
• Podman