OpenClaw 🦞

节点

节点

节点是一个 companion 设备（macOS/iOS/Android/无头模式），它通过 role: "node" 连接到网关 WebSocket（与操作员相同的端口），并通过 node.invoke 暴露命令界面（例如 canvas.*、camera.*、device.*、notifications.*、system.*）。协议详情：网关协议。

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

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

注意：

  • 节点是外围设备，不是网关。它们不运行网关服务。
  • Telegram/WhatsApp 等消息会到达网关，而不是节点。
  • 故障排除手册：/nodes/troubleshooting

配对 + 状态

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>

注意：

  • 当节点的设备配对角色包含 node 时，nodes status 会将节点标记为已配对。
  • node.pair.*（CLI：openclaw nodes pending/approve/reject）是一个独立的网关拥有的节点配对存储；它不控制 WS connect 握手。

远程节点主机（system.run）

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

运行位置

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

启动节点主机（前台）

在节点机器上：

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

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

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

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

# 终端 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"

注意：

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

启动节点主机（服务）

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

配对 + 命名

在网关主机上：

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

命名选项：

  • 在 openclaw node run / openclaw node install 上使用 --display-name（持久化在节点上的 ~/.openclaw/node.json 中）。
  • 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/exec-approvals.json。

将 exec 指向节点

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

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

相关：

调用命令

低级（原始 RPC）：

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

高级助手存在于常见的"给代理 MEDIA 附件"工作流中。

截图（画布快照）

如果节点正在显示画布（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 被拒绝）。

照片 + 视频（节点摄像头）

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

注意：

  • 节点必须处于前台才能使用 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 使用系统捕获音频）。
  • 当有多个屏幕可用时，使用 --screen <index> 选择显示器。

位置（节点）

当设置中启用位置时，节点暴露 location.get。

CLI 助手：

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

注意：

  • 位置默认关闭。
  • "始终"需要系统权限；后台获取是尽力而为。
  • 响应包括纬度/经度、精度（米）和时间戳。

短信（Android 节点）

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

低级调用：

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

注意：

  • 必须在 Android 设备上接受权限提示，然后才会宣传此功能。
  • 不支持电话功能的仅 Wi-Fi 设备不会宣传 sms.send。

Android 设备 + 个人数据命令

当启用相应功能时，Android 节点可以宣传额外的命令族。

可用族：

  • device.status、device.info、device.permissions、device.health
  • notifications.list、notifications.actions
  • photos.latest
  • contacts.search、contacts.add
  • calendar.events、calendar.add
  • motion.activity、motion.pedometer
  • app.update

调用示例：

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

注意：

  • 运动命令受可用传感器的功能限制。
  • app.update 受节点运行时的权限 + 策略限制。

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

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 应用上的通知权限状态。
  • 无法识别的节点 platform / deviceFamily 元数据使用保守的默认允许列表，排除 system.run 和 system.which。如果你故意需要为未知平台使用这些命令，请通过 gateway.nodes.allowCommands 显式添加它们。
  • 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 节点主机上，通过 cmd.exe /c 运行的 shell 包装器需要审批（仅允许列表条目不会自动允许包装器形式）。
  • system.notify 支持 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
  • 节点主机忽略 PATH 覆盖并剥离危险的启动/shell 键（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）。如果你需要额外的 PATH 条目，请配置节点主机服务环境（或将工具安装在标准位置），而不是通过 --env 传递 PATH。
  • 在 macOS 节点模式下，system.run 受 macOS 应用中的执行审批限制（设置 → 执行审批）。 询问/允许列表/完整的行为与无头节点主机相同；被拒绝的提示返回 SYSTEM_RUN_DENIED。
  • 在无头节点主机上，system.run 受执行审批限制（~/.openclaw/exec-approvals.json）。

执行节点绑定

当有多个节点可用时，你可以将执行绑定到特定节点。 这为 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.list / node.describe 中包含 permissions 映射，按权限名称键控（例如 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 在本地强制执行 （参见 执行审批）。
  • 在 macOS 上，无头节点主机默认在本地执行 system.run。设置 OPENCLAW_NODE_EXEC_HOST=app 通过 companion 应用执行主机路由 system.run；添加 OPENCLAW_NODE_EXEC_FALLBACK=0 以要求应用主机并在不可用时失败关闭。
  • 当网关 WS 使用 TLS 时，添加 --tls / --tls-fingerprint。

Mac 节点模式

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