OpenClaw mit Matrix verbinden: Schritt-für-Schritt-Anleitung

Es ist oft frustrierend, wenn man einen Bot für Matrix bauen will und an der Verschlüsselung oder den komplexen Raum-IDs scheitert. Man wünscht sich einfach eine Lösung, die stabil läuft und alle modernen Features wie Threads und E2EE direkt unterstützt, ohne dass man das Protokoll neu erfinden muss.

Matrix ist das Plugin für den Matrix-Channel in OpenClaw. Es nutzt das offizielle matrix-js-sdk und unterstützt DMs, Rooms, Threads, Media, Reactions, Polls, Location und E2EE.

Plugin erforderlich

Matrix ist ein Plugin und wird nicht mit dem OpenClaw-Core ausgeliefert.

Installation via npm:

openclaw plugins install @openclaw/matrix

Installation aus einem lokalen Verzeichnis:

openclaw plugins install ./path/to/local/matrix-plugin

Siehe Plugins für das Plugin-Verhalten und die Installationsregeln.

Einrichtung

Installiere das Plugin.
Erstelle einen Matrix-Account auf deinem homeserver.
Konfiguriere channels.matrix entweder mit:
- homeserver + accessToken oder
- homeserver + userId + password.
Starte das Gateway neu.
Starte eine DM mit dem Bot oder lade ihn in einen Room ein.

Interaktive Setup-Pfade:

openclaw channels add
openclaw configure --section channels

Was der Matrix-Wizard eigentlich abfragt:

homeserver URL
Auth-Methode: Access Token oder Passwort
User-ID (nur wenn du Passwort-Auth wählst)
Optionaler Gerätename
Ob E2EE aktiviert werden soll
Ob der Matrix-Raumzugriff jetzt konfiguriert werden soll

Wichtiges Verhalten des Wizards:

Wenn Matrix-Auth-Umgebungsvariablen für den ausgewählten Account bereits existieren und dieser Account noch keine in der Config gespeicherte Auth hat, bietet der Wizard einen Env-Shortcut an und schreibt nur enabled: true für diesen Account.
Wenn du einen weiteren Matrix-Account interaktiv hinzufügst, wird der eingegebene Account-Name in die Account-ID normalisiert, die in der Config und den Umgebungsvariablen verwendet wird. Zum Beispiel wird aus Ops Bot dann ops-bot.
Prompts für die DM-Allowlist akzeptieren sofort vollständige @user:server Werte. Display-Namen funktionieren nur, wenn die Live-Verzeichnissuche genau einen Treffer findet; andernfalls bittet dich der Wizard, es mit einer vollständigen Matrix-ID erneut zu versuchen.
Prompts für die Room-Allowlist akzeptieren Room-IDs und Aliase direkt. Sie können auch Namen von beigetretenen Räumen live auflösen, aber nicht aufgelöste Namen werden nur so gespeichert, wie sie beim Setup eingegeben wurden, und später von der Runtime-Allowlist-Auflösung ignoriert. Nutze bevorzugt !room:server oder #alias:server.
Um Room-Namen aufzulösen, bevor du sie speicherst, verwende openclaw channels resolve --channel matrix "Project Room".
Die Identität von Räumen/Sessions zur Laufzeit nutzt die stabile Matrix-Room-ID. Im Raum deklarierte Aliase werden nur als Input für die Suche verwendet, nicht als langfristiger Session-Key oder stabile Gruppen-Identität.

Minimales Token-basiertes Setup:

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

Passwort-basiertes Setup (Token wird nach dem Login gecacht):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

Matrix speichert gecachte Credentials in ~/.openclaw/credentials/matrix/. Der Standard-Account nutzt credentials.json; benannte Accounts nutzen credentials-<account>.json.

Entsprechende Umgebungsvariablen (werden verwendet, wenn der Config-Key nicht gesetzt ist):

MATRIX_HOMESERVER
MATRIX_ACCESS_TOKEN
MATRIX_USER_ID
MATRIX_PASSWORD
MATRIX_DEVICE_ID
MATRIX_DEVICE_NAME

Für Accounts, die nicht der Standard sind, verwende Account-bezogene Umgebungsvariablen:

MATRIX_<ACCOUNT_ID>_HOMESERVER
MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
MATRIX_<ACCOUNT_ID>_USER_ID
MATRIX_<ACCOUNT_ID>_PASSWORD
MATRIX_<ACCOUNT_ID>_DEVICE_ID
MATRIX_<ACCOUNT_ID>_DEVICE_NAME

Beispiel für den Account ops:

MATRIX_OPS_HOMESERVER
MATRIX_OPS_ACCESS_TOKEN

Für die normalisierte Account-ID ops-bot verwende:

MATRIX_OPS_BOT_HOMESERVER
MATRIX_OPS_BOT_ACCESS_TOKEN

Der interaktive Wizard bietet den Env-Var-Shortcut nur an, wenn diese Auth-Umgebungsvariablen bereits vorhanden sind und der ausgewählte Account noch keine Matrix-Auth in der Config gespeichert hat.

Konfigurationsbeispiel

Dies ist eine praktische Basis-Konfiguration mit DM-Pairing, Room-Allowlist und aktiviertem E2EE:

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

Streaming-Vorschauen

Das Streaming von Matrix-Antworten ist ein Opt-in-Feature.

Setze channels.matrix.streaming auf "partial", wenn OpenClaw einen einzelnen Antwort-Entwurf senden soll. Dieser Entwurf wird an Ort und Stelle bearbeitet, während das Modell Text generiert, und finalisiert, wenn die Antwort fertig ist:

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

streaming: "off" ist der Standard. OpenClaw wartet auf die finale Antwort und sendet sie einmalig.
streaming: "partial" erstellt eine bearbeitbare Vorschau-Nachricht, anstatt mehrere Teil-Nachrichten zu senden.
Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Event passt, stoppt OpenClaw das Vorschau-Streaming und nutzt die normale finale Zustellung.
Media-Antworten senden Anhänge weiterhin normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, wird sie von OpenClaw entfernt (redacted), bevor die finale Media-Antwort gesendet wird.
Vorschau-Edits verursachen zusätzliche Matrix API-Calls. Lass Streaming deaktiviert, wenn du ein sehr konservatives Rate-Limit-Verhalten wünschst.

AI Setup Assistant

Nächste Schritte

Verschlüsselung und Verifizierung

In verschlüsselten (E2EE) Räumen nutzen ausgehende Image-Events thumbnail_file, damit Vorschaubilder zusammen mit dem vollen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin thumbnail_url. Du musst nichts konfigurieren — das Plugin erkennt den E2EE-Status automatisch.

Bot-zu-Bot-Räume

Standardmäßig werden Matrix-Nachrichten von anderen konfigurierten OpenClaw Matrix-Accounts ignoriert.

Nutze allowBots, wenn du absichtlich Matrix-Traffic zwischen Agenten zulassen möchtest:

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

allowBots: true akzeptiert Nachrichten von anderen konfigurierten Matrix-Bot-Accounts in erlaubten Räumen und DMs.
allowBots: "mentions" akzeptiert diese Nachrichten nur, wenn sie diesen Bot in Räumen sichtbar erwähnen. DMs sind weiterhin erlaubt.
groups.<room>.allowBots überschreibt die Einstellung auf Account-Ebene für einen einzelnen Raum.
OpenClaw ignoriert weiterhin Nachrichten derselben Matrix-User-ID, um Self-Reply-Loops zu vermeiden.
Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw betrachtet Nachrichten als “bot-authored”, wenn sie von einem anderen konfigurierten Matrix-Account auf diesem OpenClaw Gateway gesendet wurden.

Verwende strikte Raum-Allowlists und Mention-Anforderungen, wenn du Bot-zu-Bot-Traffic in geteilten Räumen aktivierst.

Verschlüsselung aktivieren:

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Verifizierungsstatus prüfen:

openclaw matrix verify status

Ausführlicher Status (vollständige Diagnose):

openclaw matrix verify status --verbose

Den gespeicherten Recovery-Key in maschinenlesbarer Ausgabe einschließen:

openclaw matrix verify status --include-recovery-key --json

Cross-signing und Verifizierungsstatus bootstrappen:

openclaw matrix verify bootstrap

Multi-Account-Support: Nutze channels.matrix.accounts mit Zugangsdaten pro Account und optionalem name. Siehe Configuration reference für das gemeinsame Pattern.

Ausführliche Bootstrap-Diagnose:

openclaw matrix verify bootstrap --verbose

Einen frischen Reset der Cross-signing-Identität vor dem Bootstrapping erzwingen:

openclaw matrix verify bootstrap --force-reset-cross-signing

Dieses Gerät mit einem Recovery-Key verifizieren:

openclaw matrix verify device "<your-recovery-key>"

Ausführliche Details zur Geräteverifizierung:

openclaw matrix verify device "<your-recovery-key>" --verbose

Status des Room-Key-Backups prüfen:

openclaw matrix verify backup status

Ausführliche Diagnose zum Backup-Status:

openclaw matrix verify backup status --verbose

Room-Keys aus dem Server-Backup wiederherstellen:

openclaw matrix verify backup restore

Ausführliche Diagnose zur Wiederherstellung:

openclaw matrix verify backup restore --verbose

Das aktuelle Server-Backup löschen und eine frische Backup-Baseline erstellen:

openclaw matrix verify backup reset --yes

Alle verify-Befehle sind standardmäßig prägnant (einschließlich leisem internen SDK-Logging) und zeigen detaillierte Diagnosen nur mit --verbose. Nutze --json für eine vollständige maschinenlesbare Ausgabe beim Scripting.

