沙箱隔离

OpenClaw 可以在沙箱后端中执行工具，以缩小影响范围。沙箱隔离默认关闭，可通过 agents.defaults.sandbox（全局）或 agents.list[].sandbox（按智能体）控制。Gateway 网关进程始终在主机上运行；启用沙箱隔离后，只有工具执行会移入沙箱。

沙箱隔离的内容

• 工具执行：exec、read、write、edit、apply_patch、process 等。
• 可选的沙箱浏览器（agents.defaults.sandbox.browser）。

不进行沙箱隔离的内容：

• Gateway 网关进程本身。
• 通过 tools.elevated 明确允许在沙箱外运行的任何工具。提升权限的 Exec 会绕过沙箱隔离，并在配置的逃逸路径上运行（默认为 gateway；当 Exec 目标为 node 时则为 node）。如果沙箱隔离已关闭，tools.elevated 不会产生任何变化，因为 Exec 已经在主机上运行。请参阅提升权限模式。

模式、作用域和后端

三个相互独立的设置控制沙箱行为：

模式控制何时应用沙箱隔离：

• off：不进行沙箱隔离。
• non-main：除智能体主会话外，对其他所有会话进行沙箱隔离。主会话键始终为 agent:<agentId>:main（当 session.scope 为 "global" 时则为 global），不可配置。群组/渠道会话使用各自的键，因此始终被视为非主会话并进行沙箱隔离。
• all：每个会话都在沙箱中运行。

作用域控制创建多少个容器/环境：

• agent：每个智能体使用一个容器。
• session：每个会话使用一个容器。
• shared：所有进行沙箱隔离的会话共享一个容器（在此作用域下，将忽略按智能体设置的 docker/ssh/browser 覆盖项）。

后端控制由哪个运行时执行沙箱中的工具。SSH 专用配置位于 agents.defaults.sandbox.ssh；OpenShell 专用配置位于 plugins.entries.openshell.config。

Docker 后端

启用沙箱隔离后，Docker 是默认后端。它通过 Docker 守护进程套接字（/var/run/docker.sock）在本地运行工具和沙箱浏览器；隔离由 Docker 命名空间提供。

默认值：network: "none"（无出站访问）、readOnlyRoot: true、capDrop: ["ALL"]，镜像为 openclaw-sandbox:bookworm-slim。

要向沙箱开放主机 GPU，请将 agents.defaults.sandbox.docker.gpus（或按智能体设置的覆盖项）设为类似 "all" 或 "device=GPU-uuid" 的值。此值会传递给 Docker 的 --gpus 标志，并且要求主机具有兼容的运行时，例如 NVIDIA Container Toolkit。

沙箱浏览器

• 当浏览器工具需要沙箱浏览器时，它会自动启动（确保可访问 CDP）。通过 agents.defaults.sandbox.browser.autoStart（默认为 true）和 autoStartTimeoutMs（默认为 12 秒）进行配置。
• 沙箱浏览器容器使用专用 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 提供本地引导页面，并通过 URL 片段（而不是查询字符串或请求头日志）中的密码打开 noVNC。
• agents.defaults.sandbox.browser.allowHostControl（默认为 false）允许进行沙箱隔离的会话明确以主机浏览器为目标。
• 可选的允许列表会限制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。

SSH 后端

使用 backend: "ssh" 可在任意可通过 SSH 访问的计算机上对 exec、文件工具和媒体读取进行沙箱隔离。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // 或者使用 SecretRefs / 内联内容，而不是本地文件：          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

默认值：command: "ssh"、workspaceRoot: "/tmp/openclaw-sandboxes"、strictHostKeyChecking: true、updateHostKeys: true。

• 生命周期：OpenClaw 会在 sandbox.ssh.workspaceRoot 下创建一个按作用域划分的远程根目录。创建或重新创建后的首次使用时，它会从本地工作区一次性填充该远程工作区。此后，exec、read、write、edit、apply_patch、提示词媒体读取和入站媒体暂存都会通过 SSH 直接针对远程工作区运行。OpenClaw 不会自动将远程更改同步回本地工作区。
• 身份验证材料：identityFile/certificateFile/knownHostsFile 引用现有本地文件。identityData/certificateData/knownHostsData 接受内联字符串或 SecretRefs；它们通过常规机密运行时快照解析，以 0600 模式写入临时文件，并在 SSH 会话结束时删除。如果同一项同时设置了 *File 和 *Data 变体，则该会话中以 *Data 为准。
• 以远程端为准的影响：完成初始填充后，远程 SSH 工作区会成为实际的沙箱状态。在填充步骤后于 OpenClaw 外部进行的主机本地编辑不会在远程端可见，除非你重新创建沙箱。openclaw sandbox recreate 会删除按作用域划分的远程根目录，并在下次使用时再次从本地填充。此后端不支持浏览器沙箱隔离，且 sandbox.docker.* 设置不适用于此后端。

