@hpplay-lebo/cluster-hub

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

功能

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

安装

方式一：openclaw plugins install（推荐）

openclaw plugins install @hpplay-lebo/cluster-hub
openclaw gateway restart

方式二：git clone

cd ~/.openclaw/extensions
git clone https://github.com/shenyingjun5/cluster-hub.git cluster-hub
openclaw gateway restart

更新

# 方式一（推荐，需通过 plugins install 安装的）
openclaw plugins update cluster-hub
openclaw gateway restart

# 方式二（git clone 安装的）
cd ~/.openclaw/extensions/cluster-hub && git pull
openclaw gateway restart

也可以直接告诉 AI："更新 Hub 插件"，它会自动执行。

从 git clone 迁移到 plugins install

已通过 git clone 安装的用户，可以迁移到 plugins install 管理：

rm -rf ~/.openclaw/extensions/cluster-hub
openclaw plugins install @hpplay-lebo/cluster-hub
openclaw gateway restart

已有配置（nodeId、token 等）保存在 openclaw.json 中，不受影响。

验证安装

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

配置

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

{
  "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：

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

快速开始

1. 创建集群（根节点）

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

openclaw hub register

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

2. 加入集群（子节点）

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

3. 开始使用

# 查看集群状态
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 | 查看任务队列和历史 |

飞书工具（Hub 自动下发）

如果 Hub 配置了飞书应用凭据，节点连接后自动获得以下工具：

| 工具 | 说明 | |------|------| | feishu_doc | 文档操作（读/写/追加/创建/块编辑） | | feishu_wiki | 知识库操作（空间/节点/创建） | | feishu_drive | 云空间管理（文件列表/创建文件夹/移动/删除） | | feishu_perm | 权限管理（查看/添加/移除协作者） | | feishu_contact | 通讯录查询（按姓名搜索/按邮箱查 open_id） | | feishu_message | 发送飞书消息（文本/富文本/批量发送） | | feishu_app_scopes | 查看应用权限 |

冲突处理: 如果节点已安装并启用了 OpenClaw 飞书插件，Hub 下发的工具会自动跳过，不会冲突。

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）
    ├── feishu-tools.ts     # 飞书工具集（Hub 下发凭据，自动注册）
    ├── store.ts            # 持久化存储（任务/聊天/节点事件）
    └── types.ts            # 类型定义

架构

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

文档

• CLI 命令参考 — 所有 CLI 命令、AI 工具、Gateway RPC 详细说明

License

MIT