OpenClaw系列第21课:多节点架构 – 手机 / VPS / 树莓派怎么协作

这是「OpenClaw 教程课程」第 21 课。 从这一课开始，我们进入第五模块：多平台与节点。前面讲的是 Agent 怎么执行、怎么自动化；现在开始讲 OpenClaw 怎么跨设备协作。

图：OpenClaw 的核心是一个 Gateway，手机、VPS、树莓派、macOS、headless node host 都可以作为节点接入，提供各自设备上的能力。

很多人刚开始搭 OpenClaw，会先在一台机器上跑起来。

这很好。

但很快你会遇到这些问题：

• Gateway 在 VPS 上，但你想让它访问家里的摄像头
• Agent 在服务器上跑，但某些命令需要在 Mac 上执行
• 你想用手机摄像头给 Agent 看现场画面
• 你想让树莓派负责本地设备控制
• 你想把浏览器自动化放到另一台机器上跑
• 你希望 OpenClaw 不只是一台机器，而是一组设备协作

这就是多节点架构要解决的问题。

这一课我们先不讲复杂配置。

先讲最重要的架构认知：

Gateway 是中枢，Node 是外围能力提供者。

理解这句话，后面 Tailscale、节点配对、摄像头、音频、媒体节点这些课就都顺了。

一、先说结论：Gateway 是大脑，Node 是手脚和感官

在 OpenClaw 里，你可以先用这个比喻：

Gateway 像中枢大脑，Nodes 像分布在各个设备上的手脚和感官。

Gateway 负责：

• 接收 Telegram / WhatsApp / Discord / Signal 等消息
• 管理 Agent 会话
• 调用模型
• 分发工具请求
• 管理队列、cron、heartbeat、hooks
• 统一控制连接进来的节点

Node 负责：

• 连接到 Gateway
• 声明自己能做什么
• 执行自己设备上的能力
• 把结果返回给 Gateway

比如：

• 手机 Node 可以提供摄像头、定位、屏幕相关能力
• macOS Node 可以提供相机、屏幕、Canvas、浏览器代理等能力
• headless Node host 可以让 Agent 在另一台机器上执行命令
• 树莓派 Node 可以接本地硬件、摄像头或局域网设备
• VPS 可以跑 Gateway，也可以作为一个长期在线的中心节点

最简单的架构图是：

用户消息 → Gateway → Agent → 工具请求 → Node → 设备能力 → 结果回 Gateway → 回复用户

图：Gateway 负责消息、模型和编排；Node 负责提供设备侧能力，例如摄像头、屏幕、位置、远程命令和浏览器代理。

二、Node 不是 Gateway

这是新手最容易混的一点。

Node 不是另一个 Gateway。

文档里也明确写了：

Nodes are peripherals, not gateways.

翻译过来就是：

节点是外围设备，不是网关。

这句话非常重要。

Gateway 做什么？

Gateway 是长期运行的中枢。

它负责打开和维护聊天渠道，比如：

• Telegram
• WhatsApp
• Discord
• Slack
• Signal
• iMessage
• WebChat

用户消息先到 Gateway。

Agent 也主要由 Gateway 负责调度。

Node 做什么？

Node 连接到 Gateway，声明自己能提供哪些能力。

比如：

• camera.*
• canvas.*
• screen.record
• location.get
• system.run
• system.which

Node 不负责接 Telegram 消息。

Node 也不是独立的 OpenClaw 主服务。

所以一句话记住：

消息进 Gateway，能力在 Node。

三、为什么需要多节点？

如果一台机器什么都能做，那当然简单。

但现实世界不是这样。

不同设备有不同优势。

VPS 的优势

• 7×24 在线
• 公网或稳定网络
• 适合跑 Gateway
• 适合接聊天渠道
• 适合 cron、heartbeat、webhook

手机的优势

• 有摄像头
• 有定位
• 在人身边
• 可以作为移动传感器
• 可以拍照、录短视频

Mac / Windows 电脑的优势

• 有桌面环境
• 有浏览器登录态
• 有本地文件和开发环境
• 适合浏览器自动化、屏幕、命令执行

树莓派 / 家庭主机的优势

