OpenClaw 网关与子节点配对指南：构建分布式 AI 助手网络

2.3 通信机制

网关与子节点之间的通信基于 WebSocket 协议。当节点连接到网关时，会建立一个持久的双向通信通道，用于心跳检测、任务分发、结果回传以及事件推送。这种设计确保了低延迟、双向通信以及连接保持，避免了频繁建立/断开连接的开销。

2.4 安全模型

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

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

这种安全模型在提供便利性和安全性之间取得了平衡。

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

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

1. 用户发起请求：用户通过 WebChat 发送消息："让 Robot01 执行 uname -a"
2. 网关接收：Gateway 的 WebSocket 服务器接收消息
3. 意图理解：AI 模型解析请求，识别需要远程执行
4. 节点选择：根据请求中的节点标识（Robot01）选择目标节点
5. 命令封装：将请求封装为节点可执行的指令格式
6. 指令发送：通过 WebSocket 将指令发送给 Robot01 节点
7. 本地执行：Robot01 收到指令，在本地操作系统上执行
8. 结果回传：执行结果通过 WebSocket 返回给 Gateway
9. 结果处理：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 CLI 以及基础工具（curl, wget, git 等）。

# 检查 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 [email protected]

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 关键配置项解析

bind 模式

"bind": "loopback"

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

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

auth.token

"token": "xxxxx"

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

安全建议：

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

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 隧道连接到网关。

理解 SSH 隧道

SSH 隧道的工作原理如下：

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

建立 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 的节点配对是一个两阶段过程：

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

这种设计确保了未经授权的设备无法加入网络，管理员可以控制网络的规模，并在批准前验证节点的身份。

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 配置格式

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

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

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

配置项说明：

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

白名单模式

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

{
  "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 工具来管理子节点。以下是常用操作：

查看节点状态

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

在节点上执行命令

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

节点文件操作

# 从节点下载文件
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 安全建议

1. 定期更换 Token：每隔一段时间更换 Gateway Token。
2. 限制 SSH 访问：使用密钥认证，禁用密码登录。
3. 网络隔离：将节点放在独立的 VLAN 中。
4. 监控日志：定期审查节点执行日志。

14.2 性能优化

1. 减少延迟：使用有线网络连接节点。
2. 批量操作：将多个命令合并执行。
3. 缓存结果：对于频繁访问的数据使用缓存。

14.3 可维护性

1. 标准化配置：使用配置模板。
2. 文档记录：记录每个节点的功能和配置。
3. 自动化部署：使用 Ansible 等工具批量部署。

15. 总结与展望

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

1. 理解了分布式架构：从单机助手扩展为分布式 AI 网络。
2. 掌握了配置技能：学会了 Gateway 和 Node 的配置方法。
3. 建立了安全意识：深入理解了认证、审批、执行授权机制。
4. 实践了集成能力：实现了节点与 MCP 文件服务器的交互。

展望未来，我计划：

1. 添加更多子节点，扩展网络规模。
2. 集成更多 MCP 服务，丰富功能生态。
3. 实现跨互联网连接，支持远程访问。
4. 探索更复杂的自动化场景。