In Multi-Account-Setups verwenden Matrix-CLI-Befehle den impliziten Matrix-Standard-Account, es sei denn, du übergibst --account <id>. Wenn du mehrere benannte Accounts konfigurierst, setze zuerst channels.matrix.defaultAccount, sonst stoppen diese impliziten CLI-Operationen und fordern dich auf, einen Account explizit auszuwählen. Nutze --account immer dann, wenn Verifizierungs- oder Geräte-Operationen gezielt einen benannten Account ansprechen sollen:

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

Wenn die Verschlüsselung für einen benannten Account deaktiviert oder nicht verfügbar ist, weisen Matrix-Warnungen und Verifizierungsfehler auf den Konfigurationsschlüssel dieses Accounts hin, zum Beispiel channels.matrix.accounts.assistant.encryption.

Was “verifiziert” bedeutet

OpenClaw betrachtet dieses Matrix-Gerät nur dann als verifiziert, wenn es durch deine eigene Cross-signing-Identität verifiziert wurde. In der Praxis zeigt openclaw matrix verify status --verbose drei Vertrauenssignale:

Locally trusted: Dieses Gerät wird nur vom aktuellen Client als vertrauenswürdig eingestuft.
Cross-signing verified: Das SDK meldet das Gerät als durch Cross-signing verifiziert.
Signed by owner: Das Gerät ist mit deinem eigenen Self-signing-Key signiert.

Verified by owner wird nur dann zu yes, wenn eine Cross-signing-Verifizierung oder eine Signierung durch den Besitzer vorliegt. Lokales Vertrauen allein reicht für OpenClaw nicht aus, um das Gerät als vollständig verifiziert zu behandeln.

Was Bootstrap bewirkt

openclaw matrix verify bootstrap ist der Befehl zur Reparatur und Einrichtung für verschlüsselte Matrix-Accounts. Er führt alle folgenden Schritte in dieser Reihenfolge aus:

Bootstrapping des Secret Storage, wobei nach Möglichkeit ein vorhandener Recovery-Key wiederverwendet wird.
Bootstrapping von Cross-signing und Upload fehlender öffentlicher Cross-signing-Keys.
Versuch, das aktuelle Gerät zu markieren und per Cross-signing zu signieren.
Erstellung eines neuen serverseitigen Room-Key-Backups, falls noch keines existiert.

Falls der Homeserver eine interaktive Authentifizierung für den Upload von Cross-signing-Keys erfordert, versucht OpenClaw den Upload zuerst ohne Auth, dann mit m.login.dummy und schließlich mit m.login.password, sofern channels.matrix.password konfiguriert ist.

Nutze --force-reset-cross-signing nur, wenn du die aktuelle Cross-signing-Identität absichtlich verwerfen und eine neue erstellen willst.

Wenn du das aktuelle Room-Key-Backup absichtlich verwerfen und eine neue Backup-Baseline für zukünftige Nachrichten starten willst, nutze openclaw matrix verify backup reset --yes. Tue dies nur, wenn du akzeptierst, dass nicht wiederherstellbare alte verschlüsselte Verläufe nicht mehr verfügbar sein werden.

Frische Backup-Baseline

Wenn du möchtest, dass zukünftige verschlüsselte Nachrichten funktionieren, und du den Verlust nicht wiederherstellbarer alter Verläufe akzeptierst, führe diese Befehle nacheinander aus:

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

Füge jedem Befehl --account <id> hinzu, wenn du gezielt einen benannten Matrix-Account ansprechen willst.

Startup-Verhalten

Wenn encryption: true gesetzt ist, verwendet Matrix für startupVerification standardmäßig den Wert "if-unverified". Beim Start fordert Matrix eine Selbst-Verifizierung in einem anderen Matrix-Client an, falls dieses Gerät noch unverifiziert ist. Dabei werden doppelte Anfragen übersprungen, während eine Anfrage bereits aussteht, und ein lokaler Cooldown angewendet, bevor es nach Neustarts erneut versucht wird. Fehlgeschlagene Anforderungsversuche werden standardmäßig schneller wiederholt als erfolgreich erstellte Anfragen. Setze startupVerification: "off", um automatische Startanfragen zu deaktivieren, oder passe startupVerificationCooldownHours an, wenn du ein kürzeres oder längeres Wiederholungsfenster wünschst.

Beim Start wird zudem automatisch ein konservativer Crypto-Bootstrap-Durchlauf durchgeführt. Dieser Durchlauf versucht zuerst, den aktuellen Secret Storage und die Cross-signing-Identität wiederzuverwenden, und vermeidet einen Reset des Cross-signing, es sei denn, du führst einen expliziten Bootstrap-Reparatur-Flow aus.

