OpenClaw 白皮书
媒体与设备

底层节点架构

[​
](#nodes)
节点 (Nodes)
一个 节点(node) 是连接到网关 WebSocket（与控制台端相同的端口）的伴侣设备（macOS/iOS/Android/无头设备），它的角色为 role: "node" ，并通过 node.invoke 暴露一系列命令接口（例如 canvas.*, camera.*, device.*, notifications.*, system.*）。相关协议详见：网关协议。旧版传输层：Bridge 协议 (TCP JSONL；当前已弃用/移除)。
macOS 也可以在 节点模式(node mode) 下运行：菜单栏应用连接到网关的 WS 服务器，并将其本地的画布(canvas)/相机(camera)命令作为一个节点暴露出来（因此您可以对这台 Mac 执行 openclaw nodes …）。
注意事项：
  • ✦节点属于 外设(peripherals)，不是网关。它们不运行网关核心服务。
  • ✦Telegram/WhatsApp/企业微信等消息只会发送到 网关，而不是节点。
  • ✦故障排除手册：/nodes/troubleshooting

[​
](#pairing-+-status)
配对与状态
WS 节点使用设备配对。 节点在 connect 时提供设备标识；网关为此创建一个 role: node 的设备配对请求。您可以通过设备管理 CLI（或 UI）批准。使用以下快速 CLI 命令：
bash
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
注意事项：
  • ✦当节点的设备配对角色包含 node 时，nodes status 将该节点标记为 已配对(paired)。
  • ✦node.pair.* (CLI: openclaw nodes pending/approve/reject) 是一个独立的网关所属节点配对存储；它 不 控制 WS connect 的握手阶段。

[​
](#remote-node-host-system-run)
远程节点主机 (system.run)
当您的网关运行在一台机器上，而您希望在另一台机器上执行命令时，可以使用 节点主机 (node host)。模型仍然与 网关 对话；网关在检测到 host=node 参数时将 exec 调用转发到 节点主机。

[​
](#what-runs-where)
运行位置划分
  • ✦网关主机: 接收通道消息，处理多智能体模型调用，路由工具执行。
  • ✦节点主机: 在节点端机器上执行 system.run / system.which 命令。
  • ✦审批控制: 在节点主机上强制通过 ~/.openclaw/exec-approvals.json 进行管控限制。
执行审批提示：
  • ✦使用审批控制的节点运行始终绑定在严格限定的请求上下文中。
  • ✦对于直接基于文件或环境运行脚本的操作，OpenClaw 会尽最大努力绑定具体的本地目标文件，若该文件在触发执行前发生变更会被拦截阻止。

[​
](#start-a-node-host-foreground)
启动节点主机 (前台守护)
在作为节点的机器上：
bash
openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

[​
](#remote-gateway-via-ssh-tunnel-loopback-bind)
通过 SSH 隧道对接远程网关 (回环绑定)
如果网关绑定到回环地址 (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: 导出网关授权令牌并通过隧道连接
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。

[​
](#start-a-node-host-service)
启动节点主机 (后台服务)
bash
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

[​
](#pair-+-name)
配对与别名
在网关主机上：
bash
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" (网关端映射覆盖)。

[​
](#allowlist-the-commands)
开启白名单执行限制
Node Host 提供 逐点控制 定制的安全审批能力，可在网关层设置命令执行的白名单映射：
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 中。

[​
](#point-exec-at-the-node)
指定命令执行流转到边缘节点
配置默认值 (网关级配置)：
bash
openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"
或作用在某次专门的对话会话的沙盒中：
bash
/exec host=node security=allowlist node=<id-or-name>
设置完毕后，带有 host=node 的指令下发会被智能体远程调度到指定 Node 执行（基于该 Node Host 端侧对这些指定逻辑的允许）。

[​
](#invoking-commands)
接口调用规范
底层命令调度 RPC：
bash
openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
在常见的以提供给智能体 附加媒介 为特征的工作流中，已经包装与构建了更高级的预设动作助手。

[​
](#screenshots-canvas-snapshots)
UI 可视化呈现管理 / 画布 (Canvas Snapshots)
如果节点设备开启了界面可视化容器(WebView / Canvas)，通过 canvas.snapshot 读取返回值结构则能得到 { format, base64 }，您可通过其做截图提取。CLI 层面的快速触发测试提取格式支持输出：
bash
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

[​
](#canvas-controls)
控制界面
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。

[​
](#photos-+-videos-node-camera)
相机资源控制 (节点摄影像机)
截取照片 (jpg):
bash
openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
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
注意事项：
  • ✦运行节点的平台必须处于被激活开启的状态 （在前台进程），才可以将 canvas.* + camera.* 指令映射接通（后台执行可能会报异常阻断回调 NODE_BACKGROUND_UNAVAILABLE）。
  • ✦Clip 的录制会强制压缩限制 (<= 60s) 防范产生过量的流与堵塞。

[​
](#headless-node-host-cross-platform)
跨平台的无头 Node Host
OpenClaw 支持在全平台下编译一套原生且通用的 无头 Node Host (即脱离了前台界面的支持形态守护包) 与其底层网关通讯执行指令交互并管理运行暴露命令。它对于部署云端多租户或是单在后台提供挂载宿命非常有益！启动范例：
bash
openclaw node run --host <gateway-host> --port 18789
  • ✦同样使用设备鉴权模式保护底层（连接时依然会向中心网关派发生出许可绑定设备验证请求）。
认证检测节点排错
⌘I