前言
Docker 容器化是部署 OpenClaw 的推荐方式之一，它提供了隔离的运行环境和一致的部署体验。本教程将详细介绍从自动化脚本到手动构建的完整流程。
快速部署：docker-setup.sh 自动脚本
OpenClaw 提供了 docker-setup.sh 一键部署脚本，适合希望快速上手的用户：
# 下载并执行自动部署脚本
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh | bash
脚本会自动完成以下工作：
- 检测系统环境和 Docker 版本
- 拉取或构建所需的 Docker 镜像
- 生成默认配置文件
- 创建并启动容器
如果你需要自定义参数，可以先下载脚本再手动执行：
curl -fsSL -o docker-setup.sh https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh
chmod +x docker-setup.sh
# 查看帮助信息
./docker-setup.sh --help
手动构建与 Docker Compose
使用 docker build
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker build -t openclaw:latest .
使用 Docker Compose 编排
创建 docker-compose.yml 文件：
version: '3.8'
services:
openclaw:
image: openclaw:latest
container_name: openclaw
restart: unless-stopped
environment:
- OPENCLAW_HOME_VOLUME=/data/openclaw
- OPENCLAW_DOCKER_APT_PACKAGES=ffmpeg,imagemagick
volumes:
- openclaw_data:/data/openclaw
- /tmp/openclaw-workspace:/workspace
ports:
- "3000:3000"
volumes:
openclaw_data:
启动服务：
docker compose up -d
# 查看日志
docker compose logs -f openclaw
沙箱架构详解
OpenClaw 的 Docker 沙箱采用三级作用域隔离机制，确保不同层级的数据安全：
| 作用域 | 说明 | 生命周期 |
|---|---|---|
| agent | 单个 Agent 实例的私有数据 | 随 Agent 销毁而清除 |
| session | 单次会话的临时数据 | 会话结束后清除 |
| shared | 跨会话共享的持久数据 | 手动清除或容器重建 |
工作区访问级别
通过 sandbox.workspace 配置项控制工作区访问权限：
# 配置文件示例
sandbox:
workspace: rw # 可选值：none / ro / rw
- none：禁止访问宿主机工作区（最安全）
- ro：只读模式，Agent 可以查看但不能修改文件
- rw：读写模式，Agent 可以操作工作区文件
关键环境变量
OPENCLAW_HOME_VOLUME
指定 OpenClaw 主目录的持久化路径：
docker run -e OPENCLAW_HOME_VOLUME=/data/openclaw \
-v openclaw_home:/data/openclaw \
openclaw:latest
OPENCLAW_EXTRA_MOUNTS
挂载额外的目录到容器内，多个路径用逗号分隔：
docker run -e OPENCLAW_EXTRA_MOUNTS="/host/docs:/container/docs:ro,/host/data:/container/data:rw" \
openclaw:latest
OPENCLAW_DOCKER_APT_PACKAGES
在容器启动时自动安装额外的系统包：
docker run -e OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg,imagemagick,python3" \
openclaw:latest
安全加固建议
- 使用非 root 用户运行：OpenClaw 容器默认使用 uid 1000 运行，避免以 root 权限执行
- 限制网络访问：通过 Docker 网络策略限制容器的出站连接
- 只读文件系统：对不需要写入的目录使用只读挂载
- 资源限制：设置 CPU 和内存限制防止资源耗尽
docker run --memory=2g --cpus=2 \
--read-only \
--tmpfs /tmp \
openclaw:latest
常见问题排查
权限错误（uid 1000）
容器内默认以 uid 1000 的用户身份运行，如果挂载的宿主机目录权限不匹配，会出现 Permission denied 错误：
# 修复目录权限
sudo chown -R 1000:1000 /path/to/openclaw/data
镜像缺失或拉取失败
如果在国内网络环境下拉取镜像速度慢或失败，可以配置镜像加速器：
# 编辑 Docker 配置
sudo vi /etc/docker/daemon.json
# 添加加速器地址后重启 Docker
sudo systemctl restart docker
容器重建后数据丢失
确保使用 Docker Volume 或绑定挂载来持久化数据：
# 使用命名卷确保数据持久化
docker volume create openclaw_data
docker run -v openclaw_data:/data/openclaw openclaw:latest
容器无法启动
检查日志定位问题：
docker logs openclaw --tail 50
# 如果需要进入容器排查
docker exec -it openclaw /bin/bash
总结
Docker 容器化部署 OpenClaw 不仅提供了良好的环境隔离，还通过沙箱架构实现了灵活的安全控制。建议生产环境优先使用 Docker Compose 进行编排管理，并根据实际需求配置合适的工作区访问级别和安全策略。