跳转至

openclaw nodes

管理已配对节点（设备）并调用节点能力。

相关：节点概述 - 活动电脑状态 - 摄像头节点 - 图像节点

每个子命令的通用选项：--url <url>、--token <token>、--timeout <ms>（默认随命令而异）、--json。

对于数值选项（如 --location-timeout、--max-age 和 --quality），省略该标志以使用其默认值。显式提供空值或仅含空白字符的值无效，并会在节点查找或 Gateway 请求之前失败。

状态

openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
openclaw nodes list
openclaw nodes describe --node <idOrNameOrIp>

status 和 list 都接受 --connected（仅显示已连接节点）和 --last-connected <duration>（例如 24h 或 7d，仅匹配该时长内连接过的节点）。两者都使用 Gateway 记录的最近连接时间，包括近期重连以及已知连接历史但已断开的节点。list 将待处理（pending）和已配对（paired）节点分别显示在两个表格中。已配对行显示最近的连接时长（最近连接）。status 显示一个合并表格，包含每个节点的能力、版本和最近输入详情。已连接的 macOS 节点无需额外权限即可报告与 OpenClaw 交互产生的活动。可选的系统级活动检测还会报告其他应用中的物理活动，并需要“辅助功能”权限。最新的一行标记为 active。请参阅活动电脑状态。describe 输出单个节点的能力、权限、活动以及有效/待执行的调用命令。

当主机统计信息可用时，status 会包含一段详细信息，例如 load 3.2/24 · mem 151/192 GB · disk 1.2 TB free。describe 在其 Stats 行中显示同样的摘要。Load 是 1 分钟平均值加 CPU 数量，内存为已用/总量，字节值采用二进制换算并使用 GB/TB 标签。不可用的负载或磁盘读数会被省略。离线节点显示保存的快照，并带有 (last known 27d ago) 这样的时长，该时长根据快照的原始时间戳计算。请参阅节点主机统计。

--node 接受精确 ID、IP 地址、显示名称或至少六个字符的 ID 前缀。精确 ID 和 IP 匹配优先于名称和前缀。在最强匹配中，已连接节点优先。如果当前客户端共享一个名称，请使用精确 ID 来消除歧义。客户端类型不会决定目标。旧版迁移例外仅在所有其他并列条目均为已知 Clawdbot 或 Moldbot 客户端时，才优先选择唯一的 OpenClaw 客户端。

配对

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name <displayName>

这些命令管理节点在配对设备记录上已获批准的命令/能力范围。设备配对（openclaw devices approve）控制节点 WebSocket connect 握手。

对于手动注册，首先批准设备请求，然后重启或因 PAIRING_REQUIRED 暂停的节点重新运行。其重新连接会创建 nodes pending 所显示的独立请求。批准该节点请求，其 ID 与设备请求 ID 不同。完整流程请参阅节点配对与状态。

  • remove 撤销设备的 node 角色，并清除其已批准和待处理的命令/能力范围。它会断开该设备的节点角色会话。混合角色设备会保留其记录和其他角色。仅节点角色的设备记录会被删除。
  • 即使工作进程清理报告错误，删除仍然有效：已撤销的节点连接仍会关闭。
  • pending 只需要 operator.pairing 作用域。
  • gateway.nodes.pairing.autoApproveCidrs 可批准明确受信任的首次 role: node 设备配对。默认关闭，且不批准角色升级或单独的命令范围。该请求仍会出现在 nodes pending 中。
  • gateway.nodes.pairing.sshVerify 默认开启。当网关能够通过 SSH 向节点主机验证设备密钥时，它会自动批准首次 role: node 设备配对。第一个能力范围会在同一步骤中获批准。请参阅节点配对。
  • approve 的作用域要求取决于待处理请求所声明的命令：
  • 无命令请求：operator.pairing
  • 普通节点命令：operator.pairing + operator.write
  • 管理员敏感命令（system.run、system.run.prepare、system.which、browser.proxy、browser.proxy.upload.v1、fs.listDir 和 system.execApprovals.get/set）：operator.pairing + operator.admin
  • 这些要求对通过 node.invoke 中继的节点命令进行分类。顶层 Gateway fs.listDir RPC 需要 operator.write 才能浏览工作区内的主机，并在存在 nodeId 时需要 operator.admin。
  • remove 作用域：operator.pairing 可以删除非操作员节点行。设备令牌调用方在混合角色设备上撤销自己的节点角色时，额外需要 operator.admin。

调用

openclaw nodes invoke --node <id> --command system.which --params '{"bins":["uname"]}'

标志：

  • --command <command>（必需）：例如 device.info。
  • --params <json>：JSON 对象字符串（默认 {}）。
  • --invoke-timeout <ms>：节点调用超时，为正整数（默认 15000）。
  • --timeout <ms>：Gateway 传输超时（默认 30000）。对于正数的调用超时，有效传输超时为 max(timeout, invokeTimeout + 10000)，从而在节点调用截止时间之外提供传输宽限。
  • --idempotency-key <key>：可选的非空幂等键。显式空值会在节点查找或 Gateway 请求之前失败。提供的键保留其精确字节，包括空白；省略该标志会生成一个键。

调用超时涵盖 Gateway 检查、节点唤醒、就绪重试以及节点响应。时钟调整不会重置或延长此已用时间预算。

system.run 和 system.run.prepare 在此处被阻止。请改用 exec 工具并指定 host=node 进行 shell 执行。system.which 可通过 invoke 使用。

通知、推送、位置、屏幕

openclaw nodes notify --node <id> --title "Build" --body "Done" --priority timeSensitive
openclaw nodes push --node <id> --title "OpenClaw" --environment sandbox
openclaw nodes location get --node <id> --accuracy precise
openclaw nodes screen record --node <id> --duration 10s --fps 10 --out ./clip.mp4
  • notify 在声明了 system.notify 的节点上发送本地通知，包括 macOS、iOS、Android 以及直接 watchOS 节点。直接 watchOS 投递要求 OpenClaw 处于活动状态。需要 --title 或 --body。选项：--sound <name>、--priority <passive|active|timeSensitive>、--delivery <system|overlay|auto>（默认 system）、--invoke-timeout <ms>（默认 15000）。
  • push 向 iOS 节点发送 APNs 测试推送。选项：--title <text>（默认 OpenClaw）、--body <text>、--environment <sandbox|production> 用于覆盖检测到的 APNs 环境。投递被接受时退出码为 0。APNs 类型化拒绝会保留完整的文本或 JSON 诊断信息，并以非零退出。
  • location get 获取节点当前位置。选项：--max-age <ms>（复用缓存的定位）、--accuracy <coarse|balanced|precise>、--location-timeout <ms>（默认 10000）、--invoke-timeout <ms>（默认 20000）。
  • screen record 捕获一段短视频并打印保存路径（或使用 --json 写入 JSON）。选项：--screen <index>（默认 0）、--duration <ms|10s>（默认 10000）、--fps <fps>（默认 10）、--no-audio、--out <path>、--invoke-timeout <ms>（默认 120000）。
  • 显式屏幕输出路径会先在目标旁边暂存。只有在完整写入后才会替换目标。写入失败时，现有文件保持不变。

相机和 macOS 小组件面板命令有各自的文档：相机节点、小组件面板。内置的实验性 Canvas 插件会注册 openclaw nodes canvas，并保留 present、hide 和 navigate 子命令。

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