政安晨【人工智能项目随笔】OpenClaw网关与子节点完整配对指南——从零构建分布式AI助手网络

Ne0inhk

22 Mar 2026 — 26 min read

政安晨的个人主页：政安晨

欢迎 👍点赞✍评论⭐收藏

希望政安晨的博客能够对您有所裨益，如有不足之处，欢迎在评论区提出指正！

1.前言：从单机助手到分布式AI助手

2. 概念解析：OpenClaw网关与子节点

5.2.3 nodes.denyCommands

8. 执行授权：exec-approvals配置完全指南

8.1 为什么需要exec-approvals

9. 实战演练：Robot01节点完整配对过程

1.前言：从单机助手到分布式AI助手

在我过去的博客文章中，让我们见证了单个AI助手的强大能力——它可以对话、推理、生成语音、识别图像，甚至可以控制浏览器执行复杂任务。

然而，随着使用场景的不断深入，我们不可避免地会遇到一个瓶颈：单机处理能力的局限。

想象以下场景：

场景一：你正在让主电脑运行GPT-SoVITS进行语音合成，同时还要处理大量的文档分析任务，此时再让它执行浏览器自动化操作，会发现系统响应变得迟缓。
场景二：你希望在不同地点的设备上都能使用AI助手，但每个设备都独立运行一个完整的OpenClaw实例，导致数据不同步，体验碎片化。
场景三：你希望让AI助手控制家中的多台设备（如智能摄像头、NAS存储、远程服务器），但这些设备本身无法运行完整的OpenClaw。

面对这些挑战，OpenClaw提供了子节点（Node）机制，允许我们将多台设备组织成一个分布式AI助手网络。在这个网络中：

网关（Gateway） 是中央大脑，负责接收指令、协调任务、分发工作
子节点（Node） 是分布式执行单元，各自承担特定功能

这种架构带来了诸多优势：

算力扩展：通过增加节点来分担计算负载
功能分布：不同节点可以专注于不同能力（如浏览器、文件系统、硬件控制）
地理分布：节点可以部署在不同地点，通过网络连接
容错备份：某个节点故障不影响整体系统运行
统一管理：所有节点通过单一网关进行协调

本文将详细记录我为OpenClaw网关添加第一个子节点（Robot01）的完整过程，包括架构设计思路、配置步骤、常见问题以及优化经验。无论你是希望扩展现有AI助手能力，还是构建更复杂的自动化系统，本文都将提供详尽的操作指南。

2. 概念解析：OpenClaw网关与子节点

2.1 网关（Gateway）

在OpenClaw的架构中，网关（Gateway）是整个系统的核心组件。它不仅仅是一个WebSocket服务器，更是整个AI助手网络的大脑和协调中心。

网关的核心职责包括：

消息路由：接收来自各个渠道（WebChat、Telegram、飞书等）的用户消息，理解意图，并分发给相应的处理模块
任务编排：将复杂任务分解为子任务，分发给合适的执行单元
状态管理：维护整个网络的拓扑结构、节点状态、对话上下文
安全控制：验证身份、执行权限检查、管理节点配对
资源调度：协调各节点的计算资源，优化任务分配

在我的部署中，网关运行在以下环境：

主机：Ubuntu 22.04 / 24.04
IP地址：172.23.1.13
端口：18789（默认WebSocket端口）
绑定模式：loopback（本地绑定）
版本：v2026.2.13

2.2 子节点（Node）

子节点是连接到网关的外部设备，它们可以是：

树莓派：适合轻量级任务，如传感器数据采集、简单自动化
旧电脑/服务器：可以承担中等负载，如文件处理、小规模推理
高性能工作站：可以运行复杂的AI任务，如图像生成、大模型推理
移动设备：iOS/Android设备，通过配套应用连接

每个子节点可以暴露不同的能力（Capabilities），常见包括：

browser：浏览器控制能力，可以执行网页自动化
system：系统执行能力，可以在节点上运行shell命令
camera：摄像头捕获能力
canvas：画布截取能力
screen：屏幕录制能力

在我的网络中，Robot01节点具备以下能力：

nodeId: xxxxxxx displayName: Robot01 platform: linux version: 2026.2.14 caps: ["browser", "system"]

2.3 通信机制

网关与子节点之间的通信基于WebSocket协议。当节点连接到网关时，会建立一个持久的双向通信通道，用于：

心跳检测：节点定期发送心跳包，报告自身状态
任务分发：网关向节点发送执行指令
结果回传：节点将执行结果返回给网关
事件推送：节点主动向网关推送事件（如检测到移动物体）

这种设计确保了：

低延迟：相比HTTP轮询，WebSocket提供更低的通信延迟
双向通信：节点不仅可以响应请求，还能主动推送信息
连接保持：避免了频繁建立/断开连接的开销

2.4 安全模型

OpenClaw采用了多层安全模型来保护整个系统：

身份认证：节点连接时需要提供有效的Gateway Token
配对审批：新节点需要经过网关管理员审批才能加入
命令过滤：某些敏感命令（如camera.snap）被默认禁止
执行审批：节点上的命令执行可以被配置为需要审批

这种安全模型在提供便利性（自动执行）和安全性（防止恶意控制）之间取得了平衡。

3. 架构设计：为什么要使用子节点

3.1 场景驱动：从需求到架构

在深入技术细节之前，让我们先理解为什么需要子节点架构。以下是我在实际使用中遇到的具体场景：

场景一：计算资源隔离

GPT-SoVITS是一个计算密集型应用，需要大量的GPU显存。当我使用GPT-SoVITS进行语音合成时，GPU几乎满负荷运行。此时，如果再让OpenClaw执行其他AI任务（如浏览器自动化），系统响应会变得非常缓慢。

通过将GPT-SoVITS部署在独立的子节点上，我们可以：

将计算密集型任务与IO密集型任务分离
避免单点瓶颈，提高整体系统响应速度
允许不同任务独立扩展

场景二：物理设备控制

我希望在不同地点都能控制家中的智能设备。这些设备包括：

NAS存储：用于存放和同步文件
智能摄像头：用于家庭安防监控
远程服务器：用于后台数据处理

传统方式是在每台设备上安装完整的OpenClaw，但这会导致：

配置不一致，每个实例需要单独配置
数据不同步，对话历史、记忆无法共享
管理复杂，维护多个独立系统

通过子节点架构，我们可以：

保持单一的网关作为控制平面
将具体的设备控制委托给各子节点
统一数据存储和上下文管理

场景三：能力扩展

不同的子节点可以暴露不同的硬件能力：

带有摄像头的设备：可以执行视觉识别任务
配备麦克风的设备：可以接收语音输入
连接显示器的设备：可以展示图像和视频

这种模块化设计使得系统可以灵活地适应各种使用场景。

3.2 拓扑结构

基于上述需求，我设计了一个分层分布式架构：

 ┌─────────────────────────────────────────┐ │ OpenClaw Gateway │ │ (172.23.1.13:18789) │ │ │ │ • 消息路由 │ │ • 任务编排 │ │ • 状态管理 │ │ • 安全控制 │ └────────────────┬────────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Robot01 │ │ (未来节点2) │ │ (未来节点3) │ │ 172.23.1.27 │ │ IP: TBD │ │ IP: TBD │ │ │ │ │ │ │ │ • browser │ │ • system │ │ • camera │ │ • system │ │ • 文件处理 │ │ • 视觉识别 │ │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘

在这个架构中：

Gateway 是唯一的入口点，处理所有外部通信
Robot01 节点目前承担浏览器自动化和系统命令执行
未来的节点将被添加到网络中，各自承担特定功能
所有节点通过内网连接，保证低延迟和安全性

3.3 数据流设计

让我们追踪一个典型的任务执行流程：

用户发起请求：用户通过WebChat发送消息："让Robot01执行 uname -a"
网关接收：Gateway的WebSocket服务器接收消息
意图理解：AI模型解析请求，识别需要远程执行
节点选择：根据请求中的节点标识（Robot01）选择目标节点
命令封装：将请求封装为节点可执行的指令格式
指令发送：通过WebSocket将指令发送给Robot01节点
本地执行：Robot01收到指令，在本地操作系统上执行
结果回传：执行结果通过WebSocket返回给Gateway
结果处理：Gateway将结果格式化，返回给用户

整个过程对用户是透明的，用户只需要在消息中指定目标节点即可。

4. 准备工作：环境与工具清单

4.1 硬件准备

网关设备（已配置）

主机：台式机/服务器
操作系统：Ubuntu 22.04 或更高版本
网络：连接到局域网（我的是 172.23.1.13）
OpenClaw版本：v2026.2.13

子节点设备（Robot01）

主机：PC主机（华硕主板）
操作系统：Ubuntu 24.04
IP地址：172.23.1.27
网络：与网关同一局域网
OpenClaw版本：v2026.2.14

4.2 软件准备

网关端

确保Gateway上已安装OpenClaw：

# 检查OpenClaw版本 openclaw --version # 查看网关状态 openclaw gateway status # 查看节点状态 openclaw nodes status

节点端

在子节点上需要安装：

Node.js：OpenClaw基于Node.js运行
OpenClaw CLI：用于启动节点
基础工具：curl, wget, git等

# 检查Node.js版本 node --version # 检查npm版本 npm --version # 安装OpenClaw（如果未安装） npm install -g openclaw

4.3 网络配置

端口要求

端口	用途	说明
18789	Gateway WebSocket	节点连接网关使用
18790	隧道转发端口	SSH隧道本地端口

防火墙配置

确保以下端口在局域网内可访问：

# 检查端口状态 sudo ufw status # 如果需要，开放端口 sudo ufw allow 18789/tcp sudo ufw allow 18790/tcp

SSH访问

节点需要能通过SSH连接到网关（用于建立反向隧道）：

# 在节点上测试SSH连接 ssh -p 22 [email protected]

4.4 信息记录

在开始配置之前，建议记录以下信息：

项目	网关	节点
主机名	xxx-System-Product-Name	robot01-All-Series
IP地址	172.23.1.13	172.23.1.27
用户名	xxx	robot01
Gateway Token	xxxx	-
SSH端口	22	22

5. 网关配置：主节点设置详解

5.1 Gateway配置文件

OpenClaw的配置文件位于 ~/.openclaw/openclaw.json。以下是与我网络配置相关的关键部分：

{ "gateway": { "port": 18789, "mode": "local", "bind": "loopback", "auth": { "mode": "token", "token": "xxxxxxx" }, "tailscale": { "mode": "off" }, "nodes": { "denyCommands": [ "camera.snap", "camera.clip", "screen.record", "calendar.add", "contacts.add", "reminders.add" ] } }, "tools": { "exec": { "host": "sandbox" } } }

5.2 关键配置项解析

5.2.1 bind模式

"bind": "loopback"

loopback：只绑定127.0.0.1，只能本地连接
lan：绑定0.0.0.0，允许局域网连接
其他值：可以绑定特定网卡

重要：当设置为 loopback 时（默认模式），外部节点无法直接连接。这是因为WebSocket服务器只在本地回环接口上监听。此时需要使用SSH隧道来解决连接问题。

5.2.2 auth.token

"token": "xxxxx"

这是节点连接时需要提供的认证令牌。它相当于网关的"密码"，确保只有授权的设备才能加入网络。

安全建议：

使用足够长的随机字符串
定期更换token
不要将token分享给不信任的人

5.2.3 nodes.denyCommands

"denyCommands": [ "camera.snap", "camera.clip", "screen.record", "calendar.add", "contacts.add", "reminders.add" ]

这些命令在任何节点上都被禁止执行，即使节点已经获得执行权限。这是一个额外的安全层，防止恶意软件利用节点进行隐私侵犯。

5.3 查看Gateway状态

配置完成后，可以查看Gateway的运行状态：

# 启动Gateway（如果未运行） openclaw gateway start # 查看Gateway状态 openclaw gateway status # 查看已连接的节点 openclaw nodes status

输出示例：

Gateway: running on http://127.0.0.1:18789 Version: v2026.2.13 Nodes: - Robot01 (connected) Platform: linux Caps: browser, system Connected: 2026-02-15T17:54:28Z

5.4 节点管理命令

OpenClaw提供了丰富的节点管理命令：

# 查看所有节点（包括未连接的） openclaw nodes list # 查看待批准的节点请求 openclaw nodes pending # 批准节点配对 openclaw nodes approve <requestId> # 拒绝节点配对 openclaw nodes reject <requestId> # 查看节点详细信息 openclaw nodes describe --node Robot01

6. 子节点配置：从设备准备到连接

6.1 节点系统准备

在Robot01上，我们首先确保系统满足基本要求：

# 检查操作系统 uname -a # 输出: Linux robot01-All-Series 6.8.0-100-generic #100-Ubuntu SMP PREEMPT_DYNAMIC Tue Jan 13 16:40:06 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux # 检查网络连接 hostname -I # 输出: 172.23.1.27

6.2 安装OpenClaw节点

在节点设备上安装OpenClaw：

# 全局安装OpenClaw npm install -g openclaw # 检查安装 openclaw --version

6.3 SSH隧道建立

由于Gateway使用loopback绑定模式，节点需要通过SSH隧道连接到网关。

6.3.1 理解SSH隧道

SSH隧道的工作原理如下：

节点 (172.23.1.27) 网关 (172.23.1.13) | | | 1. SSH连接到网关 | | ─────────────────────────────────────> | | | | 2. 建立本地端口转发 | | 18790 -> 127.0.0.1:18789 | | | | 3. 节点连接到本地18790 | | (实际通过隧道到达网关18789) | | ─────────────────────────────────────> | | |

6.3.2 建立SSH隧道

在节点设备上执行：

# 建立SSH反向隧道（后台运行） ssh -N -L 18790:127.0.0.1:18789 [email protected] & # 验证隧道是否建立 netstat -tln | grep 18790

或者使用更简单的方式，节点直接连接（如果网络允许）：

# 直接连接到网关（如果网关绑定到lan模式） ssh -N -R 18789:127.0.0.1:18789 [email protected] &

6.4 启动节点

SSH隧道建立后，可以启动OpenClaw节点：

# 设置Gateway Token环境变量 export OPENCLAW_GATEWAY_TOKEN="xxx" # 启动节点（前台运行测试） openclaw node run --host 127.0.0.1 --port 18790 --display-name "Robot01"

启动成功的输出类似：

🔗 Node connecting to ws://127.0.0.1:18790... ✅ Node connected and awaiting approval

6.5 作为服务运行（生产环境）

生产环境中，建议将节点作为系统服务运行，以便在系统启动时自动启动：

# 安装为系统服务 sudo openclaw node install --host 127.0.0.1 --port 18790 --display-name "Robot01" # 启动服务 sudo openclaw node start # 查看服务状态 sudo openclaw node status # 查看日志 sudo openclaw node logs

7. 审批与配对：安全机制的深度理解

7.1 配对流程概述

OpenClaw的节点配对是一个两阶段过程：

节点连接阶段：节点尝试连接到网关，提供身份信息
网关审批阶段：网关管理员批准或拒绝节点加入

这种设计确保了：

未经授权的设备无法加入网络
管理员可以控制网络的规模
可以在批准前验证节点的身份

7.2 查看待批准的请求

在网关上，可以查看等待批准的节点请求：

openclaw nodes pending

输出示例：

Pending nodes: - requestId: abcxxx (Robot01) Platform: linux Version: 2026.2.14 Caps: browser, system Connection: 2026-02-15T17:54:28Z

7.3 批准节点

批准节点非常简单：

# 批准节点 openclaw nodes approve abcxxx

或者使用完整ID：

openclaw nodes approve xxx

批准后，节点状态会变为"已配对"：

Nodes: - Robot01 (connected) Platform: linux Caps: browser, system Paired: true Connected: 2026-02-15T17:54:28Z

7.4 拒绝节点

如果发现可疑的节点请求，可以拒绝：

# 拒绝节点 openclaw nodes reject <requestId>

拒绝后，节点会收到连接被拒绝的消息，并在一段时间内无法再次请求连接。

7.5 配对信息的持久化

批准节点后，配对信息会持久化到网关的配置中。即使网关重启，已配对的节点可以重新连接，无需再次审批。

8. 执行授权：exec-approvals配置完全指南

8.1 为什么需要exec-approvals

当节点连接到网关后，默认情况下，节点上的命令执行需要审批。这是OpenClaw的安全特性之一，防止AI模型在没有用户同意的情况下在节点上执行任意命令。

然而，在实际使用中，频繁的审批请求会严重影响使用体验。特别是对于自动化任务，每次执行都需要人工批准是不现实的。

exec-approvals机制允许我们配置自动执行的策略，在安全性和便利性之间取得平衡。

8.2 配置文件位置

exec-approvals配置文件位于节点的home目录下：

~/.openclaw/exec-approvals.json

注意：这个文件必须在节点设备上创建，不是在网关上。

8.3 配置格式

8.3.1 最简单的配置（允许所有）

如果你完全信任AI助手，可以配置为允许所有执行：

{ "version": 1, "defaults": { "security": "full", "ask": "off" } }

配置项说明：

security：
- deny：拒绝所有执行
- allowlist：仅允许白名单中的命令
- full：允许所有执行
ask：
- off：从不询问，直接执行
- on-miss：当命令不在白名单时询问
- always：每次执行都询问

8.3.2 白名单模式

如果你希望更安全，可以只允许特定命令：

{ "version": 1, "defaults": { "security": "allowlist", "ask": "on-miss", "askFallback": "deny" }, "allowlist": [ { "id": "1", "pattern": "curl*" }, { "id": "2", "pattern": "wget*" }, { "id": "3", "pattern": "ls*" } ] }

8.4 在Robot01上配置

在Robot01节点上执行：

# 创建配置目录 mkdir -p ~/.openclaw # 创建配置文件 cat > ~/.openclaw/exec-approvals.json << 'EOF' { "version": 1, "defaults": { "security": "full", "ask": "off" } } EOF # 验证配置 cat ~/.openclaw/exec-approvals.json

8.5 配置生效

配置修改后，需要重启节点才能生效：

# 停止当前运行的节点 pkill -f "openclaw node" # 重新启动节点 export OPENCLAW_GATEWAY_TOKEN="xxxxxx" openclaw node run --host 127.0.0.1 --port 18790 --display-name "Robot01"

8.6 验证配置

配置生效后，可以尝试在网关上执行节点命令：

openclaw nodes run --node Robot01 uname -a

9. 实战演练：Robot01节点完整配对过程

9.1 背景回顾

本次配对的背景是：

网关：运行在 Ubuntu 22.04 主机上，IP 172.23.1.13
节点：Robot01，运行在 Ubuntu 24.04 主机上，IP 172.23.1.27
目标：让Robot01能够执行浏览器自动化和系统命令

9.2 步骤一：准备工作检查

首先确认网络连通性：

# 从节点测试到网关的连接 ping -c 3 172.23.1.13 # 测试SSH端口 nc -zv 172.23.1.13 22

9.3 步骤二：创建SSH隧道

在Robot01上执行：

# 建立SSH反向隧道 # 这里使用的是从节点主动连接到网关的方式 # 注意：需要网关有SSH账号 ssh -N -R 18789:127.0.0.1:18789 [email protected] &

9.4 步骤三：启动节点

在Robot01上执行：

# 设置Token export OPENCLAW_GATEWAY_TOKEN="xxxxxx" # 启动节点 openclaw node run --host 127.0.0.1 --port 18790 --display-name "Robot01"

9.5 步骤四：批准配对

在网关上执行：

# 查看待批准列表 openclaw nodes pending # 批准节点（使用实际获得的requestId） openclaw nodes approve xxxxxx

9.6 步骤五：配置自动执行

在Robot01上执行：

# 创建exec-approvals配置 mkdir -p ~/.openclaw cat > ~/.openclaw/exec-approvals.json << 'EOF' { "version": 1, "defaults": { "security": "full", "ask": "off" } } EOF

9.7 步骤六：重启节点使配置生效

在Robot01上执行：

# 停止节点 pkill -f "openclaw node" # 重新启动 export OPENCLAW_GATEWAY_TOKEN="xxxxx" openclaw node run --host 127.0.0.1 --port 18790 --display-name "Robot01"

9.8 步骤七：验证连接

在网关上执行：

# 查看节点状态 openclaw nodes status

输出：

Nodes: - Robot01 Platform: linux Version: 2026.2.14 Caps: ["browser", "system"] Paired: true Connected: true ConnectedAt: 2026-02-15T17:54:28Z

9.9 步骤八：测试执行

在网关上测试节点命令执行：

# 测试基本命令 openclaw nodes run --node Robot01 uname -a

输出：

Linux robot01-All-Series 6.8.0-100-generic #100-Ubuntu SMP PREEMPT_DYNAMIC Tue Jan 13 16:40:06 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux

10. 节点操作：通过网关远程控制子节点

10.1 使用nodes工具

OpenClaw提供了 nodes 工具来管理子节点。以下是常用操作：

10.1.1 查看节点状态

# 查看所有节点状态 openclaw nodes status # 查看特定节点详情 openclaw nodes describe --node Robot01

10.1.2 在节点上执行命令

# 在节点上执行单个命令 openclaw nodes run --node Robot01 ls -la # 在节点上执行多个命令 openclaw nodes run --node Robot01 "uname -a && hostname"

10.1.3 节点文件操作

# 从节点下载文件 openclaw nodes download --node Robot01 /path/to/remote/file /local/path # 上传文件到节点 openclaw nodes upload --node Robot01 /local/file /path/to/remote

10.2 通过AI助手交互

最自然的交互方式是直接告诉AI助手你想在节点上执行什么：

用户：让Robot01执行 curl --version 助手：（自动调用节点接口，返回结果）

AI助手会理解你的意图，自动选择合适的节点，并执行相应的命令。

11. MCP集成：节点与文件服务器交互

11.1 MCP文件服务器概述

除了节点控制，我还部署了一个MCP文件服务器用于文件存储和共享。这个服务器提供了：

MCP协议接口：xxxx
REST API接口：
认证方式：Bearer Token

11.2 在节点上配置访问

为了让Robot01能够访问MCP服务器，我在文件服务器上为Robot01创建了专属目录，并上传了访问指南。

12. 多节点扩展：未来规划与最佳实践

12.1 扩展路线图

阶段一：单节点验证（已完成）

✅ Robot01节点配置完成
✅ 基本的执行和文件传输功能
✅ MCP服务器集成

阶段二：功能扩展（规划中）

添加第二个Linux节点，承担文件处理任务
添加摄像头节点，实现家庭安防监控
集成更多MCP服务

阶段三：地理分布（规划中）

在远程服务器上部署节点
配置Tailscale实现跨互联网连接
实现多地域容灾

12.2 节点命名规范

节点名	类型	功能	位置
Robot01	Linux PC	browser, system	本地机房
Robot02	Linux Server	文件处理	本地机房
Robot-Cam01	Raspberry Pi	camera	客厅
Robot-Remote	VPS	远程接入	云端