沙箱 vs 工具策略 vs Elevated 模式

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

Sandbox（agents.defaults.sandbox.*）：决定工具在哪里运行（沙箱后端 vs 主机）
Tool policy（tools.*）：决定哪些工具可用/被允许
Elevated（tools.elevated.*）：仅针对 exec 的逃出沙箱开关

快速调试

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

输出内容：有效沙箱模式/scope/工作区访问、当前会话是否沙箱化、有效工具 allow/deny、elevated 门控。

沙箱：工具运行位置

agents.defaults.sandbox.mode 控制：

"off"：所有工具在主机运行
"non-main"：仅非主会话沙箱化（群组/channel 的常见”惊喜”）
"all"：所有工具沙箱化

工具策略：工具可用性

优先级（deny 始终优先）：

tools.profile / agents.list[].tools.profile（基础 allowlist）
tools.allow / tools.deny（全局/per-agent）
tools.byProvider[provider].allow/deny（provider 级别）
tools.sandbox.tools.allow/deny（仅沙箱内生效）

工具组快捷方式

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

组名	包含工具
`group:runtime`	`exec`, `process`, `code_execution`
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history` 等
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:openclaw`	所有内置 OpenClaw 工具

Elevated：exec 专用逃出沙箱

不授予额外工具，仅影响 exec
沙箱中 /elevated on 或 exec 带 elevated: true → 在沙箱外运行
/elevated full → 跳过 exec 审批
已在直连模式下运行时，elevated 实际上是空操作
不覆盖工具 allow/deny

门控配置：

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: { whatsapp: ["<phone>"] },
    },
  },
}

常见”沙箱监狱”修复

工具被沙箱工具策略阻止：

禁用沙箱：agents.defaults.sandbox.mode: "off"
或在沙箱内允许该工具：从 tools.sandbox.tools.deny 移除，或加入 tools.sandbox.tools.allow

以为是 main 会话但被沙箱化：

"non-main" 模式下，群组/channel key 不是 main
使用 sandbox explain 显示的 main session key，或切换模式为 "off"

相关链接

gateway-openshell — OpenShell 沙箱后端
gateway-troubleshooting — 故障排查