Matrix

Matrix ist ein herunterladbares Kanal-Plugin für OpenClaw. Es verwendet das offizielle matrix-js-sdk und unterstützt DMs, Räume, Threads, Medien, Reaktionen, Umfragen, Standort und E2EE.

# Installation

Installieren Sie Matrix, bevor Sie den Kanal konfigurieren:

openclaw plugins install @openclaw/matrix

Aus einem lokalen Checkout:

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

plugins install registriert und aktiviert das Plugin, daher ist kein separater Schritt openclaw plugins enable matrix erforderlich. Das Plugin tut weiterhin nichts, bis Sie den untenstehenden Kanal konfigurieren. Siehe Plugins für allgemeines Plugin-Verhalten und Installationsregeln.

# Einrichtung

1. Erstellen Sie ein Matrix-Konto auf Ihrem Homeserver.
2. Konfigurieren Sie channels.matrix entweder mit homeserver + accessToken oder mit homeserver + userId + password.
3. Starten Sie das Gateway neu.
4. Starten Sie eine DM mit dem Bot oder laden Sie ihn in einen Raum ein (siehe automatisches Beitreten - neue Einladungen landen nur, wenn autoJoin sie zulässt).

# Interaktive Einrichtung

openclaw channels add
openclaw configure --section channels

Der Assistent fragt nach: Homeserver-URL, Authentifizierungsmethode (Access Token oder Passwort), Benutzer-ID (nur Passwortauthentifizierung), optionalem Gerätenamen, ob E2EE aktiviert werden soll und ob Raumzugriff und automatisches Beitreten konfiguriert werden sollen.

Wenn passende MATRIX_*-Umgebungsvariablen bereits vorhanden sind und das ausgewählte Konto keine gespeicherte Authentifizierung hat, bietet der Assistent eine Umgebungsvariablen-Abkürzung an. Um Raumnamen vor dem Speichern einer Allowlist aufzulösen, führen Sie openclaw channels resolve --channel matrix "Project Room" aus. Wenn E2EE aktiviert ist, schreibt der Assistent die Konfiguration und führt denselben Bootstrap wie openclaw matrix encryption setup aus.

# Minimale Konfiguration

Token-basiert:

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

Passwortbasiert (das Token wird nach der ersten Anmeldung zwischengespeichert):

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

# Automatisches Beitreten

channels.matrix.autoJoin ist standardmäßig off. Mit der Standardeinstellung erscheint der Bot nicht in neuen Räumen oder DMs aus neuen Einladungen, bis Sie manuell beitreten.

OpenClaw kann zum Einladungszeitpunkt nicht erkennen, ob ein eingeladener Raum eine DM oder eine Gruppe ist, daher laufen alle Einladungen - einschließlich DM-artiger Einladungen - zuerst durch autoJoin. dm.policy gilt erst später, nachdem der Bot beigetreten ist und der Raum klassifiziert wurde.

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}

Um jede Einladung anzunehmen, verwenden Sie autoJoin: "always".

# Allowlist-Zielformate

DM- und Raum-Allowlists werden am besten mit stabilen IDs befüllt:

• DMs (dm.allowFrom, groupAllowFrom, groups.<room>.users): Verwenden Sie @user:server. Anzeigenamen werden nur aufgelöst, wenn das Homeserver-Verzeichnis genau einen Treffer zurückgibt.
• Räume (groups, autoJoinAllowlist): Verwenden Sie !room:server oder #alias:server. Namen werden bestmöglich gegen beigetretene Räume aufgelöst; nicht aufgelöste Einträge werden zur Laufzeit ignoriert.

# Normalisierung der Konto-ID

Der Assistent wandelt einen freundlichen Namen in eine normalisierte Konto-ID um. Zum Beispiel wird Ops Bot zu ops-bot. Satzzeichen werden in bereichsbezogenen Umgebungsvariablennamen escaped, sodass zwei Konten nicht kollidieren können: - → _X2D_, also wird ops-prod auf MATRIX_OPS_X2D_PROD_* abgebildet.

# Zwischengespeicherte Zugangsdaten

Matrix speichert zwischengespeicherte Zugangsdaten unter ~/.openclaw/credentials/matrix/:

• Standardkonto: credentials.json
• benannte Konten: credentials-<account>.json

Wenn dort zwischengespeicherte Zugangsdaten vorhanden sind, behandelt OpenClaw Matrix als konfiguriert, auch wenn das Access Token nicht in der Konfigurationsdatei steht - das deckt Einrichtung, openclaw doctor und Kanalstatus-Prüfungen ab.

# Umgebungsvariablen

Werden verwendet, wenn der entsprechende Konfigurationsschlüssel nicht gesetzt ist. Das Standardkonto verwendet Namen ohne Präfix; benannte Konten verwenden die vor dem Suffix eingefügte Konto-ID.

Für das Konto ops werden die Namen zu MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN und so weiter. Die Recovery-Key-Umgebungsvariablen werden von Recovery-fähigen CLI-Abläufen (verify backup restore, verify device, verify bootstrap) gelesen, wenn Sie den Schlüssel über --recovery-key-stdin weiterleiten.

MATRIX_HOMESERVER kann nicht aus einer Workspace-.env gesetzt werden; siehe Workspace-.env-Dateien.

# Konfigurationsbeispiel

Eine praktische Basis mit DM-Pairing, Raum-Allowlist und E2EE:

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

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        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

Matrix-Antwort-Streaming ist Opt-in. streaming steuert, wie OpenClaw die laufende Assistentenantwort ausliefert; blockStreaming steuert, ob jeder abgeschlossene Block als eigene Matrix-Nachricht erhalten bleibt.

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

Um Live-Antwortvorschauen beizubehalten, aber Zwischenzeilen zu Tools/Fortschritt auszublenden, verwenden Sie die Objektform:

{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

blockStreaming ist unabhängig von streaming:

Hinweise:

• Wenn eine Vorschau die pro Ereignis geltende Größenbegrenzung von Matrix überschreitet, stoppt OpenClaw das Vorschau-Streaming und fällt auf reine finale Zustellung zurück.
• Medienantworten senden Anhänge immer normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, redigiert OpenClaw sie, bevor die finale Medienantwort gesendet wird.
• Vorschauaktualisierungen für Tool-Fortschritt sind standardmäßig aktiviert, wenn Matrix-Vorschau-Streaming aktiv ist. Setzen Sie streaming.preview.toolProgress: false, um Vorschau-Bearbeitungen für Antworttext beizubehalten, den Tool-Fortschritt aber auf dem normalen Zustellpfad zu belassen.
• Vorschau-Bearbeitungen kosten zusätzliche Matrix-API-Aufrufe. Lassen Sie streaming: "off" gesetzt, wenn Sie das konservativste Rate-Limit-Profil wünschen.

# Genehmigungsmetadaten

Native Matrix-Genehmigungsaufforderungen sind normale m.room.message-Ereignisse mit OpenClaw-spezifischem benutzerdefiniertem Ereignisinhalt unter com.openclaw.approval. Matrix erlaubt benutzerdefinierte Ereignisinhalts-Schlüssel, daher rendern Standard-Clients weiterhin den Textkörper, während OpenClaw-fähige Clients die strukturierte Genehmigungs-ID, Art, Status, verfügbaren Entscheidungen und Exec-/Plugin-Details lesen können.

Wenn eine Genehmigungsaufforderung zu lang für ein Matrix-Ereignis ist, teilt OpenClaw den sichtbaren Text in Blöcke auf und hängt com.openclaw.approval nur an den ersten Block an. Reaktionen für Zulassen-/Ablehnen-Entscheidungen sind an dieses erste Ereignis gebunden, sodass lange Aufforderungen dasselbe Genehmigungsziel wie Ein-Ereignis-Aufforderungen behalten.

# Selbst gehostete Push-Regeln für stille finalisierte Vorschauen

streaming: "quiet" benachrichtigt Empfänger erst, wenn ein Block oder Turn finalisiert ist - eine benutzerbezogene Push-Regel muss auf den finalisierten Vorschaumarker passen. Siehe Matrix-Push-Regeln für stille Vorschauen für das vollständige Rezept (Empfänger-Token, Pusher-Prüfung, Regelinstallation, Hinweise pro Homeserver).

# Bot-zu-Bot-Räume

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

Verwenden Sie allowBots, wenn Sie absichtlich Matrix-Datenverkehr zwischen Agenten möchten:

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

• allowBots: true akzeptiert Nachrichten von anderen konfigurierten Matrix-Bot-Konten 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 kontoweite Einstellung für einen Raum.
• OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Selbstantwort-Schleifen zu vermeiden.
• Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw behandelt „von Bots verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“.

Verwenden Sie strikte Raum-Allowlists und Erwähnungsanforderungen, wenn Sie Bot-zu-Bot-Datenverkehr in gemeinsam genutzten Räumen aktivieren.

# Verschlüsselung und Verifizierung

In verschlüsselten (E2EE-)Räumen verwenden ausgehende Bildereignisse thumbnail_file, sodass Bildvorschauen zusammen mit dem vollständigen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin normales thumbnail_url. Es ist keine Konfiguration erforderlich - das Plugin erkennt den E2EE-Status automatisch.

Alle openclaw matrix-Befehle akzeptieren --verbose (vollständige Diagnose), --json (maschinenlesbare Ausgabe) und --account <id> (Mehrkontoeinrichtungen). Die Ausgabe ist standardmäßig knapp und verwendet stilles internes SDK-Logging. Die folgenden Beispiele zeigen die kanonische Form; fügen Sie die Flags nach Bedarf hinzu.

# Verschlüsselung aktivieren

openclaw matrix encryption setup

Initialisiert Secret Storage und Cross-Signing, erstellt bei Bedarf ein Raum-Schlüssel-Backup und gibt anschließend Status und nächste Schritte aus. Nützliche Flags:

• --recovery-key <key> wendet vor dem Bootstrapping einen Wiederherstellungsschlüssel an (bevorzugen Sie die unten dokumentierte stdin-Form)
• --force-reset-cross-signing verwirft die aktuelle Cross-Signing-Identität und erstellt eine neue (nur bewusst verwenden)

Aktivieren Sie E2EE für ein neues Konto direkt bei der Erstellung:

openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

--encryption ist ein Alias für --enable-e2ee.

Manuelles Konfigurationsäquivalent:

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

# Status- und Vertrauenssignale

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

verify status meldet drei unabhängige Vertrauenssignale (--verbose zeigt alle an):

• Locally trusted: nur von diesem Client als vertrauenswürdig eingestuft
• Cross-signing verified: das SDK meldet Verifizierung per Cross-Signing
• Signed by owner: mit Ihrem eigenen Self-Signing-Schlüssel signiert (nur Diagnose)

Verified by owner wird nur dann zu yes, wenn Cross-signing verified yes ist. Lokales Vertrauen oder eine Owner-Signatur allein reicht nicht aus.

--allow-degraded-local-state gibt Best-Effort-Diagnosen zurück, ohne zuerst das Matrix-Konto vorzubereiten; nützlich für Offline- oder teilweise konfigurierte Prüfungen.

# Dieses Gerät mit einem Wiederherstellungsschlüssel verifizieren

Der Wiederherstellungsschlüssel ist sensibel - leiten Sie ihn über stdin weiter, statt ihn auf der Befehlszeile zu übergeben. Setzen Sie MATRIX_RECOVERY_KEY (oder MATRIX_<ID>_RECOVERY_KEY für ein benanntes Konto):

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

Der Befehl meldet drei Zustände:

• Recovery key accepted: Matrix hat den Schlüssel für Secret Storage oder Gerätevertrauen akzeptiert.
• Backup usable: Das Raum-Schlüssel-Backup kann mit dem vertrauenswürdigen Wiederherstellungsmaterial geladen werden.
• Device verified by owner: Dieses Gerät verfügt über vollständiges Vertrauen in die Matrix-Cross-Signing-Identität.

Er beendet sich mit einem Nicht-Null-Code, wenn das vollständige Identitätsvertrauen unvollständig ist, auch wenn der Wiederherstellungsschlüssel Backup-Material entsperrt hat. Schließen Sie in diesem Fall die Selbstverifizierung aus einem anderen Matrix-Client ab:

openclaw matrix verify self

verify self wartet auf Cross-signing verified: yes, bevor es erfolgreich beendet wird. Verwenden Sie --timeout-ms <ms>, um die Wartezeit anzupassen.

Die Literal-Schlüssel-Form openclaw matrix verify device "<recovery-key>" wird ebenfalls akzeptiert, aber der Schlüssel landet in Ihrer Shell-History.

# Cross-Signing initialisieren oder reparieren

openclaw matrix verify bootstrap

verify bootstrap ist der Reparatur- und Einrichtungsbefehl für verschlüsselte Konten. Der Reihe nach:

• initialisiert er Secret Storage und verwendet nach Möglichkeit einen vorhandenen Wiederherstellungsschlüssel erneut
• initialisiert er Cross-Signing und lädt fehlende öffentliche Schlüssel hoch
• markiert und cross-signiert er das aktuelle Gerät
• erstellt er ein serverseitiges Raum-Schlüssel-Backup, falls noch keines existiert

Wenn der Homeserver UIA zum Hochladen von Cross-Signing-Schlüsseln erfordert, versucht OpenClaw zuerst ohne Authentifizierung, dann m.login.dummy, dann m.login.password (erfordert channels.matrix.password).

Nützliche Flags:

• --recovery-key-stdin (kombinieren Sie es mit printf '%s\n' "$MATRIX_RECOVERY_KEY" | …) oder --recovery-key <key>
• --force-reset-cross-signing, um die aktuelle Cross-Signing-Identität zu verwerfen (nur bewusst)

# Raum-Schlüssel-Backup

openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

backup status zeigt, ob ein serverseitiges Backup existiert und ob dieses Gerät es entschlüsseln kann. backup restore importiert gesicherte Raum-Schlüssel in den lokalen Crypto-Store; wenn der Wiederherstellungsschlüssel bereits auf der Festplatte liegt, können Sie --recovery-key-stdin weglassen.

So ersetzen Sie ein defektes Backup durch eine neue Ausgangsbasis (akzeptiert den Verlust nicht wiederherstellbarer alter Historie; kann auch Secret Storage neu erstellen, wenn das aktuelle Backup-Secret nicht ladbar ist):

openclaw matrix verify backup reset --yes

Fügen Sie --rotate-recovery-key nur hinzu, wenn Sie bewusst möchten, dass der vorherige Wiederherstellungsschlüssel die neue Backup-Ausgangsbasis nicht mehr entsperrt.

# Verifizierungen auflisten, anfordern und beantworten

openclaw matrix verify list

Listet ausstehende Verifizierungsanfragen für das ausgewählte Konto auf.

openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

Sendet eine Verifizierungsanfrage von diesem OpenClaw-Konto. --own-user fordert eine Selbstverifizierung an (Sie akzeptieren die Aufforderung in einem anderen Matrix-Client desselben Benutzers); --user-id/--device-id/--room-id zielen auf eine andere Person. --own-user kann nicht mit den anderen Ziel-Flags kombiniert werden.

Für die Lifecycle-Behandlung auf niedrigerer Ebene - typischerweise beim Begleiten eingehender Anfragen aus einem anderen Client - wirken diese Befehle auf eine bestimmte Anfrage <id> (ausgegeben von verify list und verify request):

accept, start, sas, confirm-sas, mismatch-sas und cancel akzeptieren alle --user-id und --room-id als DM-Follow-up-Hinweise, wenn die Verifizierung an einen bestimmten Direktnachrichtenraum gebunden ist.

# Hinweise zu mehreren Konten

Ohne --account <id> verwenden Matrix-CLI-Befehle das implizite Standardkonto. Wenn Sie mehrere benannte Konten haben und channels.matrix.defaultAccount nicht gesetzt haben, verweigern sie das Raten und bitten Sie um eine Auswahl. Wenn E2EE für ein benanntes Konto deaktiviert oder nicht verfügbar ist, verweisen Fehler auf den Konfigurationsschlüssel dieses Kontos, zum Beispiel channels.matrix.accounts.assistant.encryption.

openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--user-id '@assistant:example.org' \
--password '<password>' \
--device-name OpenClaw-Gateway

openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--access-token '<token>'

openclaw matrix devices list
openclaw matrix devices prune-stale

# Profilverwaltung

Aktualisieren Sie das Matrix-Selbstprofil für das ausgewählte Konto:

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

Sie können beide Optionen in einem Aufruf übergeben. Matrix akzeptiert mxc://-Avatar-URLs direkt; wenn Sie http:// oder https:// übergeben, lädt OpenClaw die Datei zuerst hoch und speichert die aufgelöste mxc://-URL in channels.matrix.avatarUrl (oder der kontospezifischen Überschreibung).

# Threads

Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Message-Tool-Sends. Zwei unabhängige Regler steuern das Verhalten:

# Sitzungsrouting (sessionScope)

dm.sessionScope entscheidet, wie Matrix-DM-Räume OpenClaw-Sitzungen zugeordnet werden:

• "per-user" (Standard): Alle DM-Räume mit demselben gerouteten Peer teilen sich eine Sitzung.
• "per-room": Jeder Matrix-DM-Raum erhält seinen eigenen Sitzungsschlüssel, auch wenn der Peer derselbe ist.

Explizite Conversation-Bindings haben immer Vorrang vor sessionScope, sodass gebundene Räume und Threads ihre gewählte Zielsitzung behalten.

# Antwort-Threading (threadReplies)

threadReplies entscheidet, wo der Bot seine Antwort veröffentlicht:

• "off": Antworten sind Top-Level. Eingehende Thread-Nachrichten bleiben in der übergeordneten Sitzung.
• "inbound": Nur dann innerhalb eines Threads antworten, wenn die eingehende Nachricht bereits in diesem Thread war.
• "always": Innerhalb eines Threads antworten, der bei der auslösenden Nachricht beginnt; diese Conversation wird ab dem ersten Trigger über eine passende thread-bezogene Sitzung geroutet.

dm.threadReplies überschreibt dies nur für DMs - zum Beispiel, um Raum-Threads isoliert zu halten, während DMs flach bleiben.

# Thread-Vererbung und Slash-Befehle

• Eingehende Thread-Nachrichten enthalten die Thread-Stammnachricht als zusätzlichen Agent-Kontext.
• Über das Message-Tool gesendete Nachrichten erben automatisch den aktuellen Matrix-Thread, wenn sie denselben Raum (oder dasselbe DM-Benutzerziel) adressieren, sofern keine explizite threadId angegeben ist.
• Die Wiederverwendung von DM-Benutzerzielen greift nur, wenn die aktuellen Sitzungsmetadaten denselben DM-Gegenüber auf demselben Matrix-Konto belegen; andernfalls fällt OpenClaw auf normales benutzerbezogenes Routing zurück.
• /focus, /unfocus, /agents, /session idle, /session max-age und Thread-gebundenes /acp spawn funktionieren alle in Matrix-Räumen und DMs.
• /focus auf oberster Ebene erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn threadBindings.spawnSessions aktiviert ist.
• Das Ausführen von /focus oder /acp spawn --thread here innerhalb eines bestehenden Matrix-Threads bindet diesen Thread an Ort und Stelle.

Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum derselben geteilten Sitzung kollidiert, postet es einmalig ein m.notice in diesem Raum, das auf den /focus-Ausweg verweist und eine Änderung von dm.sessionScope vorschlägt. Der Hinweis erscheint nur, wenn Thread-Bindungen aktiviert sind.

# ACP-Konversationsbindungen

Matrix-Räume, DMs und bestehende Matrix-Threads können in dauerhafte ACP-Arbeitsbereiche umgewandelt werden, ohne die Chat-Oberfläche zu ändern.

Schneller Ablauf für Operatoren:

• Führen Sie /acp spawn codex --bind here in der Matrix-DM, dem Raum oder dem bestehenden Thread aus, den Sie weiterverwenden möchten.
• In einer Matrix-DM oder einem Matrix-Raum auf oberster Ebene bleibt die aktuelle DM bzw. der aktuelle Raum die Chat-Oberfläche, und zukünftige Nachrichten werden an die erzeugte ACP-Sitzung geroutet.
• Innerhalb eines bestehenden Matrix-Threads bindet --bind here diesen aktuellen Thread an Ort und Stelle.
• /new und /reset setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück.
• /acp close schließt die ACP-Sitzung und entfernt die Bindung.

Hinweise:

• --bind here erstellt keinen untergeordneten Matrix-Thread.
• threadBindings.spawnSessions steuert /acp spawn --thread auto|here, wobei OpenClaw einen untergeordneten Matrix-Thread erstellen oder binden muss.

# Thread-Bindungskonfiguration

Matrix erbt globale Standardwerte aus session.threadBindings und unterstützt außerdem kanalbezogene Überschreibungen:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

Thread-gebundene Sitzungs-Spawns von Matrix sind standardmäßig aktiviert:

• Setzen Sie threadBindings.spawnSessions: false, um zu verhindern, dass /focus auf oberster Ebene und /acp spawn --thread auto|here Matrix-Threads erstellen oder binden.
• Setzen Sie threadBindings.defaultSpawnContext: "isolated", wenn native Subagent-Thread-Spawns das übergeordnete Transkript nicht forken sollen.

# Reaktionen

Matrix unterstützt ausgehende Reaktionen, eingehende Reaktionsbenachrichtigungen und Bestätigungsreaktionen.

Die Werkzeuge für ausgehende Reaktionen werden durch channels.matrix.actions.reactions gesteuert:

• react fügt einem Matrix-Ereignis eine Reaktion hinzu.
• reactions listet die aktuelle Reaktionszusammenfassung für ein Matrix-Ereignis auf.
• emoji="" entfernt die eigenen Reaktionen des Bots auf dieses Ereignis.
• remove: true entfernt nur die angegebene Emoji-Reaktion vom Bot.

Auflösungsreihenfolge (der erste definierte Wert gewinnt):

reactionNotifications: "own" leitet hinzugefügte m.reaction-Ereignisse weiter, wenn sie auf von Bots verfasste Matrix-Nachrichten zielen; "off" deaktiviert Reaktionssystemereignisse. Reaktionsentfernungen werden nicht zu Systemereignissen synthetisiert, weil Matrix sie als Redaktionen darstellt, nicht als eigenständige m.reaction-Entfernungen.

# Verlaufskontext

• channels.matrix.historyLimit steuert, wie viele aktuelle Raumnachrichten als InboundHistory einbezogen werden, wenn eine Matrix-Raumnachricht den Agent auslöst. Fällt auf messages.groupChat.historyLimit zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert 0. Setzen Sie 0, um dies zu deaktivieren.
• Matrix-Raumverlauf ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf.
• Matrix-Raumverlauf ist nur ausstehend: OpenClaw puffert Raumnachrichten, die noch keine Antwort ausgelöst haben, und erstellt dann einen Snapshot dieses Fensters, wenn eine Erwähnung oder ein anderer Auslöser eintrifft.
• Die aktuelle Auslösenachricht wird nicht in InboundHistory aufgenommen; sie bleibt für diesen Durchlauf im Haupttext der eingehenden Nachricht.
• Wiederholungen desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot erneut, statt zu neueren Raumnachrichten weiterzurücken.

# Kontextsichtbarkeit

Matrix unterstützt die gemeinsame contextVisibility-Steuerung für zusätzlichen Raumkontext wie abgerufenen Antworttext, Thread-Stämme und ausstehenden Verlauf.

• contextVisibility: "all" ist der Standard. Zusätzlicher Kontext bleibt wie empfangen erhalten.
• contextVisibility: "allowlist" filtert zusätzlichen Kontext auf Absender, die durch die aktiven Prüfungen der Raum-/Benutzer-Allowlist erlaubt sind.
• contextVisibility: "allowlist_quote" verhält sich wie allowlist, behält aber weiterhin eine explizit zitierte Antwort bei.

Diese Einstellung beeinflusst die Sichtbarkeit von zusätzlichem Kontext, nicht, ob die eingehende Nachricht selbst eine Antwort auslösen kann. Die Auslöseautorisierung stammt weiterhin aus groupPolicy, groups, groupAllowFrom und den DM-Richtlinieneinstellungen.

# DM- und Raumrichtlinie

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

Um DMs vollständig stummzuschalten, während Räume weiter funktionieren, setzen Sie dm.enabled: false:

{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

Siehe Gruppen für Erwähnungs-Gating und Allowlist-Verhalten.

Pairing-Beispiel für Matrix-DMs:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

Wenn ein nicht genehmigter Matrix-Benutzer Ihnen vor der Genehmigung weiterhin Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und kann nach einer kurzen Abkühlzeit eine Erinnerungsantwort senden, statt einen neuen Code zu erzeugen.

Siehe Pairing für den gemeinsamen DM-Pairing-Ablauf und das Speicherlayout.

# Direkte Raumreparatur

Wenn der Direktnachrichtenstatus nicht mehr synchron ist, kann OpenClaw veraltete m.direct-Zuordnungen erhalten, die auf alte Solo-Räume statt auf die aktive DM verweisen. Prüfen Sie die aktuelle Zuordnung für einen Gegenüber:

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

Reparieren Sie sie:

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

Beide Befehle akzeptieren --account <id> für Mehrkonten-Setups. Der Reparaturablauf:

• bevorzugt eine strikte 1:1-DM, die bereits in m.direct zugeordnet ist
• fällt auf jede aktuell beigetretene strikte 1:1-DM mit diesem Benutzer zurück
• erstellt einen neuen direkten Raum und schreibt m.direct neu, wenn keine fehlerfreie DM vorhanden ist

Er löscht alte Räume nicht automatisch. Er wählt die fehlerfreie DM aus und aktualisiert die Zuordnung, damit zukünftige Matrix-Sendungen, Verifizierungshinweise und andere Direktnachrichtenabläufe den richtigen Raum adressieren.

# Exec-Genehmigungen

Matrix kann als nativer Genehmigungsclient fungieren. Konfigurieren Sie dies unter channels.matrix.execApprovals (oder channels.matrix.accounts.<account>.execApprovals für eine kontobezogene Überschreibung):

• enabled: Genehmigungen über Matrix-native Prompts zustellen. Wenn nicht gesetzt oder "auto", aktiviert Matrix dies automatisch, sobald mindestens ein Genehmigender aufgelöst werden kann. Setzen Sie false, um es explizit zu deaktivieren.
• approvers: Matrix-Benutzer-IDs (@owner:example.org), die Exec-Anfragen genehmigen dürfen. Optional - fällt auf channels.matrix.dm.allowFrom zurück.
• target: wohin Prompts gehen. "dm" (Standard) sendet an DMs der Genehmigenden; "channel" sendet an den auslösenden Matrix-Raum oder die auslösende DM; "both" sendet an beide.
• agentFilter / sessionFilter: optionale Allowlists dafür, welche Agents/Sitzungen die Matrix-Zustellung auslösen.

Die Autorisierung unterscheidet sich geringfügig zwischen Genehmigungsarten:

• Exec-Genehmigungen verwenden execApprovals.approvers und fallen auf dm.allowFrom zurück.
• Plugin-Genehmigungen autorisieren ausschließlich über dm.allowFrom.

Beide Arten teilen sich Matrix-Reaktionskürzel und Nachrichtenaktualisierungen. Genehmigende sehen Reaktionskürzel auf der primären Genehmigungsnachricht:

• ✅ einmal erlauben
• ❌ ablehnen
• ♾️ immer erlauben (wenn die effektive Exec-Richtlinie dies zulässt)

Fallback-Slash-Befehle: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.

Nur aufgelöste Genehmigende können genehmigen oder ablehnen. Kanalzustellung für Exec-Genehmigungen enthält den Befehlstext - aktivieren Sie channel oder both nur in vertrauenswürdigen Räumen.

Verwandt: Exec-Genehmigungen.

# Slash-Befehle

Slash-Befehle (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve usw.) funktionieren direkt in DMs. In Räumen erkennt OpenClaw auch Befehle, denen die eigene Matrix-Erwähnung des Bots vorangestellt ist, sodass @bot:server /new den Befehlspfad ohne benutzerdefinierten Erwähnungs-Regex auslöst. Dadurch bleibt der Bot für raumtypische @mention /command-Beiträge reaktionsfähig, die Element und ähnliche Clients ausgeben, wenn ein Benutzer den Bot per Tab-Vervollständigung auswählt, bevor er den Befehl eintippt.

Autorisierungsregeln gelten weiterhin: Befehlssender müssen dieselben DM- oder Raum-Allowlist-/Owner-Richtlinien erfüllen wie normale Nachrichten.

# Mehrere Konten

{
  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",
          },
        },
      },
    },
  },
}

