一句话定义

  • 这一组命令负责 headless node host、自有设备节点、远程通知、摄像头、位置、屏幕录制、canvas 展示与远程执行。

解决的问题

  • node 和 nodes 的区别是什么
  • 如何查看已配对设备状态
  • 如何远程发通知、拍照、录屏、取位置
  • 如何在节点上执行命令
  • 如何管理 canvas / A2UI 相关能力

核心机制

  • node：管理 headless node host 服务本身。
  • nodes：通过 gateway 管理和调用已配对节点。
  • qr：生成配对二维码 / setup code。
  • dns：配合 wide-area discovery 做网络发现辅助。

关键组成

1. Node host 服务管理

openclaw node run --host <gateway-host> --port 18789
openclaw node status
openclaw node install
openclaw node uninstall
openclaw node stop
openclaw node restart

适合场景：

  • 单独部署 headless node host
  • 把某台机器作为被 gateway 调用的节点端

2. 已配对节点管理

openclaw nodes status
openclaw nodes list
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes describe --node <id>
openclaw nodes rename --node <id> --name <displayName>
openclaw nodes remove --node <id|name|ip>
openclaw nodes push --node <id>  -- 发送 APNs 测试推送到 iOS 节点

说明：

  • remove、rename、pending、reject、push 为 v2026.5.26 新增子命令

3. 节点命令与通知

openclaw nodes invoke --node <id> --command <command> --params '{"name":"uname"}'
openclaw nodes run --node <id> -- <command>
openclaw nodes notify --node <id> --body "任务完成"

4. 摄像头、屏幕、位置与 canvas

openclaw nodes camera list --node <id>
openclaw nodes camera snap --node <id>
openclaw nodes camera clip --node <id> --duration 10s
openclaw nodes screen record --node <id> --duration 10s  -- v2026.5.26 新增
openclaw nodes location get --node <id>
openclaw nodes canvas snapshot --node <id>
openclaw nodes canvas present --node <id> --target https://example.com
openclaw nodes canvas navigate https://example.com --node <id>
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas a2ui push --node <id> --text "..."
openclaw nodes canvas a2ui reset --node <id>
openclaw nodes canvas hide --node <id>

说明：

  • screen 是 v2026.5.26 新增的 nodes 子命令（screen record）
  • camera 子命令：list、snap、clip
  • canvas 子命令：snapshot、present、hide、navigate、eval、a2ui push|reset

5. 配对与发现辅助

openclaw qr
openclaw dns setup

生命周期 / 执行流程

新设备接入

  1. openclaw qr 或配对流程发起
  2. openclaw nodes pending
  3. openclaw nodes approve <requestId>
  4. openclaw nodes status
  5. openclaw nodes describe --node <id>

做一次远程能力调用

  1. openclaw nodes status
  2. openclaw nodes describe --node <id>
  3. 根据能力执行 notify / run / camera / location / screen / canvas

排查节点为什么不可用

  1. openclaw nodes status
  2. openclaw nodes describe --node <id>
  3. 回到 gateway 层检查状态与日志
  4. 如果是 host 端问题，再看 openclaw node status

高频命令组合

查看节点并发通知

openclaw nodes status
openclaw nodes notify --node mac --body "服务器任务完成"

远程拍照与定位

openclaw nodes camera snap --node iphone
openclaw nodes location get --node iphone

远程执行命令

openclaw nodes run --node mac -- "uname -a"

边界与限制

  • node 与 nodes 是不同层级：一个是 host 服务，一个是已配对节点集合。
  • 并不是每种节点都支持所有能力，例如通知、摄像头、shell 命令可能依平台而异。
  • 摄像头、位置、录屏等能力依赖设备权限与授权状态。

常见误区

  • 误区 1：把 node status 当作 nodes status 的替代。它们关注点不同。
  • 误区 2：节点在线就一定支持所有能力。要先 describe 看 capabilities。
  • 误区 3：配对完成就万事大吉。很多设备能力还受系统权限控制。

对比项

  • node：本机 / 目标机 node host 服务维度
  • nodes：gateway 统一管理的已配对节点维度
  • browser：本地专用浏览器自动化
  • nodes canvas：节点端画布 / 展示能力