Skip to content

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 实际 在做什么:

bash
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:

json5
{
  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"。