跳转至

命令策略

命令策略

设备配对后,节点命令在调用前必须满足三个要求:

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

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

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

平台 默认允许的命令
iOS camera.list、location.get、device.info、device.status、contacts.search、calendar.events、reminders.list、photos.latest、motion.activity、motion.pedometer、system.notify
watchOS device.info、device.status、system.notify
Android camera.list、location.get、notifications.list、notifications.actions、system.notify、device.info、device.status、device.permissions、device.health、device.apps、contacts.search、calendar.events、callLog.search、reminders.list、photos.latest、motion.activity、motion.pedometer、mobile.ui.observe、mobile.ui.act
macOS camera.list、camera.ptz.status、location.get、device.info、device.status、device.apps、contacts.search、calendar.events、reminders.list、photos.latest、motion.activity、motion.pedometer、system.notify、computer.act
Windows camera.list、location.get、device.info、device.status、system.notify、computer.act
Linux system.notify、computer.act(诸如 system.run 的节点主机命令受审批门控,见下文)

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

插件拥有的默认值仅针对该插件支持的命令面扩展平台表:

插件 平台 默认允许的命令
Canvas macOS canvas.present、canvas.hide、canvas.navigate

Canvas 命令在 macOS 应用的 native panel 中呈现托管的小部件文档。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 应用将其本地开关置于 Settings → This Mac → Capabilities → Desktop sharing 下。

危险或隐私敏感命令需要一次性持久选择加入,使用 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 策略。该策略在允许列表检查之后、转发到节点之前运行,因此原始 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.deny 会移除某个命令,即使平台默认设置或 commands.allow 条目本会允许该命令。已配对的节点默认可以发布代理可见的插件工具描述符,但每个描述符的命令仍必须位于节点的已批准命令范围内。设置 gateway.nodes.pluginTools.enabled: false 可忽略所有这些描述符。有关 Gateway 节点配对和命令策略字段详情,请参阅 Gateway 配置参考。

按代理的 exec 节点覆盖:

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

权限映射

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw