OpenClaw Docker 部署实战：安全配置、探针与回滚

Docker 是部署方式，不是安全结论

官方 OpenClaw Docker 文档明确说明 Docker 是可选方案。它适合：

• 隔离、可丢弃的 Gateway 运行环境；
• 不希望在 VPS 宿主机安装 Node.js 工具链；
• 需要可复现的 Compose 运维；
• 使用受支持的 Docker Agent Sandbox。

但 Docker 不会自动提供：

• 敌对多租户隔离；
• 安全的公网暴露；
• 最小权限模型或渠道凭证；
• 对所有 Agent 工具的沙盒保护；
• 备份与回滚兼容性。

Gateway 容器、openclaw-cli Sidecar、Agent 工具沙盒、模型服务商和消息渠道处于不同信任边界，生产方案必须逐一处理。

协议和权限边界可参考 OpenClaw API 指南；产品整体信任模型可参考 OpenClaw AI Agent 完全指南。

先选择部署拓扑

应使用满足需求的最小拓扑。

单操作者或互信团队

一个 Gateway 服务一名操作者或相互信任的团队。默认绑定 Loopback，通过 SSH 或私有 VPN 管理，只连接业务真正需要的消息渠道。

多个互不信任的租户

Session Key 和聊天渠道都不是租户授权边界。官方信任模型并未把单个 Gateway 定义为敌对多租户隔离层。应按租户或信任域拆成独立 Cell，分别配置状态、凭证、网络策略和资源配额。

Gateway 容器加工具沙盒

两层的职责不同：

宿主机
  -> Gateway 容器
       -> 模型与消息渠道出站访问
       -> 可选 Sandbox Backend
            -> 临时工具容器

Gateway 容器化决定控制面运行在哪里；启用 Sandbox 决定受支持的工具在哪里执行。两者都不能让挂载凭证或无限制网络出口变得无害。

准备宿主机

官方前置条件是 Docker Engine 或 Docker Desktop 加 Compose v2。本地从源码构建镜像至少需要 6 GB 内存；预构建镜像可以避开这项构建需求。磁盘预算还应包括：

• Gateway 镜像及可选浏览器/沙盒镜像；
• 持久状态和工作区；
• 会话记录与索引；
• 日志和诊断导出；
• 至少一份完整备份与升级余量。

公网 VPS 还要检查防火墙，尤其是 Docker DOCKER-USER Chain。容器内进程监听 127.0.0.1，不等于宿主机发布端口受限；必须从另一台机器验证最终暴露面。

使用官方不可变镜像

OpenClaw 以 GHCR 为主要发布 Registry，并将同一 Release 镜像同步到 Docker Hub：

ghcr.io/openclaw/openclaw
openclaw/openclaw

资格验证阶段使用明确 Release Tag，然后记录 Digest：

export OPENCLAW_RELEASE="<tested-release>"
docker pull "ghcr.io/openclaw/openclaw:${OPENCLAW_RELEASE}"
docker image inspect \
  --format '{{index .RepoDigests 0}}' \
  "ghcr.io/openclaw/openclaw:${OPENCLAW_RELEASE}"

运行官方 Setup 前，将 OPENCLAW_IMAGE 设为已评审镜像：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw@sha256:<reviewed-digest>"
./scripts/docker/setup.sh

不要使用非官方 Mirror，也不要把浮动的 latest、main 或 Channel Tag 直接推广到生产。Tag 可移动，事故排查时无法证明当时运行的是哪一组二进制。

不同镜像 Variant 内容不同。例如 Browser Variant 内置 Chromium，Slim Variant 通过减少内置组件换取体积。应针对准确 Variant 检查插件、浏览器工具、CPU 架构、来源证明和漏洞修复策略。

理解 Setup 脚本会修改什么

官方脚本可以：

• 从源码构建 openclaw:local 或使用 OPENCLAW_IMAGE；
• 同步 Compose .env；
• 读取模型服务商凭证；
• 生成 Gateway Token；
• 创建必要状态目录与旧版 Auth Profile Secret 目录；
• 执行 Onboarding 和配置写入；
• 启动 Compose 服务。

它很方便，但本质上仍是有状态变更。应阅读固定 Release 中的脚本，把 .env 排除在版本库之外，并记录哪位操作者执行了 Onboarding。

离线主机应提前导入全部 Gateway 与 Sandbox 镜像，再使用文档化 --offline 模式。离线检查必须证明镜像已存在，不能在不知情的情况下从其他 Registry 拉取。

持久化完整状态边界

至少要保存配置的 OpenClaw State/Config 目录与 Workspace 目录。凭证、设备身份、渠道 Session、配置、记忆、对话、索引、Task/Flow 状态和插件数据不一定集中在一个显眼文件中。

先建立备份清单：

只有在隔离宿主机完成恢复，并验证 Gateway 能通过启动检查、列出预期设备、读取必要状态、完成无害端到端测试，备份才算有效。

不要只备份 Workspace 就假设系统可恢复，也不要在不了解一致性语义时直接复制正在写入的 SQLite 文件。

保护 Secret 与文件权限

整个 State 目录都应视为敏感数据，其中可能包含模型凭证、渠道 Session、对话、工具结果、记忆与配对设备状态。

运维要求：

• 使用专用宿主机账号；
• 限制 Bind Mount 目录 Owner 与 Mode；
• 将 .env 和备份归档放在仓库之外；
• 共享或便携主机启用全盘加密；
• 支持时优先使用 Secret Reference 或外部 Secret Manager；
• Gateway、模型和渠道凭证可以独立轮换；
• 导出前对日志脱敏；
• 删除策略覆盖在线状态、备份、索引与诊断包。

