沙箱 vs 工具策略 vs Elevated

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

1. 沙箱（agents.defaults.sandbox.* / agents.list[].sandbox.*）决定工具在哪里运行（Docker 还是宿主机）。
2. 工具策略（tools.*、tools.sandbox.tools.*、agents.list[].tools.*）决定哪些工具可用/被允许。
3. Elevated（tools.elevated.*、agents.list[].tools.elevated.*）是一个仅限 exec 的逃生通道，允许在沙箱环境中直接在宿主机上执行。

快速排查

用 inspector 看看 OpenClaw 实际在做什么：

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

输出内容包括：

• 生效的沙箱模式/范围/工作区访问权限
• 当前会话是否处于沙箱中（main vs 非 main）
• 生效的沙箱工具允许/拒绝列表（以及配置来源：agent 级/全局/默认）
• elevated 门控和修复配置路径

沙箱：工具在哪里运行

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

• "off"：一切都在宿主机上运行。
• "non-main"：只有非 main 会话会被沙箱化（群组/频道进来会沙箱化，这是常见的”意外”）。
• "all"：所有会话都在沙箱中运行。

详见 沙箱 了解完整矩阵（范围、工作区挂载、镜像）。

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

• docker.binds 会穿透沙箱文件系统：你挂载的路径在容器内按你设定的模式（:ro 或 :rw）可见。
• 不指定模式时默认读写；源代码/密钥建议用 :ro。
• scope: "shared" 忽略每个 agent 的绑定（只有全局绑定生效）。
• 绑定 /var/run/docker.sock 等于把宿主机控制权交给沙箱——除非你清楚后果，否则不要这样做。
• 工作区访问（workspaceAccess: "ro"/"rw"）与绑定模式互相独立。

工具策略：哪些工具存在/可调用

两个层面需要关注：

• 工具 profile：tools.profile 和 agents.list[].tools.profile（基础白名单）
• 提供商工具 profile：tools.byProvider[provider].profile 和 agents.list[].tools.byProvider[provider].profile
• 全局/per-agent 工具策略：tools.allow/tools.deny 和 agents.list[].tools.allow/agents.list[].tools.deny
• 提供商工具策略：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（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）。

工具分组（简写）

工具策略（全局、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 工具（不含提供商插件）

Elevated：仅限 exec 的”宿主机执行”

Elevated 不会赋予额外工具权限，它只影响 exec。

• 在沙箱中，/elevated on（或 exec 带 elevated: true）在宿主机上执行（审批机制仍可能生效）。
• 使用 /elevated full 可跳过该会话的 exec 审批。
• 如果已经在宿主机上直接运行，elevated 相当于空操作（仍有门控）。
• Elevated 不按 skill 隔离，也不会覆盖工具 allow/deny。
• /exec 与 elevated 是独立的。它只为授权发送者调整每会话的 exec 默认值。

门控：

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

详见 Elevated 模式。

常见的”沙箱困局”修复方法

”Tool X blocked by sandbox tool policy”

修复配置键（任选其一）：

• 关闭沙箱：agents.defaults.sandbox.mode=off（或 per-agent agents.list[].sandbox.mode=off）
• 在沙箱中允许该工具：
  • 从 tools.sandbox.tools.deny（或 per-agent agents.list[].tools.sandbox.tools.deny）中移除
  • 或者添加到 tools.sandbox.tools.allow（或 per-agent allow）

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

在 "non-main" 模式下，群组/频道的 key 不是 main。用 sandbox explain 查看实际的 main session key，或者把模式切到 "off"。