命令策略

命令策略¶

设备配对后，节点命令必须满足三个要求才能被调用：

1. 节点必须在其经过身份验证的连接元数据（connect.commands）中声明该命令。
2. 该命令必须位于节点已配对设备记录上的已批准命令面中。
3. Gateway 的平台与批准衍生允许列表必须包含所声明的命令。

使用 openclaw nodes pending 和 openclaw nodes approve <nodeRequestId> 来批准待批准的命令面。此请求 ID 与设备请求 ID 不同。初始的未批准命令面没有任何有效命令。在待批准的扩展期间，只有先前已批准且仍然被声明并允许的命令保持有效。在这些检查之后，本地执行批准和操作系统权限仍然适用。

各平台的默认允许列表（在插件默认值和 commands.allow/commands.deny 覆盖之前）：

这些行描述的是 Gateway 策略上限，而非每个节点应用所实现的命令。只有当连接的节点也声明该命令时，该命令才可用。具体来说，Android 仅在启用 Accessibility Control 时才通告移动 UI 命令，桌面节点仅在其本地 Computer Control 执行器启用时才通告 computer.act。当前 macOS 应用不会声明 macOS 策略行中列出的设备和个人数据命令族。

插件拥有的默认值仅在插件支持的命令面上扩展平台表：

Canvas 命令在 macOS 应用的原生面板中呈现托管的 widget 文档。iOS、Android、Windows、Linux 和未知平台不会收到 Canvas 插件默认值。

talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once 默认允许任何通告 talk 能力或声明 talk.* 命令的节点使用，与平台标签无关。

桌面主机命令（macOS/Windows/Linux 上的 system.run、system.run.prepare、system.which、browser.proxy、browser.proxy.upload.v1、mcp.tools.call.v1、screen.snapshot 和 desktop.stream）不属于上述静态平台默认表的一部分。一旦操作员批准声明了这些命令的配对请求，它们就变为可用，之后节点的已批准命令集会将其在重新连接时继续保留。桌面共享在桌面节点上默认启用；Mac 应用在 设置 → 此 Mac → 功能 → 桌面共享 下提供其本地开关。

危险或隐私敏感性强的命令需要一次性持久选择加入 gateway.nodes.commands.allow，即使节点声明了它们：camera.snap、camera.clip、camera.ptz.control、screen.record、contacts.add、calendar.add、reminders.add、health.summary、sms.send、sms.search。gateway.nodes.commands.deny 始终优先于默认值和额外的允许列表条目。有关桌面访问的本地启用、配对、能力和工具策略门控，请参阅 已配对节点桌面、HealthKit 摘要 和 计算机使用。

插件拥有的节点命令可以添加 Gateway 节点调用策略。该策略在允许列表检查之后、转发到节点之前运行，因此原始 node.invoke、CLI 辅助工具和专用代理工具共享同一插件权限边界。危险的插件节点命令仍需要显式选择加入 gateway.nodes.commands.allow。

当节点扩展其已声明的命令、能力或权限后， 重新连接该节点，检查 openclaw nodes pending，并使用 openclaw nodes approve <nodeRequestId> 批准扩大后的范围。 移除声明不会授予新的访问权限，也不需要为扩展进行批准。

配置（openclaw.json）¶

节点相关设置位于 gateway.nodes 和 tools.exec 下：

{
  gateway: {
    nodes: {
      // Auto-approve first-time node pairing from trusted networks (CIDR list).
      // Disabled when unset. Only applies to first-time role:node requests
      // with no requested scopes; does not auto-approve upgrades. This
      // approves the device only: the node's command/capability surface still
      // needs `openclaw nodes approve <requestId>` (see `openclaw nodes
      // pending`), because device pairing alone must not grant commands.
      // Silent same-host pairing behaves the same way. SSH-verified pairing
      // and node-profile setup codes approve the initial surface, since both
      // record explicit machine-ownership or admin consent.
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
        // SSH-verified auto-approval (default: enabled). Approves first-time
        // node pairing on an exact device-key match read back over SSH.
        sshVerify: true,
      },
      // Trust agent-visible plugin tools published by paired nodes (default: true).
      pluginTools: {
        enabled: true,
      },
      // Persistently enable dangerous/privacy-heavy node commands.
      commands: {
        allow: ["camera.snap", "screen.record"],
        // Block exact command names even if defaults or commands.allow include them.
        deny: ["camera.clip"],
      },
    },
  },
  tools: {
    exec: {
      // Default exec host: "node" routes all exec calls to a paired node.
      host: "node",
      // Exec policy mode for node exec: allow only approved/allowlisted commands.
      mode: "allowlist",
      // Pin exec to a specific node (id or name). Omit to allow any node.
      node: "build-node",
    },
  },
}

使用确切的节点命令名称。即使平台默认设置或 commands.allow 条目本应允许某个命令，commands.deny 也会移除该命令。已配对的节点默认可以发布代理可见的插件工具描述符，但每个描述符的命令仍必须位于该节点已批准命令范围内。设置 gateway.nodes.pluginTools.enabled: false 可忽略所有这些描述符。有关 Gateway 节点配对和命令策略字段详情，请参阅 Gateway 配置参考。

每个代理的 exec 节点覆盖：

{
  agents: {
    entries: {
      main: {
        default: true,
        tools: { exec: { node: "build-node" } },
      },
    },
  },
}

权限映射¶

节点可以在 node.list / node.describe 中包含一个 permissions 映射，以权限名称为键（例如 screenRecording、accessibility、location），值为布尔值（true = 已授予）。