• 在局域网内
• 可以接硬件
• 可以控制本地设备
• 可以靠近传感器或摄像头
• 成本低，适合长期运行

Build server / NAS 的优势

• 文件多
• 存储稳定
• 适合跑构建、备份、扫描、自动化脚本

所以多节点的本质是：

让每台设备提供它最擅长的能力。

图：VPS 适合跑 Gateway，手机适合提供摄像头和位置，Mac 适合浏览器和桌面能力，树莓派适合局域网硬件和边缘设备。

四、Node 怎么连接 Gateway？

OpenClaw 文档里说，Nodes 和普通控制客户端一样，连接到 Gateway 的 WebSocket。

默认 Gateway 地址通常是：

127.0.0.1:18789

但节点连接时有一个特别点：

Node 在 connect 时会声明 role: node。  

同时，它还会声明自己有哪些能力和命令。

比如：

• camera
• canvas
• location
• screen
• system.run

Gateway 收到连接后，不是直接信任它。

它会走设备配对流程。

五、节点配对：先建立信任

Node 连接 Gateway 时，会带设备身份。

如果是新设备，Gateway 会创建 pairing request。

你需要批准它。

常见命令是：

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

也可以查看节点状态：

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

这里要记住：

配对解决的是：这个设备能不能成为受信任的 node。

配对不是“允许它执行所有命令”。

节点能力还要经过命令策略、权限、exec approvals 等多层控制。

六、节点命令不是想调就调

Node 声明自己有某些命令，不代表 Gateway 一定允许调用。

文档里提到，node commands 至少要过两个 gate：

1. 节点在 WebSocket connect 时声明了这个 command
2. Gateway 的 node command policy 允许这个 command

有些相对安全的命令，平台默认可能允许。

但危险或隐私重的命令，比如：

• camera.snap
• camera.clip
• screen.record

通常需要显式 opt-in。

也就是要通过配置里的 allowlist 开启。

这很合理。

因为摄像头、屏幕、麦克风都属于隐私能力。

所以你要记住：

Node 能做什么，要看它声明了什么；OpenClaw 能不能调用，还要看策略允不允许。

七、Pairing、Command Policy、Exec Approvals 三层别混

多节点里最容易混的安全概念有三个：

• Pairing
• Command Policy
• Exec Approvals

它们不是一回事。

1）Pairing：这个设备能不能连接

它回答：

这个 node 是不是被信任的设备？

没有配对，节点不能作为 node 正常提供能力。

2）Command Policy：这个命令能不能被调用

它回答：

Gateway 是否允许调用这个 node command？

比如 camera.snap、screen.record 这种隐私能力，可能需要额外允许。

3）Exec Approvals：这条 shell 命令能不能在 node 上执行

如果你想让 Agent 在 node host 上执行命令，会走 system.run。

这时还要看节点本机的 exec approvals。

比如：

openclaw approvals get --node <idOrNameOrIp>

或者给节点添加 allowlist：

openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

所以三者关系是：

Pairing 管设备信任，Command Policy 管节点能力，Exec Approvals 管远程命令执行。

图：节点安全由三层组成：设备配对、命令策略、exec approvals。它们分别控制设备信任、能力调用和远程命令执行。

八、手机节点适合做什么？

手机节点最大的优势是：

它在现实世界里。

它可以提供很多服务器没有的能力。

1）拍照

比如：

openclaw nodes camera snap --node <id>

手机可以把当前环境拍给 Agent 看。

适合：

• 看房间状态
• 看设备指示灯
• 看纸质文档
• 看现场物品

2）短视频

比如：

openclaw nodes camera clip --node <id> --duration 10s

适合需要观察动态变化的场景。

3）位置

节点可以支持 location.get。

适合位置相关场景。

但位置是敏感信息，默认不应该随便开启。

4）移动设备上下文

手机在用户身边，适合做“随身传感器”。

但也要注意：iOS / Android 上很多能力需要 App 前台运行、系统权限允许。

文档里提到，iOS / Android 节点上的 canvas.*、camera.*、screen.* 往往有 foreground requirement。

也就是 App 在后台时，调用会失败，常见错误是：

NODE_BACKGROUND_UNAVAILABLE

这不是 bug。

