执行审批

执行审批是配套应用/节点主机的安全护栏，用于允许沙箱隔离的智能体在真实主机（gateway 或 node）上运行命令。可以将其理解为安全联锁：只有当策略 + 允许列表 +（可选的）用户审批都同意时，命令才会被允许执行。执行审批是附加于工具策略和提权门控之上的（除非 elevated 设置为 full，这会跳过审批）。生效策略取 tools.exec.* 和审批默认值中更严格的一方；如果审批字段被省略，则使用 tools.exec 的值。

如果配套应用 UI 不可用，任何需要提示的请求都将由 ask fallback（默认：deny）决定。

适用范围

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

gateway 主机 → gateway 机器上的 coderclaw 进程
node 主机 → 节点运行器（macOS 配套应用或无头节点主机）

macOS 分工：

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

设置和存储

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

~/.coderclaw/exec-approvals.json

示例结构：

{
  "version": 1,
  "socket": {
    "path": "~/.coderclaw/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：阻止所有主机执行请求。
allowlist：仅允许在允许列表中的命令。
full：允许所有命令（等同于提权模式）。

Ask（`exec.ask`）

off：从不提示。
on-miss：仅在允许列表未匹配时提示。
always：每次命令都提示。

Ask fallback（`askFallback`）

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

deny：阻止。
allowlist：仅在允许列表匹配时允许。
full：允许。

允许列表（按智能体）

允许列表是按智能体配置的。如果存在多个智能体，请在 macOS 应用中切换要编辑的智能体。模式匹配不区分大小写。模式应解析为二进制路径（仅包含基本名称的条目会被忽略）。旧版 agents.default 条目在加载时会迁移到 agents.main。

示例：

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

每个允许列表条目会跟踪：

id 用于 UI 标识的稳定 UUID（可选）
last used 时间戳
last used command
last resolved path

自动允许 skill CLI

启用 Auto-allow skill CLIs 后，已知 Skills 引用的可执行文件在节点（macOS 节点或无头节点主机）上被视为已列入允许列表。这通过 Gateway RPC 的 skills.bins 获取 skill 二进制列表。如果你想要严格的手动允许列表，请禁用此选项。

安全二进制（仅限标准输入）

tools.exec.safeBins 定义了一小组仅限标准输入的二进制文件（例如 jq），这些文件可以在允许列表模式下运行，无需显式的允许列表条目。安全二进制会拒绝位置文件参数和类路径标记，因此它们只能操作传入的流。在允许列表模式下，shell 链式命令和重定向不会被自动允许。

当每个顶级段都满足允许列表（包括安全二进制或 skill 自动允许）时，允许 shell 链式命令（&&、||、;）。重定向在允许列表模式下仍不受支持。命令替换（$() / 反引号）在允许列表解析期间会被拒绝，包括在双引号内；如果你需要字面的 $() 文本，请使用单引号。

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

Control UI 编辑

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

目标选择器可选择 Gateway（本地审批）或 Node。节点必须通告 system.execApprovals.get/set（macOS 应用或无头节点主机）。如果节点尚未通告执行审批，请直接编辑其本地的 ~/.coderclaw/exec-approvals.json。

CLI：coderclaw approvals 支持 gateway 或 node 编辑（参见 Approvals CLI）。

审批流程

当需要提示时，gateway 向操作员客户端广播 exec.approval.requested。 Control UI 和 macOS 应用通过 exec.approval.resolve 进行处理，然后 gateway 将已批准的请求转发给节点主机。

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

确认对话框包括：

命令 + 参数
cwd
智能体 id
解析后的可执行文件路径
主机 + 策略元数据

操作：

Allow once → 立即运行
Always allow → 添加到允许列表 + 运行
Deny → 阻止

审批转发到聊天渠道

你可以将执行审批提示转发到任何聊天渠道（包括插件渠道），并使用 /approve 进行批准。这使用正常的出站投递管道。

配置：

{
  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，token 存储在 exec-approvals.json 中。
同 UID 对端检查。
挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。

系统事件

执行生命周期以系统消息的形式呈现：

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

这些消息在节点报告事件后发布到智能体的会话中。 Gateway 主机执行审批在命令完成时（以及可选地在运行时间超过阈值时）发出相同的生命周期事件。经过审批门控的执行会复用审批 id 作为这些消息中的 runId，以便于关联。

影响

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

执行审批

执行审批

适用范围

设置和存储

策略选项

Security（exec.security）

Ask（exec.ask）

Ask fallback（askFallback）

允许列表（按智能体）

自动允许 skill CLI

安全二进制（仅限标准输入）

Control UI 编辑

审批流程

审批转发到聊天渠道

macOS IPC 流程

系统事件

影响

Security（`exec.security`）

Ask（`exec.ask`）

Ask fallback（`askFallback`）