OpenClaw 沙盒指南

概述

OpenClaw 可以在 Docker 容器内运行工具以减少爆炸半径。这是可选的，通过配置控制（agents.defaults.sandbox 或 agents.list[].sandbox）。如果沙盒关闭，工具在主机上运行。

Gateway 留在主机上；启用时工具执行在隔离的沙盒中运行。

这不是完美的安全边界，但当模型做傻事时，它实质性地限制了文件系统和进程访问。

什么被沙盒化

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

默认情况下，当浏览器工具需要时，沙盒浏览器自动启动（确保 CDP 可访问）。

配置通过 agents.defaults.sandbox.browser.autoStart 和 agents.defaults.sandbox.browser.autoStartTimeoutMs。

未被沙盒化：

• Gateway 进程本身
• 任何显式允许在主机上运行的工具（例如 tools.elevated）

提升的 exec 在主机上运行并绕过沙盒。

模式

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

注意: "non-main" 基于 session.mainKey（默认 “main”），不是代理 id。群组/频道会话使用自己的键，因此它们被视为非主并被沙盒化。

范围

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

工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙盒可以看到什么：

入站媒体被复制到活动沙盒工作区（media/inbound/*）。

自定义绑定挂载

agents.defaults.sandbox.docker.binds 将额外的宿主机目录挂载到容器中。

格式: host:container:mode（例如 "/home/user/source:/source:rw"）

示例：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "binds": [
            "/home/user/source:/source:ro",
            "/var/run/docker.sock:/var/run/docker.sock"
          ]
        }
      }
    }
  }
}

启用沙盒

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "user": "1000:1000"
        }
      }
    }
  }
}

构建默认沙盒镜像

scripts/sandbox-setup.sh

这使用 Dockerfile.sandbox 构建 openclaw-sandbox:bookworm-slim。

注意：默认镜像不包括 Node。如果技能需要 Node（或其他运行时），要么烘焙自定义镜像，要么通过 sandbox.docker.setupCommand 安装（需要网络出口 + 可写根 + root 用户）。

工具策略 + 逃生口

工具允许/拒绝策略在沙盒规则之前仍然适用。如果工具被全局或每个代理拒绝，沙盒不会恢复它。

tools.elevated 是一个显式逃生口，在主机上运行 exec。

多代理覆盖

每个代理可以覆盖沙盒 + 工具：

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "public",
        "sandbox": {
          "mode": "all",
          "scope": "agent",
          "workspaceAccess": "none"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["write", "edit", "exec"]
        }
      }
    ]
  }
}

来源: https://docs.openclaw.ai/gateway/sandboxing