节点

节点

节点 是连接到 Gateway WebSocket（与操作员相同端口）的配套设备（macOS/iOS/Android/无头），带有 role: "node" 并通过 node.invoke 暴露命令表面（例如 canvas.*、camera.*、system.*）。协议详情：[Gateway 协议(../gateway/protocol.html)。

遗留传输：[桥接协议(../gateway/bridge-protocol.html)（TCP JSONL；当前节点已弃用/移除）。

macOS 也可以运行在 节点模式：菜单栏应用连接到 Gateway 的 WS 服务器并将其本地 Canvas/相机命令作为节点暴露（因此 openclaw nodes … 可以针对此 Mac 工作）。

说明：

配对 + 状态

WS 节点使用设备配对。 节点在 connect 期间展示设备标识；Gateway
为 role: node 创建设备配对请求。通过设备 CLI（或 UI）批准。

快速 CLI：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

说明：

远程节点主机（system.run）

当你的 Gateway 在一台机器上运行但你想在另一台机器上执行命令时，使用 节点主机。模型仍然与 Gateway 通信；Gateway 在选择了 host=node 时将 exec 调用转发给 节点主机。

什么在哪里运行

启动节点主机（前台）

在节点机器上：

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

启动节点主机（服务）

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

配对 + 命名

在 Gateway 主机上：

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes list

命名选项：

允许列表命令

Exec 批准是 每个节点主机 的。从 Gateway 添加允许列表条目：

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

批准存在于节点主机的 ~/.openclaw/exec-approvals.json 中。

将 exec 指向节点

配置默认值（Gateway 配置）：

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

或每个会话：

/exec host=node security=allowlist node=<id-or-name>

设置后，任何带有 host=node 的 exec 调用在节点主机上运行（受节点允许列表/批准约束）。

相关：

调用命令

低级（原始 RPC）：

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

高级助手存在于常见的"给 Agent 一个 MEDIA 附件"工作流。

截图（Canvas 快照）

如果节点显示 Canvas（WebView），canvas.snapshot 返回 { format, base64 }。

CLI 助手（写入临时文件并打印 MEDIA:<path>）：

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas 控制

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

说明：

A2UI（Canvas）

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

说明：

照片 + 视频（节点相机）

照片（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：两个朝向（2 个 MEDIA 行）
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

视频片段（mp4）：

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

说明：

屏幕录制（节点）

节点暴露 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

说明：

位置（节点）

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

CLI 助手：

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

说明：

SMS（Android 节点）

当用户授予 SMS 权限且设备支持电话时，Android 节点可以暴露 sms.send。

低级调用：

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

说明：

系统命令（节点主机 / mac 节点）

macOS 节点暴露 system.run、system.notify 和 system.execApprovals.get/set。
无头节点主机暴露 system.run、system.which 和 system.execApprovals.get/set。

示例：

openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

说明：

Exec 节点绑定

当有多个节点可用时，你可以将 exec 绑定到特定节点。
这会为 exec host=node 设置默认节点（并且可以被每个 Agent 覆盖）。

全局默认值：

openclaw config set tools.exec.node "node-id-or-name"

每个 Agent 覆盖：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

取消设置以允许任何节点：

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

权限映射

节点可能在 node.list / node.describe 中包含 permissions 映射，按键为权限名称（例如 screenRecording、accessibility）带有布尔值（true = 已授予）。

无头节点主机（跨平台）

OpenClaw 可以运行 无头节点主机（无 UI），它连接到 Gateway
WebSocket 并暴露 system.run / system.which。这在 Linux/Windows 上或作为服务器旁的最小节点运行非常有用。

启动它：

openclaw node run --host <gateway-host> --port 18789

说明：

Mac 节点模式