Falls der Start einen fehlerhaften Bootstrap-Status findet und channels.matrix.password konfiguriert ist, kann OpenClaw einen strikteren Reparaturpfad versuchen. Wenn das aktuelle Gerät bereits vom Besitzer signiert ist (owner-signed), bewahrt OpenClaw diese Identität, anstatt sie automatisch zurückzusetzen.

Upgrade vom vorherigen öffentlichen Matrix-Plugin:

OpenClaw verwendet denselben Matrix-Account, Access-Token und dieselbe Geräte-Identität nach Möglichkeit automatisch weiter.
Bevor ausführbare Matrix-Migrationsänderungen laufen, erstellt oder verwendet OpenClaw einen Recovery-Snapshot unter ~/Backups/openclaw-migrations/.
Wenn du mehrere Matrix-Accounts nutzt, setze channels.matrix.defaultAccount vor dem Upgrade vom alten Flat-Store-Layout, damit OpenClaw weiß, welcher Account diesen geteilten Legacy-Status erhalten soll.
Falls das vorherige Plugin einen Matrix Room-Key-Backup-Entschlüsselungs-Key lokal gespeichert hatte, wird dieser beim Start oder durch openclaw doctor --fix automatisch in den neuen Recovery-Key-Flow importiert.
Wenn sich der Matrix-Access-Token nach der Vorbereitung der Migration geändert hat, scannt der Start nun benachbarte Token-Hash-Storage-Roots nach ausstehendem Legacy-Wiederherstellungsstatus, bevor die automatische Backup-Wiederherstellung aufgegeben wird.
Wenn sich der Matrix-Access-Token später für denselben Account, Homeserver und User ändert, bevorzugt OpenClaw nun die Wiederverwendung des am vollständigsten existierenden Token-Hash-Storage-Roots, anstatt mit einem leeren Matrix-Statusverzeichnis zu beginnen.
Beim nächsten Gateway-Start werden gesicherte Room-Keys automatisch in den neuen Crypto-Store wiederhergestellt.
Falls das alte Plugin nur lokale Room-Keys hatte, die nie gesichert wurden, warnt OpenClaw deutlich. Diese Keys können nicht automatisch aus dem vorherigen Rust-Crypto-Store exportiert werden, sodass einige alte verschlüsselte Verläufe unzugänglich bleiben können, bis sie manuell wiederhergestellt werden.
Siehe Matrix migration für den vollständigen Upgrade-Flow, Limits, Recovery-Befehle und häufige Migrationsmeldungen.

Der verschlüsselte Runtime-Status ist unter Account- und User-bezogenen Token-Hash-Roots organisiert in: ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/. Dieses Verzeichnis enthält den Sync-Store (bot-storage.json), Crypto-Store (crypto/), die Recovery-Key-Datei (recovery-key.json), den IndexedDB-Snapshot (crypto-idb-snapshot.json), Thread-Bindings (thread-bindings.json) und den Status der Start-Verifizierung (startup-verification.json), sofern diese Funktionen genutzt werden. Wenn sich der Token ändert, aber die Account-Identität gleich bleibt, verwendet OpenClaw den besten existierenden Root für dieses Account/Homeserver/User-Tupel wieder, damit vorherige Sync-Status, Crypto-Status, Thread-Bindings und Start-Verifizierungsstatus sichtbar bleiben.

Node Crypto-Store-Modell

Matrix E2EE in diesem Plugin nutzt den offiziellen matrix-js-sdk Rust-Crypto-Pfad in Node. Dieser Pfad erwartet eine IndexedDB-basierte Persistenz, damit der Crypto-Status Neustarts übersteht.

OpenClaw stellt dies in Node aktuell wie folgt bereit:

Verwendung von fake-indexeddb als vom SDK erwarteter IndexedDB-API-Shim.
Wiederherstellung der Inhalte der Rust-Crypto-IndexedDB aus crypto-idb-snapshot.json vor initRustCrypto.
Persistierung der aktualisierten IndexedDB-Inhalte zurück in die crypto-idb-snapshot.json nach der Initialisierung und während der Laufzeit.

Dies dient der Kompatibilität und Speicheranbindung, es handelt sich nicht um eine eigene Crypto-Implementierung. Die Snapshot-Datei enthält sensiblen Runtime-Status und wird mit restriktiven Dateiberechtigungen gespeichert. Im Sicherheitsmodell von OpenClaw befinden sich der Gateway-Host und das lokale OpenClaw-Statusverzeichnis bereits innerhalb der vertrauenswürdigen Operator-Grenze, daher ist dies primär ein Thema der betrieblichen Beständigkeit und keine separate Remote-Vertrauensgrenze.

Geplante Verbesserung:

Hinzufügen von SecretRef-Support für persistentes Matrix-Key-Material, damit Recovery-Keys und zugehörige Secrets zur Store-Verschlüsselung aus OpenClaw-Secrets-Providern statt nur aus lokalen Dateien bezogen werden können.

Profil-Management

Aktualisiere das Matrix-Profil für den gewählten Account mit:

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

Füge --account <id> hinzu, wenn du gezielt einen benannten Matrix-Account ansprechen willst.

Matrix akzeptiert mxc:// Avatar-URLs direkt. Wenn du eine http:// oder https:// Avatar-URL übergibst, lädt OpenClaw diese zuerst zu Matrix hoch und speichert die aufgelöste mxc:// URL zurück in channels.matrix.avatarUrl (oder den entsprechenden Account-Override).

Automatische Verifizierungshinweise

Matrix postet Verifizierungs-Lifecycle-Hinweise jetzt direkt in den strikten DM-Verifizierungsraum als m.notice Nachrichten. Das beinhaltet:

Hinweise zu Verifizierungsanfragen
Hinweise zur Verifizierungsbereitschaft (mit expliziter Anleitung “Verifizierung per Emoji”)
Hinweise zum Start und Abschluss der Verifizierung
SAS-Details (Emoji und Dezimal), sofern verfügbar

Eingehende Verifizierungsanfragen von einem anderen Matrix-Client werden von OpenClaw verfolgt und automatisch akzeptiert. Bei Selbst-Verifizierungs-Flows startet OpenClaw den SAS-Flow ebenfalls automatisch, sobald die Emoji-Verifizierung verfügbar ist, und bestätigt die eigene Seite. Bei Verifizierungsanfragen von einem anderen Matrix-User oder Gerät akzeptiert OpenClaw die Anfrage automatisch und wartet dann darauf, dass der SAS-Flow normal fortgesetzt wird. Du musst weiterhin die Emojis oder den Dezimal-SAS in deinem Matrix-Client vergleichen und dort “Sie stimmen überein” bestätigen, um die Verifizierung abzuschließen.

OpenClaw akzeptiert selbst-initiierte doppelte Flows nicht blindlings. Der Start überspringt das Erstellen einer neuen Anfrage, wenn bereits eine Selbst-Verifizierungsanfrage aussteht.

Protokoll- oder Systemhinweise zur Verifizierung werden nicht an die Agent-Chat-Pipeline weitergeleitet, erzeugen also kein NO_REPLY.

Geräte-Hygiene

Alte von OpenClaw verwaltete Matrix-Geräte können sich im Account ansammeln und das Vertrauen in verschlüsselte Räume unübersichtlicher machen. Liste sie auf mit:

openclaw matrix devices list

Entferne veraltete von OpenClaw verwaltete Geräte mit:

openclaw matrix devices prune-stale

Direkte Raum-Reparatur

Wenn der Status von Direktnachrichten asynchron wird, kann OpenClaw veraltete m.direct-Mappings behalten, die auf alte Solo-Räume statt auf die aktive DM zeigen. Überprüfe das aktuelle Mapping für einen Peer mit:

openclaw matrix direct inspect --user-id @alice:example.org

Repariere es mit:

openclaw matrix direct repair --user-id @alice:example.org

Die Reparatur behält die Matrix-spezifische Logik innerhalb des Plugins:

Sie bevorzugt eine strikte 1:1 DM, die bereits in m.direct gemappt ist.
Andernfalls greift sie auf jede aktuell beigetretene strikte 1:1 DM mit diesem User zurück.
Falls keine intakte DM existiert, erstellt sie einen frischen Direktraum und schreibt m.direct um, um darauf zu zeigen.

Der Reparatur-Flow löscht alte Räume nicht automatisch. Er wählt nur die intakte DM aus und aktualisiert das Mapping, damit neue Matrix-Sends, Verifizierungshinweise und andere Direktnachrichten-Flows wieder den richtigen Raum ansprechen.

Threads

Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für das Senden über Message-Tools.

threadReplies: "off" hält Antworten auf der obersten Ebene (top-level) und belässt eingehende Thread-Nachrichten in der übergeordneten Session.
threadReplies: "inbound" antwortet nur dann innerhalb eines Threads, wenn die eingehende Nachricht bereits Teil dieses Threads war.
threadReplies: "always" hält Antworten im Raum in einem Thread, der bei der auslösenden Nachricht beginnt, und leitet diese Konversation durch die passende Thread-scoped Session der ersten auslösenden Nachricht.
dm.threadReplies überschreibt die Top-Level-Einstellung nur für DMs. So kannst du beispielsweise Raum-Threads isoliert halten, während DMs flach bleiben.
Eingehende Thread-Nachrichten enthalten die Thread-Root-Nachricht als zusätzlichen Agenten-Kontext.
Sends über das Message-Tool erben jetzt automatisch den aktuellen Matrix-Thread, wenn das Ziel derselbe Raum oder derselbe DM-User ist, es sei denn, es wird eine explizite threadId angegeben.
Runtime-Thread-Bindings werden für Matrix unterstützt. /focus, /unfocus, /agents, /session idle, /session max-age und Thread-gebundenes /acp spawn funktionieren jetzt in Matrix-Räumen und DMs.
Ein Top-Level Matrix-Raum/DM /focus erstellt einen neuen Matrix-Thread und bindet ihn an die Ziel-Session, wenn threadBindings.spawnSubagentSessions=true gesetzt ist.
Das Ausführen von /focus oder /acp spawn --thread here innerhalb eines bestehenden Matrix-Threads bindet stattdessen diesen aktuellen Thread.

AI Setup Assistant

ACP-Konversationsbindungen

Matrix-Räume, DMs und bestehende Matrix-Threads lassen sich in dauerhafte ACP-Workspaces verwandeln, ohne die Chat-Oberfläche zu ändern.

Schneller Operator-Flow:

Nutze /acp spawn codex --bind here innerhalb des Matrix-DMs, Raums oder Threads, den du weiterverwenden willst.
In einem Top-Level Matrix-DM oder Raum bleibt der aktuelle Chat die Oberfläche und zukünftige Nachrichten werden an die erzeugte ACP-Session geleitet.
Innerhalb eines bestehenden Matrix-Threads bindet --bind here diesen aktuellen Thread direkt an Ort und Stelle.
/new und /reset setzen dieselbe gebundene ACP-Session direkt zurück.
/acp close schließt die ACP-Session und entfernt die Bindung.

Hinweise:

--bind here erstellt keinen Child-Matrix-Thread.
threadBindings.spawnAcpSessions ist nur für /acp spawn --thread auto|here erforderlich, wenn OpenClaw einen Child-Matrix-Thread erstellen oder binden muss.

Thread-Binding-Konfiguration

Matrix erbt globale Defaults von session.threadBindings und unterstützt zusätzlich Overrides pro Channel:

threadBindings.enabled
threadBindings.idleHours
threadBindings.maxAgeHours
threadBindings.spawnSubagentSessions
threadBindings.spawnAcpSessions

Matrix-Thread-bound Spawn-Flags sind Opt-in:

Setze threadBindings.spawnSubagentSessions: true, um Top-Level /focus das Erstellen und Binden neuer Matrix-Threads zu erlauben.
Setze threadBindings.spawnAcpSessions: true, um /acp spawn --thread auto|here das Binden von ACP-Sessions an Matrix-Threads zu erlauben.

Reactions

Matrix unterstützt ausgehende Reaction-Aktionen, eingehende Reaction-Benachrichtigungen und eingehende Ack-Reactions.

Outbound-Reaction-Tooling wird über channels["matrix"].actions.reactions gesteuert.
react fügt einer spezifischen Matrix-Event eine Reaction hinzu.
reactions listet die aktuelle Reaction-Zusammenfassung für ein spezifisches Matrix-Event auf.
emoji="" entfernt die eigenen Reactions des Bot-Accounts bei diesem Event.
remove: true entfernt nur die angegebene Emoji-Reaction des Bot-Accounts.

Ack-Reactions nutzen die Standard-OpenClaw-Reihenfolge zur Auflösung:

channels["matrix"].accounts.<accountId>.ackReaction
channels["matrix"].ackReaction
messages.ackReaction
Agent-Identity Emoji-Fallback

Der Scope der Ack-Reaction wird in dieser Reihenfolge aufgelöst:

channels["matrix"].accounts.<accountId>.ackReactionScope
channels["matrix"].ackReactionScope
messages.ackReactionScope

Der Modus für Reaction-Benachrichtigungen wird so aufgelöst:

channels["matrix"].accounts.<accountId>.reactionNotifications
channels["matrix"].reactionNotifications
Default: own

Aktuelles Verhalten:

reactionNotifications: "own" leitet hinzugefügte m.reaction Events weiter, wenn diese auf vom Bot verfasste Matrix-Nachrichten abzielen.
reactionNotifications: "off" deaktiviert Reaction-System-Events.
Das Entfernen von Reactions wird noch nicht in System-Events umgewandelt, da Matrix diese als Redactions darstellt und nicht als eigenständige m.reaction-Entfernungen.

History-Kontext

channels.matrix.historyLimit steuert, wie viele der letzten Raumnachrichten als InboundHistory einbezogen werden, wenn eine Matrix-Raumnachricht den Agent triggert.
Es gibt einen Fallback auf messages.groupChat.historyLimit. Setze 0, um dies zu deaktivieren.
Matrix-Raum-History bezieht sich nur auf den Raum. DMs nutzen weiterhin die normale Session-History.
Matrix-Raum-History ist “pending-only”: OpenClaw puffert Raumnachrichten, die noch keine Antwort ausgelöst haben, und erstellt einen Snapshot dieses Fensters, sobald eine Erwähnung oder ein anderer Trigger eingeht.
Die aktuelle Trigger-Nachricht ist nicht in der InboundHistory enthalten; sie bleibt im Hauptteil der eingehenden Nachricht für diesen Turn.
Retries desselben Matrix-Events verwenden den ursprünglichen History-Snapshot wieder, anstatt zu neueren Raumnachrichten vorzurücken.
Abgerufener Raum-Kontext (einschließlich Reply- und Thread-Kontext-Lookups) wird durch Sender-Allowlists (groupAllowFrom) gefiltert, sodass Nachrichten von nicht autorisierten Sendern aus dem Agent-Kontext ausgeschlossen werden.

