Nodes（节点）

节点（node） 是伴侣设备（macOS/iOS/Android/无头），通过 role: "node" 连接到 Gateway 的 WebSocket（与 operator 同端口），并通过 node.invoke 暴露命令接口（如 canvas.*、camera.*、device.*、notifications.*、system.*）。协议详情见 Gateway 协议。

旧版传输方式：Bridge 协议（TCP JSONL；当前节点已弃用/移除）。

macOS 也可以运行在 节点模式：菜单栏应用连接到 Gateway 的 WS 服务器，将本地的 canvas/camera 命令作为节点暴露（因此 openclaw nodes … 对这台 Mac 有效）。

注意：

节点是外设，不是网关，不运行 gateway 服务。
Telegram/WhatsApp 等消息落在网关，不落在节点。
故障排查手册：/openclaw/nodes/troubleshooting

配对与状态

WS 节点使用设备配对。 节点在 connect 时出示设备身份；Gateway 为 role: node 创建设备配对请求。通过设备 CLI（或界面）批准。

快速 CLI：

bash

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

若节点以更改后的认证信息重试（role/scopes/公钥），之前的待批请求将被替换，生成新的 requestId。批准前务必重新运行 openclaw devices list。

注意：

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

远程节点主机（system.run）

当 Gateway 运行在一台机器上，而你希望命令在另一台机器上执行时，可使用节点主机。模型仍与 gateway 交互，gateway 在选择 host=node 时将 exec 调用转发给节点主机。

执行位置说明

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

审批说明：

审批绑定的节点运行与精确的请求上下文绑定。
对于直接 shell/运行时文件执行，OpenClaw 会尽力绑定一个具体的本地文件操作数，若该文件在执行前发生变化则拒绝运行。
若 OpenClaw 无法识别出恰好一个具体的本地文件用于解释器/运行时命令，则拒绝审批执行，而非假装全量覆盖。如需更广泛的解释器语义，请使用沙箱、独立主机或显式可信允许列表/完整工作流。

启动节点主机（前台）

在节点机器上：

bash

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

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

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

示例（节点主机 → 网关主机）：

bash

# 终端 A（保持运行）：转发本地 18790 → 网关 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"

注意：

openclaw node run 支持 token 或密码认证。
推荐使用环境变量：OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
配置回退：gateway.auth.token / gateway.auth.password。
本地模式下，节点主机故意忽略 gateway.remote.token / gateway.remote.password。
远程模式下，gateway.remote.token / gateway.remote.password 按远程优先规则生效。
若活动的本地 gateway.auth.* SecretRef 已配置但未解析，节点主机认证失败关闭。
节点主机认证解析仅支持 OPENCLAW_GATEWAY_* 环境变量。

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

bash

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

配对与命名

在网关主机上：

bash

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

若节点以更改后的认证信息重试，重新运行 openclaw devices list 并批准当前的 requestId。

命名选项：

openclaw node run / openclaw node install 的 --display-name（持久化到节点的 ~/.openclaw/node.json）。
openclaw nodes rename --node <id|name|ip> --name "Build Node"（网关侧覆盖）。

配置命令允许列表

执行审批是按节点主机的。从网关添加允许列表条目：

bash

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 指向节点

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

bash

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）：

bash

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

常见的"为 agent 提供媒体附件"工作流有更高级的辅助命令。

截图（canvas 快照）

若节点正在显示 Canvas（WebView），canvas.snapshot 返回 { format, base64 }。

CLI 辅助命令（写入临时文件并打印 MEDIA:<path>）：

bash

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas 控制

bash

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）

bash

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）：

bash

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # 默认：前后两个摄像头（2 条 MEDIA 行）
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

视频片段（mp4）：

bash

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

注意：

iOS/Android 节点的 canvas.* 和 camera.* 要求应用在前台运行（后台调用返回 NODE_BACKGROUND_UNAVAILABLE）。
片段时长限制（当前 <= 60s）以避免 base64 载荷过大。
Android 会在可能时请求 CAMERA/RECORD_AUDIO 权限；权限被拒绝时报 *_PERMISSION_REQUIRED。

