@openclaw/bitchat

OpenClaw channel plugin for Bitchat BLE mesh network.

⚠️ Alpha Software — This plugin and bitchat-node are experimental. APIs may change without notice.

Overview

This plugin enables OpenClaw to communicate via the Bitchat peer-to-peer BLE mesh network. Messages travel directly between devices over Bluetooth Low Energy without any central server.

Requirements:

• bitchat-node running as a background service
• BLE-capable hardware (Mac, Linux with BlueZ, or Windows with BLE support)
• Other Bitchat peers nearby (iOS app, other nodes)

Installation

openclaw plugins install @openclaw/bitchat

Or for development:

openclaw plugins install -l /path/to/openclaw-bitchat

Configuration

Add to your OpenClaw config (~/.openclaw/openclaw.json):

{
  channels: {
    bitchat: {
      enabled: true,
      nickname: "my-agent",
      bridgeUrl: "http://localhost:3939",
      dmPolicy: "open", // or "allowlist", "disabled"
      allowFrom: [], // peer IDs when using allowlist
    },
  },
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable the channel | | nickname | string | "openclaw" | Display name on the mesh network | | bridgeUrl | string | "http://localhost:3939" | URL of the bitchat-node HTTP bridge | | webhookPath | string | "/bitchat-webhook" | Webhook endpoint for incoming messages | | autoStart | boolean | false | Auto-start bitchat-node daemon | | dmPolicy | string | "open" | DM access policy (open, allowlist, disabled) | | allowFrom | string[] | [] | Allowed peer IDs when using allowlist policy |

Usage

1. Start bitchat-node

First, ensure bitchat-node is running:

cd /path/to/bitchat-node
node dist/bin/bitchat.js --nickname=MyAgent --port=3939

Or run it as a background service.

2. Configure OpenClaw

Add the bitchat channel configuration to your OpenClaw config.

3. Restart OpenClaw Gateway

openclaw gateway restart

4. Test

Send a message from a Bitchat peer (iOS app or another node). OpenClaw will receive it and route it to a session.

To send messages via OpenClaw:

# Via message tool in session
message tool with channel=bitchat, target=<peerID>, message="Hello!"

Architecture

┌─────────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Bitchat Peers     │     │    bitchat-node      │     │    OpenClaw     │
│   (iOS, Android,    │◄───►│    (BLE + HTTP)      │◄───►│    Gateway      │
│    other nodes)     │ BLE │    localhost:3939    │HTTP │    + Plugin     │
└─────────────────────┘     └──────────────────────┘     └─────────────────┘

1. bitchat-node maintains BLE connections to nearby peers
2. HTTP Bridge exposes REST API for sending/receiving messages
3. OpenClaw Plugin polls the bridge or receives webhooks for incoming messages
4. Outbound messages go through the bridge API to the BLE mesh

API Endpoints (bitchat-node)

The plugin communicates with bitchat-node via these endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/status | GET | Get node status (peerID, nickname, peer count) | | /api/peers | GET | List connected peers | | /api/messages | GET | Get recent messages (polling, ?since=timestamp) | | /api/send | POST | Send a message ({ type, text, recipientPeerID? }) | | /api/webhook | POST | Register a webhook URL |

Limitations

• BLE Range: Messages only propagate within BLE range (~10-100m)
• No Media: BLE bandwidth is limited; text-only messaging
• No Persistence: Messages are ephemeral; no server-side storage
• Peer Discovery: Requires active BLE scanning/advertising

Security Considerations

• Local Only: All communication is local mesh; nothing leaves your network
• No Encryption for Public: Public messages are unencrypted
• DM Encryption: Direct messages use Noise protocol encryption
• DM Policy: Configure dmPolicy and allowFrom to restrict who can message

Development

# Clone and install
git clone https://github.com/wkyleg/openclaw-bitchat.git
cd openclaw-bitchat
npm install

# Build
npm run build

# Link for development
openclaw plugins install -l .

Related

• bitchat-node — Node.js Bitchat implementation
• Bitchat iOS — Original iOS implementation
• OpenClaw Plugins — Plugin development guide

License

Unlicense — Public Domain