沙箱 – OpenClaw - Open Source AI Coding Assistant

沙箱

Moltbot 可以在 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 进行配置。
- 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"（默认）：工具在 ~/.moltbot/sandboxes 下看到一个沙箱工作空间。
"ro"：在 /agent 处只读挂载代理工作空间（禁用 write/edit/apply_patch）。
"rw"：在 /workspace 处读写挂载代理工作空间。

入站媒体被复制到活动沙箱工作空间（media/inbound/*）。技能说明：read 工具是沙箱根目录的。使用 workspaceAccess: "none"， Moltbot 将符合条件的技能镜像到沙箱工作空间（.../skills），以便它们可以被读取。使用 "rw"，工作空间技能可从 /workspace/skills 读取。

自定义绑定挂载

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

全局和每代理绑定是 合并的（不是替换）。在 scope: "shared" 下，每代理绑定被忽略。

示例（只读源 + docker 套接字）：

{
  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"；绑定模式保持独立。
有关绑定如何与工具策略和提升 exec 交互，请参阅沙箱 vs 工具策略 vs 提升。

映像 + 设置

默认映像：moltbot-sandbox:bookworm-slim

构建一次：

scripts/sandbox-setup.sh

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

沙箱化浏览器映像：

scripts/sandbox-browser-setup.sh

默认情况下，沙箱容器在 无网络 下运行。通过 agents.defaults.sandbox.docker.network 覆盖。

Docker 安装和容器化网关位于此处： 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"）。
沙箱 exec 不继承主机 process.env。使用 agents.defaults.sandbox.docker.env（或自定义映像）来获取技能 API 密钥。

工具策略 + 逃生舱

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

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

调试：

使用 moltbot 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"
      }
    }
  }
}

沙箱