ClawCN - 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 配置。
    • agents.defaults.sandbox.browser.allowHostControl 允许沙箱会话显式地定向到宿主机浏览器。
    • 可选的白名单限制 target: "custom":allowedControlUrls、allowedControlHosts、allowedControlPorts。

不被沙箱化的:

  • Gateway 进程本身。
  • 任何明确允许在宿主机上运行的工具(例如 tools.elevated)。
    • 提权执行在宿主机上运行并绕过沙箱。
    • 如果沙箱关闭,tools.elevated 不会改变执行方式(已在宿主机上)。参见 提权模式。

模式 ​

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

  • "off":无沙箱。
  • "non-main":仅沙箱非主会话(如果您希望正常聊天在宿主机上进行,这是默认设置)。
  • "all":每个会话都在沙箱中运行。 注意:"non-main" 基于 session.mainKey(默认 "main"),而非代理 id。 群组/频道会话使用自己的键,因此它们算作非主会话并将被沙箱化。

作用域 ​

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

  • "session"(默认):每个会话一个容器。
  • "agent":每个代理一个容器。
  • "shared":所有沙箱会话共享一个容器。

工作区访问 ​

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到什么:

  • "none"(默认):工具看到 ~/.openclaw/sandboxes 下的沙箱工作区。
  • "ro":在 /agent 以只读方式挂载代理工作区(禁用 write/edit/apply_patch)。
  • "rw":在 /workspace 以读写方式挂载代理工作区。

入站媒体会被复制到活动沙箱工作区(media/inbound/*)。 技能注意事项:read 工具以沙箱为根。使用 workspaceAccess: "none" 时, OpenClaw 会将符合条件的技能镜像到沙箱工作区(.../skills)以便读取。使用 "rw" 时,工作区技能可从 /workspace/skills 读取。

自定义绑定挂载 ​

agents.defaults.sandbox.docker.binds 将额外的宿主机目录挂载到容器中。 格式:host:container:mode(例如,"/home/user/source:/source:rw")。

全局和每个代理的绑定会合并(而非替换)。在 scope: "shared" 下,每个代理的绑定会被忽略。

示例(只读源 + docker socket):

json5
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

安全注意事项:

  • 绑定会绕过沙箱文件系统:它们以您设置的任何模式(:ro 或 :rw)暴露宿主机路径。
  • 敏感挂载(例如,docker.sock、密钥、SSH 密钥)应该设为 :ro,除非绝对必要。
  • 如果只需要对工作区的读访问,可以结合 workspaceAccess: "ro";绑定模式保持独立。
  • 参见 沙箱 vs 工具策略 vs 提权 了解绑定如何与工具策略和提权执行交互。

镜像 + 设置 ​

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

构建一次:

bash
scripts/sandbox-setup.sh

注意:默认镜像不包含 Node。如果技能需要 Node(或其他运行时),可以烘焙自定义镜像或通过 sandbox.docker.setupCommand 安装(需要网络出口 + 可写根目录 + root 用户)。

沙箱浏览器镜像:

bash
scripts/sandbox-browser-setup.sh

默认情况下,沙箱容器以无网络运行。 使用 agents.defaults.sandbox.docker.network 覆盖。

Docker 安装和容器化的 gateway 位于此处: Docker

setupCommand(一次性容器设置) ​

setupCommand 在沙箱容器创建后运行一次(不是每次运行都执行)。 它通过 sh -lc 在容器内执行。

路径:

  • 全局:agents.defaults.sandbox.docker.setupCommand
  • 每个代理:agents.list[].sandbox.docker.setupCommand

常见陷阱:

  • 默认 docker.network 是 "none"(无出口),因此包安装会失败。
  • readOnlyRoot: true 阻止写入;设置 readOnlyRoot: false 或烘焙自定义镜像。
  • user 必须是 root 才能安装包(省略 user 或设置 user: "0:0")。
  • 沙箱执行不继承宿主机 process.env。使用 agents.defaults.sandbox.docker.env(或自定义镜像)来提供技能 API 密钥。

工具策略 + 逃逸舱口 ​

工具允许/拒绝策略仍然在沙箱规则之前应用。如果工具在全局或每个代理级别被拒绝,沙箱化不会使其恢复。

tools.elevated 是一个显式的逃逸舱口,在宿主机上运行 exec。 /exec 指令仅适用于授权发送者并在每个会话中持久化;要硬禁用 exec,使用工具策略拒绝(参见 沙箱 vs 工具策略 vs 提权)。

调试:

  • 使用 openclaw sandbox explain 检查有效的沙箱模式、工具策略和修复配置键。
  • 参见 沙箱 vs 工具策略 vs 提权 了解"为什么被阻止?"的思维模型。 保持锁定状态。

多代理覆盖 ​

每个代理可以覆盖沙箱 + 工具: agents.list[].sandbox 和 agents.list[].tools(加上用于沙箱工具策略的 agents.list[].tools.sandbox.tools)。 参见 多代理沙箱和工具 了解优先级。

最小启用示例 ​

json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

相关文档 ​