节点

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

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

macOS 也可以运行为节点模式：菜单栏应用连接到 Gateway 的 WS 服务器，将其本地 canvas/camera 命令作为节点暴露（这样 openclaw nodes … 就能操控这台 Mac）。

说明：

  • 节点是外围设备，不是网关。它们不运行网关服务。
  • Telegram/WhatsApp 等消息落在网关上，不在节点上。
  • 故障排查手册：/nodes/troubleshooting

配对与状态

WS 节点使用设备配对。 节点在 connect 时提交设备身份；Gateway 为 role: node 创建设备配对请求。通过设备 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.pair.*（CLI: openclaw nodes pending/approve/reject）是 Gateway 自有的节点配对存储；它不控制 WS connect 握手。

远程节点主机（system.run）

当 Gateway 在一台机器上运行，而你想在另一台机器上执行命令时，可以使用节点主机。模型仍然与 Gateway 通信；Gateway 在选择 host=node 时将 exec 调用转发到节点主机。

各部分运行位置

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

审批说明：

  • 基于审批的节点运行绑定精确的请求上下文。
  • 对于直接的 shell/运行时文件执行，OpenClaw 还会尽力绑定一个具体的本地文件操作数，如果该文件在执行前被修改则拒绝运行。
  • 如果 OpenClaw 无法为解释器/运行时命令识别出恰好一个具体的本地文件，基于审批的执行会被拒绝，而不是假装完全覆盖了运行时语义。遇到这种情况，请使用沙箱、独立主机或显式信任的白名单/完整工作流。

启动节点主机（前台）

在节点机器上：

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

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

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

示例（节点主机 → Gateway 主机）：

# 终端 A（保持运行）：将本地 18790 转发到 gateway 的 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 已配置但未解析，节点主机认证会安全失败。
  • 旧版 CLAWDBOT_GATEWAY_* 环境变量被节点主机认证解析有意忽略。

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

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

配对与命名

在 Gateway 主机上：

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"（Gateway 端覆盖）。

白名单命令

执行审批是按节点主机的。从 Gateway 添加白名单条目：

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

配置默认值（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 调用都在节点主机上运行（受节点白名单/审批控制）。

相关文档：

调用命令

底层（原始 RPC）：

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

常见的”给 agent 一个 MEDIA 附件”工作流有更高层的辅助命令。

截图（canvas 快照）

如果节点正在显示 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

Canvas 控制

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）

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 payload 过大。
  • 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 是否可用取决于节点平台。
  • 屏幕录制时长上限 <= 60s。
  • --no-audio 在支持的平台上禁用麦克风录制。
  • 使用 --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 节点）

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

底层调用：

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

说明：

  • 必须先在 Android 设备上接受权限提示，才会广播 sms.send 能力。
  • 不支持电话功能的纯 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

调用示例：

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。

示例：

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/exit code。
  • 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）。
  • 对于白名单模式下的 allow-always 决策，已知的调度包装器（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 应用中执行审批的控制（Settings → Exec approvals）。 ask/allowlist/full 的行为与无头节点主机相同；拒绝的提示返回 SYSTEM_RUN_DENIED。
  • 无头节点主机上，system.run 受执行审批控制（~/.openclaw/exec-approvals.json）。

Exec 节点绑定

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

全局默认：

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

按 agent 覆盖：

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

启动：

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

说明：

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

Mac 节点模式

  • macOS 菜单栏应用作为节点连接到 Gateway WS 服务器（这样 openclaw nodes … 就能操控这台 Mac）。
  • 远程模式下，应用为 Gateway 端口打开 SSH 隧道并连接到 localhost。
arrow_back
上一页
Auth Monitoring
下一页
Troubleshooting
arrow_forward