Matrix & OpenClaw — Setup, Fallstricke und Praxis – netfreak.de

Warum Matrix statt Telegram?

Telegram ist praktisch — kein Zweifel. Aber wenn man einen KI-Agenten betreibt, der 24/7 erreichbar sein soll, stellen sich Fragen: Wer hat meine Daten? Wer kann den Bot kicken? Was passiert wenn Telegram den API-Zugang ändert?

Matrix bietet hier eine überzeugende Alternative:

E2EE — Ende-zu-Ende-Verschlüsselung in jedem Raum
Dezentral — Eigener Synapse-Server, keine Abhängigkeit von einem Anbieter
Selbstgehostet — Volle Kontrolle über Daten, Logs und Nutzer
Offen — Open-Source-Protokoll, aktive Community

Nach vier Monaten Telegram mit OpenClaw war der Umstieg auf Matrix der logische nächste Schritt. Hier ist, was ich dabei gelernt habe.

Setup: Synapse auf Debian

Die Installation von Synapse auf Debian ist dank des offiziellen Matrix-Pakets relativ schmerzlos:

sudo apt install -y matrix-synapse-py3
sudo systemctl enable --now matrix-synapse

Wichtige Konfiguration in homeserver.yaml:

server_name auf die eigene Domain setzen
Registration deaktivieren und über Shared Secret steuern
max_upload_size erhöhen (Standard ist nur 10 MB)
Database — PostgreSQL statt SQLite für Produktivbetrieb

Caddy als Reverse Proxy

Caddy übernimmt TLS automatisch via Let’s Encrypt:

meinedomain.example {
    reverse_proxy localhost:8008
}

Für die Federation müssen die .well-known/matrix/server und .well-known/matrix/client Dateien korrekt ausgeliefert werden. Hier lohnt es sich, die offizielle Delegations-Doku genau zu lesen.

OpenClaw Matrix-Integration

OpenClaw bringt ein eingebautes Matrix-Plugin mit. Die Grundkonfiguration in openclaw.json:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://meinedomain.example",
      "userId": "@bot:meinedomain.example",
      "accessToken": "***"
    }
  }
}

Long-Polling statt Cron

Anfänglich lief mein Matrix-Chat über einen Cron-Job, der alle 3 Minuten den Raum per curl und Client-API abfragte. Das funktioniert, ist aber träge — 3 Minuten Latenz bei jeder Nachricht.

Besser ist OpenClaw’s integriertes Long-Polling: Der Agent hält eine persistente Verbindung zum Synapse-Server und reagiert in Echtzeit. Der Wechsel von Cron zu Long-Polling hat die Reaktionszeit von Minuten auf Sekunden gesenkt.

Voice: Opus und TTS

Matrix-Nachrichten mit Voice zu beantworten war ein eigenes Projekt:

Text generieren
Piper (lokales TTS) erzeugt Opus-Audio
Opus-Datei per Matrix-API als asVoice senden
Parallel: speak-local.sh für lokale Audio-Ausgabe über ALSA

Tipp: Piper (16kHz) braucht ein ffmpeg-Resampling auf 44100Hz, sonst wird alles zu schnell abgespielt. Eine kurze Zeile im Skript löst das.

Lektionen aus der Praxis

1. E2EE: Drei Schritte zur verschlüsselten Kommunikation

Ende-zu-Ende-Verschlüsselung mit einem KI-Bot zum Laufen zu bringen braucht drei Dinge, die zusammen stimmen müssen. Wenn alle drei stimmen, funktioniert es zuverlässig.

Schritt 1: encryption: true setzen in openclaw.json:

"matrix": {
  "encryption": true
}

Damit aktiviert OpenClaw die Crypto-Bibliothek und erstellt eigene Device-Keys.

Schritt 2: Device verifizieren. Nach dem Neustart erstellt OpenClaw ein neues Device. Der menschliche Nutzer muss dieses Device in seinem Matrix-Client (Element, FluffyChat, etc.) verifizieren. Erst dann teilt der Client die Megolm-Session-Keys mit dem Bot. Das ist der entscheidende Schritt — ohne Verifikation bleiben verschlüsselte Nachrichten unlesbar.

Schritt 3: Crypto-Store sichern. Der Crypto-Store liegt unter ~/.openclaw/matrix/accounts/default/. Wenn der weg ist, muss das Device neu verifiziert werden. Ein regelmäßiges Backup erspart das:

cp -r ~/.openclaw/matrix/accounts/default/ \
  ~/backups/matrix-crypto-$(date +%Y%m%d)/

Hinweis zu alten Nachrichten: Nachrichten die vor dem Device-Login verschlüsselt wurden, können nicht gelesen werden — es sei denn, ein Key-Backup existiert auf dem Server. Ab der Verifikation funktionieren alle neuen Nachrichten aber zuverlässig.

Tipp: Cross-Signing und Key-Backup auf dem Server einrichten, dann klappt auch die Wiederherstellung alter Nachrichten nach einem Device-Reset.

2. Systemd: Ein Service reicht

OpenClaw wird über einen user-level Service verwaltet (~/.config/systemd/user/openclaw-gateway.service), der automatisch von openclaw gateway install erstellt wird. Falls zusätzlich ein system-level Service existiert, einfach deaktivieren:

sudo systemctl disable openclaw.service

Lingering muss aktiv sein damit user-level Services ohne aktives Login laufen:

loginctl enable-linger <username>

3. File-Upload Limits

Synapse’s Standard-Limit von 10MB ist für Voice-Dateien oft knapp. In der homeserver.yaml erhöhen:

max_upload_size: 50M

4. Doppel-Antworten vermeiden

Wenn sowohl das Matrix-Plugin als auch ein Cron-Poll aktiv sind, antwortet der Agent doppelt. Entweder das Plugin ODER den Cron nutzen — nie beide gleichzeitig.

5. Synapse-RAM überwachen

Synapse kann über Wochen hinweg RAM verbrauchen, besonders bei vielen synchronisierten Räumen. Ein Watchdog-Skript, das den RAM-Verbrauch überwacht und Synapse bei Bedarf neustartet, sorgt für Stabilität.

6. Federation: DNS und TLS

Federation mit anderen Homeservern funktioniert wenn DNS, SRV-Records und TLS-Zertifikate korrekt konfiguriert sind. Bei DynDNS-Domains empfiehlt es sich, Caddy als einzigen TLS-Terminator zu nutzen und Synapse intern ohne TLS zu betreiben.

7. Bot-Permissions prüfen

Matrix-Bots brauchen explizite Rechte in jedem Raum: Nachrichten lesen, senden, Reaktionen setzen. Falls der Bot nichts mehr sieht, lohnt sich ein Blick auf die Power Levels im Raum.

8. Audio: plughw statt hw

Für Audio-Ausgabe über ALSA immer plughw:0,0 statt hw:0,0 nutzen. plughw übernimmt automatisch Format-Konvertierung (z.B. Mono zu Stereo), hw schlägt bei Format-Mismatches fehl:

# Konvertiert automatisch:
aplay -D plughw:0,0 audiofile.wav

Config-Backup: Was man sichern sollte

Für den Fall der Fälle — diese Dateien sichern und man ist in 15 Minuten wieder online:

openclaw.json — Haupt-Config (Agent, Channels, E2EE)
Crypto-Store — ~/.openclaw/matrix/accounts/default/ (Megolm-Sessions, Device-Keys)
Recovery Key — recovery-key.json im Crypto-Store-Verzeichnis
homeserver.yaml — Synapse-Config
Signing Key — Der Federation-Signing-Key (ohne diesen bricht Federation)
Caddyfile — Reverse-Proxy-Config inkl. SSL
docker-compose.yml — Matrix Docker-Stack
UFW-Regeln — Firewall-Konfiguration
Crontab — Wecker, DynDNS-Updates, Watchdogs
DynDNS-Skript — Update-Skript für wechselnde IP
Systemd User Service — openclaw-gateway.service

Backup-Skript zum Mitnehmen:

BACKUP=~/backups/matrix-e2ee-$(date +%Y%m%d)
mkdir -p "$BACKUP"
cp ~/.openclaw/openclaw.json "$BACKUP/"
cp -r ~/.openclaw/matrix/accounts/default/ "$BACKUP/accounts-default/"
cp ~/.openclaw/matrix/synapse/homeserver.yaml "$BACKUP/"
cp ~/.openclaw/matrix/synapse/*.signing.key "$BACKUP/"
cp ~/.openclaw/matrix/Caddyfile "$BACKUP/"
cp ~/matrix/docker-compose.yml "$BACKUP/"
sudo ufw status verbose > "$BACKUP/ufw-rules.txt"
crontab -l > "$BACKUP/crontab.txt"

Nach einem Reset: Config zurückkopieren, docker compose up -d, systemctl --user restart openclaw-gateway, und das Bot-Device in Element neu verifizieren.

Netzwerk-Ports

Port	Service	Protokoll
80	Caddy HTTP (Redirect)	TCP
443	Caddy HTTPS (Matrix Client + Element Web)	TCP
8448	Matrix Federation	TCP

Intern: Synapse auf 8008, Caddy routet alles darüber. Der OpenClaw Gateway Port (z.B. 18789) muss nur nach außen wenn man ihn extern erreichbar machen will.

Tipps aus der Praxis

Watchdog-Skripte

Ein einfaches Bash-Skript, das alle 5 Minuten prüft:

Läuft Synapse? → systemctl is-active matrix-synapse
RAM-Verbrauch okay? → free -m
Läuft OpenClaw Gateway? → systemctl --user is-active openclaw-gateway

Bei Problemen → automatischer Restart + Benachrichtigung.

Tor-Integration

Für sicheren Zugang aus der Ferne bietet sich Tor SOCKS5 an (127.0.0.1:9050). So bleibt die Server-IP verborgen:

curl --socks5-hostname 127.0.0.1:9050 https://example.com

Wie der Gateway funktioniert — unter der Haube

Wenn man einen KI-Bot in Matrix betreibt, läuft alles über den OpenClaw Gateway. Das ist der zentrale Prozess, der alle Verbindungen hält und orchestriert.

Was der Gateway macht:

HTTP-Server auf dem konfigurierten Port — die API-Schnittstelle für alle Kanäle
Matrix-Client — verbindet sich via Long-Polling mit Synapse, hört auf neue Nachrichten in allen Räumen, verschlüsselt und entschlüsselt E2EE
Telegram-Client — Polling gegen die Telegram Bot API, empfängt und sendet Nachrichten
Agent-Orchestrierung — wenn eine Nachricht reinkommt, startet er einen Agent-Run (LLM + Tools), wartet auf die Antwort und schickt sie zurück
Plugin-System — lädt Erweiterungen (Memory, Search, etc.)
Health-Monitor — regelmäßiger Check aller Komponenten

Der Nachrichten-Flow Schritt für Schritt:

Nutzer schreibt in Matrix/Telegram
  → Gateway empfängt Nachricht
    → [Matrix] E2EE entschlüsseln
      → Gateway startet Agent-Run (LLM-Modell + Tool-Aufrufe)
        → Agent generiert Antwort
          → [Matrix] Antwort E2EE verschlüsseln
            → Gateway sendet Antwort an Kanal
              → Nutzer liest Antwort

Wie der Prozess gestartet wird:
Der Gateway läuft als systemd user-level Service mit Restart=always. Das heißt: Wenn der Prozess crasht, startet systemd ihn automatisch neu. So bleibt der Bot 24/7 verfügbar — auch nach Fehlern oder Server-Neustarts (vorausgesetzt Lingering ist aktiviert).

Was ohne Gateway nicht funktioniert:
Alles. Ohne Gateway gibt es keine Brücke zwischen Matrix/Telegram und dem KI-Agenten. Er hält die Verbindungen offen, verwaltet Sessions und Crypto-Keys, und orchestriert die LLM-Aufrufe. Kurz: Der Gateway IST der Bot.

Fazit

Matrix + OpenClaw ist eine mächtige Kombination. Die Einrichtung braucht etwas Geduld — besonders E2EE will Schritt für Schritt eingerichtet werden. Aber einmal konfiguriert, läuft es stabil und zuverlässig.

Der größte Gewinn: Volle Kontrolle. Kein Provider kann den Bot kicken, kein API-Change macht ihn handlungsunfähig. Mein Agent, mein Server, meine Regeln.

Wer bereit ist, die Schritte nachzugehen, wird mit einer privaten, verschlüsselten KI-Kommunikation belohnt. Für alle anderen bleibt Telegram, Signal, WhatsApp oder Discord — und das ist auch okay.