沙盒化

OpenClaw can run ''tools inside Docker containers'' to reduce blast radius. This is ''optional'' and controlled by configuration (''agents.defaults.sandbox'' or ''agents.list[].sandbox''). If sandboxing is off, tools run on the host.

The Gateway stays on the host; tool execution runs in an isolated sandbox when enabled.

这不是一个完美的安全边界，但它实际上限制了当模型做蠢事时的文件系统和进程访问。

ReferenceGatewaySandboxingPage.intro.p4

ReferenceGatewaySandboxingPage.intro.p5

ReferenceGatewaySandboxingPage.intro.p6

ReferenceGatewaySandboxingPage.intro.p7

- Tool execution (''exec'', ''read'', ''write'', ''edit'', ''apply_patch'', ''process'', etc.).

- 选项的沙盒浏览器（''agents.defaults.sandbox.browser''）。

- By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via ''agents.defaults.sandbox.browser.autoStart'' and ''agents.defaults.sandbox.browser.autoStartTimeoutMs''.

- ''agents.defaults.sandbox.browser.allowHostControl'' lets sandboxed sessions target the host browser explicitly.

- Optional allowlists gate ''target: "custom"'': ''allowedControlUrls'', ''allowedControlHosts'', ''allowedControlPorts''.

- The Gateway process itself.

沙盒化未被也的：

- Any tool explicitly allowed to run on the host (e.g. ''tools.elevated'').

- Elevated exec runs on the host and bypasses sandboxing.

- If sandboxing is off, ''tools.elevated'' does not change execution (already on host). See ''Elevated Mode''.

ReferenceGatewaySandboxingPage.step01.item10

''agents.defaults.sandbox.mode'' controls ''when'' sandboxing is used:

- ''"off"'': no sandboxing.

- ''"non-main"'': sandbox only ''non-main'' sessions (default if you want normal chats on host).

- ''"all"''：所有会话但沙盒在被执行。

Note: ''"non-main"'' is based on ''session.mainKey'' (default ''"main"''), not agent id.

Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.

''agents.defaults.sandbox.scope'' 是创建执行''容器的数''控制执行：

- ''"session"''（默认）：会话每个 1 次的容器。

- ''"agent"''：代理每个 1 次的容器。

- ''"shared"'': one container shared by all sandboxed sessions.

''agents.defaults.sandbox.workspaceAccess'' controls ''what the sandbox can see'':

- ''"none"'' (default): tools see a sandbox workspace under ''~/.openclaw/sandboxes''.

- ''"ro"'': mounts the agent workspace read-only at ''/agent'' (disables ''write''/''edit''/''apply_patch'').

- ''"rw"'': mounts the agent workspace read/write at ''/workspace''.

入站媒体是活跃那沙盒工作区（''media/inbound/*''）在复制被。

Skills note: the ''read'' tool is sandbox-rooted. With ''workspaceAccess: "none"'',

OpenClaw 将符合条件的技能镜像到沙盒工作区（''.../skills''）以便

they can be read. With ''"rw"'', workspace skills are readable from

''/workspace/skills''.

''agents.defaults.sandbox.docker.binds'' mounts additional host directories into the container. Format: ''host:container:mode'' (e.g., ''"/home/user/source:/source:rw"'').

Global and per-agent binds are ''merged'' (not replaced). Under ''scope: "shared"'', per-agent binds are ignored.

Example (read-only source + docker socket):

Security notes:

{
  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"],
          },
        },
      },
    ],
  },
}

ReferenceGatewaySandboxingPage.step05.p5

- Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (:ro or :rw).

- Sensitive mounts (e.g., docker.sock, secrets, SSH keys) should be :ro unless absolutely required.

- Combine with ''workspaceAccess: "ro"'' if you only need read access to the workspace; bind modes stay independent.

- See ''Sandbox vs Tool Policy vs Elevated'' for how binds interact with tool policy and elevated exec.

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

一度构建执行：

scripts/sandbox-setup.sh

Note: the default image does ''not'' include Node. If a skill needs Node (or other runtimes), either bake a custom image or install via ''sandbox.docker.setupCommand'' (requires network egress + writable root + root user).

Sandboxed browser image:

By default, sandbox containers run with ''no network''. Override with ''agents.defaults.sandbox.docker.network''.

Docker 安装和容器化网关位于此处：''Docker''。

沙盒浏览器镜像：

scripts/sandbox-browser-setup.sh

ReferenceGatewaySandboxingPage.step06.p8

ReferenceGatewaySandboxingPage.step06.p9

ReferenceGatewaySandboxingPage.step06.p10

''Docker''

''setupCommand'' runs ''once'' after the sandbox container is created (not on every run). It executes inside the container via ''sh -lc''.

Paths:

路径：

- 全局：''agents.defaults.sandbox.docker.setupCommand''

- Per-agent: ''agents.list[].sandbox.docker.setupCommand''

Common Pitfalls：

- Default ''docker.network'' is ''"none"'' (no egress), so package installs will fail.

- ''readOnlyRoot: true'' prevents writes; set ''readOnlyRoot: false'' or bake a custom image.

- ''user'' must be root for package installs (omit ''user'' or set ''user: "0:0"'').

- Sandbox exec does ''not'' inherit host ''process.env''. Use ''agents.defaults.sandbox.docker.env'' (or a custom image) for skill API keys.

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back.

''tools.elevated'' is an explicit escape hatch that runs ''exec'' on the host. ''/exec'' directives only apply for authorized senders and persist per session; to hard-disable ''exec'', use tool policy deny (see ''Sandbox vs Tool Policy vs Elevated'').

Debugging:

保持锁定。

ReferenceGatewaySandboxingPage.step08.p5

- Use ''openclaw sandbox explain'' to inspect effective sandbox mode, tool policy, and fix-it config keys.

- See ''Sandbox vs Tool Policy vs Elevated'' for the "why is this blocked?" mental model.

调试：

每个代理都可以覆盖沙盒 + 工具：''agents.list[].sandbox'' 和 ''agents.list[].tools''（加上 ''agents.list[].tools.sandbox.tools'' 用于沙盒工具策略）。

See ''Multi-Agent Sandbox & Tools'' for precedence.

- ''沙盒配置''

- ''多代理沙盒和工具''

- ''安全''