沙盒

OpenClaw 可以?**Docker 容器内运行工?以减少爆炸半径。这?可选的，由配置控制（agents.defaults.sandbox ?agents.list[].sandbox）。如果沙盒关闭，工具在主机上运行。网关留在主机上；工具执行在启用时在隔离的沙盒中运行?

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

什么被沙盒?

工具执行（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 白名单（例如 172.21.0.1/32）限制容器边?CDP 入口?
- noVNC 观察器访问默认受密码保护；OpenClaw 发出一个短期令?URL，解析到观察器会话?
- agents.defaults.sandbox.browser.allowHostControl 让沙盒化会话明确针对主机浏览器?
- 可选白名单控制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts?

未沙盒化?

网关进程本身?
任何明确允许在主机上运行的工具（例如 tools.elevated）?
- *提权 exec 在主机上运行并绕过沙盒化?
- 如果沙盒关闭，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" 下，忽略每代理绑定?

agents.defaults.sandbox.browser.binds 仅将额外主机目录挂载?*沙盒浏览?*容器?

设置时（包括 []），它替换浏览器容器?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 提权了解绑定如何与工具策略和提权 exec 交互?

镜像 + 设置

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

构建一次：

scripts/sandbox-setup.sh

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

沙盒浏览器镜像：

scripts/sandbox-browser-setup.sh

默认情况下，沙盒容器**无网?*运行? 通过 agents.defaults.sandbox.docker.network 覆盖?

安全默认?

network: "host" 被阻止?
network: "container:<id>" 默认被阻止（命名空间连接绕过风险）?
打破玻璃覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true?

Docker 安装和容器化网关位于? Docker

setupCommand（一次性容器设置）

setupCommand 在沙盒容器创建后运行一次（不是每次运行）? 它通过 sh -lc 在容器内执行?

路径?

全局：agents.defaults.sandbox.docker.setupCommand
每代理：agents.list[].sandbox.docker.setupCommand

常见陷阱?

默认 docker.network ?"none"（无出口），因此包安装会失败?
docker.network: "container:<id>" 需?dangerouslyAllowContainerNamespaceJoin: true 且仅是打破玻璃?
readOnlyRoot: true 阻止写入；设?readOnlyRoot: false 或烘焙自定义镜像?
包安装必须是根用户（省略 user 或设?user: "0:0"）?
沙盒 exec **不继?*主机 process.env。使? agents.defaults.sandbox.docker.env（或自定义镜像）用于技?API 密钥?

工具策略 + 逃生?

工具 allow/deny 策略在沙盒规则之前仍然适用。如果工具被全局或按代理拒绝? 沙盒化不会带回它?

tools.elevated 是一个明确在主机上运?exec 的逃生舱? /exec 指令仅适用于授权发送者并按会话持久化；要硬性禁? exec，使用工具策略拒绝（请参阅沙盒 vs 工具策略 vs 提权）?

调试?

使用 openclaw sandbox explain 检查有效的沙盒模式、工具策略和修复配置密钥?
请参阅沙盒 vs 工具策略 vs 提权获取”为什么被阻止?心智模型? 保持锁定?

多代理覆?

每个代理可以覆盖沙盒 + 工具：agents.list[].sandbox ?agents.list[].tools（加?agents.list[].tools.sandbox.tools 用于沙盒工具策略）? 请参阅多代理沙盒和工具了解优先级?

最小启用示?

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

沙盒