沙盒机制

OpenClaw 可以在沙盒后端中运行工具，以降低失误造成的影响范围。这是可选功能，通过配置项（agents.defaults.sandbox 或 agents.list[].sandbox）控制。若沙盒关闭，工具直接在宿主机上运行。Gateway 进程始终在宿主机上运行，工具执行在启用时才进入隔离沙盒。

这不是完美的安全边界，但当模型执行了愚蠢操作时，它能有效限制文件系统和进程访问范围。

哪些内容被沙盒化

工具执行（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 白名单限制容器边缘的 CDP 入站（例如 172.21.0.1/32）。
- noVNC 观察器访问默认受密码保护；OpenClaw 生成短效 token URL，供本地引导页使用并通过 URL fragment（非 query/header 日志）传递密码打开 noVNC。
- agents.defaults.sandbox.browser.allowHostControl 允许沙盒会话显式以宿主机浏览器为目标。
- 可选白名单限制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。

不被沙盒化的内容：

Gateway 进程本身。
任何被显式允许在宿主机上运行的工具（例如 tools.elevated）。
- Elevated exec 在宿主机上运行，绕过沙盒。
- 若沙盒关闭，tools.elevated 不会改变执行方式（本来就在宿主机上）。参见 Elevated Mode。

模式（mode）

agents.defaults.sandbox.mode 控制沙盒何时启用：

"off"：不使用沙盒。
"non-main"：仅对非主会话使用沙盒（适合希望普通聊天在宿主机运行的场景）。
"all"：所有会话都在沙盒中运行。注意："non-main" 基于 session.mainKey（默认 "main"），而非 agent id。群组/频道会话使用各自的 key，因此会被视为非主会话并沙盒化。

作用域（scope）

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

"session"（默认）：每个会话一个容器。
"agent"：每个 Agent 一个容器。
"shared"：所有沙盒会话共享一个容器。

后端（backend）

agents.defaults.sandbox.backend 控制使用哪种运行时提供沙盒：

"docker"（默认）：本地 Docker 沙盒运行时。
"ssh"：通用 SSH 远端沙盒运行时。
"openshell"：OpenShell 托管沙盒运行时。

SSH 特有配置在 agents.defaults.sandbox.ssh 下。 OpenShell 特有配置在 plugins.entries.openshell.config 下。

后端选型指南

	Docker	SSH	OpenShell
运行位置	本地容器	任意 SSH 可访问的宿主机	OpenShell 托管沙盒
配置方式	`scripts/sandbox-setup.sh`	SSH 密钥 + 目标宿主机	启用 OpenShell 插件
工作区模型	绑定挂载或复制	远端权威（单次初始化）	`mirror` 或 `remote`
网络控制	`docker.network`（默认无网络）	取决于远端宿主机	取决于 OpenShell
浏览器沙盒	支持	不支持	暂不支持
绑定挂载	`docker.binds`	不适用	不适用
适用场景	本地开发、完整隔离	卸载到远端机器	托管远端沙盒，可选双向同步

SSH 后端

使用 backend: "ssh" 时，OpenClaw 将 exec、文件工具和媒体读取沙盒化到任意 SSH 可访问的机器上。

json5

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

工作原理：

OpenClaw 在 sandbox.ssh.workspaceRoot 下按作用域创建远端根目录。
首次创建或重建后首次使用时，OpenClaw 从本地工作区一次性初始化远端工作区。
之后，exec、read、write、edit、apply_patch、提示词媒体读取和入站媒体暂存通过 SSH 直接在远端工作区上操作。
OpenClaw 不会自动将远端改动同步回本地工作区。

认证材料：

identityFile、certificateFile、knownHostsFile：使用现有本地文件，通过 OpenSSH 配置传递。
identityData、certificateData、knownHostsData：使用内联字符串或 SecretRef。OpenClaw 通过正常的 secrets 运行时快照解析它们，写入权限为 0600 的临时文件，并在 SSH 会话结束后删除。
同一项若同时设置了 *File 和 *Data，该 SSH 会话以 *Data 为准。

这是一个远端权威模型。初始化后，远端 SSH 工作区成为真正的沙盒状态。

重要后果：

