OpenClaw 沙箱隔离完全指南：把 Agent 关进笼子里

为什么要沙箱隔离

OpenClaw 可以把 Agent 的工具执行放在沙箱后端里运行，从而缩小爆炸半径（blast radius）。

这是可选功能，通过配置控制（agents.defaults.sandbox 或 agents.list[].sandbox）。如果不开启沙箱，工具就在主机上直接运行。

这不是一个完美的安全边界，但当模型做出错误操作时，它能实质性限制文件系统和进程访问。

核心理念：把 Agent 的执行环境关进笼子里，即使出问题也不会影响主机。

什么会被沙箱化

会沙箱化的：

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

不会沙箱化的：

Gateway 进程本身
明确允许在主机运行的工具（如 tools.elevated）
- ⚠️ elevated exec 会在主机上运行，绕过沙箱！

三种模式：什么时候沙箱

agents.defaults.sandbox.mode 控制何时使用沙箱：

模式	说明
`"off"`	不沙箱，所有工具在主机执行
`"non-main"`	仅非 main 会话沙箱（默认，适合普通聊天在主机）
`"all"`	每个会话都在沙箱中运行

注意："non-main" 基于 session.mainKey（默认 "main"）判断，不是 agent id。群组/频道会话用自己的 key，所以算 non-main，会被沙箱化。

三种后端：在哪里沙箱

agents.defaults.sandbox.backend 控制使用哪种运行时提供沙箱：

	Docker	SSH	OpenShell
运行位置	本地容器	任意 SSH 可访问主机	OpenShell 托管沙箱
配置难度	中等	高	低（托管）
工作区模式	Bind-mount 或 Copy	远程规范（seed 一次）	mirror 或 remote
网络控制	docker.network	取决于远程主机	取决于 OpenShell
浏览器沙箱	支持	不支持	暂不支持
适用场景	本地开发，完全隔离	卸载到远程机器	托管远程沙箱+可选双向同步

Docker 后端详解

默认后端。需先构建镜像：

scripts/sandbox-setup.sh

Docker 沙箱默认使用专用 Docker 网络（openclaw-sandbox-browser），而不是全局 bridge 网络。可以通过 agents.defaults.sandbox.browser.network 配置。

SSH 后端详解

通过 SSH 在远程机器上沙箱化 exec、文件工具和媒体读取：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          identityFile: "~/.ssh/id_ed25519",
        },
      },
    },
  },
}

工作原理：

OpenClao 在 sandbox.ssh.workspaceRoot 下创建 per-scope 远程根目录
首次使用后，OpenClaw 从本地 workspace seed 一次到远程
之后 exec、read、write、edit、apply_patch、媒体读取直接在远程 workspace 上通过 SSH 执行
OpenClaw 不会自动将远程更改同步回本地 workspace

OpenShell 后端

使用 OpenShell 托管的远程环境进行沙箱化工具执行，适合不想自己管理基础设施的场景。

作用域：多少容器

agents.defaults.sandbox.scope 控制创建多少个容器：

Scope	说明
`"session"`（默认）	每个会话一个容器
`"agent"`	每个 Agent 一个容器
`"shared"`	所有沙箱会话共享一个容器

浏览器沙箱配置

沙箱浏览器有以下高级选项：

autoStart：浏览器工具需要时自动启动（确保 CDP 可达）
autoStartTimeoutMs：自动启动超时
network：Docker 网络配置（默认无）
cdpSourceRange：限制容器边界 CDP 入口的 CIDR 允许列表
allowHostControl：允许沙箱会话显式定向主机浏览器
allowedControlUrls、allowedControlHosts、allowedControlPorts：自定义目标 URL/主机/端口的允许列表

noVNC 访问默认有密码保护。OpenClaw 发出一个短生命期 token URL，服务本地引导页面并将密码通过 URL fragment（不在 query/header 日志中）打开 noVNC。

沙箱的局限性

这不是完美的安全边界。沙箱能：

✅ 实质性限制文件系统访问
✅ 限制进程执行权限
✅ 隔离网络访问（Docker 网络模式）
❌ 无法防止提示词注入（prompt injection）
❌ 无法防止社会工程攻击
❌ 无法完全阻止通过 tools.elevated 绕过

正确的安全策略 = 沙箱 + 最小权限原则 + 用户意识，而不是单靠沙箱。

快速配置建议

开发环境（推荐 non-main）：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        backend: "docker",
      },
    },
  },
}

生产环境（高风险工具全沙箱）：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "session",
        backend: "docker",
      },
    },
  },
}

本指南编译自 OpenClaw 沙箱文档