在 OpenClaw 中遇到"工具被拒绝执行"这类问题时，很多人会第一时间怀疑是权限没配对——但官方文档特别指出，OpenClaw 实际上有三套相关但完全不同的控制机制，搞混它们是排障时最常见的坑。本文基于官方文档理清 Sandbox、Tool Policy、Elevated 各自的职责边界。
三层控制各管一件事
1. Sandbox（沙箱） 决定：工具在哪里运行（Docker 还是宿主机）
配置键：agents.defaults.sandbox.* / agents.list[].sandbox.*
2. Tool Policy（工具策略） 决定：哪些工具可用/被允许
配置键：tools.* / tools.sandbox.tools.* / agents.list[].tools.*
3. Elevated（提权） 仅针对：exec 的"逃生舱"——
在沙箱环境下临时切到宿主机执行
配置键：tools.elevated.* / agents.list[].tools.elevated.*
理解这三者独立且叠加生效，是排查"为什么这个工具用不了"这类问题的关键前提——三个控制点里任何一个说"不行"，结果就是不行。
第一步排障：用 sandbox explain 看真相
bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json这个命令会打印出当前生效的完整状态——沙箱模式/范围/工作区访问权限、当前会话是否真的处于沙箱中（区分 main 和非-main 会话）、沙箱下工具的有效允许/拒绝清单（以及这个清单是从 agent 级、全局级还是默认值继承来的）、以及提权的门禁状态和对应的修复配置键路径。排障永远从这条命令开始，比凭猜测改配置高效得多。
Sandbox：工具在哪跑
agents.defaults.sandbox.mode 三种取值：
"off" 全部在宿主机上运行
"non-main" 只有非-main 会话被沙箱化
（群组/频道场景下常见的"意外惊喜"来源）
"all" 所有会话都被沙箱化
Bind mounts 安全速查——这是容易被忽视的安全细节：
- docker.binds 会"穿透"沙箱文件系统：挂载的内容会以
你设置的模式（:ro 或 :rw）出现在容器内
- 省略模式默认是读写（read-write），涉及源码/密钥挂载
建议显式加 :ro
- scope: "shared" 会忽略 per-agent 绑定，只有全局绑定生效
- 挂载 /var/run/docker.sock 相当于把宿主机控制权交给了沙箱，
务必是有意为之才这么做
- workspaceAccess（"ro"/"rw"）和 bind 模式是相互独立的两个设置
Tool Policy：哪些工具存在/可调用
两条铁律，记住这两条能避免大部分困惑：
1. deny 永远优先生效
2. 一旦 allow 非空，其他所有未列出的工具都视为被拦截
Tool Policy 是硬性拦截——/exec 命令无法覆盖一个已被拒绝
的 exec 工具。/exec 只能改动已授权发送者的会话默认设置，
它本身不授予工具访问权限。
工具组简写能显著简化配置：
json5
{
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（或 exec 时带 elevated: true 参数）
会切到宿主机运行（审批可能仍然适用）
- /elevated full 可以为当前会话跳过 exec 审批
- 如果已经是非沙箱直接运行状态，elevated 基本是空操作
（仍受门禁约束）
- Elevated 不区分技能范围（skill-scoped），也不会覆盖
工具的 allow/deny 设置
- /exec 和 elevated 是两回事——/exec 只调整已授权发送者的
会话级 exec 默认行为
门禁配置键：
启用开关：tools.elevated.enabled
（及可选的 agents.list[].tools.elevated.enabled）
发送者白名单：tools.elevated.allowFrom.<provider>
（及可选的 agents.list[].tools.elevated.allowFrom.<provider>）
常见"沙箱越狱"问题的修复清单
"Tool X blocked by sandbox tool policy"
修复方式（任选一种）：
1. 关闭沙箱：agents.defaults.sandbox.mode=off
（或单独针对某 agent：agents.list[].sandbox.mode=off）
2. 在沙箱内放行该工具：
- 从 tools.sandbox.tools.deny 中移除
（或对应的 agents.list[].tools.sandbox.tools.deny）
- 或加入 tools.sandbox.tools.allow（或对应 agent 级 allow）
"我以为这是 main 会话，为什么被沙箱化了？"
在 "non-main" 模式下，群组/频道的 key 并不算 main。
用 sandbox explain 显示的 main 会话 key，
或者干脆把 mode 切成 "off"
实战建议
1. 遇到任何权限相关的报错，第一反应是跑一次
openclaw sandbox explain --json，而不是直接改配置猜
2. 涉及 docker.binds 挂载源码或密钥目录时，
养成显式写 :ro 的习惯，不要依赖"默认行为"
3. 团队/多agent场景，优先用 group:* 简写而不是逐个列举工具名，
减少遗漏和维护成本
4. Elevated 权限的 allowFrom 白名单要按 provider 精确配置，
避免"启用了但没限定谁能用"这种半成品配置
总结
Sandbox 决定"在哪跑"，Tool Policy 决定"能不能用"，Elevated 决定"沙箱里能不能临时越到宿主机跑 exec"——三者相互独立又叠加生效，任何一层说"不"结果就是不行。记住 openclaw sandbox explain 这一条命令，能省下大量对着配置文件瞎猜的时间。
来源：Sandbox vs Tool Policy vs Elevated — OpenClaw 官方文档