ClawCN - OpenClaw 中文版

主题

Exec 审批 ​

Exec 审批是伴侣应用 / 节点主机的防护机制,用于让沙箱化的代理在真实主机上运行命令(gateway 或 node)。可以将其视为安全联锁:只有当策略 + 白名单 + (可选)用户审批全部同意时才允许命令执行。 Exec 审批是在工具策略和提升门控之外的额外机制(除非 elevated 设置为 full,这会跳过审批)。 有效策略是 tools.exec.* 和审批默认值中更严格的那个;如果省略了审批字段,则使用 tools.exec 值。

如果伴侣应用 UI 不可用,任何需要提示的请求都会通过询问回退(默认:拒绝)来解决。

适用范围 ​

Exec 审批在执行主机上本地强制执行:

  • 网关主机 → 网关机器上的 openclaw 进程
  • 节点主机 → 节点运行器(macOS 伴侣应用或无头节点主机)

macOS 拆分:

  • 节点主机服务通过本地 IPC 将 system.run 转发到 macOS 应用。
  • macOS 应用强制执行审批并在 UI 上下文中执行命令。

设置和存储 ​

审批存储在执行主机上的本地 JSON 文件中:

~/.openclaw/exec-approvals.json

示例模式:

json
{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

策略控制 ​

安全性 (exec.security) ​

  • deny: 阻止所有主机 exec 请求。
  • allowlist: 仅允许白名单中的命令。
  • full: 允许所有内容(等同于 elevated)。

询问 (exec.ask) ​

  • off: 永不提示。
  • on-miss: 仅在白名单不匹配时提示。
  • always: 每个命令都提示。

询问回退 (askFallback) ​

如果需要提示但无法访问 UI,回退决定:

  • deny: 阻止。
  • allowlist: 仅在白名单匹配时允许。
  • full: 允许。

白名单(按代理) ​

白名单是按代理的。如果存在多个代理,在 macOS 应用中切换你正在编辑的代理。模式是不区分大小写的 glob 匹配。 模式应解析为二进制路径(仅基本名称的条目会被忽略)。 旧版 agents.default 条目在加载时会迁移到 agents.main。

示例:

  • ~/Projects/**/bin/bird
  • ~/.local/bin/*
  • /opt/homebrew/bin/rg

每个白名单条目跟踪:

  • id 用于 UI 标识的稳定 UUID(可选)
  • 上次使用时间戳
  • 上次使用的命令
  • 上次解析的路径

自动允许技能 CLI ​

启用自动允许技能 CLI 后,已知技能引用的可执行文件在节点上(macOS 节点或无头节点主机)被视为白名单。这使用通过 Gateway RPC 的 skills.bins 来获取技能二进制列表。如果你想要严格的手动白名单,请禁用此功能。

安全二进制文件(仅 stdin) ​

tools.exec.safeBins 定义了一个小型仅 stdin 二进制文件列表(例如 jq),可以在白名单模式下运行,无需显式白名单条目。安全二进制文件拒绝位置文件参数和类路径令牌,因此只能对传入流进行操作。 在白名单模式下不会自动允许 Shell 链接和重定向。

当每个顶级段都满足白名单(包括安全二进制文件或技能自动允许)时,允许 Shell 链接(&&、||、;)。在白名单模式下重定向仍不支持。 在白名单解析期间拒绝命令替换($() / 反引号),包括在双引号内;如果需要字面 $() 文本,请使用单引号。

默认安全二进制文件: jq、grep、cut、sort、uniq、head、tail、tr、wc。

Control UI 编辑 ​

使用 Control UI → Nodes → Exec approvals 卡片来编辑默认值、按代理覆盖和白名单。选择一个范围(默认值或代理),调整策略,添加/删除白名单模式,然后保存。UI 显示每个模式的上次使用元数据,以便保持列表整洁。

目标选择器选择网关(本地审批)或节点。节点必须公布 system.execApprovals.get/set(macOS 应用或无头节点主机)。 如果节点尚未公布 exec 审批,直接编辑其本地 ~/.openclaw/exec-approvals.json。

CLI: openclaw approvals 支持网关或节点编辑(参见 审批 CLI)。

审批流程 ​

需要提示时,网关向操作员客户端广播 exec.approval.requested。 Control UI 和 macOS 应用通过 exec.approval.resolve 解析它,然后网关将批准的请求转发到节点主机。

需要审批时,exec 工具会立即返回审批 ID。使用该 ID 关联后续的系统事件(Exec finished / Exec denied)。如果在超时前没有到达决定,该请求将被视为审批超时,并作为拒绝原因呈现。

确认对话框包括:

  • 命令 + 参数
  • cwd
  • 代理 ID
  • 解析的可执行路径
  • 主机 + 策略元数据

操作:

  • 允许一次 → 立即运行
  • 始终允许 → 添加到白名单 + 运行
  • 拒绝 → 阻止

审批转发到聊天频道 ​

你可以将 exec 审批提示转发到任何聊天频道(包括插件频道),并使用 /approve 批准它们。这使用正常的出站传递管道。

配置:

json5
{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

在聊天中回复:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

macOS IPC 流程 ​

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

安全说明:

  • Unix socket 模式 0600,令牌存储在 exec-approvals.json。
  • 相同 UID 对等检查。
  • 挑战/响应(nonce + HMAC 令牌 + 请求哈希)+ 短 TTL。

系统事件 ​

Exec 生命周期作为系统消息呈现:

  • Exec running(仅当命令超过运行通知阈值时)
  • Exec finished
  • Exec denied

这些在节点报告事件后发布到代理的会话中。 网关主机 exec 审批在命令完成时(以及可选地当运行时间超过阈值时)发出相同的生命周期事件。 审批门控的 exec 在这些消息中重用审批 ID 作为 runId,以便轻松关联。

影响 ​

  • full 非常强大;尽可能首选白名单。
  • ask 让你保持了解,同时仍然允许快速审批。
  • 按代理白名单防止一个代理的审批泄漏到其他代理。
  • 审批仅适用于来自授权发送者的主机 exec 请求。未授权的发送者无法发出 /exec。
  • /exec security=full 是授权操作员的会话级便利功能,设计上跳过审批。 要硬性阻止主机 exec,将审批安全性设置为 deny,或通过工具策略拒绝 exec 工具。

相关: