Sandbox vs Tool Policy vs Elevated

OpenClaw 有三种相关但不同的访问控制机制：

Sandbox（agents.defaults.sandbox.* / agents.list[].sandbox.*）决定工具在哪里运行（Docker 容器 vs 宿主机）。
Tool policy（tools.*、tools.sandbox.tools.*、agents.list[].tools.*）决定哪些工具可用/被允许调用。
Elevated（tools.elevated.*、agents.list[].tools.elevated.*）是仅限 exec 的逃生通道，让你在沙盒中仍能在宿主机上运行 exec。

快速调试

使用检查器查看 OpenClaw 的实际执行状态：

bash

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

输出内容包括：

生效中的沙盒 mode/scope/workspace access
当前会话是否处于沙盒中（main vs non-main）
生效中的沙盒工具允许/拒绝（以及来自 agent/global/default 的哪层）
elevated 门禁和修复建议配置路径

Sandbox：工具在哪里运行

沙盒由 agents.defaults.sandbox.mode 控制：

"off"：所有内容在宿主机上运行。
"non-main"：仅非主会话被沙盒化（群组/频道常见"意外"来源）。
"all"：所有内容都被沙盒化。

参见 Sandboxing 查看完整矩阵（作用域、工作区挂载、镜像）。

绑定挂载（安全速查）

docker.binds 会穿透沙盒文件系统：你挂载的内容在容器内以你设定的模式（:ro 或 :rw）可见。
省略模式时默认读写；源码/密钥推荐用 :ro。
scope: "shared" 忽略按 Agent 的绑定（仅全局绑定生效）。
绑定 /var/run/docker.sock 实际上将宿主机控制权交给沙盒，只有在有意为之时才这样做。
工作区访问权限（workspaceAccess: "ro"/"rw"）与绑定模式是独立的。

Tool policy：哪些工具存在/可调用

两个层级很重要：

工具 profile：tools.profile 和 agents.list[].tools.profile（基础白名单）
Provider 工具 profile：tools.byProvider[provider].profile 和 agents.list[].tools.byProvider[provider].profile
全局/按 Agent 工具策略：tools.allow/tools.deny 和 agents.list[].tools.allow/agents.list[].tools.deny
Provider 工具策略：tools.byProvider[provider].allow/deny 和 agents.list[].tools.byProvider[provider].allow/deny
沙盒工具策略（仅沙盒化时生效）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 和 agents.list[].tools.sandbox.tools.*

经验法则：

deny 始终优先。
若 allow 非空，其他所有工具视为被拦截。
工具策略是硬性阻断：/exec 不能绕过已被拒绝的 exec 工具。
/exec 只为授权发送方修改会话默认值，不授予工具访问权限。 Provider 工具 key 接受 provider（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）两种格式。

工具分组（简写）

工具策略（全局、agent、沙盒）支持展开为多个工具的 group:* 条目：

json5

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

可用分组：

group:runtime：exec、bash、process
group:fs：read、write、edit、apply_patch
group:sessions：sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
group:memory：memory_search、memory_get
group:ui：browser、canvas
group:automation：cron、gateway
group:messaging：message
group:nodes：nodes
group:openclaw：所有内置 OpenClaw 工具（不含 provider 插件）

Elevated：仅限 exec 的"在宿主机运行"

Elevated 不授予额外工具；它只影响 exec。

若处于沙盒中，/elevated on（或 exec 携带 elevated: true）会在宿主机上运行（审批仍可能适用）。
使用 /elevated full 跳过当前会话的 exec 审批。
若本来就是直接运行，elevated 实际上是无操作（仍受门禁限制）。
Elevated 不受技能作用域限制，也不覆盖工具允许/拒绝策略。
/exec 与 elevated 是分开的，它只为授权发送方调整会话级别的 exec 默认值。

门禁：

启用控制：tools.elevated.enabled（以及可选的 agents.list[].tools.elevated.enabled）
发送方白名单：tools.elevated.allowFrom.<provider>（以及可选的 agents.list[].tools.elevated.allowFrom.<provider>）

参见 Elevated Mode。

常见"沙盒牢笼"修复方案

"工具 X 被沙盒工具策略拦截"

修复方案（三选一）：

禁用沙盒：agents.defaults.sandbox.mode=off（或按 Agent agents.list[].sandbox.mode=off）
在沙盒内允许该工具：
- 从 tools.sandbox.tools.deny 移除（或按 Agent agents.list[].tools.sandbox.tools.deny）
- 或添加到 tools.sandbox.tools.allow（或按 Agent allow）

"我以为这是主会话，为什么被沙盒化了？"

在 "non-main" 模式下，群组/频道 key 不是 main。使用 sandbox explain 显示的主会话 key，或将模式切换为 "off"。

Sandbox vs Tool Policy vs Elevated ​

快速调试 ​

Sandbox：工具在哪里运行 ​

绑定挂载（安全速查） ​

Tool policy：哪些工具存在/可调用 ​

工具分组（简写） ​

Elevated：仅限 exec 的"在宿主机运行" ​

常见"沙盒牢笼"修复方案 ​

"工具 X 被沙盒工具策略拦截" ​

"我以为这是主会话，为什么被沙盒化了？" ​

相关文档 ​