OpenClaw 支持在 Docker 容器中运行工具，限制 AI Agent 对主机系统的访问范围。这不是完美的安全边界，但能大幅降低 AI「做蠢事」时的爆炸半径。
沙箱保护范围
沙箱化的内容：
- 工具执行（exec、read、write、edit 等）
- 可选的沙箱浏览器（独立 Docker 容器）
不受沙箱保护：
- Gateway 进程本身
- 明确标记为 elevated 的工具（在主机上运行，绕过沙箱）
三种沙箱模式
通过 agents.defaults.sandbox.mode 控制：
| 模式 | 说明 | 适用场景 |
|---|---|---|
off | 不使用沙箱（默认） | 信任环境、开发调试 |
non-main | 只隔离非主会话 | 群组用沙箱，私信不隔离 |
all | 所有会话都在沙箱 | 高安全要求场景 |
注意：non-main 基于 session.mainKey 判断，不是 Agent ID。群组/频道会话有自己的 key，算作 non-main，会被沙箱化。
三种容器粒度
通过 agents.defaults.sandbox.scope 控制：
| 粒度 | 说明 |
|---|---|
session（默认） | 每个会话一个容器 |
agent | 每个 Agent 一个容器 |
shared | 所有沙箱会话共享一个容器 |
工作区访问权限
通过 agents.defaults.sandbox.workspaceAccess 控制：
| 模式 | 说明 |
|---|---|
none（默认） | 工具只看到沙箱工作区目录 |
ro | Agent 工作区只读挂载到 /agent |
rw | Agent 工作区读写挂载到 /workspace |
快速启用
第 1 步：构建沙箱镜像
bash
scripts/sandbox-setup.sh默认镜像 openclaw-sandbox:bookworm-slim 不含 Node。需要 Node 的技能可通过 setupCommand 安装或使用自定义镜像。
第 2 步：最小化配置
json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session",
"workspaceAccess": "none"
}
}
}
}第 3 步：验证配置
bash
openclaw sandbox explain输出有效的沙箱模式、工具策略和修复建议。
自定义挂载（Bind Mounts）
json
{
"agents": {
"defaults": {
"sandbox": {
"docker": {
"binds": [
"/home/user/source:/source:ro",
"/var/data/myapp:/data:ro"
]
}
}
},
"list": [
{
"id": "build",
"sandbox": {
"docker": {
"binds": ["/mnt/cache:/cache:rw"]
}
}
}
]
}
}全局和 per-Agent 的 binds 会合并（不覆盖）。
安全限制：
- OpenClaw 阻止危险挂载源（
docker.sock、/etc、/proc、/sys、/dev） - 敏感目录使用
:ro network: host被阻止
网络配置
默认 network: none（无网络出口）。需联网安装依赖时临时设为 bridge：
json
{
"agents": {
"defaults": {
"sandbox": {
"docker": { "network": "bridge" }
}
}
}
}setupCommand：一次性容器初始化
json
{
"agents": {
"defaults": {
"sandbox": {
"docker": {
"network": "bridge",
"setupCommand": "apt-get update && apt-get install -y nodejs"
}
}
}
}
}注意：默认 network: none 时包管理器会失败，先设为 bridge 再安装。setupCommand 只在容器创建后执行一次。
沙箱浏览器
独立的沙箱浏览器容器：
bash
scripts/sandbox-browser-setup.shjson
{
"agents": {
"defaults": {
"sandbox": {
"browser": {
"autoStart": true,
"network": "openclaw-sandbox-browser"
}
}
}
}
}per-Agent 沙箱覆盖
json
{
"agents": {
"defaults": { "sandbox": { "mode": "non-main" } },
"list": [
{ "id": "safe", "sandbox": { "mode": "all", "workspaceAccess": "ro" } },
{ "id": "local", "sandbox": { "mode": "off" } }
]
}
}Elevated 工具：沙箱逃生通道
某些工具需要直接在主机上运行：
json
{
"tools": {
"elevated": { "exec": true }
}
}elevated exec 在主机上运行，完全绕过沙箱。只对授权发件人有效，且只在会话生命周期内持续。要硬性禁用，使用工具策略 deny。
调试命令
bash
openclaw sandbox explain # 查看有效配置和问题诊断原文：Sandboxing - OpenClaw | 来源：OpenClaw 官方文档