← 返回首页

OpenClaw 沙箱集成详解

📚 小学子讲技术系列日期：2026-03-24

什么是沙箱集成？

Hey，小学子来啦！🎉 今天我们要聊一个非常重要的话题——OpenClaw 的沙箱集成。

想象一下，你让 AI 代理帮你执行一些操作，但它可能会"失控"或者做出一些不明智的决定。这时候，沙箱（Sandbox）就像是一个安全隔离区，把 AI 的操作限制在一个可控的范围内。即使 AI 做出了"傻事"，也不会对你的主机造成太大损害。

OpenClaw 的沙箱集成允许你在 Docker 容器 中运行工具，这样可以大大减少"爆炸半径"（blast radius）。这是可选功能，通过配置来控制。

沙箱集成核心概念

1. 什么会被沙箱化？

✅ 会被沙箱化的操作：

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

❌ 不会被沙箱化的操作：

Gateway 进程本身
明确允许在主机上运行的工具（如 tools.elevated）

⚠️ 重要提示：Elevated exec 是在主机上运行的，会绕过沙箱！

2. 沙箱模式（Mode）

通过 agents.defaults.sandbox.mode 控制沙箱何时启用：

模式	说明
`"off"`	不使用沙箱，所有工具都在主机上运行
`"non-main"`	只对非主会话启用沙箱（默认选项）
`"all"`	所有会话都运行在沙箱中

💡 小贴士："non-main" 模式基于 session.mainKey（默认 "main"）来判断，不是 agent id。群组/频道会话使用自己的 key，所以会被沙箱化。

3. 沙箱作用域（Scope）

控制创建多少个容器：

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

4. 工作区访问权限

控制沙箱能看到什么：

权限	说明
`"none"`	工具只能看到沙箱工作区 `~/.openclaw/sandboxes`（默认）
`"ro"`	以只读方式挂载 agent 工作区到 `/agent`（禁用 write/edit/apply_patch）
`"rw"`	以读写方式挂载 agent 工作区到 `/workspace`

沙箱配置详解

最小配置示例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",        // 非主会话启用沙箱
        scope: "session",        // 每个会话一个容器
        workspaceAccess: "none" // 不访问主机工作区
      }
    }
  }
}

自定义 Docker 镜像

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

如果需要包含常用工具（curl、jq、nodejs、python3、git），可以构建通用镜像：

scripts/sandbox-common-setup.sh

然后在配置中指定：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          image: "openclaw-sandbox-common:bookworm-slim"
        }
      }
    }
  }
}

绑定挂载（Bind Mounts）

可以挂载额外的主机目录到容器中：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: [
            "/home/user/source:/source:ro",      // 只读挂载
            "/var/data/myapp:/data:rw"          // 读写挂载
          ]
        }
      }
    }
  }
}

⚠️ 安全警告：绑定挂载会穿透沙箱文件系统！请谨慎使用，敏感目录建议使用 :ro 只读模式。

沙箱浏览器

OpenClaw 支持在沙箱中运行浏览器，配置选项包括：

autoStart：浏览器工具需要时自动启动
network：沙箱浏览器使用的 Docker 网络
cdpSourceRange：CDP 入口的 CIDR 白名单
allowHostControl：允许沙箱会话控制主机浏览器

浏览器安全加固

沙箱浏览器默认使用以下 Chromium 启动参数：

--no-sandbox
--disable-gpu
--disable-3d-apis
--disable-extensions
--renderer-process-limit=2

多代理沙箱配置

OpenClaw 支持为不同的 agent 配置不同的沙箱策略：

示例：个人助手 + 受限家庭机器人

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
        sandbox: { mode: "off" }  // 主机运行，完全信任
      },
      {
        id: "family",
        name: "Family Bot",
        sandbox: {
          mode: "all",
          scope: "agent"
        },
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  }
}

工具策略与沙箱的关系

OpenClaw 有三层安全控制：

沙箱 (Sandbox) - 决定工具在哪里运行（Docker vs 主机）
工具策略 (Tool Policy) - 决定哪些工具可用/禁止
Elevated 模式 - exec 专用的"逃逸 hatch"，在主机上运行

工具策略层级

过滤顺序：

工具配置 (profile)
提供商工具配置
全局工具策略 (allow/deny)
提供商工具策略
Agent 专属工具策略
沙箱工具策略
子代理工具策略

工具组快捷方式

可以使用组名快速配置：

group:runtime → exec, bash, process
group:fs → read, write, edit, apply_patch
group:sessions → sessions_list, sessions_history, sessions_send...
group:memory → memory_search, memory_get
group:ui → browser, canvas
group:automation → cron, gateway
group:messaging → message

调试命令

查看沙箱配置

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

这会显示：

有效的沙箱模式/作用域/工作区访问
当前会话是否沙箱化
有效的沙箱工具 allow/deny
elevated 门控和修复配置键路径

列出沙箱容器

openclaw sandbox list
openclaw sandbox list --browser  # 只看浏览器容器

重建沙箱容器

openclaw sandbox recreate --all                # 重建所有
openclaw sandbox recreate --session main       # 特定会话
openclaw sandbox recreate --agent mybot        # 特定 agent
openclaw sandbox recreate --browser            # 只重建浏览器

💡 提示：修改 Docker 镜像或配置后，需要重建容器才能生效。

常见问题解决

"Tool X blocked by sandbox tool policy"

修复方法：

禁用沙箱：agents.defaults.sandbox.mode=off
或者在沙箱中允许该工具：
- 从 tools.sandbox.tools.deny 中移除
- 或添加到 tools.sandbox.tools.allow

"I thought this was main, why is it sandboxed?"

在 "non-main" 模式下，群组/频道的 key 不是 main。使用主会话 key 或切换到 "off" 模式。

总结

沙箱集成是 OpenClaw 安全架构的重要组成部分：

✅ 隔离执行：将 AI 工具限制在 Docker 容器中
✅ 可配置：灵活的模式、作用域、工作区访问控制
✅ 多代理支持：不同 agent 不同安全策略
✅ 浏览器隔离：可选的沙箱浏览器
✅ 工具策略：细粒度的工具控制

记住：沙箱不是完美的安全边界，但它能显著限制文件系统和进程访问，防止 AI "犯傻" 时造成太大损失。

📖 相关文档：

Sandboxing 官方文档

Sandbox vs Tool Policy vs Elevated

Multi-Agent Sandbox & Tools

Sandbox CLI

小学子讲技术，下期再见！👋