屏幕录制（节点）

支持的节点暴露 screen.record（mp4）。示例：

bash

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

注意：

screen.record 可用性取决于节点平台。
屏幕录制限制为 <= 60s。
--no-audio 在支持的平台上禁用麦克风捕获。
有多个屏幕时，用 --screen <index> 选择显示器。

位置（节点）

节点在设置中启用 Location 后暴露 location.get。

CLI 辅助命令：

bash

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

注意：

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

短信（Android 节点）

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

底层调用：

bash

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
callLog.search
sms.search
motion.activity、motion.pedometer

调用示例：

bash

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}'

注意：

运动命令受可用传感器的功能门控。

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

macOS 节点暴露 system.run、system.notify 和 system.execApprovals.get/set。无头节点主机暴露 system.run、system.which 和 system.execApprovals.get/set。

示例：

bash

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 应用的 exec 审批控制（设置 → Exec 审批）。Ask/allowlist/full 行为与无头节点主机相同；被拒绝的提示返回 SYSTEM_RUN_DENIED。
在无头节点主机下，system.run 受 exec 审批（~/.openclaw/exec-approvals.json）控制。

Exec 节点绑定

有多个节点时，可将 exec 绑定到特定节点。这设置了 exec host=node 的默认节点（可被 agent 覆盖）。

全局默认：

bash

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

每个 agent 覆盖：

bash

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

取消设置以允许任意节点：

bash

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），连接到 Gateway WebSocket 并暴露 system.run/system.which。适用于 Linux/Windows 或在服务器旁运行最小化节点。

启动：

bash

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

注意：

仍需配对（Gateway 会显示设备配对提示）。
节点主机将节点 ID、token、显示名称和网关连接信息存储在 ~/.openclaw/node.json。
Exec 审批通过 ~/.openclaw/exec-approvals.json 在本地强制执行（参见 Exec 审批）。
在 macOS 上，无头节点主机默认在本地执行 system.run。设置 OPENCLAW_NODE_EXEC_HOST=app 可将 system.run 路由到伴侣应用的 exec 主机；加 OPENCLAW_NODE_EXEC_FALLBACK=0 则要求应用主机，若不可用则失败关闭。
Gateway WS 使用 TLS 时，添加 --tls/--tls-fingerprint。

Mac 节点模式

macOS 菜单栏应用作为节点连接到 Gateway WS 服务器（openclaw nodes … 对这台 Mac 有效）。
在远程模式下，应用会为 Gateway 端口打开 SSH 隧道并连接到 localhost。

Nodes（节点） ​

配对与状态 ​

远程节点主机（system.run） ​

执行位置说明 ​

启动节点主机（前台） ​

通过 SSH 隧道连接远程网关（回环绑定） ​

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

配对与命名 ​

配置命令允许列表 ​

将 exec 指向节点 ​

调用命令 ​

截图（canvas 快照） ​

Canvas 控制 ​

A2UI（Canvas） ​

照片与视频（节点摄像头） ​

屏幕录制（节点） ​

位置（节点） ​

短信（Android 节点） ​

Android 设备与个人数据命令 ​

系统命令（节点主机/Mac 节点） ​

Exec 节点绑定 ​

权限映射 ​

无头节点主机（跨平台） ​

Mac 节点模式 ​

Nodes（节点）

配对与状态

远程节点主机（system.run）

执行位置说明

启动节点主机（前台）

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

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

配对与命名

配置命令允许列表

将 exec 指向节点

调用命令

截图（canvas 快照）

Canvas 控制

A2UI（Canvas）

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

屏幕录制（节点）

位置（节点）

短信（Android 节点）

Android 设备与个人数据命令

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

Exec 节点绑定

权限映射

无头节点主机（跨平台）

Mac 节点模式