OpenClaw 节点文档

概述

**节点（Node）**是一个配套设备，支持 macOS/iOS/Android/无头模式，它使用 role: "node" 连接到 Gateway WebSocket，并通过 node.invoke 暴露命令接口。协议详情可在 Gateway 协议文档中找到。

关键要点

  • 节点是外设，不是网关

  • 它们不运行网关服务

  • 消息落在网关上，而不是节点上

  • 故障排除可参考节点故障排除部分

配对与状态

WS 节点使用设备配对。节点在 connect 期间呈现设备身份，Gateway 为 role: node 创建设备配对请求。

快速 CLI 命令

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

远程节点主机 (system.run)

当你的 Gateway 在一台机器上运行，而你希望命令在另一台机器上执行时，使用节点主机。

架构说明

组件 职责
Gateway 主机 接收消息、运行模型、路由工具调用
Node 主机 在节点机器上执行 system.run/system.which
批准机制 通过节点主机上的 ~/.openclaw/exec-approvals.json 强制执行

启动节点主机（前台）

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

通过 SSH 隧道的远程 Gateway

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"

启动节点主机（服务模式）

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

# 重命名节点
openclaw nodes rename --node <id|name|ip> --name "Build Node"

命令白名单配置

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

指向节点执行

配置默认值

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>

调用命令

底层 RPC 调用

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

截图（画布快照）

CLI 辅助工具

# PNG 格式
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png

# JPG 格式，指定宽度和质量
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>

# 执行 JavaScript
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

A2UI（画布交互）

# 推送文本
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"

# 推送 JSONL 文件
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl

# 重置 A2UI
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

照片与视频（节点相机）

拍照

# 列出可用相机
openclaw nodes camera list --node <idOrNameOrIp>

# 拍照
openclaw nodes camera snap --node <idOrNameOrIp>

# 使用前置摄像头拍照
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

录制视频片段

# 录制 10 秒视频
openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s

# 录制 3 秒视频，无音频
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

屏幕录制

# 录制 10 秒，10 FPS
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10

# 录制 10 秒，10 FPS，无音频
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

位置服务

# 获取位置
openclaw nodes location get --node <idOrNameOrIp>

# 精确定位，指定最大时效和超时
openclaw nodes location get --node <idOrNameOrIp> \
  --accuracy precise --max-age 15000 --location-timeout 10000

SMS（Android 节点）

底层调用

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

系统命令

节点主机 / Mac 节点

# 在节点上执行命令
openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"

# 发送通知
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

Exec 节点绑定

全局默认值

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

按代理覆盖

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

取消设置

openclaw config unset tools.exec.node

无头节点主机（跨平台）

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

Mac 节点模式

macOS 菜单栏应用作为节点连接到 Gateway WS 服务器。在远程模式下，应用会为 Gateway 端口打开 SSH 隧道并连接到 localhost。

总结

OpenClaw 节点系统提供了强大的远程执行能力，支持：

  • ✅ 多平台支持（macOS/iOS/Android/无头）

  • ✅ 远程命令执行

  • ✅ 画布控制与截图

  • ✅ 相机与屏幕录制

  • ✅ 位置服务

  • ✅ SMS 发送

  • ✅ 系统通知

通过合理的配置和权限管理，可以构建安全、高效的分布式执行环境。

文档来源：OpenClaw Nodes Documentation

最后更新：2026-03-18