Beispiel für DM- und Raum-Policies

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

Schau unter Groups nach, um mehr über Mention-Gating und Allowlist-Verhalten zu erfahren.

Pairing-Beispiel für Matrix-DMs:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

Wenn dir ein nicht freigeschalteter Matrix-Nutzer vor der Genehmigung wiederholt Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code wieder und sendet nach einem kurzen Cooldown eventuell erneut eine Erinnerung, anstatt einen neuen Code zu generieren.

Details zum gemeinsamen DM-Pairing-Flow und zum Storage-Layout findest du unter Pairing.

Beispiel für mehrere Accounts

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

Werte auf der obersten Ebene von channels.matrix dienen als Standardwerte für benannte Accounts, sofern ein Account diese nicht überschreibt. Du kannst geerbte Raumeinträge mit groups.<room>.account (oder dem veralteten rooms.<room>.account) auf einen bestimmten Matrix-Account beschränken. Einträge ohne account bleiben für alle Matrix-Accounts geteilt. Einträge mit account: "default" funktionieren weiterhin, wenn der Standard-Account direkt oben unter channels.matrix.* konfiguriert ist.

Teilweise geteilte Auth-Standardwerte erstellen von sich aus keinen separaten impliziten Standard-Account. OpenClaw erstellt den Top-Level default Account nur dann, wenn dieser über frische Auth-Daten verfügt (homeserver plus accessToken oder homeserver plus userId und password). Benannte Accounts bleiben über homeserver plus userId auffindbar, wenn gecachte Anmeldedaten die Authentifizierung später ermöglichen.

Setze defaultAccount, wenn OpenClaw einen bestimmten benannten Matrix-Account für implizites Routing, Probing und CLI-Operationen bevorzugen soll. Wenn du mehrere benannte Accounts konfigurierst, setze defaultAccount oder übergib --account <id> bei CLI-Befehlen, die auf einer impliziten Account-Auswahl basieren. Übergib --account <id> an openclaw matrix verify ... und openclaw matrix devices ..., wenn du diese implizite Auswahl für einen einzelnen Befehl überschreiben willst.

Private/LAN Homeserver

Standardmäßig blockiert OpenClaw private oder interne Matrix-Homeserver zum Schutz vor SSRF, es sei denn, du aktivierst dies explizit pro Account.

Wenn dein Homeserver auf localhost, einer LAN/Tailscale-IP oder einem internen Hostnamen läuft, aktiviere allowPrivateNetwork für diesen Matrix-Account:

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}

Beispiel für das CLI-Setup:

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

Diese Aktivierung erlaubt nur vertrauenswürdige private oder interne Ziele. Öffentliche Klartext-Homeserver wie http://matrix.example.org:8008 bleiben blockiert. Verwende nach Möglichkeit immer https://.

Matrix-Traffic über einen Proxy leiten

Wenn dein Matrix-Deployment einen expliziten Outbound-HTTP(S)-Proxy benötigt, setzt du channels.matrix.proxy:

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

Benannte Accounts können den globalen Standardwert mit channels.matrix.accounts.<id>.proxy überschreiben. OpenClaw nutzt dieselbe Proxy-Einstellung sowohl für den Matrix-Traffic zur Laufzeit als auch für die Status-Probes der Accounts.

Auflösung von Zielen

Matrix akzeptiert diese Formate überall dort, wo OpenClaw dich nach einem Raum- oder User-Ziel fragt:

Users: @user:server, user:@user:server oder matrix:user:@user:server
Rooms: !room:server, room:!room:server oder matrix:room:!room:server
Aliases: #alias:server, channel:#alias:server oder matrix:channel:#alias:server

Die Live-Verzeichnissuche nutzt den jeweils angemeldeten Matrix-Account:

User-Lookups fragen das Matrix-User-Verzeichnis auf diesem Homeserver ab.
Raum-Lookups akzeptieren IDs und Aliases direkt. Falls das nicht funktioniert, durchsucht das System die Namen der Räume, denen der Account beigetreten ist.
Die Suche nach Namen beigetretener Räume erfolgt nach dem Best-Effort-Prinzip. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird dieser bei der Allowlist-Prüfung zur Laufzeit ignoriert.

Konfigurationsreferenz

