Sandbox vs Tool Policy vs Elevated

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

  1. Sandbox（agents.defaults.sandbox.* / agents.list[].sandbox.*）决定工具在哪里运行（Docker 还是主机）。
  2. Tool policy（tools.*、tools.sandbox.tools.*、agents.list[].tools.*）决定哪些工具可用/允许使用。
  3. Elevated（tools.elevated.*、agents.list[].tools.elevated.*）是一个仅限 exec 的逃生舱口，让你在沙箱化时可以在主机上运行。

快速调试

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

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

它会打印：

  • 生效的 sandbox 模式/作用域/workspace 访问权限
  • 当前 session 是否被沙箱化（main vs non-main）
  • 生效的 sandbox tool 允许/拒绝规则（以及它来自 agent/全局/默认配置）
  • elevated 门控和修复配置项路径

Sandbox：工具在哪里运行

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

  • "off"：所有东西都在主机上运行。
  • "non-main"：只有非 main session 被沙箱化（群组/频道常见的”意外”情况）。
  • "all"：所有东西都被沙箱化。

查看 Sandboxing 了解完整矩阵（作用域、workspace 挂载、镜像）。

绑定挂载（安全快速检查）

  • docker.binds 穿透 sandbox 文件系统：你挂载的任何东西都会以你设置的模式（:ro 或 :rw）在容器内可见。
  • 如果省略模式，默认是读写；对于源代码/密钥，建议用 :ro。
  • scope: "shared" 会忽略每个 agent 的绑定（只应用全局绑定）。
  • 绑定 /var/run/docker.sock 实际上把主机控制权交给了 sandbox；只在有意为之时这样做。
  • Workspace 访问权限（workspaceAccess: "ro"/"rw"）独立于绑定模式。

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

两层配置很重要：

  • Tool profile：tools.profile 和 agents.list[].tools.profile（基础白名单）
  • 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
  • Sandbox tool policy（仅在沙箱化时应用）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 和 agents.list[].tools.sandbox.tools.*

经验法则：

  • deny 总是优先。
  • 如果 allow 非空，其他所有东西都被视为阻止。
  • Tool policy 是硬性限制：/exec 无法覆盖被拒绝的 exec 工具。
  • /exec 只为授权发送者更改 session 默认值；它不授予工具访问权限。 Provider tool 键接受 provider（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）。

Tool 组（简写）

Tool 策略（全局、agent、sandbox）支持 group:* 条目，可展开为多个工具：

{
  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 plugin）

Elevated：仅限 exec 的”在主机上运行”

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

  • 如果你被沙箱化了，/elevated on（或带 elevated: true 的 exec）会在主机上运行（可能仍需批准）。
  • 用 /elevated full 跳过该 session 的 exec 批准。
  • 如果你已经在直接运行，elevated 实际上是无操作（仍然有门控）。
  • Elevated 不是 skill 作用域的，也不会覆盖 tool 允许/拒绝规则。
  • /exec 与 elevated 是分开的。它只为授权发送者调整每个 session 的 exec 默认值。

门控：

  • 启用：tools.elevated.enabled（可选 agents.list[].tools.elevated.enabled）
  • 发送者白名单：tools.elevated.allowFrom.<provider>（可选 agents.list[].tools.elevated.allowFrom.<provider>）

查看 Elevated Mode。

常见 “sandbox jail” 修复方法

”Tool X blocked by sandbox tool policy”

修复配置项（选一个）：

  • 禁用 sandbox：agents.defaults.sandbox.mode=off（或每个 agent 的 agents.list[].sandbox.mode=off）
  • 在 sandbox 内允许该工具：
    • 从 tools.sandbox.tools.deny 中移除它（或每个 agent 的 agents.list[].tools.sandbox.tools.deny）
    • 或将它添加到 tools.sandbox.tools.allow（或每个 agent 的 allow）

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

在 "non-main" 模式下，群组/频道键不是 main。使用 main session 键（由 sandbox explain 显示）或将模式切换为 "off"。