跳转至

沙箱 vs 工具策略 vs 提升权限

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

  1. 沙箱（agents.defaults.sandbox.*、agents.entries.*.sandbox.*，或必需的创建者角色策略）决定工具在哪里运行（沙箱后端 vs 主机）。
  2. 工具策略（tools.*、tools.sandbox.tools.*、agents.entries.*.tools.*）决定哪些工具可用/被允许。
  3. 提权（tools.elevated.*、agents.entries.*.tools.elevated.*）是从常规沙箱中逃逸的仅限 exec 的逃生舱（默认是 gateway，当执行目标配置为 node 时则是 node）。它不能绕过创建者角色的强制沙箱。

快速调试

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

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

它会输出：

  • 生效的沙箱模式/范围/工作区访问权限
  • 会话当前是否处于沙箱中（main 与 non-main）
  • 生效的沙箱工具允许/拒绝列表（以及它来自 agent/global/default 中的哪一层）
  • 提权门控和 fix-it 关键路径

沙箱：工具在哪里运行

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

  • "off"：会话在主机上运行，除非其创建者的操作者角色要求沙箱。
  • "non-main"：只有 non-main 会话会被沙箱化（对群组/频道来说常见的“意外”）。
  • "all"：所有内容都被沙箱化。

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到什么："none"、"ro" 或 "rw"。

带有 sandbox: "required" 的操作者角色会覆盖 agent 模式，无法通过提权执行或主机覆盖来绕过，并且当其沙箱无法配置时会失败关闭（fail closed）。参见 命名操作者角色。

完整的矩阵（范围、工作区挂载、镜像）请参见 沙箱。

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

  • docker.binds 会_穿透_沙箱文件系统：你挂载的任何内容都会以你设置的模式（:ro 或 :rw）在容器内可见。
  • 如果省略模式，默认为读写；对于源代码/机密信息，建议使用 :ro。
  • scope: "shared" 会忽略每个 agent 的绑定（仅应用全局绑定）。
  • OpenClaw 会对绑定来源进行两次验证：先验证规范化后的来源路径，然后在通过最深已存在祖先目录解析后再次验证。符号链接父目录逃逸无法绕过 blocked-path 或 allowed-root 检查。
  • 不存在的叶子路径仍会被安全检查。如果 /workspace/alias-out/new-file 通过符号链接的父目录解析到被阻止的路径，或超出配置的 allowed roots，绑定将被拒绝。
  • 绑定 /var/run/docker.sock 实际上将主机控制权交给了沙箱；请仅在有意为之的情况下这样做。
  • 工作区访问权限（workspaceAccess）独立于绑定模式。

有关包含多个主机文件夹、访问模式以及外部来源安全选择启用（opt-in）的每个 agent 配置，请参见 单个 agent 的多个文件夹。

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

有五个层很重要：

  • 工具配置文件：tools.profile 和 agents.entries.*.tools.profile（基础允许列表）
  • 提供方工具配置文件：tools.byProvider[provider].profile 和 agents.entries.*.tools.byProvider[provider].profile
  • 全局/每个 agent 的工具策略：tools.allow/tools.deny 和 agents.entries.*.tools.allow/agents.entries.*.tools.deny
  • 提供方工具策略：tools.byProvider[provider].allow/deny 和 agents.entries.*.tools.byProvider[provider].allow/deny
  • 沙箱工具策略（仅在沙箱化时生效）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 和 agents.entries.*.tools.sandbox.tools.*

经验法则：

  • deny 始终优先。
  • 如果 allow 非空，则其他所有内容都被视为阻止。
  • 工具策略是硬性停止：/exec 不能覆盖被拒绝的 exec 工具。
  • 工具策略按名称过滤工具的可用性；它不检查 exec 内部的副作用。如果 exec 被允许，拒绝 write、edit 或 apply_patch 并不会让 shell 命令变成只读。
  • /exec 只会为经过授权的发送者更改会话默认值；它不会授予工具访问权限。
  • 提供方工具键接受 provider（例如 anthropic）或 provider/model（例如 openai/gpt-5.4）。
  • 当工具策略步骤移除工具或沙箱工具策略阻止调用时，Gateway 日志会包含 agents/tool-policy 审计条目。使用 openclaw logs 查看规则标签、配置键和受影响的工具名称。

工具组（简写）