enabled: Aktiviert oder deaktiviert den Channel.
name: Optionales Label für den Account.
defaultAccount: Bevorzugte Account-ID, wenn du mehrere Matrix-Accounts konfiguriert hast.
homeserver: Homeserver-URL, zum Beispiel https://matrix.example.org.
allowPrivateNetwork: Erlaubt diesem Matrix-Account, sich mit privaten oder internen Homeservern zu verbinden. Aktiviere das, wenn der Homeserver zu localhost, einer LAN/Tailscale-IP oder einem internen Host wie matrix-synapse auflöst.
proxy: Optionale HTTP(S)-Proxy-URL für Matrix-Traffic. Benannte Accounts können den Standardwert auf oberster Ebene mit ihrem eigenen proxy überschreiben.
userId: Vollständige Matrix-User-ID, zum Beispiel @bot:example.org.
accessToken: Access Token für Token-basierte Authentifizierung. Plaintext-Werte und SecretRef-Werte werden für channels.matrix.accessToken und channels.matrix.accounts.<id>.accessToken über env/file/exec Provider hinweg unterstützt. Siehe Secrets Management.
password: Passwort für den Passwort-basierten Login. Plaintext-Werte und SecretRef-Werte werden unterstützt.
deviceId: Explizite Matrix-Device-ID.
deviceName: Display-Name des Geräts für den Passwort-Login.
avatarUrl: Gespeicherte URL des eigenen Avatars für Profile-Sync und set-profile Updates.
initialSyncLimit: Limit für Sync-Events beim Start.
encryption: Aktiviert E2EE.
allowlistOnly: Erzwingt Allowlist-Verhalten für DMs und Räume.
groupPolicy: open, allowlist oder disabled.
groupAllowFrom: Allowlist von User-IDs für Room-Traffic.
Einträge in groupAllowFrom sollten vollständige Matrix-User-IDs sein. Nicht aufgelöste Namen werden zur Laufzeit ignoriert.
historyLimit: Maximale Anzahl an Raumnachrichten, die als Kontext für die Gruppen-History einbezogen werden. Nutzt messages.groupChat.historyLimit als Fallback. Setze den Wert auf 0, um die Funktion zu deaktivieren.
replyToMode: off, first oder all.
streaming: off (Standard) oder partial. partial aktiviert Entwurfsvorschauen für einzelne Nachrichten mit Edit-in-Place-Updates.
threadReplies: off, inbound oder always.
threadBindings: Overrides pro Channel für Thread-gebundenes Session-Routing und Lifecycle.
startupVerification: Modus für automatische Self-Verification-Anfragen beim Start (if-unverified, off).
startupVerificationCooldownHours: Cooldown, bevor automatische Startup-Verification-Anfragen erneut versucht werden.
textChunkLimit: Chunk-Größe für ausgehende Nachrichten.
chunkMode: length oder newline.
responsePrefix: Optionaler Nachrichten-Präfix für ausgehende Antworten.
ackReaction: Optionaler Ack-Reaction-Override für diesen Channel oder Account.
ackReactionScope: Optionaler Ack-Reaction-Scope-Override (group-mentions, group-all, direct, all, none, off).
reactionNotifications: Modus für Benachrichtigungen bei eingehenden Reaktionen (own, off).
mediaMaxMb: Obergrenze für die Mediengröße in MB für das Matrix-Media-Handling. Das gilt für ausgehendes Senden und die eingehende Medienverarbeitung.
autoJoin: Policy für automatisches Beitreten bei Einladungen (always, allowlist, off). Standard: off.
autoJoinAllowlist: Räume oder Aliase, die erlaubt sind, wenn autoJoin auf allowlist steht. Alias-Einträge werden während der Einladungsverarbeitung zu Room-IDs aufgelöst; OpenClaw vertraut nicht auf den vom eingeladenen Raum behaupteten Alias-Status.
dm: DM-Policy-Block (enabled, policy, allowFrom, threadReplies).
Einträge in dm.allowFrom sollten vollständige Matrix-User-IDs sein, es sei denn, du hast sie bereits über ein Live-Directory-Lookup aufgelöst.
dm.threadReplies: Thread-Policy-Override nur für DMs (off, inbound, always). Diese Einstellung überschreibt threadReplies auf oberster Ebene sowohl für die Platzierung von Antworten als auch für die Session-Isolation in DMs.
accounts: Benannte Overrides pro Account. Die Werte von channels.matrix auf oberster Ebene dienen als Standard für diese Einträge.
groups: Policy-Map pro Raum. Bevorzuge Room-IDs oder Aliase; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Die Session- oder Gruppen-Identität verwendet nach der Auflösung die stabile Room-ID, während menschenlesbare Labels weiterhin von den Raumnamen kommen.
rooms: Legacy-Alias für groups.
actions: Tool-Gating pro Aktion (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.