Vererbung:

• Werte auf oberster Ebene von channels.matrix dienen als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt.
• Beschränken Sie einen geerbten Raumeintrag mit groups.<room>.account auf ein bestimmtes Konto. Einträge ohne account werden kontoübergreifend geteilt; account: "default" funktioniert weiterhin, wenn das Standardkonto auf oberster Ebene konfiguriert ist.

Auswahl des Standardkontos:

• Setzen Sie defaultAccount, um das benannte Konto auszuwählen, das implizites Routing, Probing und CLI-Befehle bevorzugen.
• Wenn Sie mehrere Konten haben und eines davon wörtlich default heißt, verwendet OpenClaw es implizit, auch wenn defaultAccount nicht gesetzt ist.
• Wenn Sie mehrere benannte Konten haben und kein Standard ausgewählt ist, weigern sich CLI-Befehle zu raten - setzen Sie defaultAccount oder übergeben Sie --account <id>.
• Der Block channels.matrix.* auf oberster Ebene wird nur dann als implizites default-Konto behandelt, wenn seine Authentifizierung vollständig ist (homeserver + accessToken oder homeserver + userId + password). Benannte Konten bleiben über homeserver + userId auffindbar, sobald zwischengespeicherte Anmeldedaten die Authentifizierung abdecken.

