沙箱

为安全沙箱化代理。隔离工具与工作区。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"），非 agent id。群组/频道会话使用自己的 key，因此视为非主并被沙箱化。

作用域

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

"session"（默认）：每会话一容器。
"agent"：每代理一容器。
"shared"：所有沙箱会话共享一容器。

工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙箱可见内容：

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

入站媒体会复制到活跃沙箱工作区（media/inbound/*）。技能说明：read 工具以沙箱为根。workspaceAccess: "none" 时，Moltbot 会将符合条件的技能镜像到沙箱工作区（.../skills）以便读取。"rw" 时，工作区技能可从 /workspace/skills 读取。

自定义绑定挂载

agents.defaults.sandbox.docker.binds 将额外主机目录挂载到容器。格式：host:container:mode（例如 "/home/user/source:/source:rw"）。全局与按 agent 的绑定会合并（不替换）。scope: "shared" 下，按 agent 的绑定会被忽略。示例（只读源码 + docker socket）：


{
  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 提升了解绑定与工具策略和提升 exec 的交互。

镜像与设置

默认镜像：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；按 agent 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 密钥。

工具策略与逃生口

工具允许/拒绝策略在沙箱规则前仍适用。若工具被全局或按 agent 拒绝，沙箱不会恢复它。tools.elevated 是显式逃生口，在主机上运行 exec。/exec 指令仅适用于授权发件人并持久化到会话；要硬禁用 exec，使用工具策略拒绝（见沙箱 vs 工具策略 vs 提升）。调试：使用 moltbot sandbox explain 检查有效沙箱模式、工具策略与修复配置键；见沙箱 vs 工具策略 vs 提升了解「为何被阻止」的心智模型。保持锁定。

多代理覆盖

每个 agent 可覆盖沙箱与工具：agents.list[].sandbox 与 agents.list[].tools（以及 agents.list[].tools.sandbox.tools 用于沙箱工具策略）。见多 Agent 沙箱与工具了解优先级。

最小启用示例


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

沙箱