Node 命令策略

命令策略

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

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

使用 openclaw nodes pending 和 openclaw nodes approve <nodeRequestId> 批准待处理的曲面。该请求 ID 与设备请求 ID 不同。初始未经批准的表面没有有效命令。在待扩展期间，只有先前批准的仍然声明和允许的命令才有效。这些检查后，本地执行批准和操作系统权限仍然适用。

按平台划分的默认允许列表（在插件默认值以及 commands.allow/commands.deny 覆盖之前）：

这些行描述了网关策略上限，而不是每个节点应用程序实现的命令。仅当连接的节点也声明该命令时，该命令才可用。特别是，Android 仅在启用辅助功能 Control 时才通告移动 UI 命令，而桌面节点仅在启用其本地计算机 Control 实现器时通告 computer.act。当前的 macOS 应用程序不会声明 macOS 策略行中列出的设备和个人数据系列。

插件拥有的默认值仅针对插件支持的表面扩展平台表：

Canvas 命令在 macOS 应用程序的本机面板中显示托管小部件文档。 iOS、Android、Windows、Linux 和未知平台不接收 Canvas 插件默认值。

talk.ptt.start、talk.ptt.stop、talk.ptt.cancel 和 talk.ptt.once 对于任何声明了 talk 能力或声明了 talk.* 命令的节点，都会默认允许，与平台标记无关。

桌面主机命令（system.run、system.run.prepare、system.which、browser.proxy、browser.proxy.upload.v1、mcp.tools.call.v1、screen.snapshot 和 macOS/Windows/Linux 上的 desktop.stream）不属于上面的静态平台默认表。一旦操作员批准了声明它们的配对请求，它们就变得可用，之后节点批准的命令集在重新连接时将它们向前传送。桌面节点默认开启桌面共享； 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 摘要 和 计算机使用 实现围绕桌面访问的本地启用、配对、功能和工具策略门。

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

节点扩展其声明的命令、功能或权限后，重新连接它，检查 openclaw nodes pending，并使用 openclaw nodes approve <nodeRequestId> 批准扩展的表面。删除声明并不授予新的访问权限或需要批准才能进行扩展。

配置（openclaw.json）

Node-相关设置位于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 以忽略所有此类描述符。有关网关节点配对和命令策略字段详细信息，请参阅 网关配置参考。

按代理覆盖 exec 节点：

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

权限映射

节点可能包括 node.list / node.describe 中的 permissions 映射，由权限名称（e.g. screenRecording、accessibility、location）和布尔值（true = 已授予）作为键控。