Exec 审批

Exec 审批是配套应用 / Node 主机的安全防护机制，用于让沙箱中的 Agent 在真实主机（gateway 或 node）上运行命令。可以把它想象成一个安全联锁装置：只有当策略 + Allowlist +（可选的）用户审批全部同意时，命令才会被允许执行。Exec 审批是额外的安全层，在工具策略和提升权限控制之上（除非 elevated 设置为 full，这会跳过审批）。实际生效的策略是 tools.exec.* 和审批默认值中更严格的那个；如果审批字段被省略，则使用 tools.exec 的值。

如果配套应用界面不可用，任何需要提示的请求都会由 ask fallback（默认：拒绝）来决定。

适用范围

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

  • gateway host → Gateway 机器上的 openclaw 进程
  • node host → Node 运行器（macOS 配套应用或无头 Node 主机）

macOS 分工：

  • node host service 通过本地 IPC 将 system.run 转发给 macOS app
  • macOS app 强制执行审批 + 在 UI 上下文中执行命令

设置和存储

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

~/.openclaw/exec-approvals.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"
        }
      ]
    }
  }
}

策略选项

Security（exec.security）

  • deny：阻止所有主机 exec 请求
  • allowlist：只允许白名单中的命令
  • full：允许所有命令（等同于 elevated）

Ask（exec.ask）

  • off：从不提示
  • on-miss：仅当 Allowlist 不匹配时提示
  • always：每次命令都提示

Ask fallback（askFallback）

如果需要提示但无法访问 UI，fallback 决定如何处理：

  • deny：阻止
  • allowlist：仅当 Allowlist 匹配时允许
  • full：允许

Allowlist（每个 Agent 独立）

Allowlist 是按 Agent 独立配置的。如果存在多个 Agent，在 macOS 应用中切换你要编辑的 Agent。模式是不区分大小写的 glob 匹配。模式应该解析为二进制文件路径（仅基础名称的条目会被忽略）。旧版的 agents.default 条目在加载时会迁移到 agents.main。

示例：

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

每个 Allowlist 条目会跟踪：

  • id 用于 UI 标识的稳定 UUID（可选）
  • last used 时间戳
  • last used command 最后使用的命令
  • last resolved path 最后解析的路径

自动允许 Skill CLI

当启用 Auto-allow skill CLIs 时，已知 Skill 引用的可执行文件会在 Node（macOS Node 或无头 Node 主机）上被视为已加入白名单。这会通过 Gateway RPC 使用 skills.bins 来获取 Skill 二进制文件列表。如果你想要严格的手动白名单，可以禁用此选项。

Safe bins（仅 stdin）

tools.exec.safeBins 定义了一小部分仅 stdin 的二进制文件（例如 jq），它们可以在 Allowlist 模式下运行，无需显式的 Allowlist 条目。Safe bins 会拒绝位置文件参数和类似路径的 token，因此它们只能操作传入的流。Shell 链式命令和重定向在 Allowlist 模式下不会自动允许。

当每个顶级段都满足 Allowlist（包括 safe bins 或 Skill 自动允许）时，Shell 链式命令（&&、||、;）是允许的。重定向在 Allowlist 模式下仍然不支持。

默认的 safe bins：jq、grep、cut、sort、uniq、head、tail、tr、wc。

Control UI 编辑

使用 Control UI → Nodes → Exec approvals 卡片来编辑默认值、每个 Agent 的覆盖设置和 Allowlist。选择一个作用域（Defaults 或某个 Agent），调整策略，添加/删除 Allowlist 模式，然后点击 Save。UI 会显示每个模式的 last used 元数据，方便你保持列表整洁。

目标选择器可以选择 Gateway（本地审批）或某个 Node。Node 必须支持 system.execApprovals.get/set（macOS 应用或无头 Node 主机）。如果某个 Node 还不支持 exec 审批，直接编辑它本地的 ~/.openclaw/exec-approvals.json 文件。

CLI：openclaw approvals 支持 Gateway 或 Node 编辑（参见 Approvals CLI）。

审批流程

当需要提示时，Gateway 会向操作员客户端广播 exec.approval.requested。Control UI 和 macOS 应用通过 exec.approval.resolve 解决它，然后 Gateway 将批准的请求转发给 Node 主机。

当需要审批时，exec 工具会立即返回一个审批 ID。使用该 ID 来关联后续的系统事件（Exec finished / Exec denied）。如果在超时前没有收到决定，请求会被视为审批超时，并作为拒绝原因显示。

确认对话框包括：

  • 命令 + 参数
  • cwd（当前工作目录）
  • Agent ID
  • 解析的可执行文件路径
  • 主机 + 策略元数据

操作选项：

  • Allow once → 立即运行
  • Always allow → 添加到 Allowlist + 运行
  • Deny → 阻止

审批转发到聊天频道

你可以将 exec 审批提示转发到任何聊天 Channel（包括 Plugin Channel），并使用 /approve 来批准它们。这使用正常的出站传递管道。

配置：

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // 子字符串或正则表达式
      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，token 存储在 exec-approvals.json 中
  • 相同 UID 对等检查
  • 挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL

系统事件

Exec 生命周期会以系统消息的形式显示：

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

这些消息会在 Node 报告事件后发布到 Agent 的 Session。Gateway 主机的 exec 审批在命令完成时（以及可选地当运行时间超过阈值时）会发出相同的生命周期事件。需要审批的 exec 会重用审批 ID 作为这些消息中的 runId，方便关联。

注意事项

  • full 权限很强大；尽可能优先使用 Allowlist
  • ask 让你保持知情，同时仍允许快速审批
  • 每个 Agent 的 Allowlist 防止一个 Agent 的审批泄漏到其他 Agent
  • 审批仅适用于来自授权发送者的主机 exec 请求。未授权的发送者无法发出 /exec
  • /exec security=full 是授权操作员的 Session 级便利功能，设计上会跳过审批。要完全阻止主机 exec，将审批安全性设置为 deny，或通过工具策略拒绝 exec 工具

相关内容：