mirror of https://github.com/Heretek-AI/heretek-openclaw-core.git synced 2026-07-21 00:05:21 -04:00

Files

T

John Doe 8deeddb3a3 feat(monitoring): Add Matrix keepalive daemon, metrics server, and routing guide

- scripts/matrix-keepalive.sh: periodic keepalive for Matrix connections
- scripts/metrics-server.py: lightweight HTTP metrics endpoint
- docs/operations/MATRIX-ROUTING-GUIDE.md: routing documentation
- scripts/export-agent-metrics.sh: streamlined (legacy cleanup)

2026-04-01 10:33:27 -04:00

3.0 KiB

Raw Permalink Blame History

Matrix Channel Routing Guide — The Collective

Date: 2026-04-01
Server: http://localhost:8008
Status: Active

Architecture

Following OpenClaw channel architecture:

Channels: Matrix rooms as communication surfaces
Routing: Agent-specific room assignments
Location: Homeserver-based with local rooms
Groups: Coordinated by purpose (Triad, Operations, Monitoring, General)

Channel Configuration

Primary Channel: matrix-primary

Room	ID	Purpose	Members
Triad Private	!HmOlxqnRPkezdwanNl:localhost	Deliberation	Alpha, Beta, Charlie
Operations	!VxwUQnCOIPmISUFnEr:localhost	Coordination	Working agents
Monitoring	!mOEbnkWEmfmYqrllgB:localhost	Broadcast	All (read-mostly)
General	!jYzxmaetoEsMjxdpYb:localhost	Open comms	All agents

Agent Routing

Default Routing

All agents route to matrix-primary channel by default.

Agent-Specific Rooms

Agent	Primary Rooms	Secondary Rooms
steward	general, monitoring	operations, triad (observer)
alpha	triad-private	general
beta	triad-private	general
charlie	triad-private	general
coder	operations	general
examiner	operations	general
explorer	operations	general
sentinel	operations, monitoring	general
oracle	operations	general
(others)	general	monitoring

Keepalive System

Script: /root/.openclaw/workspace-steward/heretek-openclaw-core/scripts/matrix-keepalive.sh
Schedule: Every 2 minutes via cron
Functions:

Updates presence status for all 23 agents
Auto-refreshes expired tokens
Logs activity to /var/log/openclaw-matrix-keepalive.log

Message Flow

Agent → Matrix Room → All Room Members
   ↓
Gateway (ws://127.0.0.1:18789)
   ↓
A2A Protocol v1.0
   ↓
Other Agents

Message Types Supported:

m.room.message - Text messages
m.reaction - Reactions/emoji responses
m.room.topic - Room topic changes
Custom events for structured data

Troubleshooting

Agent Not Appearing in Room

Check token validity: grep "^agent:" /tmp/matrix-agents.txt
Verify room membership: Matrix client → Room settings → Members
Re-invite if needed using steward token

Token Expired

The keepalive script auto-refreshes tokens. Check logs:

tail -20 /var/log/openclaw-matrix-keepalive.log

Messages Not Delivering

Verify gateway is running: openclaw gateway status
Check room ID is correct in agent config
Test manual message send via curl

Configuration Files

Channel Config: /root/.openclaw/openclaw-channels.json
Agent Credentials: /tmp/matrix-agents.txt
Room IDs: Documented in each agent's TOOLS.md
Keepalive Logs: /var/log/openclaw-matrix-keepalive.log

🦞

Coordinated communication enables collective intelligence.

3.0 KiB Raw Permalink Blame History