这是移动系统的权限和隐私限制。

九、macOS 节点适合做什么？

macOS 节点很适合作为桌面能力提供者。

它可以提供：

• 本机摄像头
• 屏幕录制
• Canvas
• 浏览器相关能力
• 本地文件和开发环境
• 通过 node host 执行命令

如果你经常需要 Agent 帮你看网页、截图、做桌面验证，Mac 节点很有价值。

不过 macOS 的隐私权限也很多，比如：

• Camera
• Microphone
• Screen Recording
• Accessibility

如果权限没给，节点能连接，但能力会失败。

所以排错时不能只看“节点在线”。

还要看：

• 节点是否声明了能力
• Gateway 是否允许命令
• macOS 权限是否给了
• App 是否处于需要的状态

十、headless node host：让命令跑在另一台机器上

文档里有一个很重要的 CLI：

openclaw node run

它可以启动一个 headless node host。

这类节点主要提供：

• system.run
• system.which

也就是让 Agent 可以在另一台机器上执行命令。

常见场景：

• Gateway 在 VPS，但命令要在家里 NAS 跑
• Gateway 在云服务器，但构建要在本地 Mac 跑
• Gateway 在小机器上，但重任务要在 build server 跑
• Agent 要管理多个实验机器或开发机器

启动示例：

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 start

这里要注意：

headless node host 不是 Gateway。它只是连接到 Gateway，提供远程执行能力。  

十一、exec 怎么跑到 node 上？

第 12 课讲过 exec。

当你有 node host 后，exec 可以选择：

host=node

也就是把 shell 命令转发到节点机器执行。

可以通过配置设置默认：

openclaw config set tools.exec.host nodeopenclaw config set tools.exec.security allowlistopenclaw config set tools.exec.node "<id-or-name>"

也可以在当前会话里设置：

/exec host=node security=allowlist node=<id-or-name>

这里有两个关键点。

1）host=auto 不会自动选 node

文档里提到：

host=auto will not implicitly choose the node on its own.

也就是说，默认 auto 不会自己猜“我要去哪个节点跑”。

你要显式指定 node。

2）node exec 仍然受 approvals 控制

即使指定了 node，也不是随便执行。

还要经过 node host 上的 exec approvals。

这是安全边界。

十二、树莓派节点适合做什么？

树莓派不是 OpenClaw 特殊概念。

它本质上可以作为一种 Linux node host 或边缘设备。

适合这些场景：

• 长期开机
• 放在家里局域网
• 接摄像头
• 接传感器
• 控制本地设备
• 执行轻量脚本
• 作为家庭自动化桥接点

比如：

• 检查门口摄像头
• 读取局域网设备状态
• 控制某个本地脚本
• 在家里网络里访问不能公网暴露的服务

树莓派的优势是：

离设备近，长期在线，成本低。

但它也有局限：

• 性能有限
• 存储容易损坏
• 网络可能不稳定
• 不适合重模型推理或大规模构建

所以别把树莓派当万能服务器。

让它做边缘能力提供者更合适。

十三、VPS 适合放 Gateway 吗？

很多情况下，VPS 很适合放 Gateway。

原因是：

• 长久在线
• 网络稳定
• 方便接 Telegram / Discord / Webhook
• cron / heartbeat 不容易断
• 手机和本地节点都可以连回来

但也不是必须。

如果你只在本地使用，也可以在本机跑 Gateway。

VPS 更适合：

• 你希望 OpenClaw 7×24 在线
• 你需要外部 webhook 触发
• 你要远程聊天渠道一直可用
• 你有多个节点要接入

不过 Gateway 放 VPS 时，要特别注意：

• 认证 token
• Gateway 端口暴露
• Tailscale / VPN
• HTTPS / WSS
• 节点连接安全
• 不要把私有入口裸露公网

第 22 课会专门讲 Tailscale 组网。

这里先记住：

Gateway 可以放 VPS，但不要裸奔暴露。

十四、节点之间会互相通信吗？

通常不是。

OpenClaw 的基本模式是：

Node A → Gateway ← Node B

节点连接到 Gateway。

Gateway 编排它们。

节点之间一般不直接互相调度。

比如：

