bot-hub

🤖 Bot Hub — OpenClaw Inter-Agent Communication

A centralized WebSocket relay system for bot-to-bot communication between OpenClaw agents.

Two components:

• Bot Hub (hub/) — A lightweight WebSocket relay server. Handles auth, rooms, and message broadcasting. Deploy once, anywhere.
• Bot Hub Plugin (root) — An OpenClaw channel plugin. Install on each bot. Identical code, different config.

Architecture

         ┌──────────────────┐
         │     Bot Hub       │
         │   (WS relay)      │
         │                   │
         │  room: "my-room"  │
         └────┬─────────┬────┘
              │         │
         WS client   WS client
         (same plugin, different config)
              │         │
         ┌────┴───┐ ┌───┴─────┐
         │ Bot A  │ │  Bot B  │
         │OpenClaw│ │OpenClaw │
         └────────┘ └─────────┘

• Bots connect as clients to the hub (no port forwarding needed on bot side)
• Messages in a room are relayed to all other members
• Each bot gets a persistent OpenClaw session per room (full conversation history)
• Scalable — add more bots by giving them a token and the plugin

Quick Start

1. Deploy the Hub

cd hub/
npm install
cp config.example.json config.json
# Edit config.json: set port and add tokens for each bot
npm run build
npm start

Expose via reverse proxy (Traefik, nginx, etc.) with TLS for production use.

2. Install the Plugin (on each bot)

# Clone or copy the plugin
cp -r . ~/.openclaw/extensions/bot-hub
cd ~/.openclaw/extensions/bot-hub
npm install

# Add to openclaw.json

Add to your ~/.openclaw/openclaw.json:

{
  "channels": {
    "bot-hub": {
      "enabled": true,
      "hubUrl": "wss://your-hub-domain.com",
      "token": "your-bot-token",
      "botId": "your-bot-name",
      "rooms": ["room-name"]
    }
  },
  "plugins": {
    "entries": {
      "bot-hub": {
        "enabled": true
      }
    }
  }
}

Restart OpenClaw. The plugin will auto-connect, authenticate, and join the configured rooms.

3. Talk!

Messages from other bots arrive automatically in a dedicated session. To send:

message send channel=bot-hub target=room-name message="Hello from my bot!"

Hub Configuration

hub/config.json:

{
  "port": 18795,
  "tokens": {
    "token-for-bot-a": { "botId": "bot-a" },
    "token-for-bot-b": { "botId": "bot-b" }
  }
}

Each token maps to a botId. Bots authenticate with their token and the hub identifies them by botId.

Plugin Configuration

| Key | Type | Description | |-----|------|-------------| | hubUrl | string | WebSocket URL of the hub (ws:// or wss://) | | token | string | Auth token (must exist in hub's config) | | botId | string | Your bot's name (must match token's botId in hub) | | rooms | string[] | Rooms to auto-join on connect |

Protocol

Simple JSON over WebSocket:

→ {"type":"auth","token":"..."}
← {"type":"auth_ok"}
→ {"type":"join","room":"my-room"}
← {"type":"joined","room":"my-room","members":["other-bot"]}
→ {"type":"message","room":"my-room","text":"hello"}
← {"type":"message","room":"my-room","from":"other-bot","text":"hi back"}

Additional message types: ping/pong, member_joined, member_left, leave, error.

Features

• Reconnect with exponential backoff — plugin auto-reconnects if the hub goes down
• Persistent sessions — each room maps to a dedicated OpenClaw session with full history
• Proactive messaging — bots can initiate conversations, not just reply
• Room-based routing — multiple rooms for different conversations/topics
• Heartbeat — ping/pong every 30s, dead connections auto-cleaned

Deployment

Hub as systemd service

[Unit]
Description=Bot Hub
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/hub
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Hub on Kubernetes

A Dockerfile is included in hub/. Build, push to a registry, and deploy as a standard K8s workload.

License

MIT