避免宽泛宿主机挂载。把整个 Home 目录以读写方式挂入容器，会让容器逃逸或工具策略失效扩大为宿主机级访问。只挂载状态与工作区所需路径，能够只读的路径就不要读写。

限制网络入口

默认 Control UI 使用 18789 端口，应限制在 Loopback 或私有入口。远程管理优先使用：

• SSH 本地端口转发；
• Tailscale 或其他认证私网；
• 只有在身份 Header 与 Trust 配置正确验证时才使用加固反向代理。

绝不能无鉴权发布 Gateway。gateway.auth.mode: "none" 只适用于私有入口，不能用于公网或不可信网络。

CLI Sidecar 与 Gateway 共用 Network Namespace，因此可以通过 127.0.0.1 访问 Gateway。这也是共享信任边界。官方 Compose 的 Capability Drop 与 no-new-privileges 能缩小风险，但不能替代凭证隔离和命令授权。

正确使用三个探针

OpenClaw 暴露三个语义不同的端点：

curl --fail --silent http://127.0.0.1:18789/healthz
curl --fail --silent http://127.0.0.1:18789/startupz
curl --fail --silent http://127.0.0.1:18789/readyz

一个可选渠道断线，可能导致深层 Readiness 失败，但 Gateway 进程仍然健康。如果编排器把 /readyz 当 Liveness，外部服务故障会引发容器重启循环，既丢失诊断证据又增加负载。

应分别监控各探针，并根据本部署真正必需的能力定义接流条件，而不是默认所有配置渠道同等关键。

显式启用 Agent Sandbox

Sandbox 默认关闭。OpenClaw 支持 Docker、Podman、SSH 与 OpenShell Backend，并且即使 Gateway 不在容器中，也可以为受支持工具启用沙盒。

Docker Setup 流程：

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

Rootless Docker Socket：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET="/run/user/1000/docker.sock"
./scripts/docker/setup.sh

Setup 只有在前置检查通过后才挂载 Docker Socket。该 Socket 赋予 Gateway 对 Docker Daemon 的高权限，因此 Gateway 被入侵仍是严重事件。绝不能把宿主机 Docker Socket 挂入 Agent Sandbox 容器。

沙盒评审必须覆盖：

• 允许的工具与命令；
• Workspace 可见范围与挂载模式；
• 网络出口与 DNS；
• 环境变量与凭证；
• 进程、内存、CPU 与时间限制；
• 浏览器 Profile 与下载处理；
• 镜像来源与补丁周期；
• 取消或崩溃后的清理。

官方文档明确说明 Sandbox 只能缩小影响面，并非完美安全边界。可结合 AI Agent 工具安全指南完成完整威胁建模。

日常运维

应在部署文件所在目录运行 Compose 命令，并始终使用相同的 -f 文件集合与顺序：

docker compose up -d openclaw-gateway
docker compose ps
docker compose logs -f openclaw-gateway
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli config get gateway
docker compose down

自动化环境应关闭伪终端：

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

建议采集以下有界证据：

• 镜像 Digest 与配置 Revision；
• 容器重启次数；
• 三类探针状态；
• Gateway 结构化错误；
• 队列、模型、渠道与工具延迟；
• 磁盘增长与最近备份时间；
• 设备配对与审批变更；
• Sandbox 创建、拒绝、超时与清理。

不要导出 Authorization Header、原始会话内容、模型 Key 或无限制工具参数。

受控升级与回滚

可靠升级是一次数据迁移，不只是拉取镜像。

升级前

1. 阅读 Release Note 与迁移警告。
2. 记录当前镜像 Digest、Compose 文件、环境 Schema 与插件版本。
3. 对 State 和 Workspace 创建一致性加密快照。
4. 在临时环境恢复快照。
5. 验证配对、只读会话、无害工具、定时任务和探针。
6. 按 Digest 拉取并扫描候选镜像。

升级时

1. 停止接收新的高影响任务。
2. 等待活跃 Task/Flow 结束，或记录可恢复状态。
3. 使用未改变且已评审的 Compose 布线部署新镜像。
4. 先检查 /startupz，再检查本部署的就绪策略。
5. 执行协议、渠道、Task 与 Sandbox Smoke Test。
6. 观察错误率、延迟、重启、磁盘写入与出站调用。

回滚原则

如果新版本修改了持久状态，不能只把镜像 Tag 切回旧版。必须把升级前状态快照、旧镜像与旧配置一起恢复。新状态格式加旧二进制不是有效回滚。

启动前就要明确不可逆点。Release 未承诺降级兼容时，“回滚”就意味着完整状态恢复。

生产门禁

• 使用官方镜像并锁定 Digest。
• 从宿主机外验证私有入口。
• 开启 Gateway 鉴权并测试设备配对。
• 盘点、加密持久目录，并完成恢复演练。
• 正确映射三个探针职责。
• Agent Sandbox 明确关闭，或已完成配置与测试。
• Sandbox 容器中不存在宿主机 Docker Socket。
• 工具和出站网络策略通过评审。
• 设置资源与费用预算。
• 演练升级与状态兼容回滚。
• 按 OpenClaw 工作流指南验证自动化行为。

一手资料

• OpenClaw Docker 安装
• Docker Compose 运维
• Gateway 健康检查
• OpenClaw Sandboxing
• 安全与网络暴露
• Secret 与存储
• 升级与回滚

总结

生产级 OpenClaw Docker 部署的关键不是 docker compose up 成功，而是状态、身份、网络入口、探针、工具执行和回滚都受控。使用官方不可变镜像，保持 Gateway 私有，完整持久化并验证状态恢复，区分 Liveness 与深层 Readiness，把 Agent Sandbox 当作独立控制进行评审。最重要的是，二进制和兼容状态必须一起回滚。