模式、范围和后端

模式、范围和后端设置、创建者角色要求如何覆盖代理模式以及运行时身份包含的内容。

模式、作用范围和后端

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

模式 控制何时应用沙箱：

• off：无代理范围沙箱；其创建者角色需要沙箱的会话仍以沙箱方式运行。
• non-main：对除代理主会话之外的每个会话进行沙箱处理。主会话密钥始终为 agent:<agentId>:main（或 global，当 session.scope 为 "global" 时）；它是不可配置的。 Group/channel 会话使用自己的密钥，因此它们始终被视为非主会话并被沙箱化。
• all：每个会话都在沙箱中运行。

设置指定操作员角色sandbox政策"required"无论代理模式如何，都对该角色新创建的会话进行沙箱处理。创建者要求对于会话来说是不可变的；不可用的后端阻止执行，并提升执行或Gateway/node主机覆盖无法绕过它。默认"inherit"保留现有的代理模式行为。看命名操作员角色。

Per-chat 沙箱选择退出

管理员可以从配置的沙箱中选择一个空闲聊天，而无需更改代理或全局配置。sessions.patch接受sandboxMode: "off"； sandboxMode: null清除该选择并恢复配置的策略。两种突变都需要operator.admin以及对目标会话的现有访问权限。创建者角色要求（sandbox: "required"） 是不可变的并且始终优先：即使是管理员也无法选择退出该会话。

对于比赛安全更新，包括expectedSessionId， expectedLifecycleRevision， 和expectedSandboxMode （null表示不覆盖）。过时的期望会拒绝突变，而不是更改替换的聊天或覆盖另一个选择。sessions.patchMany支持相同的沙箱突变以及对每个目标的期望。在更改沙箱模式之前停止任何活动的运行；网关在提交之前会再次检查，并且不会在运行回合下更改遏制。

在重新启动和重置后，该选择仍然存在于该聊天中。新分叉的聊天不会继承选择退出；在同一个聊天中恢复检查点会保留它。清除覆盖不会删除沙箱容器或更改其他聊天。不支持此首选项的旧版本将遵循其配置的沙箱策略。

当管理员明确选择本机代理自己的权限时，本机运行时选择和发送可以提供 继续此聊天。这将可选的沙箱选择退出与绑定到该聊天和运行时的完全访问权限和同意结合在一起。然后将可选的本机工具和工作空间限制委托给本机代理； OpenClaw-托管工具保留其现有策略。如果安装程序已记住聊天所属代理对该运行时的同意，则管理员无需再次提示即可恢复。否则，普通代理聊天和全局聊天都需要显式确认。拒绝发送后，确认会保存权限并重试该消息一次。仅选择确认，不发送草稿。两者都不会更改全局设置。本机同意在重置或运行时更改时清除，并且永远不会被分叉继承。所需的沙箱、所需的工作区边界和远程执行放置仍然独立执行。请参阅 native 运行时权限。

范围和后端

Scope 控制创建多少个 containers/environments：

• agent：每个代理一个容器。
• session：每个会话一个容器。
• shared：所有被沙箱化的会话共享一个容器（在此作用范围下，按代理的 docker/ssh/browser 覆盖项会被忽略）。

具有经过验证的网关配置文件创建者所需的沙箱使用该配置文件作为其隔离边界。无论配置的范围如何，同一代理上的不同来宾都会收到单独的环境和工作区。由同一配置文件创建的会话重用其现有环境和工作区，包括当配置的范围为 session 时；这种重用不会重新设置这些路径的密钥。相反，频道、未知和其他非配置文件创建者会在每个解析的会话中收到一个单独的所需沙箱。匹配的原始 ID 无法重用配置文件的资源。所需的沙箱和只读工作空间上限仍然有效；后端故障永远不会退回到主机执行。没有角色所需的沙箱的会话将保留配置的范围行为。

当原始来宾访问被撤销时，注册的后台命令将保留该访问依赖性，并且即使在其前台轮流完成后也会被取消。关闭浏览器或停止一圈不会撤销此保留的访问权限。

OpenClaw 还会在原始访问权限下创建 Docker 或 Podman 容器时停止并验证该容器，并且每次使用都保留相同的原始邀请和配置文件。多个连接和会话可以共享该私有容器。撤销一个设备或来源会保留它，而另一个来源仍保持授权；撤销邀请就结束了所有的事情。这会保留已保存的工作区文件和容器的可写层；停止会丢失临时文件系统和进程状态。普通授权使用可以重启保留的容器；停止它并不会删除其邀请和个人资料历史记录。

不同的邀请、员工访问或非保密使用使该容器不符合此次关闭的资格。显式共享容器、网关启动时已存在的容器、沙箱浏览器和其他后端也保持运行。他们现有的取消所有者针对的是受影响的工作。当访问被撤销时，不能保证这些共享或非机密环境中的任意分离进程会停止。

creator 命名空间迁移 不会删除或采用旧的不明确工作区或容器。升级后，此类会话将使用单独的资源启动。在正常沙箱保留或手动清理之前保留任何所需的旧数据，然后以操作员身份显式恢复所选文件；不要自动将整个不明确的环境复制到受信任的配置文件工作区中。

非共享运行时身份还包括解析后的代理工作区路径。这可以防止共用主机且重复使用相同代理或会话键的工作区共享 Docker、浏览器、SSH、OpenShell 或插件提供的沙箱状态。shared 作用范围则有意与工作区无关。

从旧版本升级后的首次使用，会在包含工作区信息的身份下创建非共享运行时和沙箱工作区。现有的非共享运行时不会被接管；这是一次有意的重置。它们可以通过配置的清理设置自然过期，也可以使用 openclaw sandbox recreate 移除；下次使用时会为当前身份配置运行时。

Backend 控制哪个运行时执行沙盒工具。 Docker 和 Podman 共享 agents.defaults.sandbox.docker； SSH-特定配置位于agents.defaults.sandbox.ssh下； OpenShell-特定配置位于plugins.entries.openshell.config下； Crabbox 租赁设置位于 plugins.entries.crabbox.config.sandbox 下（请参阅 Crabbox 后端）。