Exec 审批

Exec 审批是伴侣应用/节点主机护栏，用于让沙箱代理在真实主机（gateway 或 node）上执行命令。可理解为安全联锁：仅当策略 + 白名单 +（可选）用户审批均通过时才允许执行。Exec 审批叠加在工具策略与 elevated 门控之上（除非 elevated 设为 full，此时跳过审批）。有效策略取 tools.exec.* 与审批默认中更严的一方；若审批某字段未设置，则使用 tools.exec 的值。若无法使用伴侣应用 UI，任何需要弹窗的请求将按 ask 回退（默认 deny）处理。

适用位置

审批在执行主机本地生效：

• 网关主机 → 网关机器上的 moltbot 进程
• 节点主机 → 节点运行器（macOS 伴侣应用或无头节点主机）

macOS 分工：

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

设置与存储

审批存储在执行主机上的本地 JSON 文件中：~/.clawdbot/exec-approvals.json。示例结构：

{
  "version": 1,
  "socket": {
    "path": "~/.clawdbot/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：仅在白名单未匹配时弹窗。
• always：每条命令都弹窗。

Ask 回退（askFallback）

当需要弹窗但无法连接 UI 时，由回退决定：

• deny：拒绝。
• allowlist：仅当白名单匹配时允许。
• full：允许。

白名单（按代理）

白名单按代理。若存在多个代理，在 macOS 应用中切换正在编辑的代理。模式为大小写不敏感的通配匹配。模式应解析为二进制路径（仅 basename 的条目会被忽略）。旧版 agents.default 条目在加载时会迁移到 agents.main。示例：

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

每个白名单条目可记录：id（稳定 UUID，用于 UI 标识，可选）、last used 时间戳、last used command、last resolved path。

自动允许技能 CLI

启用 Auto-allow skill CLIs 时，已知技能引用的可执行文件在节点（macOS 节点或无头节点主机）上视为已加入白名单。通过 Gateway RPC 的 skills.bins 获取技能 bin 列表。若需严格手动白名单可关闭此功能。

Safe bins（仅 stdin）

tools.exec.safeBins 定义少量仅 stdin 的二进制（如 jq），在 allowlist 模式下无需显式白名单条目即可运行。Safe bins 拒绝位置参数和路径形式 token，只能对传入流操作。Allowlist 模式下不支持 shell 链式和重定向。当每个顶层片段都满足白名单（含 safe bins 或技能自动允许）时，允许 shell 链式（&&、||、;）。Allowlist 模式下重定向仍不支持。默认 safe bins：jq、grep、cut、sort、uniq、head、tail、tr、wc。

控制 UI 编辑

在 Control UI → Nodes → Exec approvals 卡片中编辑默认值、每代理覆盖和白名单。选择范围（Defaults 或某代理）、调整策略、添加/删除白名单模式，然后 Save。UI 会显示每个模式的 last used 元数据便于维护。目标选择器可选 Gateway（本地审批）或 Node。节点须对外提供 system.execApprovals.get/set（macOS 应用或无头节点主机）。若节点尚未提供 exec 审批，可直接编辑其本地 ~/.clawdbot/exec-approvals.json。CLI：moltbot approvals 支持网关或节点编辑（见 审批 CLI）。

审批流程

当需要弹窗时，网关向操作端广播 exec.approval.requested。Control UI 与 macOS 应用通过 exec.approval.resolve 处理，网关再将已批准的请求转发给节点主机。当需要审批时，exec 工具会立即返回一个 approval id。用该 id 关联后续系统事件（Exec finished / Exec denied）。若在超时前无决定，请求按审批超时处理并作为拒绝原因展示。确认对话框包含：命令与参数、cwd、代理 id、解析后的可执行路径、主机与策略元数据。操作：Allow once → 立即执行；Always allow → 加入白名单并执行；Deny → 拒绝。

审批转发到聊天频道

可将 exec 审批弹窗转发到任意聊天频道（含插件频道），并用 /approve 审批。使用正常出站投递管道。配置示例：

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
      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 对等校验。Challenge/response（nonce + HMAC token + 请求哈希）+ 短 TTL。

系统事件

Exec 生命周期以系统消息形式发出：Exec running（仅当命令超过运行通知阈值时）、Exec finished、Exec denied。这些在节点上报事件后发往代理会话。网关主机的 exec 审批在命令结束（以及可选地运行超过阈值）时发出相同生命周期事件。需审批的 exec 在这些消息中用 approval id 作为 runId 便于关联。

影响

• full 权限大，尽量使用 allowlist。
• ask 让你保持知情的同时仍可快速批准。
• 按代理白名单避免不同代理的审批互相影响。
• 审批仅适用于授权发送方的主机 exec 请求。未授权发送方无法执行 /exec。
• /exec security=full 是面向授权操作员的会话级便利，设计上会跳过审批。要彻底禁止主机 exec，可将审批 security 设为 deny 或通过工具策略拒绝 exec 工具。

相关：

• Exec 工具
• Elevated 模式
• 技能