OpenClaw Docker 部署指南：Gateway 网关容器化与智能体沙箱详解
在部署 OpenClaw 时，Docker 并不是必须的，但在某些场景下却非常实用。例如你希望获得隔离环境、快速测试流程，或者在没有完整开发环境的服务器上运行 OpenClaw。
家兴网络将介绍 如何使用 Docker 运行 OpenClaw Gateway 网关，以及如何启用智能体沙箱隔离环境。
一、Docker 是否适合你？
在开始之前，可以先判断自己是否需要 Docker 版本。
适合使用 Docker 的情况
希望获得一个隔离、可随时删除的 Gateway 环境
在 VPS 或云服务器上部署 OpenClaw
想测试完整的容器化运行流程
不太适合的情况
在本地开发机器上运行
希望获得最快的开发迭代速度
如果只是本地开发，通常直接使用官方安装脚本会更简单。
需要注意的是：
OpenClaw 的 智能体沙箱隔离也会使用 Docker，但即使使用沙箱，也不一定需要把整个 Gateway 放进 Docker 里。
二、运行 Docker 版 OpenClaw 的前提条件
部署前需要准备以下环境：
Docker Desktop 或 Docker Engine
Docker Compose v2
足够的磁盘空间（用于镜像和日志）
三、Docker 方式部署 OpenClaw（推荐方法）
最简单的方式是使用官方提供的自动化脚本。
在项目根目录执行：
./docker-setup.sh
该脚本会自动完成以下操作：
构建 OpenClaw Gateway 镜像
运行首次安装向导
输出 AI 提供商配置提示
使用 Docker Compose 启动 Gateway
自动生成 Gateway Token 并写入
.env
完成后，在浏览器打开：
http://127.0.0.1:18789
然后在 Settings → Token 中粘贴生成的 Token 即可连接控制界面。
如果需要再次获取仪表板地址，可以运行：
docker compose run --rm openclaw-cli dashboard --no-open
默认情况下，OpenClaw 会在主机生成以下目录：
~/.openclaw/ ~/.openclaw/workspace
四、手动 Docker 部署流程
如果不使用自动脚本，也可以手动部署。
1 构建镜像
docker build -t openclaw:local -f Dockerfile .
2 运行初始化向导
docker compose run --rm openclaw-cli onboard
3 启动 Gateway
docker compose up -d openclaw-gateway
注意：
必须在 项目仓库根目录执行这些命令。
五、解决 Token 配对问题
如果 Dashboard 出现：
unauthorized
或者：
disconnected (1008): pairing required
可以重新生成设备授权：
docker compose run --rm openclaw-cli dashboard --no-open docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve <requestId>
六、额外挂载主机目录（可选）
如果需要将主机目录挂载到容器，可以使用环境变量：
OPENCLAW_EXTRA_MOUNTS
示例：
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw" ./docker-setup.sh
注意事项：
Mac 和 Windows 必须在 Docker Desktop 中共享路径
修改后需要重新运行
docker-setup.sh
七、持久化容器 Home 目录
如果希望 /home/node 在容器删除后仍然保留，可以设置 Docker 命名卷：
export OPENCLAW_HOME_VOLUME="openclaw_home" ./docker-setup.sh
该方式可以保留：
浏览器缓存
工具下载文件
用户环境配置
删除卷的方法：
docker volume rm openclaw_home
八、安装额外系统依赖
如果需要在镜像中安装系统包，例如：
ffmpeg
build-essential
git
可以在构建前指定：
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential" ./docker-setup.sh
这些依赖会在镜像构建时安装，即使容器删除也会保留。
九、权限问题解决（EACCES）
Docker 镜像默认使用 **node 用户（UID 1000）**运行。
如果遇到权限错误，可以在 Linux 主机执行：
sudo chown -R 1000:1000 /path/to/openclaw-config sudo chown -R 1000:1000 /path/to/openclaw-workspace
这样可以避免容器访问文件时出现权限问题。
十、OpenClaw 智能体沙箱隔离
OpenClaw 还支持 智能体工具运行隔离（Sandbox）。
启用后：
Gateway 仍在主机运行
工具执行在 Docker 容器内完成
隔离方式包括：
| 模式 | 说明 |
|---|---|
| session | 每个会话一个容器 |
| agent | 每个智能体一个容器 |
| shared | 所有会话共享容器 |
默认配置：
镜像：
openclaw-sandbox:bookworm-slim网络：默认关闭
root 文件系统：只读
CPU / 内存限制可配置
示例配置：
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "agent",
workspaceAccess: "none",
docker: {
image: "openclaw-sandbox:bookworm-slim",
network: "none",
memory: "1g",
cpus: 1
}
}
}
}十一、构建沙箱镜像
可以使用官方脚本快速构建：
scripts/sandbox-setup.sh
如果需要开发工具环境，可以构建通用镜像：
scripts/sandbox-common-setup.sh
该镜像包含常见开发语言工具，例如：
Node
Go
Rust
十二、沙箱浏览器环境
如果智能体需要浏览器能力，可以构建浏览器镜像：
scripts/sandbox-browser-setup.sh
该镜像包含：
Chromium
CDP 控制接口
可选 noVNC 远程桌面
配置示例：
agents: {
defaults: {
sandbox: {
browser: { enabled: true }
}
}
}十三、容器清理策略
OpenClaw 会自动清理沙箱容器。
默认规则：
| 参数 | 说明 |
|---|---|
| idleHours | 空闲多少小时删除 |
| maxAgeDays | 最大存活天数 |
默认设置：
24 小时未使用删除
最多保留 7 天
十四、安全注意事项
需要特别注意：
沙箱只隔离 工具执行
主机级工具默认被禁用，例如：
browser
camera
canvas
如果开启浏览器工具，隔离能力会下降，因为浏览器运行在主机上。
总结
使用 Docker 部署 OpenClaw 可以带来很多优势：
环境隔离
快速部署
可重复构建
适合服务器运行
而智能体沙箱则进一步提升了安全性，让工具执行更加可控。
对于开发者来说：
本地开发建议使用普通安装方式，而服务器部署和多智能体环境则更适合 Docker。
