Sandbox vs Tool Policy vs Elevated（沙盒 vs 工具策略 vs 提权）

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

  1. Sandbox（沙盒）（agents.defaults.sandbox.* / agents.list[].sandbox.*）决定工具在哪里运行（Docker vs 主机）。
  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

它会打印：

  • 有效的沙盒模式/范围/工作区访问
  • 会话当前是否沙盒化（main vs non-main）
  • 有效的沙盒工具允许/拒绝（以及是否来自 agent/global/default）
  • 提权门控和修复键路径

Sandbox（沙盒）：工具在哪里运行

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

  • "off"：所有内容都在主机上运行。
  • "non-main"：仅非主会话被沙盒化（组/频道的常见"惊喜"）。
  • "all"：所有内容都被沙盒化。

完整矩阵（范围、工作区挂载、镜像）请参阅 Sandboxing。

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

  • docker.binds 穿透沙盒文件系统：无论你挂载什么，都以你设置的模式（:ro 或 :rw）在容器内可见。
  • 如果省略模式，默认为读写；对于源代码/机密，首选 :ro。
  • scope: "shared" 忽略每个 agent 的绑定（仅应用全局绑定）。
  • 绑定 /var/run/docker.sock 实际上将主机控制权交给了沙盒；仅在有意时才这样做。
  • 工作区访问（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 的工具策略：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 非空，其他所有内容都被视为被阻止。
  • 工具策略是硬停止：/exec 无法覆盖被拒绝的 exec 工具。
  • /exec 仅更改授权发送者的会话默认值；它不授予工具访问权限。 Provider tool 键接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.2）。

Tool groups（工具组）（简写）

工具策略（全局、agent、沙盒）支持 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 插件）

Elevated（提权）：仅限 exec 的"在主机上运行"

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

  • 如果你被沙盒化，/elevated on（或带有 elevated: true 的 exec）在主机上运行（可能仍需要审批）。
  • 使用 /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）

"我以为这是 main，为什么被沙盒化？"

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

← 返回文档首页