Sandbox vs Tool Policy vs Elevated

OpenClaw 有三个相关（但不同）的控制面：

1. Sandbox（agents.defaults.sandbox.* / agents.list[].sandbox.*）决定 tools 在哪里运行（Docker vs 宿主机）。
2. Tool policy（tools.*、tools.sandbox.tools.*、agents.list[].tools.*）决定 哪些 tools 可用/可调用。
3. Elevated（tools.elevated.*、agents.list[].tools.elevated.*）是一个 仅针对 exec 的逃生阀：当你在沙箱里时，让 exec 在宿主机上运行。

快速排障

用检查器看 OpenClaw 实际 在做什么：

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

它会打印：

• 实际生效的 sandbox mode/scope/workspace access
• 当前 session 是否处于沙箱（main vs non-main）
• 实际生效的沙箱内 tool allow/deny（以及来源：agent/global/default）
• elevated gates 与可修复的 key paths

Sandbox：tools 在哪里运行

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

• "off"：一切在宿主机上运行。
• "non-main"：只把 non-main sessions 放进沙箱（群聊/频道常见“意外”来源）。
• "all"：所有都沙箱化。

完整矩阵（scope、workspace mounts、images）见 Sandboxing。

Bind mounts（安全快速检查）

• docker.binds 会“刺穿”沙箱文件系统：你挂载的内容会以你设置的模式（:ro 或 :rw）直接在容器内可见。
• 如果省略 mode，默认是读写；源码/密钥优先用 :ro。
• scope: "shared" 会忽略 per-agent binds（只应用全局 binds）。
• 绑定 /var/run/docker.sock 实质上把宿主机控制权交给沙箱；只能在你明确要这样做时使用。
• workspace access（workspaceAccess: "ro"/"rw"）与 bind 的模式彼此独立。

Tool policy：哪些 tools 存在/可被调用

有两层会影响结果：

• Tool profile：tools.profile 与 agents.list[].tools.profile（基础 allowlist）
• Provider tool profile：tools.byProvider[provider].profile 与 agents.list[].tools.byProvider[provider].profile
• 全局/按 agent 的 tool policy：tools.allow/tools.deny 与 agents.list[].tools.allow/agents.list[].tools.deny
• 按 provider 的 tool policy：tools.byProvider[provider].allow/deny 与 agents.list[].tools.byProvider[provider].allow/deny
• 沙箱内 tool policy（仅在沙箱时生效）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 与 agents.list[].tools.sandbox.tools.*

经验法则：

• deny 永远优先。
• 如果 allow 非空，其他所有都视为 blocked。
• tool policy 是硬停止：/exec 不能覆盖被 deny 的 exec tool。
• /exec 只会改变已授权发送者的 session 默认值；它不会赋予 tool 权限。 provider tool keys 既支持 provider（例如 google-antigravity）也支持 provider/model（例如 openai/gpt-5.2）。

Tool groups（快捷写法）

tool policies（全局、agent、sandbox）支持 group:* 条目，会展开为多个 tools：

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

可用 groups：

• 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 tools（不包含 provider plugins）

Elevated：仅针对 exec 的“在宿主机运行”

Elevated 不会 赋予更多 tools；它只影响 exec。

• 如果你在沙箱里，/elevated on（或 exec 使用 elevated: true）会在宿主机上运行（仍可能需要 approvals）。
• 用 /elevated full 可以跳过该 session 的 exec approvals。
• 如果你已经在宿主机直连执行，elevated 基本是 no-op（但仍受门禁控制）。
• Elevated 不按 skill 作用域，并且 不会 覆盖 tool allow/deny。
• /exec 与 elevated 是两件事：它只会调整已授权发送者的 per-session exec 默认值。

门禁（Gates）：

• 启用开关：tools.elevated.enabled（以及可选的 agents.list[].tools.elevated.enabled）
• 发送者 allowlists：tools.elevated.allowFrom.<provider>（以及可选的 agents.list[].tools.elevated.allowFrom.<provider>）

参见 Elevated Mode。

常见的 “sandbox jail” 修复

“Tool X 被沙箱内 tool policy 阻止”

可修复的 key（任选其一）：

• 关闭沙箱：agents.defaults.sandbox.mode=off（或 per-agent：agents.list[].sandbox.mode=off）
• 允许该 tool 在沙箱内运行：
  • 从 tools.sandbox.tools.deny 移除（或 per-agent：agents.list[].tools.sandbox.tools.deny）
  • 或加入 tools.sandbox.tools.allow（或 per-agent allow）

“我以为这是 main，为什么会被沙箱化？”

在 "non-main" 模式下，群聊/频道的 key 不是 main。请使用 main session key（sandbox explain 会显示），或把 mode 改为 "off"。