Cluster Hub

Name: Cluster Hub
Rating: 3.5 (1 reviews)
Author: shenyingjun5

By shenyingjun5 👁 8 views ▲ 0 votes

OpenClaw Hub cluster plugin — cross-network node collaboration, chat, and task orchestration

GitHub

Configuration Example

{
  "plugins": {
    "entries": {
      "cluster-hub": {
        "enabled": true,
        "config": {
          // Hub 服务地址
          "hubUrl": "https://hub.openclaw.ai",
          // 节点显示名称
          "nodeName": "My Mac",
          // 节点别名（集群内唯一，用于 #别名 提及）
          "nodeAlias": "home",
          // 能力标签
          "capabilities": ["coding", "shell"],
          // 启动时自动连接 Hub
          "autoConnect": true

          // === 以下字段注册后自动写入，无需手动填 ===
          // "nodeId": "",
          // "token": "",
          // "clusterId": "",
          // "parentId": null
        }
      }
    }
  }
}

README

# @hpplay-lebo/cluster-hub

OpenClaw Hub 集群插件 — 让多台 OpenClaw 节点跨网络协作，实现聊天、任务分发和集群管理。

## 功能

- 🌐 **跨网络组网** — 通过云端 Hub 中转，不同网络下的 OpenClaw 节点自动组成集群
- 💬 **节点间聊天** — 从飞书/控制台与集群中任意节点对话（不限父子关系）
- ⚡ **任务分发** — 向子节点下发任务，支持批量并行 + 等待汇总
- 🌳 **树形集群** — 支持多层树形结构（最大深度 5 层），邀请码加入
- 📊 **状态监控** — 实时心跳、在线状态、任务统计
- 🔌 **自动重连** — 断线后自动重连，离线消息队列
- 🛠️ **CLI + AI 工具 + RPC** — 三种使用方式

## 安装

```bash
# 克隆到 OpenClaw 插件目录
cd ~/.openclaw/extensions
git clone https://github.com/shenyingjun5/cluster-hub.git cluster-hub

# 重启 Gateway
openclaw gateway restart
```

### 验证安装

```bash
openclaw plugins list
# 应看到 cluster-hub 状态为 loaded
```

## 配置

安装后编辑 `~/.openclaw/openclaw.json`，在 `plugins.entries` 中添加 `cluster-hub` 配置：

```jsonc
{
  "plugins": {
    "entries": {
      "cluster-hub": {
        "enabled": true,
        "config": {
          // Hub 服务地址
          "hubUrl": "https://hub.openclaw.ai",
          // 节点显示名称
          "nodeName": "My Mac",
          // 节点别名（集群内唯一，用于 #别名 提及）
          "nodeAlias": "home",
          // 能力标签
          "capabilities": ["coding", "shell"],
          // 启动时自动连接 Hub
          "autoConnect": true

          // === 以下字段注册后自动写入，无需手动填 ===
          // "nodeId": "",
          // "token": "",
          // "clusterId": "",
          // "parentId": null
        }
      }
    }
  }
}
```

> **注意**: 以上只展示了 `cluster-hub` 相关配置，实际 `openclaw.json` 中还有其他配置项（`auth`、`agents`、`channels` 等），请勿覆盖已有内容。

### 加入已有集群（子节点）

获取父节点的 ID 和邀请码，在配置中添加 `parentId`：

```jsonc
{
  "config": {
    "hubUrl": "https://hub.openclaw.ai",
    "nodeName": "Office Mac",
    "nodeAlias": "office",
    "parentId": "父节点的UUID",
    "capabilities": ["coding", "shell"]
  }
}
```

## 快速开始

### 1. 创建集群（根节点）

配置好 `hubUrl`、`nodeName`、`nodeAlias` 后注册：

```bash
openclaw hub register
```

注册成功后 `nodeId`、`token`、`clusterId` 自动写入配置。

### 2. 加入集群（子节点）

```bash
openclaw hub register --parent <父节点ID> --invite <邀请码>
```

### 3. 开始使用

```bash
# 查看集群状态
openclaw hub status

# 查看所有节点
openclaw hub nodes

# 给节点发指令
openclaw hub send <节点别名> "检查磁盘空间"

# 查看任务
openclaw hub tasks
```

## AI 工具

安装后 AI 自动获得以下工具：

| 工具 | 说明 |
|------|------|
| `hub_status` | 查看 Hub 连接状态和节点列表 |
| `hub_nodes` | 列出集群所有节点详情 |
| `hub_send` | 给节点发送任务 |
| `hub_batch_send` | 批量向多个节点下发任务（并行） |
| `hub_wait_task` | 等待单个任务完成并返回结果 |
| `hub_wait_all` | 等待多个任务全部完成并汇总 |
| `hub_tasks` | 查看任务队列和历史 |

**AI 对话示例：**

```
"查看集群状态"
"让 #office 执行 ls -la"
"给所有节点发送 '报告系统负载'"
```

## Gateway RPC

插件向 Gateway 注册了 18+ 个 RPC 方法（`hub.*`），供控制台和外部工具调用：

| RPC | 说明 |
|-----|------|
| `hub.status` | 连接状态 + changeSeq |
| `hub.connect` / `hub.disconnect` | 连接/断开 Hub |
| `hub.register` / `hub.unregister` | 注册/注销节点 |
| `hub.nodes` / `hub.node` | 节点列表/详情 |
| `hub.children` / `hub.tree` / `hub.clusters` | 子节点/树形/集群 |
| `hub.node.update` | 更新节点名称/别名 |
| `hub.invite.set` / `hub.invite.get` | 设置/获取邀请码 |
| `hub.task.send` / `hub.task.list` / `hub.task.get` / `hub.task.cancel` / `hub.task.clear` | 任务管理 |
| `hub.chat.send` / `hub.chat.history` / `hub.chat.list` / `hub.chat.clear` | 聊天管理 |
| `hub.node.events` | 节点上下线事件 |

## 配置项

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `hubUrl` | string | — | Hub 服务地址 |
| `nodeName` | string | — | 节点显示名称 |
| `nodeAlias` | string | — | 节点别名（`#` 提及用，集群内唯一） |
| `capabilities` | string[] | `["coding","shell"]` | 能力标签 |
| `parentId` | string\|null | null | 父节点 ID（null = 创建新集群） |
| `autoConnect` | boolean | true | 启动时自动连接 |
| `selfTaskMode` | `"local"\|"hub"` | `"local"` | 自发任务模式 |
| `heartbeatIntervalMs` | number | 30000 | 心跳间隔 (ms) |
| `reconnectIntervalMs` | number | 5000 | 断线重连间隔 (ms) |
| `taskTimeoutMs` | number | 300000 | 任务超时 (ms) |
| `nodeId` | string | — | 注册后自动写入 |
| `token` | string | — | JWT Token，注册后自动写入 |
| `clusterId` | string | — | 集群 ID，注册后自动写入 |

## 消息类型

Hub 节点间通过 WebSocket 通信，支持以下消息类型：

| 类型 | 方向 | 说明 |
|------|------|------|
| `task` | 父→子 | 下发任务 |
| `result` | 子→父 | 任务结果 |
| `task_ack` / `task_status` | 子→父 | 任务状态上报 |
| `task_cancel` | 父→子 | 取消任务 |
| `chat` | 任意 | 节点间聊天（不限父子） |
| `direct` | 任意 | 点对点消息（同集群） |
| `broadcast` | 父→全部 | 广播 |
| `heartbeat` | 双向 | 心跳保活 |

## 文件结构

```
cluster-hub/
├── package.json
├── openclaw.plugin.json    # 插件清单 + 配置 Schema
├── README.md
├── docs/
│   └── CLI.md              # CLI 命令完整参考
└── src/
    ├── index.ts            # 插件入口（RPC + AI 工具 + CLI + 后台服务）
    ├── hub-client.ts       # Hub 通讯客户端（WebSocket + REST）
    ├── store.ts            # 持久化存储（任务/聊天/节点事件）
    └── types.ts            # 类型定义
```

## 架构

```
┌─────────────────┐     ┌─────────────────┐
│  OpenClaw Node  │     │  OpenClaw Node  │
│  (cluster-hub)  │     │  (cluster-hub)  │
└────────┬────────┘     └────────┬────────┘
         │ WebSocket              │ WebSocket
         └──────────┐  ┌─────────┘
                 ┌───┴──┴───┐
                 │  Hub 服务  │
                 │ (云端中转)  │
                 └───┬──┬───┘
         ┌──────────┘  └─────────┐
         │ WebSocket              │ WebSocket
┌────────┴────────┐     ┌────────┴────────┐
│  OpenClaw Node  │     │   飞书机器人     │
│  (cluster-hub)  │     │  (Hub 内置)     │
└─────────────────┘     └─────────────────┘
```

## 文档

- **[CLI 命令参考](docs/CLI.md)** — 所有 CLI 命令、AI 工具、Gateway RPC 详细说明

## License

MIT

tools