12.1 节点概述 - OpenClaw中文社区

"节点"（Node）是作为伴侣设备（macOS/iOS/Android/无头模式）运行的组件，通过 role: "node" 连接到网关 WebSocket，并通过 node.invoke 暴露命令接口，如 canvas.*、camera.* 和 system.*。节点是外围设备而非网关本身——它们不运行网关服务。

核心概念

节点使AI代理能够与物理设备交互，包括：

画布操作：显示网页内容、截图、执行JavaScript
摄像头控制：拍照和录制视频
位置服务：获取设备位置信息
系统命令：在节点设备上执行命令
短信功能：Android节点可发送短信

设备配对与状态

节点在运行前需要进行设备配对。网关会创建配对请求，用户通过CLI或UI审批：

# 列出设备
openclaw devices list

# 审批配对请求
openclaw devices approve <requestId>

# 查看节点状态
openclaw nodes status

配对完成后，节点会被标记为"已配对"状态。

远程节点主机架构

当网关运行在一台机器上，但命令需要在另一台机器上执行时，节点主机可以桥接这种差距。模型与网关通信，网关再将执行调用转发到指定的节点机器。

职责分配

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

启动节点主机

前台模式：

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

服务安装：

# 安装服务
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"

# 重启服务
openclaw node restart

配置与安全

审批后，将特定命令加入白名单：

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

命令调用

原始RPC调用方式：

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

画布与截图功能

显示Canvas WebView的节点可以捕获快照，返回格式和base64数据：

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

# JPG格式截图（指定宽度和质量）
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

画布控制

导航、展示和JavaScript执行：

# 展示URL
openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com

# 导航到URL
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>

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

A2UI支持

通过JSONL推送UI元素（支持v0.8）：

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

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

媒体捕获：照片与视频

照片拍摄：

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

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

视频录制（MP4）：

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

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

注意

节点必须在前台运行才能执行这些操作。时长限制为最大60秒以防止载荷过大。Android可能会提示摄像头和音频权限。

屏幕录制

节点可以进行MP4屏幕录制：

# 录制10秒屏幕（10fps）
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10

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

同样需要前台运行。Android会显示系统屏幕捕获提示。可通过 --screen <index> 选择多显示器。

位置服务

当在设置中启用时，节点可提供位置数据：

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

# 精确位置（带参数）
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

位置默认关闭，需要明确的系统权限。

短信功能（Android）

具有用户授予短信权限的Android节点可使用 sms.send：

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

仅在支持电话功能且已接受权限的设备上可用。

系统命令

macOS节点和无头主机暴露 system.run 和 system.notify：

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

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

系统操作返回stdout/stderr/退出码。macOS节点通过应用级审批设置控制执行。无头主机使用 ~/.openclaw/exec-approvals.json。

执行节点绑定

通过全局或每代理配置绑定执行到特定节点：

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

权限映射

节点在 node.list 和 node.describe 输出中报告权限状态（摄像头、麦克风、位置、辅助功能、屏幕录制）为布尔值。

无头节点主机

跨平台无头操作（Linux/Windows/macOS）无需UI：

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

配置存储在 ~/.openclaw/node.json。macOS主机优先使用伴侣应用（可用时），可通过环境变量配置回退选项。支持TLS，使用 --tls 和 --tls-fingerprint 标志。

Mac节点模式

macOS菜单栏应用作为节点连接到网关WebSocket，通过标准节点命令启用远程管理。远程模式建立SSH隧道以实现安全的网关连接。

提示

更多详细信息请参考官方英文文档。