1. 概述

OpenClaw Sandbox是基于Docker容器技术的工具执行隔离机制，通过在容器中运行 AI 工具来减少爆炸半径（blast radius）。本文结合Docker工作原理，深入分析 OpenClaw Sandbox的架构设计、隔离机制、执行流程和配置方式。

1.1 设计目标

OpenClaw Sandbox 的核心设计目标：

目标	说明
安全隔离	限制 AI 工具对主机文件系统、进程和网络的访问
最小权限	默认拒绝所有访问，显式配置允许
灵活配置	支持多种隔离级别和作用域
透明运行	对用户和 AI 模型透明，无需修改工具代码

1.2 适用范围

沙箱化的工具： - exec、read、write、edit、apply_patch、process 等 - 可选的沙箱化浏览器（agents.defaults.sandbox.browser）

不沙箱化的组件： - Gateway 进程本身 - 显式允许在主机运行的工具（如 tools.elevated）

2. Docker 容器隔离原理

2.1 Docker 核心隔离机制

Docker容器通过以下 Linux 内核特性实现隔离：

图-1 Docker 容器隔离机制

2.2 Namespaces 隔离

Namespace	隔离内容	OpenClaw 应用
PID	进程 ID	容器内进程独立编号
Mount	文件系统挂载点	独立文件系统视图
Network	网络设备	独立网络栈
UTS	主机名和域名	独立主机名
IPC	进程间通信	独立 IPC 资源
User	用户 ID	用户映射隔离

2.3 Cgroups 资源限制

{
  "memory": {
    "limit": "512MB",      // 内存上限
    "swap": "0"            // 禁用交换
  },
  "cpu": {
    "quota": "50000",      // CPU 时间配额
    "period": "100000"     // 周期（微秒）
  },
  "pids": {
    "max": 100             // 最大进程数
  }
}

OpenClaw Sandbox 架构

3.1 整体架构

图-2 OpenClaw Sandbox 整体架构

3.2 组件层次

层次	组件	功能
L1	Gateway	沙箱策略决策、容器生命周期管理
L2	Docker Daemon	容器创建、启动、停止
L3	容器运行时	工具执行环境
L4	绑定挂载	受控的主机资源访问

4. 沙箱配置模式

4.1 沙箱模式（Mode）

配置位置：agents.defaults.sandbox.mode

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main"  // off | non-main | all
      }
    }
  }
}

模式对比：

模式	说明	适用场景
off	不启用沙箱	开发环境、完全信任
non-main	仅非主会话沙箱化	推荐：DM 在主机，群组在沙箱
all	所有会话沙箱化	高安全场景、多用户环境

4.2 沙箱作用域（Scope）

配置位置：agents.defaults.sandbox.scope

图-3 沙箱作用域对比

作用域对比：

作用域	容器数量	隔离级别	资源消耗
session	每会话 1 个	最高	最高
agent	每代理 1 个	中等	中等
shared	所有共享 1 个	最低	最低

4.3 工作区访问（Workspace Access）

配置位置：agents.defaults.sandbox.workspaceAccess

{
  agents: {
    defaults: {
      sandbox: {
        workspaceAccess: "none"  // none | ro | rw
      }
    }
  }
}

访问级别：

级别	挂载路径	权限	影响
none	~/.openclaw/sandboxes	隔离	无法访问主机工作区
ro	/agent	只读	可读取，不可写入
rw	/workspace	读写	完全访问工作区

5. 容器镜像与网络

5.1 沙箱镜像

默认镜像：openclaw-sandbox:bookworm-slim

镜像构建：

# 基础镜像
./scripts/sandbox-setup.sh

# 常用工具镜像（curl, jq, nodejs, python3, git）
./scripts/sandbox-common-setup.sh

# 浏览器镜像
./scripts/sandbox-browser-setup.sh

镜像层次：

openclaw-sandbox:bookworm-slim
├── Debian Bookworm Slim (基础)
├── 基本工具 (bash, coreutils)
└── OpenClaw 运行时配置

openclaw-sandbox-common:bookworm-slim
├── openclaw-sandbox:bookworm-slim
├── curl
├── jq
├── nodejs
├── python3
└── git

5.2 网络隔离

默认配置：network: "none"（无网络）

网络选项：

网络模式	说明	安全级别
none	无网络访问	最高
bridge	Docker 桥接网络	高
openclaw-sandbox-browser	专用浏览器网络	高
host	主机网络（被阻止）	低
container:<id>	命名空间加入（需 break-glass）	低

安全限制：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          network: "none",  // 默认无网络
          dangerouslyAllowContainerNamespaceJoin: false  // 禁止命名空间加入
        }
      }
    }
  }
}