OpenClaw 的 Docker 部署指南

OpenClaw 支持通过 Docker 容器化部署，适用于需要环境隔离、快速验证或在无本地安装权限的主机上运行的场景。本文将详细介绍两种主要使用模式：完整容器化网关 和 主机网关 + 代理沙箱，并提供配置建议、安全注意事项及高级用法。

一、是否该使用 Docker？

• 推荐使用：

  • 希望获得一个干净、可随时销毁的开发/测试环境；
  • 在服务器或受限主机上运行 OpenClaw，无法进行全局安装。

• 不推荐使用：

  • 在个人开发机上追求最快的迭代速度——此时应选择标准本地安装流程。

注意：即使网关运行在主机上，只要启用了“代理沙箱”（Agent Sandbox），工具执行仍会通过 Docker 隔离。因此，Docker 并非仅用于全容器化部署。

二、系统要求

• Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
• Docker Compose v2
• 至少 2GB 内存（1GB 主机可能因内存不足导致构建失败）
• 足够磁盘空间存储镜像与日志
• 若部署于公网 VPS，请务必参考《安全加固》文档，特别是关于 DOCKER-USER 防火墙策略的配置。

三、快速启动：容器化网关

从项目根目录运行：

./docker-setup.sh

该脚本将自动完成以下操作：

1. 构建本地镜像（或拉取远程镜像，若设置了 OPENCLAW_IMAGE）
2. 启动首次配置向导
3. 生成访问令牌并写入 .env
4. 通过 Docker Compose 启动网关服务

完成后，打开浏览器访问 http://127.0.0.1:18789，输入令牌即可使用控制界面。

常用环境变量

所有配置变更后，需重新运行 docker-setup.sh 以生效。

四、代理沙箱：安全执行工具

即使网关运行在主机上，也可为每个代理（Agent）启用 Docker 沙箱，确保工具执行过程被严格隔离。

核心特性

• 作用域：支持 agent（默认）、session（每会话独立）或 shared（共享，不推荐）
• 工作区隔离：工具在 /workspace 中运行；可选只读或读写访问代理主工作区
• 网络限制：默认无外网访问（network: none），可按需配置 DNS 或 hosts
• 资源限制：可设置 CPU、内存、进程数、文件描述符等上限
• 自动清理：空闲超 24 小时或创建超 7 天的容器将被自动删除

启用方式

export OPENCLAW_SANDBOX=1
./docker-setup.sh

系统将自动配置沙箱参数，并挂载 Docker 套接字（仅当沙箱启用且前置条件满足时）。

默认沙箱镜像为 openclaw-sandbox:bookworm-slim。可通过 scripts/sandbox-setup.sh 本地构建，或使用预置的通用/浏览器镜像。

五、高级配置与优化

1. 浏览器工具支持

若需在沙箱中运行浏览器（如自动化网页操作），请构建专用镜像：

scripts/sandbox-browser-setup.sh

该镜像基于 Xvfb 提供有头 Chromium，支持 CDP 调试与 noVNC 远程观察。可通过配置开启 WebGL、扩展或调整渲染进程限制。

2. 持久化与性能

• 使用 OPENCLAW_HOME_VOLUME 保留 Playwright 浏览器缓存、npm 全局包等
• 通过 OPENCLAW_DOCKER_APT_PACKAGES 将依赖固化到镜像，避免每次重建
• 合理设置 PLAYWRIGHT_BROWSERS_PATH 环境变量以复用浏览器二进制文件

3. 权限问题处理

容器以 UID 1000（node 用户）运行。若挂载的主机目录权限不符，需手动修正：

sudo chown -R 1000:1000 ~/.openclaw

六、安全与运维

网络与隔离

• CLI 与网关共享网络命名空间（network_mode: service:openclaw-gateway），视为同一信任边界
• 生产环境中，建议从独立容器调用 CLI，而非使用内置服务
• 沙箱容器默认禁用 NET_RAW、NET_ADMIN，并启用 no-new-privileges

健康检查

• /healthz：进程存活检查
• /readyz：服务就绪检查（等待渠道连接完成）
• 内置 HEALTHCHECK 指令，支持 Docker 自动重启异常容器

日志与存储

• 配置与工作区通过绑定挂载持久化到 ~/.openclaw/
• 沙箱临时文件使用 tmpfs，随容器销毁自动清理
• 注意监控媒体文件、会话记录、transcript 日志等可能快速增长的数据

七、其他实用功能

• 多渠道集成：通过 CLI 容器一键配置 WhatsApp、Telegram、Discord 等
• CI/自动化支持：使用 -T 参数禁用 TTY，适配脚本与流水线
• Shell 快捷命令：安装 ClawDock 工具集，提供 clawdock-start、clawdock-stop 等便捷命令
• 手动部署：支持直接使用 docker build + docker compose 流程，适合定制化场景

总结

Docker 为 OpenClaw 提供了灵活的部署选项：既可作为轻量级开发沙箱，也能构建高隔离性的生产环境。通过合理组合 容器化网关 与 代理沙箱，用户能在安全性、便利性与性能之间取得最佳平衡。

官方镜像地址：ghcr.io/openclaw/openclaw
文档参考：https://docs.openclaw.ai/install/docker