命令策略
命令策略¶
设备配对后,节点命令在调用前必须满足三个要求:
- 节点必须在经过身份验证的连接元数据(
connect.commands)中声明该命令。 - 该命令必须位于节点在其配对设备记录中的已批准命令面内。
- 网关基于平台和审批派生的允许列表必须包含已声明的命令。
使用 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 节点覆盖:
权限映射¶
节点可以在 node.list / node.describe 中包含一个 permissions 映射,以权限名称(例如 screenRecording、accessibility、location)为键,值为布尔值(true = 已授予)。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw