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 sichert

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.

Update September 2026: „Unable to decrypt“ — Wurzel gefunden und entschärft

Das Setup lief monatelang stabil, dann kam das Muster: Nachrichten kommen an, plötzlich sind sie unlesbar („Unable to decrypt“), ein Neustart hilft kurz, das Problem kehrt wieder. Die Recherche hat die Wurzel gefunden — und sie liegt in OpenClaw selbst, dokumentiert als zwei offene P1-Bugs:

1. Der Crypto-Store wird nur alle 60 Sekunden persistiert (Issue #76611)

Die Matrix-Erweiterung schreibt ihren Verschlüsselungs-Zustand (Olm/Megolm-Keys) nur alle 60 Sekunden auf die Platte — im eigenen Build nachgemessen: MATRIX_IDB_PERSIST_INTERVAL_MS = 6e4. Stirbt der Prozess in diesem Fenster (Crash, OOM, Restart), sind frisch ausgehandelte Keys weg. Der Live-Beweis im eigenen Log: [IdbPersistence] Failed to persist IndexedDB snapshot: Matrix runtime not initialized — exakt beim Shutdown. Danach verschlüsselt der Sender weiter mit Keys, die der Bot nicht mehr hat.

2. Eine verwaiste Lock-Datei kann E2EE dauerhaft lahmlegen (Issue #129735)

Überschreitet der Stop-Vorgang sein 5-Sekunden-Abbruchfenster, bleibt crypto-idb-snapshot.json.lock als Leiche zurück. Jeder folgende Start läuft dann in file lock timeout — und der Zustand ist latchend: Er überlebt beliebig viele Neustarts, während der Account „connected, healthy“ meldet. Genau deshalb wirkte der Bot „da, aber taub“.

Bewährtes Heilverfahren

Der schnellste Reparaturweg (~17 Sekunden): Server-seitiges Key-Backup zurückspielen.

node /pfad/zu/openclaw/dist/index.js matrix verify backup restore

Das importiert alle Keys aus dem Server-Backup (Version 16, 1600+ Keys) und die Entschlüsselung kommt sofort zurück — erfolgreich drei Mal am selben Vormittag getestet.

Dauerhafte Abwehrschichten

Lock-Sweep beim Start: Ein ExecStartPre im systemd-Unit löscht verwaiste Locks älter als 5 Minuten, bevor der Gateway hochfährt — der latchende Dauer-Defekt aus #129735 kann nicht mehr greifen.
Nächtliche Wartung um 04:00: Cron-Job: Backup der Keys → sauberer kontrollierter Gateway-Restart → Key-Restore → Health-Check. Nebeneffekt: Der Node-Prozess wächst über Stunden (typisches Leak-Muster) — nachts startet er frisch, tagsüber bleibt der RAM flach.
Wachhund nur beobachten: RAM-Watchdogs, die bei Überschreitung automatisch neu starten, sind als Neustarter entwaffnet. Jeder unkontrollierte Neustart reißt die E2EE-Aushandlung ab — die Watchdogs melden jetzt nur noch ins Log.
Decrypt-Guard mit kurzer Nachlegezeit: Ein Wächter prüft alle 2 Minuten die Entschlüsselung und restauriert bei anhaltender Störung nach spätestens 3 Minuten nach — statt vorher 10.

Wichtig für die Einordnung: RAM war in diesem Setup nie der Killer — 38 GB gesamt, 28 GB frei. Die Decrypt-Fehler kamen von den Neustarts selbst, nicht von Speichermangel. Bis OpenClaw die beiden Bugs upstream fixt, trägen diese Schichten: Ein Decrypt-Fenster ist so von Stunden auf unter 4 Minuten begrenzt.

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.