节点

节点是连接到网关 WebSocket 的配套设备（macOS/iOS/Android/无头），具有 role: "node" 并通过 node.invoke 公开命令界面（例如 canvas.*、camera.*、system.*）。

协议详情：网关协议

什么是节点？

▹节点是外围设备，不是网关。它们不运行网关服务。
▹Telegram/WhatsApp 等消息到达网关，而不是节点。
▹macOS 也可以在节点模式下运行：菜单栏应用连接到网关的 WS 服务器并将其本地 canvas/camera 命令公开为节点。

配对和状态

WS 节点使用设备配对。节点在连接期间呈现设备身份；网关为 role: node 创建设备配对请求。通过设备 CLI（或 UI）批准。

快速 CLI：


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

注意：

▹nodes status 在设备配对角色包含 node 时将节点标记为已配对。
▹node.pair.*（CLI：openclaw nodes pending/approve/reject）是一个单独的网关拥有的节点配对存储；它不会阻止 WS 连接握手。

远程节点主机（system.run）

当您的网关在一台机器上运行而您希望命令在另一台机器上执行时，使用节点主机。模型仍然与网关通信；当选择 host=node 时，网关将 exec 调用转发到节点主机。

运行位置

▹网关主机：接收消息，运行模型，路由工具调用。
▹节点主机：在节点机器上执行 system.run/system.which。
▹批准：通过 ~/.openclaw/exec-approvals.json 在节点主机上强制执行。

启动节点主机（前台）

在节点机器上：


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

通过 SSH 隧道的远程网关（回环绑定）

如果网关绑定到回环（gateway.bind=loopback，本地模式下的默认值），远程节点主机无法直接连接。创建 SSH 隧道并将节点主机指向隧道的本地端。

示例（节点主机 -> 网关主机）：


bash
# 终端 A（保持运行）：转发本地 18790 -> 网关 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# 终端 B：导出网关令牌并通过隧道连接
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

注意：

▹令牌是网关配置中的 gateway.auth.token（网关主机上的 ~/.openclaw/openclaw.json）。
▹openclaw node run 读取 OPENCLAW_GATEWAY_TOKEN 进行身份验证。

启动节点主机（服务）


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

配对和命名

在网关主机上：


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

命名选项：

▹--display-name 在 openclaw node run / openclaw node install 上（保存在节点上的 ~/.openclaw/node.json 中）。
▹openclaw nodes rename --node <id|name|ip> --name "Build Node"（网关覆盖）。

允许列表命令

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


bash
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 指向节点

配置默认值（网关配置）：


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

或每个会话：


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

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

调用命令

低级（原始 RPC）


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

屏幕截图（canvas 快照）

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

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


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

Canvas 控制


bash
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"

照片和视频（节点相机）

照片（jpg）：


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

视频片段（mp4）：


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

注意：

▹节点必须在前台才能使用 canvas.* 和 camera.*（后台调用返回 NODE_BACKGROUND_UNAVAILABLE）。
▹片段持续时间被限制（当前 <= 60s）以避免过大的 base64 有效负载。

屏幕录制（节点）

节点公开 screen.record（mp4）。示例：


bash
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 助手：


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

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

macOS 节点公开 system.run、system.notify 和 system.execApprovals.get/set。

无头节点主机公开 system.run、system.which 和 system.execApprovals.get/set。

示例：


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

无头节点主机（跨平台）

OpenClaw 可以运行无头节点主机（无 UI），连接到网关 WebSocket 并公开 system.run / system.which。这在 Linux/Windows 上或在服务器旁边运行最小节点时很有用。

启动它：


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

注意：

▹仍需要配对（网关将显示节点批准提示）。
▹节点主机将其节点 ID、令牌、显示名称和网关连接信息存储在 ~/.openclaw/node.json 中。
▹Exec 批准通过 ~/.openclaw/exec-approvals.json 在本地强制执行。

Mac 节点模式

macOS 菜单栏应用作为节点连接到网关 WS 服务器（因此 openclaw nodes … 可以针对此 Mac 工作）。

在远程模式下，应用为网关端口打开 SSH 隧道并连接到 localhost。

节点