英文 Sandboxing

2026年4月5日约 12 分钟

原始链接：https://docs.openclaw.ai/gateway/sandboxing
来源章节：4. 官方文档：核心概念、模型与安全
来源小节：无
抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/gateway/sandboxing
抓取时间：2026-04-05 13:47:10
状态：ok

中文内容

沙盒 - OpenClaw

跳到主要内容

[OpenClaw主页！图片1：深色徽标！图片2：深色徽标](http://docs.openclaw.ai/)

图3：美国

英语

搜索...

⌘K

搜索...

导航

安全和沙箱

沙盒

开始安装频道代理工具和插件模型平台网关和操作参考帮助

网关

网关运行手册
配置和操作
安全和沙箱
协议和API
网络和发现

远程访问

安全

节点和媒体

节点
节点故障排除
媒体功能
节点特性

网页界面

在此页面上

.openclaw.ai/gateway/sandboxing#tool-policy-%2B-escape-hatches)

安全和沙箱

沙盒

OpenClaw 可以在沙箱后端运行工具以减少爆炸半径。这是可选并由配置（“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”进行配置。
- 默认情况下，沙盒浏览器容器使用专用的 Docker 网络（openclaw-sandbox-browser）而不是全局的“bridge”网络。使用“agents.defaults.sandbox.browser.network”进行配置。
- 可选的“agents.defaults.sandbox.browser.cdpSourceRange”使用 CIDR 允许列表（例如“172.21.0.1/32”）限制容器边缘 CDP 入口。
- noVNC观察者访问默认受密码保护； OpenClaw 发出一个短暂的令牌 URL，该 URL 服务于本地引导页面，并使用 URL 片段（不是查询/标头日志）中的密码打开 noVNC。
- agents.defaults.sandbox.browser.allowHostControl 让沙盒会话明确地针对主机浏览器。
- 可选允许列表门 target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts。

未沙盒化：

网关进程本身。
明确允许在沙箱外运行的任何工具（例如“tools.elevated”）。
- 提升的 exec 绕过沙箱并使用配置的转义路径（默认为“gateway”，或当 exec 目标为“node”时使用“node”）。
- 如果沙箱关闭，“tools.elevated”不会更改执行（已在主机上）。请参阅提升模式。

模式

agents.defaults.sandbox.mode 控制何时使用沙箱：

“off”：无沙箱。
“non-main”：仅限沙箱非主会话（如果您想在主机上正常聊天，则默认）。
“all”：每个会话都在沙箱中运行。注意：“non-main”基于“session.mainKey”（默认“main”），而不是代理 ID。组/频道会话使用自己的密钥，因此它们被视为非主要会话，并将被沙箱化。

适用范围

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

"agent"（默认）：每个代理一个容器。
"session"：每个会话一个容器。
“共享”：由所有沙盒会话共享的一个容器。

后端

agents.defaults.sandbox.backend 控制哪个运行时提供沙箱：

"docker"（默认）：本地 Docker 支持的沙箱运行时。
"ssh"：通用 SSH 支持的远程沙箱运行时。
"openshell"：OpenShell 支持的沙箱运行时。

特定于 SSH 的配置位于“agents.defaults.sandbox.ssh”下。 OpenShell 特定的配置位于“plugins.entries.openshell.config”下。

选择后端

	码头工人	SSH	开放外壳
它在哪里运行	本地集装箱	任何可通过 SSH 访问的主机	OpenShell 托管沙箱
设置	`scripts/sandbox-setup.sh`	SSH 密钥 + 目标主机	OpenShell 插件已启用
工作空间模型	绑定安装或复制	远程规范（种子一次）	“镜像”或“远程”
网络控制	`docker.network`（默认：无）	取决于远程主机	取决于 OpenShell
浏览器沙箱	支持	不支持	尚不支持
绑定安装座	`docker.binds`	不适用	不适用
最适合	本地开发，完全隔离	卸载到远程机器	具有可选双向同步功能的托管远程沙箱

SSH后端

当您希望 OpenClaw 在任意可 SSH 访问的计算机上沙箱“exec”、文件工具和媒体读取时，请使用“后端：“ssh””。

{
  代理商：{
    默认值：{
      沙箱：{
        模式：“全部”，
        后端：“ssh”，
        范围：“会话”，
        工作空间访问：“rw”，
        SSH：{
          目标：“用户@网关主机：22”，
          工作区根：“/tmp/openclaw-sandboxes”，
          strictHostKeyChecking：true，
          更新主机密钥：true，
          身份文件：“~/.ssh/id_ed25519”，
          证书文件：“~/.ssh/id_ed25519-cert.pub”，
          knownHostsFile: "~/.ssh/known_hosts",
          // 或者使用 SecretRefs / 内联内容代替本地文件：
          // IdentityData: { 源: "env", 提供者: "default", id: "SSH_IDENTITY" },
          // 证书数据: { 源: "env", 提供者: "default", id: "SSH_CERTIFICATE" },
          //knownHostsData: { 源: "env", 提供者: "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 通过正常的秘密运行时快照解析它们，将它们写入带有“0600”的临时文件，并在 SSH 会话结束时删除它们。
如果为同一项目设置了“*File”和“*Data”，则该 SSH 会话的“*Data”优先。

这是一个远程规范模型。远程 SSH 工作空间在初始种子后成为真正的沙箱状态。重要后果：

在重新创建沙箱之前，种子步骤后在 OpenClaw 外部进行的主机本地编辑无法远程可见。
openclaw sandbox recreate 会在下次使用时再次从本地删除每个范围的远程根和种子。
SSH 后端不支持浏览器沙箱。
sandbox.docker.* 设置不适用于 SSH 后端。

OpenShell 后端

当您希望 OpenClaw 在 OpenShell 管理的远程环境中沙箱工具时，请使用“后端：“openshell””。有关完整的设置指南、配置参考和工作区模式比较，请参阅专用的 OpenShell 页面。OpenShell 重用与通用 SSH 后端相同的核心 SSH 传输和远程文件系统桥，并添加 OpenShell 特定的生命周期（“sandbox create/get/delete”、“sandbox ssh-config”）以及可选的“mirror”工作区模式。

{
  代理商：{
    默认值：{
      沙箱：{
        模式：“全部”，
        后端：“openshell”，
        范围：“会话”，
        工作空间访问：“rw”，
      },
    },
  },
  插件：{
    条目：{
      开壳：{
        启用：真，
        配置：{
          来自：“张开爪”，
          模式：“远程”，//镜像|远程
          远程工作空间目录：“/sandbox”，
          RemoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

OpenShell 模式：

mirror（默认）：本地工作空间保持规范。 OpenClaw 在执行之前将本地文件同步到 OpenShell，并在执行之后将远程工作空间同步回来。
remote：OpenShell 工作空间在创建沙箱后是规范的。 OpenClaw 从本地工作区播种远程工作区一次，然后文件工具和执行程序直接针对远程沙箱运行，而无需同步更改。

远程运输详情：

OpenClaw 通过 openshell sandbox ssh-config <name> 向 OpenShell 请求特定于沙箱的 SSH 配置。
核心将 SSH 配置写入临时文件，打开 SSH 会话，并重用“后端：“ssh””使用的相同远程文件系统桥。
在“镜像”模式下，只有生命周期不同：在执行之前将本地同步到远程，然后在执行之后同步回来。

当前 OpenShell 的限制：

尚不支持沙盒浏览器
OpenShell 后端不支持 sandbox.docker.binds
sandbox.docker.* 下特定于 Docker 的运行时旋钮仍然仅适用于 Docker 后端

工作区模式

OpenShell 有两个工作区模型。这是实践中最重要的部分。 #####镜子

当您希望 本地工作区保持规范时，请使用 plugins.entries.openshell.config.mode: "mirror"。行为：

在 exec 之前，OpenClaw 会将本地工作空间同步到 OpenShell 沙箱中。
在 exec 之后，OpenClaw 将远程工作空间同步回本地工作空间。
文件工具仍然通过沙箱桥进行操作，但本地工作区仍然是轮次之间的事实来源。

在以下情况下使用此功能：

您在 OpenClaw 之外本地编辑文件，并希望这些更改自动显示在沙箱中
您希望 OpenShell 沙箱的行为尽可能类似于 Docker 后端
您希望主机工作区在每次执行后反映沙箱写入

权衡：

执行前后的额外同步成本

`远程`

当您希望 OpenShell 工作区成为规范时，请使用 plugins.entries.openshell.config.mode: "remote"。行为：

首次创建沙箱时，OpenClaw 从本地工作区播种远程工作区一次。
之后，exec、read、write、edit 和 apply_patch 直接对远程 OpenShell 工作区进行操作。
OpenClaw 在执行后不将远程更改同步回本地工作区。
即时媒体读取仍然有效，因为文件和媒体工具通过沙箱桥读取而不是假设本地主机路径。
通过 SSH 传输到 openshell sandbox ssh-config 返回的 OpenShell 沙箱。

重要后果：

如果您在种子步骤后在 OpenClaw 外部的主机上编辑文件，则远程沙箱将不会自动看到这些更改。
如果重新创建沙箱，则会再次从本地工作区播种远程工作区。
使用 scope: "agent" 或 scope: "shared"，远程工作空间在同一范围内共享。

在以下情况下使用此功能：

沙箱应该主要存在于远程 OpenShell 端
你想要更低的每回合同步开销
您不希望主机本地编辑默默地覆盖远程沙箱状态

如果您将沙箱视为临时执行环境，请选择“镜像”。如果您将沙箱视为真正的工作区，请选择“远程”。

OpenShell 生命周期

OpenShell 沙箱仍然通过正常的沙箱生命周期进行管理：

openclaw sandbox list 显示 OpenShell 运行时以及 Docker 运行时
openclaw sandbox recreate 删除当前运行时并让 OpenClaw 在下次使用时重新创建它
修剪逻辑也是后端感知的

对于“远程”模式，重新创建尤为重要：

重新创建删除该范围的规范远程工作空间
下一次使用从本地工作区种子一个新的远程工作区

对于“镜像”模式，重新创建主要重置远程执行环境，因为无论如何本地工作空间仍然是规范的。

工作区访问

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

“none”（默认）：工具在~/.openclaw/sandboxes下看到沙箱工作区。
"ro"：将代理工作区以只读方式安装在/agent（禁用write/edit/apply_patch）。
"rw"：将代理工作区安装在/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"）。全局和每个代理绑定合并（不替换）。在“范围：“共享””下，每个代理的绑定将被忽略。“agents.defaults.sandbox.browser.binds”仅将其他主机目录安装到沙盒浏览器容器中。

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

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

{
  代理商：{
    默认值：{
      沙箱：{
        泊坞窗：{
          绑定：["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    列表：[
      {
        id：“构建”，
        沙箱：{
          泊坞窗：{
            绑定：[“/mnt/cache:/cache:rw”]，
          },
        },
      },
    ],
  },
}

安全注意事项：

绑定绕过沙箱文件系统：它们以您设置的任何模式（:ro 或 :rw）公开主机路径。
OpenClaw 阻止危险的绑定源（例如：docker.sock、/etc、/proc、/sys、/dev 以及会暴露它们的父挂载）。
OpenClaw 还阻止常见的主目录凭证根，例如 ~/.aws、~/.cargo、~/.config、~/.docker、~/.gnupg、~/.netrc、~/.npm 和 ~/.ssh。
绑定验证不仅仅是字符串匹配。 OpenClaw 标准化源路径，然后通过最深的现有祖先再次解析它，然后重新检查阻止的路径和允许的根。
这意味着即使最后的叶子还不存在，符号链接父转义仍然无法关闭。示例：如果“run-link”指向“/workspace/run-link/new-file”，则“/workspace/run-link/new-file”仍会解析为“/var/run/...”。
允许的源根以相同的方式规范化，因此在符号链接解析之前仅查看允许列表内部的路径仍会被拒绝为“外部允许的根”。
敏感挂载（秘密、SSH 密钥、服务凭证）应为 :ro，除非绝对需要。
如果您只需要读取访问权限，请与“workspaceAccess: "ro"”结合使用

工作区；绑定模式保持独立。

请参阅沙盒、工具策略与提升了解绑定如何与工具策略和提升的 exec 交互。

图像+设置

默认 Docker 镜像：openclaw-sandbox:bookworm-slim构建一次：

脚本/sandbox-setup.sh

注意：默认图像不包含 Node.js。如果技能需要 Node（或其他运行时），则可以烘焙自定义映像或通过“sandbox.docker.setupCommand”安装（需要网络出口 + 可写 root + root 用户）。如果您想要具有通用工具（例如“curl”、“jq”、“nodejs”、“python3”、“git”）的功能更强大的沙箱映像，请构建：

脚本/sandbox-common-setup.sh

然后将 agents.defaults.sandbox.docker.image 设置为 openclaw-sandbox-common:bookworm-slim。沙盒浏览器图像：

脚本/sandbox-browser-setup.sh

默认情况下，Docker 沙箱容器在无网络的情况下运行。使用“agents.defaults.sandbox.docker.network”覆盖。捆绑的沙箱浏览器映像还为容器化工作负载应用保守的 Chromium 启动默认值。当前容器默认值包括：

--远程调试地址=127.0.0.1
--remote-debugging-port=<源自 OPENCLAW_BROWSER_CDP_PORT>
--user-data-dir=${HOME}/.chrome
--无首次运行
--无默认浏览器检查
--禁用 3d-apis
--禁用 GPU
--disable-dev-shm-usage
--禁用后台网络
--禁用扩展
--disable-features=TranslateUI
--禁用breakpad
--禁用崩溃报告器
--禁用软件光栅化器
--无受精卵
--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”。
`--禁用

e-extensions 默认情况下处于启用状态，并且可以使用“OPENCLAW_BROWSER_DISABLE_EXTENSIONS = 0”来禁用依赖于扩展的流程。

--renderer-process-limit=2 由 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，其中 0 保留 Chromium 的默认值。

如果您需要不同的运行时配置文件，请使用自定义浏览器图像并提供您自己的入口点。对于本地（非容器）Chromium 配置文件，请使用“browser.extraArgs”附加额外的启动标志。安全默认值：

网络：“主机” 被阻止。
network: "container:<id>" 默认被阻止（命名空间加入绕过风险）。
Break-glass 覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

Docker 安装和容器化网关位于此处：Docker对于 Docker 网关部署，“scripts/docker/setup.sh”可以引导沙箱配置。设置“OPENCLAW_SANDBOX=1”（或“true”/“yes”/“on”）以启用该路径。您可以使用“OPENCLAW_DOCKER_SOCKET”覆盖套接字位置。完整设置和环境参考：Docker。

setupCommand（一次性容器设置）

创建沙箱容器后，“setupCommand”运行一次（不是每次运行）。它通过“sh -lc”在容器内执行。路径：

全局：agents.defaults.sandbox.docker.setupCommand
每个代理：agents.list[].sandbox.docker.setupCommand

常见陷阱：

默认 docker.network 是 "none"（无出口），因此包安装将失败。
docker.network: "container:<id>" 需要 dangerouslyAllowContainerNamespaceJoin: true 并且只是打破玻璃。
readOnlyRoot: true 防止写入；设置“readOnlyRoot: false”或烘焙自定义图像。
user 必须是 root 才能安装软件包（省略 user 或设置 user: "0:0"）。
沙箱 exec 不继承主机 process.env。使用“agents.defaults.sandbox.docker.env”（或自定义映像）作为技能 API 密钥。

工具政策+逃生舱口

工具允许/拒绝策略在沙箱规则之前仍然适用。如果某个工具被全局或每个代理拒绝，沙箱不会将其恢复。tools.elevated 是一个显式逃逸舱口，在沙箱外部运行 exec（默认情况下为 gateway，当 exec 目标为 node 时则为 node）。 /exec 指令仅适用于授权发件人并在每个会话中持续存在；要硬禁用“exec”，请使用工具策略拒绝（请参阅沙盒、工具策略与 Elevated）。调试：

使用“openclaw sandbox说明”来检查有效的沙箱模式、工具策略和修复配置键。
请参阅沙盒、工具策略与 Elevated 了解“为什么会被阻止？”心理模型。将其锁定。

多代理覆盖

每个代理都可以覆盖沙箱+工具：“agents.list[].sandbox”和“agents.list[].tools”（加上用于沙箱工具策略的“agents.list[].tools.sandbox.tools”）。请参阅多代理沙箱和工具了解优先顺序。

最小启用示例

{
  代理商：{
    默认值：{
      沙箱：{
        模式：“非主”，
        范围：“会话”，
        工作空间访问：“无”，
      },
    },
  },
}

英文 Sandboxing

中文内容

沙盒 - OpenClaw

网关

远程访问

安全

节点和媒体

网页界面

沙盒

`远程`

On this page

英文 Sandboxing

中文内容

沙盒 - OpenClaw

网关

远程访问

安全

节点和媒体

网页界面

沙盒

`远程`

On this page