Promotion:

• Wenn OpenClaw während Reparatur oder Einrichtung eine Einzelkonto-Konfiguration zu einer Mehrkonten-Konfiguration promoted, behält es das bestehende benannte Konto bei, falls eines vorhanden ist oder defaultAccount bereits auf eines zeigt. Nur Matrix-Authentifizierungs-/Bootstrap-Schlüssel werden in das promotete Konto verschoben; gemeinsame Zustellungsrichtlinien-Schlüssel bleiben auf oberster Ebene.

Siehe Konfigurationsreferenz für das gemeinsame Mehrkonten-Muster.

# Private/LAN-Homeserver

Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum Schutz vor SSRF, sofern Sie sich nicht explizit pro Konto dafür entscheiden.

Wenn Ihr Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen Hostnamen läuft, aktivieren Sie network.dangerouslyAllowPrivateNetwork für dieses Matrix-Konto:

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

CLI-Einrichtungsbeispiel:

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

Diese Opt-in-Einstellung erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche Klartext-Homeserver wie http://matrix.example.org:8008 bleiben blockiert. Verwenden Sie nach Möglichkeit https://.

# Matrix-Datenverkehr über einen Proxy leiten

Wenn Ihre Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benötigt, setzen Sie channels.matrix.proxy:

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

Benannte Konten können die Standardvorgabe auf oberster Ebene mit channels.matrix.accounts.<id>.proxy überschreiben. OpenClaw verwendet dieselbe Proxy-Einstellung für Matrix-Datenverkehr zur Laufzeit und für Kontostatusprüfungen.

