设备命令

macOS 小组件面板¶

openclaw nodes canvas present --node <idOrNameOrIp>
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate "/__openclaw__/canvas/documents/<document-id>/index.html" --node <idOrNameOrIp>

说明：

• canvas present 接受现有的可选目标，外加 --x/--y/--width/--height 布局参数。
• canvas navigate 接受托管的小组件文档路径或应用本地 Canvas URL。macOS 应用会通过其当前作用域内的 Canvas 能力 URL 解析托管路径。
• 面向智能体的路径是 show_widget，其中 presentation.target: "node_panel"；如需直接由操作员控制，请使用 CLI 辅助命令。
• A2UI 在会话仪表盘上渲染，而不是通过节点 Canvas 命令。

照片和视频（节点摄像头）¶

照片（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: one node-selected photo
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera snap --node <idOrNameOrIp> --facing both # front then back (2 saved paths)
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

视频片段（mp4）：

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

说明：

• 对于 camera.*，节点必须处于前台（后台调用会返回 NODE_BACKGROUND_UNAVAILABLE）。
• 节点会限制片段时长，以保持 base64 载荷可管理（有关各平台的精确限制，请参见摄像头捕获）。nodes 智能体工具在转发调用之前，还会将请求的 durationMs 上限设为 300000（5 分钟）；节点本身会执行更严格的限制。
• Android 会在可能时请求 CAMERA/RECORD_AUDIO 权限；被拒绝的权限会以 *_PERMISSION_REQUIRED 失败。

屏幕录制（节点）¶

受支持的节点会暴露 screen.record（mp4）。示例：

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

说明：

• screen.record 的可用性取决于节点平台。
• nodes 智能体工具会将请求的 durationMs 上限设为 300000（5 分钟）；节点可能会执行更严格的限制，以限制返回的载荷大小。
• --no-audio 会在受支持的平台上禁用麦克风采集。
• 当有多个屏幕可用时，使用 --screen <index> 选择显示器（0 = 主屏幕）。

位置（节点）¶

当设置中启用位置时，节点会暴露 location.get。

CLI 辅助命令：

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

说明：

• 位置功能默认关闭。
• “始终”需要系统权限；后台获取为尽力而为。
• 响应包括纬度/经度、精度（米）和时间戳。
• 完整的参数/响应结构和错误代码：位置命令。

短信（Android 节点）¶

当用户授予 SMS 权限且设备支持电话功能时，Android 节点可以暴露 sms.send 和 sms.search。这两个命令默认具有危险性：网关操作员还必须将它们添加到 gateway.nodes.commands.allow 中，之后才能调用它们（参见命令策略）。

对于只读短信搜索，请在 openclaw.json 中显式选择加入：

{
  gateway: {
    nodes: {
      commands: { allow: ["sms.search"] },
    },
  },
}

仅当节点也需要能够发送消息时，才单独添加 sms.send。Android 权限和 Gateway 命令授权是相互独立的；授予手机权限不会修改 Gateway 策略。

低层调用：

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

说明：

• 可以在授予 READ_SMS 之前声明 sms.search，以便调用能够返回权限诊断信息；读取消息仍然需要该 Android 权限。
• 仅支持 Wi-Fi 且没有电话功能的设备不会通告 sms.send。
• requires explicit gateway.nodes.commands.allow opt-in 错误表示手机已声明该命令，但 Gateway 操作员尚未授权。

设备和个人数据命令¶

iOS 和 Android 节点默认会通告若干只读数据命令（参见命令策略表格）；Android 还会额外暴露一个更大的命令族，由其自身的应用内设置控制。macOS 或 headless-mac TypeScript 节点宿主只有在操作员使用 --share-installed-apps 启用已安装应用共享后，才会通告 device.apps。

可用命令族：

• device.status、device.info — iOS、Android、Windows。
• device.permissions、device.health — 仅 Android。
• device.apps — Android、macOS 和 headless-mac 节点。Android 需要在设置中启用已安装应用共享，默认返回启动器中可见的应用。TypeScript 节点宿主默认保持共享关闭，并接受 query、limit 和 includeSystem；macOS 结果包含 label、bundleId、path 和 system。
• notifications.list、notifications.actions — 仅 Android。
• photos.latest — iOS、Android。
• contacts.search — iOS、Android（默认只读）；contacts.add 具有危险性，需要 gateway.nodes.commands.allow。
• calendar.events — iOS、Android（默认只读）；calendar.add 具有危险性，需要 gateway.nodes.commands.allow。
• reminders.list — iOS、Android（默认只读）；reminders.add 具有危险性，需要 gateway.nodes.commands.allow。
• callLog.search — 仅 Android。
• motion.activity、motion.pedometer — iOS、Android；由可用传感器进行能力控制。

nodes 智能体工具的 invoke 操作接受用于节点 调用的 invokeTimeoutMs。除非显式设置 timeoutMs，Gateway 传输层会收到该 预算加上 30 秒，用于转发和响应。

调用示例：

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command device.apps --params '{"limit":10}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'