2026 OpenClaw mit Matrix auf Linux-Cloud-VPS: Plugin, Homeserver, Token und Mehrraum-Routing

Matrix ist für OpenClaw attraktiv, weil Räume, Bridges und Bots auf dauerhafte Erreichbarkeit ausgelegt sind. Ein kleiner Linux-Cloud-VPS kann Gateway, Reverse Proxy und Matrix-Connector tragen, während der Homeserver bei Synapse, Dendrite, Conduit oder einem Managed-Anbieter liegt. Kritisch ist die reproduzierbare Kette: Plugin aktiv, Homeserver-URL korrekt, Zugriffstoken passend, Raumzuordnung eindeutig und Sync-Loop beobachtbar.

1. Matrix-Baseline vor OpenClaw festziehen

Bevor OpenClaw ins Spiel kommt, muss der Matrix-Teil allein funktionieren. Legen Sie einen eigenen Bot-Benutzer an, laden Sie ihn in die Zielräume ein und testen Sie mit einem einfachen Client, ob er Nachrichten lesen und schreiben darf. Speichern Sie die echte Raum-ID im Format !abc:example.org, nicht nur den Alias #ops:example.org; Aliase sind für Menschen praktisch, aber in Routing-Regeln weniger robust.

2. OpenClaw-Plugin aktivieren und geheim halten

Halten Sie die OpenClaw-Konfiguration bewusst zweigeteilt: versionierte Routing-Logik in der Hauptdatei, Secrets in einer lokalen Env-Datei oder im Secret Store Ihres Deployments. So kann das Team prüfen, welche Räume wofür zuständig sind, ohne Tokens in Git zu riskieren. Bei Docker gehört die Secret-Datei als read-only Mount in den Container; bei systemd nutzen Sie EnvironmentFile=.

# .env.matrix, nicht committen
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_USER_ID=@openclaw-bot:example.org

# openclaw.yaml
channels:
  matrix:
    enabled: true
    homeserver: ${MATRIX_HOMESERVER}
    accessToken: ${MATRIX_ACCESS_TOKEN}
    userId: ${MATRIX_USER_ID}
    defaultRoom: "!ops:example.org"

Nach dem Neustart prüfen Sie zuerst den Login und erst danach die Routing-Logik. Ein kurzer Test ist besser als ein Screenshot aus dem Dashboard: eine Nachricht aus dem Matrix-Raum an OpenClaw senden, Antwort im selben Raum abwarten, dann einen zweiten Raum hinzufügen. Für Webhook- und Callback-Grundlagen im OpenClaw-Umfeld ist außerdem der Leitfaden zu OpenClaw auf Slack für Linux-Cloud-VPS hilfreich, weil dieselbe Denkweise bei Signatur, URL-Pfad und Gateway-Logs gilt.

3. Mehrraum-Routing reproduzierbar machen

Mehrraum-Routing ist die Stelle, an der kleine Unschärfen später teuer werden. Definieren Sie deshalb eine klare Matrix: Welche Projektgruppe darf den Agenten ansprechen, welche Raum-ID ist der Default, welche Räume bekommen nur Statusmeldungen, und in welchen Räumen darf OpenClaw Aktionen auslösen. Bewährt hat sich ein Präfix-Modell: ops für Betrieb, support für Nutzerfragen, release für Build- und Rollout-Status.

routes:
  - match: "ops:*"
    room: "!ops:example.org"
    mode: "read_write"
  - match: "support:*"
    room: "!support:example.org"
    mode: "read_write"
  - match: "release:*"
    room: "!release:example.org"
    mode: "status_only"

Testen Sie jede Regel mit einer festen Nachricht. Im Runbook sollte stehen: Eingabetext, erwarteter Zielraum, erwartete Antwort und Logzeile. Wenn ein Raum archiviert, umbenannt oder neu angelegt wird, ändern Sie nur die Raum-ID und wiederholen den Test. Für Teams mit mehreren Messenger-Brücken passt die Kanaltrennung aus OpenClaw Telegram und Discord im Dual-Channel-Betrieb als Vergleichslogik.

4. Sync-Fehler schichtweise eingrenzen

Wenn Matrix „nicht synchronisiert“, ist selten sofort klar, ob Netzwerk, Auth, Mitgliedschaft oder OpenClaw betroffen ist. Arbeiten Sie von unten nach oben: Kann der VPS den Homeserver per HTTPS erreichen? Ist die Systemzeit korrekt? Akzeptiert /sync?timeout=0 den Token? Sieht der Bot den Raum in joined_rooms? Erst wenn diese vier Antworten stimmen, lohnt sich der Blick in OpenClaw-Routing und Agent-Logs.

• DNS / TLS: curl -v $MATRIX_HOMESERVER/_matrix/client/versions schlägt fehl.
• Token: HTTP 401 oder 403 bei /sync, Token rotieren und Bot neu starten.
• Raum-Mitgliedschaft: Bot ist eingeladen, aber noch nicht beigetreten oder darf nicht senden.
• Sync-Offset: alter since-Wert, lokale State-Datei sichern und kontrolliert neu synchronisieren.
• OpenClaw-Routing: Matrix empfängt Events, aber kein Prefix passt zur Route.

Ein häufiger Sonderfall sind föderierte Räume: Der Bot ist Mitglied, aber Events kommen verzögert oder nur in eine Richtung. Testen Sie dann zuerst einen Raum auf demselben Homeserver. Wenn lokal alles funktioniert und nur Federation hängt, gehört das Ticket zum Homeserver oder Remote-Server, nicht zu OpenClaw. Protokollieren Sie bei jedem Fehler HTTP-Status, Matrix-Error-Code und die OpenClaw-Correlation-ID, damit die nächste Person nicht wieder bei DNS beginnt.

Für Day-two-Betrieb lohnt sich ein kleiner Health-Check: alle fünf Minuten eine leichte Anfrage an den Homeserver, aber keine Testnachricht in Produktivräume. Alarme sollten „Homeserver nicht erreichbar“, „Token abgelehnt“ und „OpenClaw-Prozess neu gestartet“ getrennt melden, weil Besitzer und Rollback-Wege verschieden sind.

5. Checkliste für den produktionsnahen VPS

Am Ende sollte die Einrichtung als kurze, wiederholbare Liste vorliegen: VPS-Paket, Firewall-Regeln, OpenClaw-Version, Matrix-Homeserver, Bot-User, Secret-Ablage, Raumtabelle, Restart-Befehl und Logpfad. Wer Docker nutzt, pinnt Image-Tags und mountet State-Verzeichnisse bewusst; wer systemd nutzt, dokumentiert Unit-Namen und Environment-Datei. Backups brauchen vor allem Konfiguration und Sync-State, nicht zwingend die gesamte Disk.

Planen Sie Token-Rotation wie einen normalen Wartungsvorgang: neuen Token erzeugen, Secret aktualisieren, OpenClaw neu starten, /sync testen, alten Token widerrufen. So bleibt Matrix ein berechenbarer Eingangskanal statt einer zweiten, schlecht dokumentierten Produktionsplattform.