# Zielauflösung

Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw Sie nach einem Raum- oder Benutzerziel fragt:

• Benutzer: @user:server, user:@user:server oder matrix:user:@user:server
• Räume: !room:server, room:!room:server oder matrix:room:!room:server
• Aliasse: #alias:server, channel:#alias:server oder matrix:channel:#alias:server

Matrix-Raum-IDs unterscheiden Groß- und Kleinschreibung. Verwenden Sie die exakte Groß-/Kleinschreibung der Raum-ID aus Matrix, wenn Sie explizite Zustellziele, Cron-Jobs, Bindings oder Allowlists konfigurieren. OpenClaw hält interne Sitzungsschlüssel für die Speicherung kanonisch, daher sind diese kleingeschriebenen Schlüssel keine zuverlässige Quelle für Matrix-Zustell-IDs.

Die Live-Verzeichnissuche verwendet das angemeldete Matrix-Konto:

• Benutzersuchen fragen das Matrix-Benutzerverzeichnis auf diesem Homeserver ab.
• Raumsuchen akzeptieren explizite Raum-IDs und Aliasse direkt und greifen dann auf die Suche nach Namen beigetretener Räume für dieses Konto zurück.
• Die Namenssuche in beigetretenen Räumen erfolgt nach bestem Aufwand. Wenn ein Raumname nicht in eine ID oder einen Alias aufgelöst werden kann, wird er von der Allowlist-Auflösung zur Laufzeit ignoriert.

