节点

节点是一个配套设备（macOS/iOS/Android/无头），它连接到网关 WebSocket（与操作员相同的端口），使用 role: "node"，并通过 node.invoke 暴露命令表面（例如 node.invoke、node.invoke、node.invoke）。协议详情：网关协议。

传统传输：桥接协议（TCP JSONL；已弃用/删除当前节点）。

macOS 也可以在节点模式下运行：菜单栏应用程序连接到网关的 WS 服务器，并将其本地画布/摄像头命令作为节点公开（因此 openclaw nodes … 可以在此 Mac 上工作）。

备注：

- 节点是外设，不是网关。它们不运行网关服务。

- Telegram/WhatsApp/等消息落在网关上，而不是节点上。

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

快速 CLI：

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 connect 握手。

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

#

- 网关主机：接收消息，运行模型，路由工具调用。

- 节点主机：在节点机器上执行 system.run/system.which。

- 批准：通过 ~/.openclaw/exec-approvals.json 在节点主机上强制执行。

#

在节点机器上：

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

#

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

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

ssh -N -L 18790:127.0.0.1:18789 user@gateway-host


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 进行身份验证。

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

#

在网关主机上：

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" (gateway override).

#

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

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。

#

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

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 的 host=node 调用都在节点主机上运行（受节点允许列表/批准的约束）。

相关：

- 节点主机 CLI

- Exec 工具

- Exec 批准

低级（原始 RPC）：

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

存在用于常见的“给代理一个 MEDIA 附件”工作流的高级助手。

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

CLI helper (writes to a temp file and prints MEDIA:<path>):

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

#

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"

备注：

- canvas present 接受 URL 或本地文件路径（--target），以及用于定位的可选 --x/--y/--width/--height。

- canvas eval 接受内联 JS（--js）或位置参数。

#

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>

备注：

- 仅支持 A2UI v0.8 JSONL（拒绝 v0.9/createSurface）。

照片（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
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

备注：

- 节点必须处于前台才能使用 canvas.* 和 camera.*（后台调用返回 NODE_BACKGROUND_UNAVAILABLE）。

- 剪辑持续时间被限制（当前 <= 60s）以避免过大的 base64 负载。

- 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 需要节点应用程序处于前台。

- Android 将在录制前显示系统屏幕捕获提示。

- 屏幕录制被限制为 <= 60s。

- --no-audio 禁用麦克风捕获（在 iOS/Android 上支持；macOS 使用系统捕获音频）。

- Use --screen <index> to select a display when multiple screens are available.

当在设置中启用位置时，节点公开 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.send。

低级调用：

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

备注：

- 必须在 Android 设备上接受权限提示，然后才会通告功能。

- 没有电话功能的仅 Wi-Fi 设备不会通告 sms.send。

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"

备注：

- system.run 在负载中返回 stdout/stderr/退出代码。

- system.notify 尊重 macOS 应用程序上的通知权限状态。

- system.run 支持 --cwd、--env KEY=VAL、--command-timeout 和 --needs-screen-recording。

- system.notify supports --priority <passive|active|timeSensitive> and --delivery <system|overlay|auto>.

- macOS 节点删除 PATH 覆盖；无头节点主机仅在它前置节点主机 PATH 时才接受 PATH。

- 在 macOS 节点模式下，system.run 受 macOS 应用程序中的执行批准限制（设置 → Exec 批准）。

- 询问/允许列表/全部的行为与无头节点主机相同；被拒绝的提示返回 SYSTEM_RUN_DENIED。

- 在无头节点主机上，system.run 受执行批准限制（~/.openclaw/exec-approvals.json）。

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

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

全局默认值：

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.describe / node.list 中包含 node.describe 映射，按权限名称键入（例如 screenRecording、accessibility），并带有布尔值（true = 已授予）。

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

启动它：

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

备注：

- 仍然需要配对（网关将显示节点批准提示）。

- 节点主机将其节点 ID、令牌、显示名称和网关连接信息存储在 ~/.openclaw/node.json 中。

- 批准通过 ~/.openclaw/exec-approvals.json 在本地强制执行（参见 Exec 批准）。

- 在 macOS 上，无头节点主机在可访问时首选配套应用程序执行主机，并在应用程序不可用时回退到本地执行。设置 OPENCLAW_NODE_EXEC_HOST=app 以要求应用程序，或 OPENCLAW_NODE_EXEC_FALLBACK=0 以禁用回退。

- 当网关 WS 使用 TLS 时，添加 --tls / --tls-fingerprint。

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

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