模式、作用域和后端

模式、作用域和后端设置，创建者角色要求如何覆盖 Agent 模式，以及运行时身份包含哪些内容。

模式、作用域和后端¶

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

模式控制何时应用沙箱：

• off：不进行 Agent 级沙箱；创建者角色要求沙箱的会话仍会在沙箱中运行。
• non-main：除 Agent 的主会话外，对所有会话进行沙箱化。主会话键始终为 agent:<agentId>:main（当 session.scope 为 "global" 时为 global）；该键不可配置。群组/频道会话使用各自的键，因此它们始终被视为非主会话并被沙箱化。
• all：每个会话都在沙箱中运行。

将命名操作员角色的 sandbox 策略设置为 "required"，即可对该角色新建的会话进行沙箱化，无论 Agent 模式如何。创建者要求对会话而言是不可变的；不可用的后端会按失败关闭处理，提权执行或 Gateway/节点主机覆盖设置无法绕过它。默认的 "inherit" 保留现有的 Agent 模式行为。请参阅命名操作员角色。

按聊天退出沙箱¶

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

为了保证竞态安全更新，请包含 expectedSessionId、expectedLifecycleRevision 和 expectedSandboxMode（null 表示没有覆盖）。过期的期望值会拒绝该变更，而不会更改已被替换的聊天或覆盖其他选择。sessions.patchMany 支持相同的沙箱变更，可对每个目标设置期望值。在更改沙箱模式之前，请停止任何正在运行的任务；Gateway 在提交前会再次检查，绝不会在正在进行的轮次中更改隔离。

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

当管理员明确选择原生 Agent 自身的权限时，原生运行时的选择和发送可以提供继续此聊天选项。这会将可选的沙箱退出与绑定到该聊天和运行时的完全访问和同意结合起来。可选的原生工具和工作区限制随后委托给原生 Agent；由 OpenClaw 托管的工具保留其现有策略。发送被拒绝后，确认会保存权限并重试该消息一次。仅选择的确认不会发送草稿。两者都不会更改全局设置。原生同意会在重置或运行时更改时被清除，并且永远不会被分支继承。强制沙箱、强制工作区边界和远程执行放置仍然独立实施。请参阅原生运行时权限。

作用域和后端¶

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

• agent：每个 Agent 一个容器。
• session：每个会话一个容器。
• shared：所有沙箱会话共享一个容器（在此作用域下，每个 Agent 的 docker/ssh/browser 覆盖设置会被忽略）。

对于创建者已通过 Gateway 配置文件验证的强制沙箱，该配置文件将作为其隔离边界。同一 Agent 上的不同访客会获得独立的环境和工作区，无论配置的作用域如何。由同一配置文件创建的会话会复用其现有的环境和工作区，即使配置的作用域为 session 也是如此；这种复用不会重新生成这些路径的密钥。频道、未知及其他非配置文件创建者则会为每个规范会话获得一个独立的强制沙箱。匹配的原始 ID 不能复用配置文件的资源。强制沙箱和只读工作区上限仍然有效；后端失败绝不会回退到主机执行。没有角色强制沙箱要求的会话保持配置的作用域行为。

当原始的 Guest 访问被撤销时，已注册的后台命令仍保留该访问依赖，并且即使其前台轮次结束后也会被取消。关闭浏览器或停止一个轮次并不会撤销此保留的访问。

如果 OpenClaw 是在原始访问下创建了某个 Docker 或 Podman 容器，且该容器的每次使用都保持相同的原始邀请和配置文件，则 OpenClaw 也会停止并验证该容器。多个连接和会话可以共享该私有容器。撤销一个设备或来源会保留该容器，只要另一个来源仍然获得授权；撤销邀请则会终止所有连接和会话。这样可以保留已保存的工作区文件和容器的可写层；停止则会丢失临时文件系统和进程状态。普通的授权使用可以重新启动保留的容器；停止它并不会抹除其邀请和配置文件历史。

不同的邀请、staff 访问或未分类的使用会使该容器不符合此关闭条件。显式共享的容器、Gateway 启动时已存在的容器、沙箱浏览器以及其他后端也会保持运行。其现有的取消所有者会针对受影响的工作执行取消。在这些共享或未分类的环境中，任意分离的进程在访问被撤销时并不保证会被停止。

creator 命名空间迁移 不会删除或接管旧的模糊工作区或容器。此类会话 在升级后从独立资源开始。在常规沙箱保留策略或手动清理之前， 请保留任何需要的旧数据，然后以操作员身份显式恢复所选文件； 不要自动将整个模糊环境复制到受信任的个人工作区中。

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

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

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