Nodes

Node 是一个配套设备（macOS/iOS/Android/无界面），通过 role: "node" 连接到 Gateway 的 WebSocket（与 operators 使用同一端口），并通过 node.invoke 暴露命令接口（如 canvas.*、camera.*、system.*）。协议详情：Gateway 协议。

旧版传输方式：Bridge 协议（TCP JSONL；已弃用/移除，当前 nodes 不再使用）。

macOS 也可以运行在 node 模式：菜单栏应用连接到 Gateway 的 WS 服务器，并将其本地 canvas/camera 命令作为 node 暴露（这样 openclaw nodes … 就能操作这台 Mac）。

注意：

  • Nodes 是外设，不是 gateways。它们不运行 gateway 服务。
  • Telegram/WhatsApp 等消息会到达 gateway，而不是 nodes。

Pairing + 状态

WS nodes 使用设备配对。 Nodes 在 connect 时提供设备身份；Gateway 为 role: node 创建设备配对请求。通过 devices 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 标记为 paired。
  • node.pair.*（CLI：openclaw nodes pending/approve/reject）是一个独立的 gateway 拥有的 node 配对存储；它不会阻止 WS connect 握手。

远程 node host（system.run）

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

运行位置

  • Gateway host：接收消息，运行模型，路由工具调用。
  • Node host：在 node 机器上执行 system.run/system.which。
  • Approvals：通过 ~/.openclaw/exec-approvals.json 在 node host 上强制执行。

启动 node host（前台）

在 node 机器上：

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

通过 SSH 隧道连接远程 gateway（loopback 绑定）

如果 Gateway 绑定到 loopback（gateway.bind=loopback，本地模式下的默认值），远程 node hosts 无法直接连接。创建一个 SSH 隧道，并将 node host 指向隧道的本地端。

示例（node host -> gateway host）：

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

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

注意：

  • token 是 gateway 配置中的 gateway.auth.token（在 gateway host 上的 ~/.openclaw/openclaw.json）。
  • openclaw node run 读取 OPENCLAW_GATEWAY_TOKEN 进行认证。

启动 node host（服务）

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

配对 + 命名

在 gateway host 上：

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

命名选项：

  • 在 openclaw node run / openclaw node install 上使用 --display-name（持久化在 node 上的 ~/.openclaw/node.json 中）。
  • openclaw nodes rename --node <id|name|ip> --name "Build Node"（gateway 覆盖）。

将命令加入白名单

Exec approvals 是每个 node host 独立的。从 gateway 添加白名单条目：

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

Approvals 存储在 node host 的 ~/.openclaw/exec-approvals.json。

将 exec 指向 node

配置默认值（gateway 配置）：

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

或按 session 配置：

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

设置后，任何带有 host=node 的 exec 调用都会在 node host 上运行（受 node 白名单/approvals 约束）。

相关：

调用命令

底层（原始 RPC）：

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

对于常见的”给 agent 提供 MEDIA 附件”工作流，存在更高级的辅助工具。

截图（canvas 快照）

如果 node 正在显示 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"

注意：

  • canvas present 接受 URL 或本地文件路径（--target），以及可选的 --x/--y/--width/--height 用于定位。
  • canvas eval 接受内联 JS（--js）或位置参数。

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>

注意：

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

照片 + 视频（node camera）

照片（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

注意：

  • Node 必须在前台才能使用 canvas.* 和 camera.*（后台调用返回 NODE_BACKGROUND_UNAVAILABLE）。
  • 片段时长被限制（当前 <= 60s）以避免过大的 base64 负载。
  • Android 会在可能时提示 CAMERA/RECORD_AUDIO 权限；拒绝权限会导致 *_PERMISSION_REQUIRED 失败。

屏幕录制（nodes）

Nodes 暴露 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 要求 node 应用在前台。
  • Android 会在录制前显示系统屏幕捕获提示。
  • 屏幕录制被限制为 <= 60s。
  • --no-audio 禁用麦克风捕获（iOS/Android 支持；macOS 使用系统捕获音频）。
  • 当有多个屏幕可用时，使用 --screen <index> 选择显示器。

位置（nodes）

当在设置中启用位置时，Nodes 暴露 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 nodes）

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

底层调用：

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

注意：

  • 在 Android 设备上接受权限提示后，才会广播该能力。
  • 仅支持 Wi-Fi 且没有电话功能的设备不会广播 sms.send。

系统命令（node host / mac node）

macOS node 暴露 system.run、system.notify 和 system.execApprovals.get/set。 无界面 node host 暴露 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 支持 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
  • macOS nodes 会丢弃 PATH 覆盖；无界面 node hosts 仅在 PATH 前置到 node host PATH 时才接受。
  • 在 macOS node 模式下，system.run 受 macOS 应用中的 exec approvals 控制（Settings → Exec approvals）。 Ask/allowlist/full 的行为与无界面 node host 相同；拒绝的提示返回 SYSTEM_RUN_DENIED。
  • 在无界面 node host 上，system.run 受 exec approvals（~/.openclaw/exec-approvals.json）控制。

Exec node 绑定

当有多个 nodes 可用时，你可以将 exec 绑定到特定 node。 这会设置 exec host=node 的默认 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"

取消设置以允许任何 node：

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

权限映射

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

无界面 node host（跨平台）

OpenClaw 可以运行无界面 node host（无 UI），连接到 Gateway WebSocket 并暴露 system.run / system.which。这在 Linux/Windows 上或在服务器旁边运行最小 node 时很有用。

启动它：

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

注意：

  • 仍然需要配对（Gateway 会显示 node 批准提示）。
  • Node host 将其 node id、token、显示名称和 gateway 连接信息存储在 ~/.openclaw/node.json 中。
  • Exec approvals 通过 ~/.openclaw/exec-approvals.json 在本地强制执行 （参见 Exec approvals）。
  • 在 macOS 上，无界面 node host 在可达时优先使用配套应用的 exec host，如果应用不可用则回退到本地执行。设置 OPENCLAW_NODE_EXEC_HOST=app 以要求应用，或 OPENCLAW_NODE_EXEC_FALLBACK=0 以禁用回退。
  • 当 Gateway WS 使用 TLS 时，添加 --tls / --tls-fingerprint。

Mac node 模式

  • macOS 菜单栏应用作为 node 连接到 Gateway WS 服务器（这样 openclaw nodes … 就能操作这台 Mac）。
  • 在远程模式下，应用为 Gateway 端口打开 SSH 隧道并连接到 localhost。