工具策略（全局、agent、沙箱）支持 group:* 条目，这些条目会展开为多个工具：

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

可用的组：

  • group:runtime：exec、process、code_execution（bash 可作为 exec 的别名）
  • group:fs：read、write、edit、apply_patch
  • group:sessions：sessions、sessions_list、sessions_history、sessions_search、conversations_list、conversations_send、conversations_turn、sessions_send、sessions_spawn、sessions_yield、subagents、session_status、suggest_task、dismiss_task
  • group:memory：memory_search、memory_get
  • group:web：web_search、x_search、web_fetch
  • group:ui：browser、screen、terminal、canvas、progress_card、show_widget
  • group:automation：heartbeat_respond、cron、gateway
  • group:messaging：message
  • group:nodes：nodes、computer
  • group:agents：agents_list、get_goal、create_goal、update_goal、progress_card、ask_user、skill_workshop
  • group:media：view_image、image_generate、music_generate、video_generate、tts、pdf
  • group:openclaw：大多数 OpenClaw 内置工具（不包括 read/write/edit/apply_patch/exec/process 这些 fs 和运行时原语、canvas，以及提供方插件）
  • group:plugins：所有已加载的插件所属工具，包括通过 bundle-mcp 暴露的已配置 MCP 服务器

对于只读代理，除非沙箱文件系统策略或独立的主机边界强制执行只读约束，否则还应拒绝 group:runtime 以及会修改文件系统的工具。

对于沙箱化的 MCP 服务器，沙箱工具策略是第二道允许门。如果已配置 mcp.servers，但沙箱回合中只显示内置工具，请将 bundle-mcp、group:plugins，或带服务器前缀的 MCP 工具名称/通配符（例如 outlook__send_mail 或 outlook__*）添加到 tools.sandbox.tools.alsoAllow，然后重启/重新加载网关并重新获取工具列表。服务器通配符使用提供程序安全的 MCP 服务器前缀：非 [A-Za-z0-9_-] 字符会变为 -，不以字母开头的名称会添加 mcp- 前缀，过长或重复的前缀可能会被截断或添加后缀。

openclaw doctor 目前会检查 mcp.servers 中由 OpenClaw 管理的服务器是否符合此结构。从捆绑插件清单或 Claude .mcp.json 加载的 MCP 服务器使用相同的沙箱门，但该诊断功能尚未枚举这些来源；如果它们的工具在沙箱回合中消失，请使用相同的允许列表条目。

提权：仅限 exec 的“在主机上运行”

提权不会授予额外工具；它只影响 exec。

  • 如果你通常处于沙箱中，/elevated on（或带有 elevated: true 的 exec）会在沙箱外运行（仍可能需要审批）。要求创建者角色的沙箱会拒绝提权执行。
  • 使用 /elevated full 可跳过该会话的 exec 审批。
  • 如果你已经直接运行，提权实际上是无操作（仍受门控）。
  • 提权不是技能作用域的，也不会覆盖工具允许/拒绝。
  • 提权不会授予来自 host=auto 的任意跨主机覆盖；它遵循正常的 exec 目标规则，并且仅当配置/会话目标已经是 node 时才保留 node。
  • /exec 与提权相互独立。它只为授权发送者调整每个会话的 exec 默认值。

门控：

  • 启用：tools.elevated.enabled（以及可选的 agents.entries.*.tools.elevated.enabled）
  • 发送者允许列表：tools.elevated.allowFrom.<provider>（以及可选的 agents.entries.*.tools.elevated.allowFrom.<provider>）

参见 提权模式。

常见“沙箱隔离”修复

“工具 X 被沙箱工具策略阻止”

修复键（任选其一）：

  • 禁用普通沙箱：agents.defaults.sandbox.mode=off（或按代理 agents.entries.*.sandbox.mode=off）；这不会覆盖创建者角色要求的沙箱。
  • 在沙箱内允许该工具：
  • 将其从 tools.sandbox.tools.deny（或按代理 agents.entries.*.tools.sandbox.tools.deny）中移除
  • 或将其添加到 tools.sandbox.tools.allow（或按代理允许列表）
  • 检查 openclaw logs 中的 agents/tool-policy 条目。它会记录沙箱模式，以及是允许规则还是拒绝规则阻止了该工具。

“我以为这是主会话，为什么它被沙箱化了？”

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw