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

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

欢迎 👍点赞✍评论⭐收藏

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

目录

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

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

2.1 网关（Gateway）

2.2 子节点（Node）

2.3 通信机制

2.4 安全模型

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

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

场景一：计算资源隔离

场景二：物理设备控制

场景三：能力扩展

3.2 拓扑结构

3.3 数据流设计

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

4.1 硬件准备

网关设备（已配置）

子节点设备（Robot01）

4.2 软件准备

网关端

节点端

4.3 网络配置

端口要求

防火墙配置

SSH访问

4.4 信息记录

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

5.1 Gateway配置文件

5.2 关键配置项解析

5.2.1 bind模式

5.2.2 auth.token

5.2.3 nodes.denyCommands

5.3 查看Gateway状态

5.4 节点管理命令

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

6.1 节点系统准备

6.2 安装OpenClaw节点

6.3 SSH隧道建立

6.3.1 理解SSH隧道

6.3.2 建立SSH隧道

6.4 启动节点

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

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

7.1 配对流程概述

7.2 查看待批准的请求

7.3 批准节点

7.4 拒绝节点

7.5 配对信息的持久化

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

8.1 为什么需要exec-approvals

8.2 配置文件位置

8.3 配置格式

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

8.3.2 白名单模式

8.4 在Robot01上配置

8.5 配置生效

8.6 验证配置

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

9.1 背景回顾

9.2 步骤一：准备工作检查

9.3 步骤二：创建SSH隧道

9.4 步骤三：启动节点

9.5 步骤四：批准配对

9.6 步骤五：配置自动执行

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

9.8 步骤七：验证连接

9.9 步骤八：测试执行

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

10.1 使用nodes工具

10.1.1 查看节点状态

10.1.2 在节点上执行命令

10.1.3 节点文件操作

10.2 通过AI助手交互

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

11.1 MCP文件服务器概述

11.2 在节点上配置访问

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

12.1 扩展路线图

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

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

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

12.2 节点命名规范

13. 故障排除：常见问题与解决方案

13.1 节点无法连接

13.2 执行被拒绝

13.3 命令执行失败

14. 深度优化：安全、性能与可维护性

14.1 安全建议

14.2 性能优化

14.3 可维护性

15. 总结与展望

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助手网络的大脑和协调中心。

网关的核心职责包括：

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

• 主机：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采用了多层安全模型来保护整个系统：

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

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 数据流设计

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

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

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版本
node –version

# 检查npm版本
npm –version

# 安装OpenClaw（如果未安装）
npm install -g openclaw

4.3 网络配置

端口要求

防火墙配置

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

# 检查端口状态
sudo ufw status

# 如果需要，开放端口
sudo ufw allow 18789/tcp
sudo ufw allow 18790/tcp

SSH访问

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

# 在节点上测试SSH连接
ssh -p 22 xxx@172.23.1.13

4.4 信息记录

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

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 xxx@172.23.1.13 &

# 验证隧道是否建立
netstat -tln | grep 18790

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

# 直接连接到网关（如果网关绑定到lan模式）
ssh -N -R 18789:127.0.0.1:18789 xxx@172.23.1.13 &

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 xxxxx@172.23.1.13 &

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 节点命名规范

13. 故障排除：常见问题与解决方案

13.1 节点无法连接

13.2 执行被拒绝

13.3 命令执行失败

14. 深度优化：安全、性能与可维护性

14.1 安全建议

14.2 性能优化

14.3 可维护性

15. 总结与展望

本文详细记录了为OpenClaw网关添加第一个子节点（Robot01）的完整过程。通过这个过程，我们：

展望未来，我计划：