# Konfigurationsreferenz

Allowlist-artige Felder (groupAllowFrom, dm.allowFrom, groups.<room>.users) akzeptieren vollständige Matrix-Benutzer-IDs (am sichersten). Exakte Verzeichnistreffer werden beim Start und immer dann aufgelöst, wenn sich die Allowlist ändert, während der Monitor läuft; Einträge, die nicht aufgelöst werden können, werden zur Laufzeit ignoriert. Raum-Allowlists sollten aus demselben Grund Raum-IDs oder Aliasse bevorzugen.

# Konto und Verbindung

• enabled: aktiviert oder deaktiviert den Kanal.
• name: optionale Anzeigebezeichnung für das Konto.
• defaultAccount: bevorzugte Konto-ID, wenn mehrere Matrix-Konten konfiguriert sind.
• accounts: benannte Überschreibungen pro Konto. Werte auf oberster Ebene unter channels.matrix werden als Standardwerte geerbt.
• homeserver: Homeserver-URL, zum Beispiel https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: erlaubt diesem Konto, Verbindungen zu localhost, LAN-/Tailscale-IPs oder internen Hostnamen herzustellen.
• proxy: optionale HTTP(S)-Proxy-URL für Matrix-Datenverkehr. Überschreibung pro Konto wird unterstützt.
• userId: vollständige Matrix-Benutzer-ID (@bot:example.org).
• accessToken: Zugriffstoken für tokenbasierte Authentifizierung. Klartext- und SecretRef-Werte werden über env/file/exec-Provider hinweg unterstützt (Geheimnisverwaltung).
• password: Passwort für passwortbasierte Anmeldung. Klartext- und SecretRef-Werte werden unterstützt.
• deviceId: explizite Matrix-Geräte-ID.
• deviceName: Geräteanzeigename, der bei der Passwortanmeldung verwendet wird.
• avatarUrl: gespeicherte eigene Avatar-URL für Profilsynchronisierung und profile set-Aktualisierungen.
• initialSyncLimit: maximale Anzahl von Ereignissen, die während der Startsynchronisierung abgerufen werden.