• 手机拍照，结果回 Gateway
• Gateway 把图片给 Agent 分析
• Agent 再决定是否让树莓派执行某个命令

看起来像手机和树莓派协作。

但实际调度中心是 Gateway。

所以更准确地说：

节点不是互相串联，而是围绕 Gateway 协作。

图：多个节点通常不直接互相通信，而是围绕 Gateway 协作。Gateway 负责接收、编排、转发和汇总结果。

十五、一个典型家庭架构

假设你想搭一个家庭 OpenClaw。

可以这样设计：

VPS

负责：

• 跑 Gateway
• 接 Telegram
• 接 Webhook
• 跑 Cron / Heartbeat

手机 Node

负责：

• 拍照
• 获取位置
• 移动场景上下文

树莓派 Node

负责：

• 局域网设备检查
• 轻量脚本
• 本地传感器
• 家庭自动化桥接

Mac Node

负责：

• 浏览器自动化
• 本机开发环境
• 屏幕 / 摄像头
• 某些需要登录态的网站操作

Agent 工作流

比如你问：

帮我看看家里网络是不是正常。

可能流程是：

1. Telegram 消息到 VPS Gateway
2. Agent 判断需要局域网信息
3. Gateway 调用树莓派 Node 执行只读检查
4. 如果需要视觉信息，调用手机或摄像头节点拍照
5. Agent 汇总结果
6. Gateway 通过 Telegram 回复你

这就是多节点协作。

十六、一个开发者架构

如果你是开发者，可能更适合这样：

VPS Gateway

负责：

• 长期在线
• 接收消息
• 自动化任务
• webhook

Mac / Linux Build Node

负责：

• 跑测试
• 跑构建
• 访问本地 repo
• 浏览器登录态

手机 Node

负责：

• 临时拍照
• 移动通知
• 现实世界输入

工作流例子：

GitHub webhook 触发 Gateway，Agent 分析失败日志，然后让 Build Node 拉代码跑测试，最后把结果发到 Telegram。

这里 Gateway 不需要自己承担所有执行。

它只负责协调。

执行发生在更合适的节点上。

十七、一个最小多节点入门路径

新手不要一开始就搭很复杂。

我建议按这个顺序来：

第一步：先跑单 Gateway

确认：

• OpenClaw 能正常聊天
• Gateway 状态正常
• Agent 能回复

第二步：接一个手机节点

先学会：

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

确认节点能连接。

第三步：只测试低风险能力

比如：

openclaw nodes statusopenclaw nodes describe --node <id>

不要一上来就开摄像头、屏幕录制、远程命令。

第四步：再测试 camera / location 等能力

确保 App 在前台，权限已允许。

第五步：再接 headless node host

让另一台机器提供 system.run。

但一定先配 exec approvals 和 allowlist。

第六步：再考虑 Tailscale 组网

如果跨网络连接节点，下一课会讲 Tailscale。

这个顺序更安全。

不要一上来就：

VPS + 手机 + Mac + 树莓派 + 公网暴露 + 远程命令全开。  

那样排错会很痛苦。

十八、常用节点检查命令

多节点排错时，先用这些命令。

查看节点状态

openclaw nodes statusopenclaw nodes status --connectedopenclaw nodes listopenclaw nodes list --connected

查看待批准设备

openclaw devices list

批准设备

openclaw devices approve <requestId>

查看节点详情

openclaw nodes describe --node <idOrNameOrIp>

查看 node exec approvals

openclaw approvals get --node <idOrNameOrIp>

调用节点能力

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

不过新手尽量先用高级 helper，比如 camera、canvas、screen 这些 CLI 子命令，而不是一开始就 raw invoke。

十九、常见错误和排查方向

1）节点看起来在线，但能力调用失败

可能原因：

• 节点没有声明这个 command
• Gateway policy 没允许这个 command
• App 在后台
• 系统权限没给
• 设备设置里关闭了能力

2）手机 camera 失败

常见原因：

• App 不在前台
• Camera 权限没给
• 节点设置里 camera disabled

可能错误：

NODE_BACKGROUND_UNAVAILABLECAMERA_DISABLED*_PERMISSION_REQUIRED

3）location 失败

常见原因：

• location mode 是 off
• OS 权限没给
• Android App 在后台
• precise location 没开

4）node exec 失败

常见原因：

• node 没配对
• system.run 没声明或没允许
• exec approvals 拒绝
• allowlist miss
• 命令路径不匹配

5）跨网络连不上

常见原因：

• Gateway 只绑定 loopback
• 没有 SSH tunnel / Tailscale
• token 没传
• 防火墙拦截
• ws/wss 配置不对

这些我们会在第 22、23 课继续讲。

二十、多节点安全原则

我建议记住这几条。

1. Gateway 是中枢，Node 是外围能力。
2. 节点不是 Gateway，不负责接聊天渠道。
3. 先配对，再调用能力。
4. 摄像头、位置、屏幕都是隐私能力，必须谨慎启用。
5. 远程命令执行必须经过 exec approvals。
6. 不要把 Gateway 端口裸露公网。
7. 跨网络连接优先用 Tailscale / VPN / SSH tunnel。
8. 先搭一个节点跑通，再扩展多节点。

图：多节点架构要先建立信任，再开放能力。设备配对、命令策略、权限和网络边界都不能省。

二十一、适合新手的多节点提问模板

下面这些句式可以直接复制。

1）检查节点状态

请帮我检查当前 OpenClaw 节点状态，只做只读检查，不要修改配置。

2）解释某个节点能做什么

请查看这个节点的 describe 信息，解释它声明了哪些能力，哪些能力可能还需要权限或策略允许。

3）排查 camera 失败

手机节点 camera.snap 失败了。请按 pairing、command policy、App 前台、系统权限、节点设置这几个方向排查。

4）设计家庭多节点架构

我有一台 VPS、一台手机和一个树莓派。请帮我设计 OpenClaw 多节点架构，说明 Gateway 放哪里、每个节点负责什么、哪些能力先不要开启。

5）设计开发者多节点架构

我想让 Gateway 跑在 VPS，但构建和浏览器自动化跑在 Mac。请帮我设计 node host 和 exec host=node 的安全配置思路。

6）检查 node exec 安全

请帮我检查 node exec approvals，只读查看当前策略，不要放开 full 权限，优先建议 allowlist。

7）跨网络连接规划

Gateway 在 VPS，节点在家里局域网。请先说明推荐网络方案，不要建议裸露公网端口。

这些模板的重点是：

先理解架构和边界，再开启能力。

二十二、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

Gateway 负责接收、思考和编排；Node 负责提供设备侧能力。

再补一句安全原则：

节点先配对，能力再授权，远程命令还要 approvals。

二十三、总结

今天这节课，我们讲清楚了 OpenClaw 的多节点架构：

1. Gateway 是中枢，Node 是外围能力提供者。
2. Node 不是 Gateway，不负责接聊天渠道。
3. Nodes 通过 WebSocket 连接 Gateway，并声明 role: node。
4. 节点需要设备配对，配对是信任入口。
5. 节点命令还要受 Gateway command policy 控制。
6. 远程 shell 执行还要经过 node host 上的 exec approvals。
7. 手机节点适合摄像头、位置、现场感知。
8. macOS 节点适合桌面、浏览器、本地开发环境。
9. headless node host 适合远程命令执行。
10. 树莓派适合局域网、硬件、边缘设备能力。
11. VPS 适合跑 Gateway，但不要裸露公网。
12. 多节点不是越多越好，要先小范围跑通，再扩展。

从这一课开始，OpenClaw 不再只是“一个 Agent 跑在一台机器上”。

它开始变成一个跨设备的个人 AI 系统：

• VPS 做中枢
• 手机做感官
• Mac 做桌面能力
• 树莓派做边缘控制
• Node host 做远程执行

这就是 OpenClaw 多平台协作的基础。

下一课预告

下一课我们会讲：

第 22 课：Tailscale 组网——跨网络连 OpenClaw

也就是：

• 为什么多节点经常需要 Tailscale
• Gateway 在 VPS、节点在家里时怎么连接
• 为什么不建议裸露公网端口
• Tailscale 和 SSH tunnel 怎么选
• Tailnet 下节点配对和安全要注意什么

🦞 本文由八条撰写，持续更新中。