ClawCN - OpenClaw 中文版

主题

沙箱 vs 工具策略 vs 提权 ​

OpenClaw 有三个相关(但不同)的控制机制:

  1. 沙箱(agents.defaults.sandbox.* / agents.list[].sandbox.*)决定工具在哪里运行(Docker vs 主机)。
  2. 工具策略(tools.*、tools.sandbox.tools.*、agents.list[].tools.*)决定哪些工具可用/允许。
  3. 提权(tools.elevated.*、agents.list[].tools.elevated.*)是一个仅限执行的逃生舱口,用于在沙箱环境中在主机上运行。

快速调试 ​

使用检查器查看 OpenClaw _实际_正在做什么:

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

它会打印:

  • 有效的沙箱模式/作用域/工作区访问
  • 会话当前是否处于沙箱中(主会话 vs 非主会话)
  • 有效的沙箱工具允许/拒绝(以及它来自代理/全局/默认)
  • 提权门控和修复键路径

沙箱:工具运行位置 ​

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

  • "off":所有内容都在主机上运行。
  • "non-main":只有非主会话被沙箱化(群组/频道的常见"意外")。
  • "all":所有内容都被沙箱化。

有关完整矩阵(作用域、工作区挂载、镜像),请参阅 沙箱。

绑定挂载(安全快速检查) ​

  • docker.binds _穿透_沙箱文件系统:无论你挂载什么,都会以你设置的模式(:ro 或 :rw)在容器内可见。
  • 如果省略模式,默认为读写;对于源代码/密钥,首选 :ro。
  • scope: "shared" 忽略每个代理的绑定(仅应用全局绑定)。
  • 绑定 /var/run/docker.sock 实际上将主机控制权交给沙箱;只在有意为之时这样做。
  • 工作区访问(workspaceAccess: "ro"/"rw")独立于绑定模式。

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

两个层次很重要:

  • 工具配置文件:tools.profile 和 agents.list[].tools.profile(基础白名单)
  • 提供程序工具配置文件:tools.byProvider[provider].profile 和 agents.list[].tools.byProvider[provider].profile
  • 全局/每代理工具策略: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)。

工具组(简写) ​

工具策略(全局、代理、沙箱)支持可扩展为多个工具的 group:* 条目:

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 工具(不包括提供程序插件)

提权:仅限执行的"在主机上运行" ​

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

  • 如果你处于沙箱中,/elevated on(或带有 elevated: true 的 exec)在主机上运行(可能仍需要批准)。
  • 使用 /elevated full 跳过会话的执行批准。
  • 如果你已经直接运行,提权实际上是无操作(仍然受门控)。
  • 提权不限定于技能范围,不覆盖工具允许/拒绝。
  • /exec 与提权分离。它仅为授权发送者调整每会话执行默认值。

门控:

  • 启用:tools.elevated.enabled(以及可选的 agents.list[].tools.elevated.enabled)
  • 发送者白名单:tools.elevated.allowFrom.<provider>(以及可选的 agents.list[].tools.elevated.allowFrom.<provider>)

参阅 提权模式。

常见"沙箱监禁"修复 ​

"工具 X 被沙箱工具策略阻止" ​

修复键(选择一个):

  • 禁用沙箱:agents.defaults.sandbox.mode=off(或每代理 agents.list[].sandbox.mode=off)
  • 在沙箱内允许该工具:
    • 从 tools.sandbox.tools.deny(或每代理 agents.list[].tools.sandbox.tools.deny)中移除它
    • 或将其添加到 tools.sandbox.tools.allow(或每代理允许)

"我以为这是主会话,为什么被沙箱化了?" ​

在 "non-main" 模式下,群组/频道键_不是_主会话。使用主会话键(由 sandbox explain 显示)或将模式切换到 "off"。