初始化后在 OpenClaw 外部本地编辑的文件，在重建沙盒之前不会出现在远端。
openclaw sandbox recreate 删除按作用域创建的远端根目录，下次使用时从本地重新初始化。
SSH 后端不支持浏览器沙盒。
sandbox.docker.* 配置不适用于 SSH 后端。

OpenShell 后端

使用 backend: "openshell" 时，OpenClaw 将工具沙盒化到 OpenShell 托管的远端环境中。完整配置指南、配置参数和工作区模式对比，参见专题页面 OpenShell。

OpenShell 复用与通用 SSH 后端相同的核心 SSH 传输层和远端文件系统桥接逻辑，并在此基础上增加了 OpenShell 特有的生命周期管理（sandbox create/get/delete、sandbox ssh-config）以及可选的 mirror 工作区模式。

json5

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

OpenShell 模式：

mirror（默认）：本地工作区保持为权威源。OpenClaw 在 exec 前同步本地文件到 OpenShell，exec 后同步远端工作区回本地。
remote：沙盒创建后 OpenShell 工作区成为权威源。OpenClaw 一次性从本地工作区初始化远端，之后文件工具和 exec 直接在远端沙盒上操作，不同步回本地。

远端传输细节：

OpenClaw 通过 openshell sandbox ssh-config <name> 向 OpenShell 请求沙盒特有的 SSH 配置。
核心层将该 SSH 配置写入临时文件，建立 SSH 会话，并复用 backend: "ssh" 所用的相同远端文件系统桥接。
仅在 mirror 模式下生命周期有所不同：exec 前同步本地到远端，exec 后同步回来。

当前 OpenShell 限制：

沙盒浏览器暂不支持
sandbox.docker.binds 不适用于 OpenShell 后端
sandbox.docker.* 下的 Docker 特有运行时参数仍仅对 Docker 后端生效

OpenShell 生命周期

OpenShell 沙盒仍通过标准沙盒生命周期管理：

openclaw sandbox list 同时显示 OpenShell 和 Docker 运行时
openclaw sandbox recreate 删除当前运行时，下次使用时让 OpenClaw 重新创建
清理逻辑也感知后端类型

对于 remote 模式，重建尤为重要：

重建会删除该作用域的权威远端工作区
下次使用时从本地工作区重新初始化

对于 mirror 模式，重建主要是重置远端执行环境，因为本地工作区始终是权威源。

工作区访问权限

agents.defaults.sandbox.workspaceAccess 控制沙盒能看到什么：

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

使用 OpenShell 后端时：

mirror 模式在每次 exec 轮次之间仍使用本地工作区作为权威源
remote 模式在初始化后使用远端 OpenShell 工作区作为权威源
workspaceAccess: "ro" 和 "none" 对写入行为的限制方式相同

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

自定义绑定挂载

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

全局和按 Agent 的绑定会合并（不替换）。在 scope: "shared" 下，按 Agent 的绑定会被忽略。

agents.defaults.sandbox.browser.binds 仅将额外目录挂载到沙盒浏览器容器。

设置后（包括 []），它会替换浏览器容器的 agents.defaults.sandbox.docker.binds。
未设置时，浏览器容器回退到 agents.defaults.sandbox.docker.binds（向后兼容）。

示例（只读源码 + 额外数据目录）：

json5

{
  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，以及会暴露它们的父挂载）。
包含敏感内容（secrets、SSH 密钥、服务凭据）的挂载应使用 :ro，除非绝对必要。
如果只需要工作区的读访问，与 workspaceAccess: "ro" 组合使用；绑定挂载的模式与之独立。
参见 Sandbox vs Tool Policy vs Elevated 了解绑定如何与工具策略和 elevated exec 互动。

镜像与配置

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

一次性构建：

bash

scripts/sandbox-setup.sh

注意：默认镜像不包含 Node。若技能需要 Node（或其他运行时），要么构建自定义镜像，要么通过 sandbox.docker.setupCommand 安装（需要网络出口 + 可写根目录 + root 用户）。

若需要功能更完整的沙盒镜像（包含 curl、jq、nodejs、python3、git 等常用工具），构建：

bash

scripts/sandbox-common-setup.sh

然后将 agents.defaults.sandbox.docker.image 设为 openclaw-sandbox-common:bookworm-slim。

沙盒浏览器镜像：

bash

scripts/sandbox-browser-setup.sh

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

内置沙盒浏览器镜像也针对容器化工作负载应用了保守的 Chromium 启动默认值。当前容器默认配置包括：

--remote-debugging-address=127.0.0.1
--remote-debugging-port=<从 OPENCLAW_BROWSER_CDP_PORT 派生>
--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-3d-apis
--disable-gpu
--disable-dev-shm-usage
--disable-background-networking
--disable-extensions
--disable-features=TranslateUI
--disable-breakpad
--disable-crash-reporter
--disable-software-rasterizer
--no-zygote
--metrics-recording-only
--renderer-process-limit=2
启用 noSandbox 时还有 --no-sandbox 和 --disable-setuid-sandbox。
三个图形硬化参数（--disable-3d-apis、--disable-software-rasterizer、--disable-gpu）是可选的，在容器缺乏 GPU 支持时有用。若工作负载需要 WebGL 或其他 3D/浏览器特性，设置 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0。
--disable-extensions 默认启用，可设置 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 禁用（用于依赖扩展的流程）。
--renderer-process-limit=2 由 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，0 表示使用 Chromium 默认值。

若需要不同的运行时配置，使用自定义浏览器镜像并提供自己的入口点。对于本地（非容器）Chromium profiles，使用 browser.extraArgs 追加额外的启动参数。

安全默认值：

阻止 network: "host"。
默认阻止 network: "container:<id>"（命名空间加入绕过风险）。
紧急开关：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

Docker 安装及容器化 Gateway：Docker

对于 Docker Gateway 部署，scripts/docker/setup.sh 可引导沙盒配置。设置 OPENCLAW_SANDBOX=1（或 true/yes/on）启用该路径。可通过 OPENCLAW_DOCKER_SOCKET 覆盖 socket 位置。完整配置和环境变量参考：Docker。

setupCommand（一次性容器设置）

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

路径：

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

常见坑：

默认 docker.network 为 "none"（无网络出口），包安装会失败。
docker.network: "container:<id>" 需要 dangerouslyAllowContainerNamespaceJoin: true，仅作为紧急方案。
readOnlyRoot: true 阻止写入，设置 readOnlyRoot: false 或构建自定义镜像。
包安装需要 root 用户（省略 user 或设 user: "0:0"）。
沙盒 exec 不继承宿主机 process.env。通过 agents.defaults.sandbox.docker.env（或自定义镜像）为技能 API keys 传入环境变量。

工具策略 + 逃生通道

工具允许/拒绝策略在沙盒规则之前生效。若某工具被全局或按 Agent 拒绝，沙盒不会让它起死回生。

tools.elevated 是显式逃生通道，让 exec 在宿主机上运行。 /exec 指令仅对已授权的发送方生效且仅限当前会话；要彻底禁用 exec，使用工具策略拒绝（参见 Sandbox vs Tool Policy vs Elevated）。

调试：

使用 openclaw sandbox explain 检查生效中的沙盒模式、工具策略和修复建议配置键。
参见 Sandbox vs Tool Policy vs Elevated 了解"为什么被拦截"的心智模型。保持锁定状态。

多 Agent 覆盖

每个 Agent 可独立覆盖沙盒 + 工具配置： agents.list[].sandbox 和 agents.list[].tools（以及 agents.list[].tools.sandbox.tools，用于沙盒工具策略）。参见 Multi-Agent Sandbox & Tools 了解优先级规则。

最简启用示例

json5

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

沙盒机制 ​

哪些内容被沙盒化 ​

模式（mode） ​

作用域（scope） ​

后端（backend） ​

后端选型指南 ​

SSH 后端 ​

OpenShell 后端 ​

OpenShell 生命周期 ​

工作区访问权限 ​

自定义绑定挂载 ​

镜像与配置 ​

setupCommand（一次性容器设置） ​

工具策略 + 逃生通道 ​

多 Agent 覆盖 ​

最简启用示例 ​

相关文档 ​

沙盒机制

哪些内容被沙盒化

模式（mode）

作用域（scope）

后端（backend）

后端选型指南

SSH 后端

OpenShell 后端

OpenShell 生命周期

工作区访问权限

自定义绑定挂载

镜像与配置

setupCommand（一次性容器设置）

工具策略 + 逃生通道

多 Agent 覆盖

最简启用示例

相关文档