Nodes

Node 是一种伴侣设备（macOS/iOS/Android/无头），通过 WebSocket 连接�?Gateway（与操作员相同的端口），使用 role: "node"，并通过 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/etc. 消息到达 Gateway，而不�?nodes�?
  • 故障排除手册：/zh/docs/nodes/troubleshooting

配对 + 状�?

*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 标记�?已配�?�?
  • node.pair.*（CLI：openclaw nodes pending/approve/reject）是单独�?Gateway 拥有�?node 配对存储；它**�?*限制 WS connect 握手�?

远程 node 主机（system.run�?

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

哪里运行什�?

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

启动 node host（前台）

�?node 机器上：

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

通过 SSH 隧道远程 Gateway（loopback 绑定�?

如果 Gateway 绑定�?loopback（gateway.bind=loopback，本地模式默认），远�?node 主机无法直接连接。创�?SSH 隧道并将 node 主机指向隧道的本地端�?

示例（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 令牌并通过隧道连接
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

注意�?

  • 令牌�?Gateway 配置中的 gateway.auth.token（Gateway 主机上的 ~/.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 主机上：

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 批准�?每个 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"

批准存在�?node 主机上的 ~/.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>"

或每个会话：

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

设置后，任何带有 host=node �?exec 调用都在 node host 上运行（�?node 白名�?批准限制）�?

相关�?

调用命令

低级（原�?RPC）：

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

高级辅助工具存在用于常见�?给智能体一�?MEDIA 附件”工作流�?

截图（画布快照）

如果 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

画布控制

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（画布）

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 相机�?

照片（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：两个摄像头�? �?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 payload�?
  • 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�?

低级 invoke�?

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 �?payload 中返�?stdout/stderr/退出码�?
  • system.notify �?macOS 应用上尊重通知权限状态�?
  • system.run 支持 --cwd、--env KEY=VAL、--command-timeout �?--needs-screen-recording�?
  • 对于 shell 包装器（bash|sh|zsh ... -c/-lc），请求作用域的 --env 值被缩减为明确的白名单（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）�?
  • 对于白名单模式中的始终允许决策，已知调度包装器（env、nice、nohup、stdbuf、timeout）持久化内部可执行文件路径而不是包装器路径。如果解包不安全，则不会自动持久化白名单条目�?
  • �?Windows node hosts 的白名单模式下，通过 cmd.exe /c 运行�?shell-wrapper 需要批准（白名单条目本身不会自动允许包装器形式）�?
  • system.notify 支持 --priority <passive|active|timeSensitive> �?--delivery <system|overlay|auto>�?
  • Node hosts 忽略 PATH 覆盖并剥离危险的启动/shell 键（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）。如果你需要额外的 PATH 条目，请配置 node host 服务环境（或将工具安装到标准位置），而不是通过 --env 传�?PATH�?
  • �?macOS node 模式下，system.run �?macOS 应用中的执行批准限制（设�?�?执行批准）�? 询问/白名�?完全允许的行为与无头 node host 相同；被拒绝的提示返�?SYSTEM_RUN_DENIED�?
  • 在无�?node host 上，system.run 受执行批准限制（~/.openclaw/exec-approvals.json）�?

Exec node 绑定

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

取消设置以允许任�?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、令牌、显示名称和 Gateway 连接信息存储�?~/.openclaw/node.json 中�?
  • 执行批准通过 ~/.openclaw/exec-approvals.json 本地强制执行（请参阅 Exec 批准）�?
  • �?macOS 上，无头 node host 默认在本地执�?system.run。设�?OPENCLAW_NODE_EXEC_HOST=app �?system.run 路由到伴侣应�?exec host；添�?OPENCLAW_NODE_EXEC_FALLBACK=0 以要求应用主机并在不可用时关闭失败�?
  • �?Gateway WS 使用 TLS 时，添加 --tls / --tls-fingerprint�?

Mac node 模式

  • macOS 菜单栏应用作�?node 连接�?Gateway WS 服务器（因此 openclaw nodes … 可以对此 Mac 运行）�?
  • 在远程模式下，应用为 Gateway 端口打开 SSH 隧道并连接到 localhost�?