# Verschlüsselung

• encryption: aktiviert E2EE. Standard: false.
• startupVerification: "if-unverified" (Standard, wenn E2EE aktiviert ist) oder "off". Fordert beim Start automatisch eine Selbstverifizierung an, wenn dieses Gerät nicht verifiziert ist.
• startupVerificationCooldownHours: Wartezeit bis zur nächsten automatischen Startanforderung. Standard: 24.

# Zugriff und Richtlinie

• groupPolicy: "open", "allowlist" oder "disabled". Standard: "allowlist".
• groupAllowFrom: Allowlist von Benutzer-IDs für Raumdatenverkehr.
• dm.enabled: wenn false, alle DMs ignorieren. Standard: true.
• dm.policy: "pairing" (Standard), "allowlist", "open" oder "disabled". Gilt, nachdem der Bot dem Raum beigetreten ist und ihn als DM klassifiziert hat; dies beeinflusst die Behandlung von Einladungen nicht.
• dm.allowFrom: Allowlist von Benutzer-IDs für DM-Datenverkehr.
• dm.sessionScope: "per-user" (Standard) oder "per-room".
• dm.threadReplies: nur für DMs geltende Überschreibung für Antwort-Threading ("off", "inbound", "always").
• allowBots: Nachrichten von anderen konfigurierten Matrix-Bot-Konten akzeptieren (true oder "mentions").
• allowlistOnly: wenn true, erzwingt alle aktiven DM-Richtlinien (außer "disabled") und "open"-Gruppenrichtlinien auf "allowlist". Ändert keine "disabled"-Richtlinien.
• autoJoin: "always", "allowlist" oder "off". Standard: "off". Gilt für jede Matrix-Einladung, einschließlich DM-artiger Einladungen.
• autoJoinAllowlist: Räume/Aliasse, die erlaubt sind, wenn autoJoin "allowlist" ist. Alias-Einträge werden gegen den Homeserver aufgelöst, nicht gegen den vom eingeladenen Raum beanspruchten Zustand.
• contextVisibility: zusätzliche Kontextsichtbarkeit (Standard "all", "allowlist", "allowlist_quote").

