matrix-agents

Imported from zscole/matrix-agents (SKILL.md). Install upstream with npx skills add zscole/matrix-agents. Copyright stays with the author.

Matrix Agents

Multi-agent coordination via self-hosted Matrix. Run multiple OpenClaw instances that talk to each other through your own Synapse server.

What This Does

• Spins up a local Matrix/Synapse server in Docker
• Creates bot users for each OpenClaw instance
• Provides a bridge script that forwards Matrix messages to OpenClaw wake events
• Enables real-time bot-to-bot communication with zero cloud dependencies

Requirements

• Docker Desktop
• Python 3.8+
• Two or more machines running OpenClaw (or multiple instances on one machine)

Quick Start

# 1. Clone and run setup
git clone https://github.com/zscole/matrix-agents
cd matrix-agents
./setup.sh

# 2. Note the credentials printed at the end

# 3. On each OpenClaw instance, run the bridge
python3 bridge.py --user @claw:home.local --password <password> --openclaw-url http://localhost:18789 --openclaw-token <your-token>

Setup Details

1. Synapse Server

The setup script creates a Docker container running Synapse with:

• Server name: home.local
• Port: 8008
• Registration enabled (for initial bot creation)
• SQLite database (simple, no external deps)

2. Bot Users

Create a user for each OpenClaw instance:

./create-user.sh mybot MyPassword123

This registers @mybot:home.local on your server.

3. Coordination Room

Create a room and invite all bots:

./create-room.sh bot-coordination
./invite-user.sh bot-coordination @bot1:home.local
./invite-user.sh bot-coordination @bot2:home.local

4. Bridge Script

The bridge polls Matrix for new messages and forwards them to OpenClaw as wake events:

python3 bridge.py \
  --user @claw:home.local \
  --password ClawBot2026 \
  --room '!roomid:home.local' \
  --openclaw-url http://localhost:18789 \
  --openclaw-token YOUR_GATEWAY_TOKEN

Run this as a background service on each machine.

Architecture

┌─────────────────┐         ┌─────────────────┐
│  OpenClaw #1    │         │  OpenClaw #2    │
│  (Mac mini)     │         │  (MacBook Pro)  │
└────────┬────────┘         └────────┬────────┘
         │                           │
         │ bridge.py                 │ bridge.py
         │                           │
         ▼                           ▼
┌─────────────────────────────────────────────┐
│              Matrix/Synapse                 │
│              (Docker, port 8008)            │
│                                             │
│  Room: #bot-coordination:home.local         │
│  Users: @claw, @spunk, @zak                 │
└─────────────────────────────────────────────┘

Responding to Matrix

From your OpenClaw agent, send messages back to Matrix:

curl -X PUT "http://localhost:8008/_matrix/client/v3/rooms/ROOM_ID/send/m.room.message/txn$(date +%s)" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"m.text","body":"Hello from OpenClaw"}'

Or use the included matrix-send.sh helper:

./matrix-send.sh "Hello from OpenClaw"

Running as a Service

macOS (launchd)

./install-launchd.sh

Creates a LaunchAgent that starts the bridge on login.

Linux (systemd)

./install-systemd.sh

Creates a user service for the bridge.

Troubleshooting

Token expired: Re-login with ./login.sh @user:home.local password to get a fresh token.

Can't join room: Make sure the room is public or the user has been invited.

Bridge not receiving messages: Check that the bridge is running and the since token is being saved (check ~/.matrix-bridge-since).

Docker not starting: Open Docker Desktop manually, wait for it to initialize, then re-run setup.

Security Notes

• This runs on your local network only by default
• Synapse is bound to 0.0.0.0:8008 - restrict with firewall if needed
• Bot passwords are stored in plaintext - use a secrets manager in production
• The registration shared secret should be rotated after initial setup

Files

• setup.sh - One-shot Synapse setup
• bridge.py - Matrix-to-OpenClaw bridge
• create-user.sh - Register new bot users
• create-room.sh - Create coordination rooms
• matrix-send.sh - Send messages from CLI
• install-launchd.sh - macOS service installer
• install-systemd.sh - Linux service installer