OpenShell 后端

使用 backend: "openshell" 可在 OpenShell 管理的远程环境中对工具进行沙箱隔离。OpenShell 会复用与通用 SSH 后端相同的 SSH 传输和远程文件系统桥接，并添加 OpenShell 生命周期（sandbox create/get/delete/ssh-config）以及可选的 mirror 工作区同步模式。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror"（默认）以本地工作区为准：OpenClaw 会在执行 exec 前将本地内容同步到沙箱，并在执行后同步回来。mode: "remote" 会从本地一次性填充远程工作区，然后直接针对远程工作区运行 exec/read/write/edit/apply_patch，而不会同步回来；填充后的本地编辑不可见，直到你运行 openclaw sandbox recreate。在 scope: "agent" 或 scope: "shared" 下，该远程工作区会在相同作用域内共享。当前限制：尚不支持沙箱浏览器，且 sandbox.docker.binds 不适用于此后端。

openclaw sandbox list/recreate/prune 对 OpenShell 运行时和 Docker 运行时采用相同处理方式；清理逻辑会感知后端类型。

有关完整的前置条件、配置参考、工作区模式比较和生命周期详情，请参阅 OpenShell。

工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到的内容：

使用 OpenShell 后端时，mirror 模式仍会在各次 exec 轮次之间将本地工作区作为规范来源；remote 模式会在初始填充后将远程 OpenShell 工作区作为规范来源；而 workspaceAccess: "ro"/"none" 仍会以相同方式限制写入行为。

入站媒体会复制到活跃的沙箱工作区中（media/inbound/*）。

自定义绑定挂载

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

全局绑定与按 Agent 配置的绑定会合并（而非替换）。在 scope: "shared" 下，会忽略按 Agent 配置的绑定。

agents.defaults.sandbox.browser.binds 仅将额外的主机目录挂载到沙箱浏览器容器中。设置该项时（包括 []），它会替换浏览器容器的 docker.binds；省略时，浏览器容器会回退使用 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"],          },        },      },    ],  },}

镜像和设置

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

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

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

对于 Docker Gateway 网关部署，scripts/docker/setup.sh 可以引导生成沙箱配置。将 OPENCLAW_SANDBOX=1（或 true/yes/on）设置为启用该路径。可通过 OPENCLAW_DOCKER_SOCKET 覆盖套接字位置。完整设置和环境变量参考：Docker。

setupCommand（一次性容器设置）

setupCommand 在创建沙箱容器后运行一次（不会在每次运行时执行）。它通过 sh -lc 在容器内执行。

路径：

• 全局：agents.defaults.sandbox.docker.setupCommand
• 按 Agent 配置：agents.list[].sandbox.docker.setupCommand

工具策略和逃生通道

工具允许/拒绝策略仍会先于沙箱规则应用。如果某个工具在全局或按 Agent 配置中被拒绝，沙箱隔离不会重新启用它。

tools.elevated 是一个显式逃生通道，用于在沙箱外运行 exec（默认在 gateway 上运行；当 exec 目标为 node 时，则在 node 上运行）。/exec 指令仅适用于已授权的发送者，并会按会话持久化；若要彻底禁用 exec，请使用工具策略拒绝（参阅沙箱、工具策略和提升权限）。

调试：

• openclaw sandbox list 显示沙箱容器、状态、镜像匹配情况、存在时间、空闲时间以及关联的会话/Agent。
• openclaw sandbox explain [--session <key>] [--agent <id>] 检查生效的沙箱模式、主机工作区、运行时工作目录、Docker 挂载、工具策略以及修复配置键。其 workspaceRoot 字段仍表示配置的沙箱根目录；effectiveHostWorkspaceRoot 显示活跃工作区的实际位置。
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] 删除容器/环境，以便下次使用时按当前配置重新创建。
• 有关“为什么会被阻止？”的思维模型，请参阅沙箱、工具策略和提升权限。

多 Agent 覆盖

每个 Agent 都可以覆盖沙箱和工具配置：agents.list[].sandbox 和 agents.list[].tools（沙箱工具策略还可使用 agents.list[].tools.sandbox.tools）。有关优先级，请参阅多 Agent 沙盒和工具。

最小启用示例

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

相关内容

• 多 Agent 沙盒和工具 -- 按 Agent 配置的覆盖项和优先级
• OpenShell -- 托管式沙箱后端设置、工作区模式和配置参考
• 沙箱配置
• 沙箱、工具策略和提升权限 -- 调试“为什么此操作被阻止？”
• 安全性