​

沙箱机制

​

什么会被沙箱化

• 工具执行（exec、read、write、edit、apply_patch、process 等）。
• 可选的沙箱浏览器（agents.defaults.sandbox.browser）。
  • 默认情况下，当浏览器工具需要时，沙箱浏览器会自动启动（确保 CDP 可访问）。 可通过 agents.defaults.sandbox.browser.autoStart 和 agents.defaults.sandbox.browser.autoStartTimeoutMs 配置。
  • 默认情况下，沙箱浏览器容器会使用专用 Docker 网络（openclaw-sandbox-browser），而非全局 bridge 网络。 可通过 agents.defaults.sandbox.browser.network 配置。
  • 可选的 agents.defaults.sandbox.browser.cdpSourceRange 使用 CIDR 白名单限制容器端的 CDP 入站流量（例如 172.21.0.1/32）。
  • noVNC 观察者访问默认启用密码保护；OpenClaw 会发出一个短时效令牌 URL，提供本地引导页面，并通过 URL 片段密码（非查询/头部日志）打开 noVNC。
  • agents.defaults.sandbox.browser.allowHostControl 允许沙箱会话显式控制宿主机浏览器。
  • 可选白名单控制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。

• 网关进程本身。
• 任何明确允许在宿主机上运行的工具（例如 tools.elevated）。
  • Elevated 执行在宿主机上，绕过沙箱机制。
  • 如果关闭沙箱，tools.elevated 不改变执行位置（已在宿主机上）。详情见 Elevated 模式。

​

模式

• "off"：不启用沙箱。
• "non-main"：仅对非主会话启用沙箱（如果您希望普通聊天运行在宿主机上，则默认选项）。
• "all"：所有会话均运行于沙箱中。 注："non-main"基于 session.mainKey（默认 "main"）判断，而非 agent id。 群组/频道会话有自己的键，因此视为非主，会被沙箱限制。

​

范围

• "session"（默认）：每个会话一个容器。
• "agent"：每个 agent 一个容器。
• "shared"：所有沙箱会话共用一个容器。

​

工作区访问权限

• "none"（默认）：工具只能看到位于 ~/.openclaw/sandboxes 下的沙箱工作区。
• "ro"：以只读模式挂载 agent 工作区到 /agent（禁用 write/edit/apply_patch）。
• "rw"：以读写模式挂载 agent 工作区到 /workspace。

​

自定义绑定挂载

• 设置后（包括设置为空数组 []），会替代浏览器容器的 agents.defaults.sandbox.docker.binds。
• 未设置时，浏览器容器回退使用 agents.defaults.sandbox.docker.binds（兼容旧配置）。

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

• 绑定绕过沙箱文件系统限制：它们会暴露宿主机路径及您设置的访问模式（:ro 或 :rw）。
• OpenClaw 会阻止危险的绑定来源（例如：docker.sock、/etc、/proc、/sys、/dev，及任何父挂载暴露这些路径的绑定）。
• 敏感挂载（秘密、SSH 密钥、服务凭证）应保持 :ro，除非绝对必要。
• 如果只需工作区读取权限，请结合使用 workspaceAccess: "ro"；绑定模式独立控制。
• 详见 沙箱 vs 工具策略 vs Elevated 执行，了解绑定如何与工具策略和 Elevated 执行交互。

​

镜像与设置

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<由 OPENCLAW_BROWSER_CDP_PORT 派生>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• 启用 noSandbox 时，额外加上 --no-sandbox 和 --disable-setuid-sandbox。
• 三个图形防护参数（--disable-3d-apis、--disable-software-rasterizer、--disable-gpu）是可选的，适用于无 GPU 支持的容器。 如果您的工作负载需要 WebGL 或其他 3D/浏览器功能，请设置环境变量 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0。
• 默认启用 --disable-extensions，可以通过 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 禁用，此时适合依赖扩展的场景。
• --renderer-process-limit=2 由环境变量 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，设置为 0 时为 Chromium 默认值。

• 禁止使用 network: "host"。
• 默认禁止使用 network: "container:<id>"（存在命名空间加入绕过风险）。
• 破防措施：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

​

setupCommand（容器首次初始化命令）

• 全局：agents.defaults.sandbox.docker.setupCommand
• 每个 agent：agents.list[].sandbox.docker.setupCommand

• 默认 docker.network 是 "none"（无出网），导致包安装失败。
• docker.network: "container:<id>" 需要设置 dangerouslyAllowContainerNamespaceJoin: true，且仅作破防使用。
• readOnlyRoot: true 阻止写入；应设置 readOnlyRoot: false 或自行构建镜像。
• 运行用户必须是 root，才能安装软件包（省略 user 或设置为 user: "0:0"）。
• 沙箱执行不会继承宿主机 process.env，请通过 agents.defaults.sandbox.docker.env 配置环境变量（或自定义镜像）来传递技能 API Key。

​

工具策略及逃生通道

• 使用 openclaw sandbox explain 查看生效的沙箱模式、工具策略和修复建议配置键。
• 参见 沙箱 vs 工具策略 vs Elevated 理解“为何被阻止”的思维模型。 请保持策略严格。

​

多 agent 覆盖设置

​

最小启用示例

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

​

相关文档

• 沙箱配置
• 多 Agent 沙箱与工具
• 安全