# Antwortverhalten

• replyToMode: "off", "first", "all" oder "batched".
• threadReplies: "off", "inbound" oder "always".
• threadBindings: Überschreibungen pro Kanal für sitzungsgebundenes Routing und den Lebenszyklus von Threads.
• streaming: "off" (Standard), "partial", "quiet" oder Objektform { mode, preview: { toolProgress } }. true ↔ "partial", false ↔ "off".
• blockStreaming: wenn true, werden abgeschlossene Assistentenblöcke als separate Fortschrittsnachrichten beibehalten.
• markdown: optionale Markdown-Rendering-Konfiguration für ausgehenden Text.
• responsePrefix: optionale Zeichenfolge, die ausgehenden Antworten vorangestellt wird.
• textChunkLimit: Größe ausgehender Chunks in Zeichen, wenn chunkMode: "length". Standard: 4000.
• chunkMode: "length" (Standard, teilt nach Zeichenanzahl) oder "newline" (teilt an Zeilengrenzen).
• historyLimit: Anzahl der neuesten Raumnachrichten, die als InboundHistory einbezogen werden, wenn eine Raumnachricht den Agenten auslöst. Fällt auf messages.groupChat.historyLimit zurück; effektiver Standard 0 (deaktiviert).
• mediaMaxMb: Mediengrößenobergrenze in MB für ausgehende Sendungen und eingehende Verarbeitung.

# Reaktionseinstellungen

• ackReaction: Überschreibung der Bestätigungsreaktion für diesen Kanal/dieses Konto.
• ackReactionScope: Bereichsüberschreibung (Standard "group-mentions", "group-all", "direct", "all", "none", "off").
• reactionNotifications: Benachrichtigungsmodus für eingehende Reaktionen (Standard "own", "off").

# Werkzeuge und Überschreibungen pro Raum

• actions: Tool-Gating pro Aktion (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: Richtlinienzuordnung pro Raum. Die Sitzungsidentität verwendet nach der Auflösung die stabile Raum-ID. (rooms ist ein Legacy-Alias.)
  • groups.<room>.account: einen geerbten Raumeintrag auf ein bestimmtes Konto beschränken.
  • groups.<room>.allowBots: Überschreibung der Einstellung auf Kanalebene pro Raum (true oder "mentions").
  • groups.<room>.users: Absender-Allowlist pro Raum.
  • groups.<room>.tools: Tool-Zulassen/-Ablehnen-Überschreibungen pro Raum.
  • groups.<room>.autoReply: Überschreibung des Mention-Gatings pro Raum. true deaktiviert Erwähnungsanforderungen für diesen Raum; false erzwingt sie wieder.
  • groups.<room>.skills: Skills-Filter pro Raum.
  • groups.<room>.systemPrompt: System-Prompt-Ausschnitt pro Raum.

# Einstellungen für Exec-Genehmigungen

• execApprovals.enabled: Exec-Genehmigungen über Matrix-native Prompts zustellen.
• execApprovals.approvers: Matrix-Benutzer-IDs, die genehmigen dürfen. Fällt auf dm.allowFrom zurück.
• execApprovals.target: "dm" (Standard), "channel" oder "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: optionale Agenten-/Sitzungs-Allowlists für die Zustellung.

# Verwandte Themen

• Kanalübersicht - alle unterstützten Kanäle
• Pairing - DM-Authentifizierung und Pairing-Ablauf
• Gruppen - Gruppenchatverhalten und Mention-Gating
• Kanal-Routing - Sitzungsrouting für Nachrichten
• Sicherheit - Zugriffsmodell und Härtung