​

Matrix

​

Gebündeltes Plugin

openclaw plugins install @openclaw/matrix

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

​

Einrichtung

1. Stelle sicher, dass das Matrix-Plugin verfügbar ist.
   • Aktuelle paketierte OpenClaw-Releases enthalten es bereits gebündelt.
   • Ältere/benutzerdefinierte Installationen können es manuell mit den obigen Befehlen hinzufügen.
2. Erstelle ein Matrix-Konto auf deinem Homeserver.
3. Konfiguriere channels.matrix mit entweder:
   • homeserver + accessToken, oder
   • homeserver + userId + password.
4. Starte das Gateway neu.
5. Starte eine DM mit dem Bot oder lade ihn in einen Raum ein.
   • Neue Matrix-Einladungen funktionieren nur, wenn channels.matrix.autoJoin sie zulässt.

openclaw channels add
openclaw configure --section channels

• Homeserver-URL
• Authentifizierungsmethode: Access Token oder Passwort
• Benutzer-ID (nur bei Passwort-Authentifizierung)
• optionaler Gerätename
• ob E2EE aktiviert werden soll
• ob Raumzugriff und automatisches Beitreten zu Einladungen konfiguriert werden sollen

• Wenn Matrix-Auth-Umgebungsvariablen bereits vorhanden sind und für dieses Konto noch keine Authentifizierung in der Konfiguration gespeichert ist, bietet der Assistent eine Umgebungsvariablen-Verknüpfung an, um die Authentifizierung in Umgebungsvariablen zu belassen.
• Kontonamen werden zur Konto-ID normalisiert. Zum Beispiel wird Ops Bot zu ops-bot.
• DM-Allowlist-Einträge akzeptieren @user:server direkt; Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau einen Treffer findet.
• Raum-Allowlist-Einträge akzeptieren Raum-IDs und Aliase direkt. Bevorzuge !room:server oder #alias:server; nicht aufgelöste Namen werden zur Laufzeit von der Allowlist-Auflösung ignoriert.
• Im Allowlist-Modus für automatisches Beitreten zu Einladungen nur stabile Einladungsziele verwenden: !roomId:server, #alias:server oder *. Einfache Raumnamen werden abgelehnt.
• Um Raumnamen vor dem Speichern aufzulösen, verwende openclaw channels resolve --channel matrix "Project Room".

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

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

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

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

• 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

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

Konfigurationsbeispiel

{
  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

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

• streaming: "off" ist die Standardeinstellung. OpenClaw wartet auf die endgültige Antwort und sendet sie einmal.
• streaming: "partial" erstellt eine bearbeitbare Vorschau-Nachricht für den aktuellen Assistentenblock mit normalen Matrix-Textnachrichten. Dadurch bleibt das ältere benachrichtigungsorientierte Vorschau-zuerst-Verhalten von Matrix erhalten, sodass Standard-Clients möglicherweise beim ersten gestreamten Vorschautext statt beim fertigen Block benachrichtigen.
• streaming: "quiet" erstellt einen bearbeitbaren unauffälligen Vorschauhinweis für den aktuellen Assistentenblock. Verwende dies nur, wenn du zusätzlich Push-Regeln für Empfänger für abgeschlossene Vorschau-Bearbeitungen konfigurierst.
• blockStreaming: true aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und lässt abgeschlossene Blöcke als separate Nachrichten bestehen.
• Wenn Vorschau-Streaming aktiviert und blockStreaming deaktiviert ist, bearbeitet Matrix den Live-Entwurf an Ort und Stelle und schließt dasselbe Ereignis ab, wenn der Block oder Turn endet.
• Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Ereignis passt, beendet OpenClaw das Vorschau-Streaming und fällt auf normale endgültige Zustellung zurück.
• Medienantworten senden Anhänge weiterhin normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, entfernt OpenClaw sie vor dem Senden der endgültigen Medienantwort.
• Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lasse Streaming deaktiviert, wenn du das konservativste Rate-Limit-Verhalten möchtest.

• blockStreaming: true sendet jeden abgeschlossenen Block als normale benachrichtigende Matrix-Nachricht.
• blockStreaming: false sendet nur die endgültige abgeschlossene Antwort als normale benachrichtigende Matrix-Nachricht.

​

Selbstgehostete Push-Regeln für unauffällige abgeschlossene Vorschauen

• Empfängerbenutzer = die Person, die die Benachrichtigung erhalten soll
• Bot-Benutzer = das OpenClaw-Matrix-Konto, das die Antwort sendet
• verwende für die folgenden API-Aufrufe das Access Token des Empfängerbenutzers
• gleiche sender in der Push-Regel mit der vollständigen MXID des Bot-Benutzers ab

1. Konfiguriere OpenClaw so, dass unauffällige Vorschauen verwendet werden:

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

2. Stelle sicher, dass das Empfängerkonto bereits normale Matrix-Push-Benachrichtigungen erhält. Regeln für unauffällige Vorschauen funktionieren nur, wenn dieser Benutzer bereits funktionierende Pusher/Geräte hat.
3. Hole das Access Token des Empfängerbenutzers.
   • Verwende das Token des empfangenden Benutzers, nicht das Token des Bots.
   • Die Wiederverwendung eines vorhandenen Client-Sitzungstokens ist normalerweise am einfachsten.
   • Wenn du ein neues Token erzeugen musst, kannst du dich über die Standard-Matrix-Client-Server-API anmelden:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. Verifiziere, dass das Empfängerkonto bereits Pusher hat:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. Erstelle für jedes Empfängerkonto, das diese Benachrichtigungen erhalten soll, eine Override-Push-Regel:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: die Basis-URL deines Homeservers
• $USER_ACCESS_TOKEN: das Access Token des empfangenden Benutzers
• openclaw-finalized-preview-botname: eine Regel-ID, die für diesen Bot bei diesem empfangenden Benutzer eindeutig ist
• @bot:example.org: die MXID deines OpenClaw-Matrix-Bots, nicht die MXID des empfangenden Benutzers

• Push-Regeln werden über ruleId referenziert. Ein erneutes PUT mit derselben Regel-ID aktualisiert diese eine Regel.
• Wenn ein empfangender Benutzer für mehrere OpenClaw-Matrix-Bot-Konten benachrichtigt werden soll, erstelle eine Regel pro Bot mit einer eindeutigen Regel-ID für jede sender-Übereinstimmung.
• Ein einfaches Muster ist openclaw-finalized-preview-<botname>, zum Beispiel openclaw-finalized-preview-ops oder openclaw-finalized-preview-support.

• authentifiziere dich mit dem Token des empfangenden Benutzers
• gleiche sender mit der MXID des OpenClaw-Bots ab

6. Verifiziere, dass die Regel existiert:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. Teste eine gestreamte Antwort. Im leisen Modus sollte der Raum eine leise Entwurfsvorschau anzeigen und die endgültige Bearbeitung an Ort und Stelle sollte benachrichtigen, sobald der Block oder Turn abgeschlossen ist.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• Erstelle die Regel mit dem Access Token des empfangenden Benutzers, nicht mit dem Token des Bots.
• Neue benutzerdefinierte override-Regeln werden vor den standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Reihenfolgeparameter erforderlich.
• Dies betrifft nur Vorschau-Bearbeitungen nur mit Text, die OpenClaw sicher an Ort und Stelle abschließen kann. Medien-Fallbacks und Fallbacks für veraltete Vorschauen verwenden weiterhin die normale Matrix-Zustellung.
• Wenn GET /_matrix/client/v3/pushers keine Pusher anzeigt, hat der Benutzer für dieses Konto/Gerät noch keine funktionierende Matrix-Push-Zustellung.

​

Synapse

• Es ist keine spezielle Änderung an homeserver.yaml für abgeschlossene OpenClaw-Vorschau-Benachrichtigungen erforderlich.
• Wenn deine Synapse-Bereitstellung bereits normale Matrix-Push-Benachrichtigungen sendet, sind das Benutzertoken und der obige pushrules-Aufruf der wichtigste Einrichtungsschritt.
• Wenn du Synapse hinter einem Reverse-Proxy oder mit Workern betreibst, stelle sicher, dass /_matrix/client/.../pushrules/ Synapse korrekt erreicht.
• Wenn du Synapse-Worker betreibst, stelle sicher, dass die Pusher fehlerfrei arbeiten. Die Push-Zustellung wird vom Hauptprozess oder von synapse.app.pusher / konfigurierten Pusher-Workern übernommen.

​

Tuwunel

• Für die Markierung der abgeschlossenen Vorschau selbst ist keine Tuwunel-spezifische Konfiguration erforderlich.
• Wenn normale Matrix-Benachrichtigungen für diesen Benutzer bereits funktionieren, sind das Benutzertoken und der obige pushrules-Aufruf der wichtigste Einrichtungsschritt.
• Wenn Benachrichtigungen zu verschwinden scheinen, während der Benutzer auf einem anderen Gerät aktiv ist, prüfe, ob suppress_push_when_active aktiviert ist. Tuwunel hat diese Option in Tuwunel 1.4.2 am 12. September 2025 hinzugefügt, und sie kann Pushes an andere Geräte absichtlich unterdrücken, während ein Gerät aktiv ist.

​

Bot-zu-Bot-Räume

{
  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 in Räumen nur dann, wenn sie diesen Bot sichtbar erwähnen. DMs sind weiterhin erlaubt.
• groups.<room>.allowBots überschreibt die Einstellung auf Kontoebene für einen einzelnen Raum.
• OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Schleifen durch Selbstantworten zu vermeiden.
• Matrix bietet hier kein natives Bot-Flag; OpenClaw behandelt „von Bots verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“.

​

Verschlüsselung und Verifizierung

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

openclaw matrix verify status

openclaw matrix verify status --verbose

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

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

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

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

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

openclaw matrix verify backup status

openclaw matrix verify backup status --verbose

openclaw matrix verify backup restore

openclaw matrix verify backup restore --verbose

openclaw matrix verify backup reset --yes

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

​

Was „verifiziert“ bedeutet

• Locally trusted: Dieses Gerät ist nur durch den aktuellen Client als vertrauenswürdig markiert
• 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-Schlüssel signiert

​

Was Bootstrap macht

• initialisiert den Secret Storage und verwendet nach Möglichkeit einen vorhandenen Wiederherstellungsschlüssel erneut
• initialisiert Cross-Signing und lädt fehlende öffentliche Cross-Signing-Schlüssel hoch
• versucht, das aktuelle Gerät zu markieren und per Cross-Signing zu signieren
• erstellt ein neues serverseitiges Raumschlüssel-Backup, falls noch keines existiert

​

Neue Backup-Basis

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

​

Startverhalten

​

Verifizierungshinweise

• Hinweise zu Verifizierungsanfragen
• Hinweise zur Verifizierungsbereitschaft (mit ausdrücklichem Hinweis „Per Emoji verifizieren“)
• Hinweise zum Start und Abschluss der Verifizierung
• SAS-Details (Emoji und Dezimalzahl), wenn verfügbar

​

Gerätehygiene

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Crypto-Store

​

Profilverwaltung

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

​

Threads

• dm.sessionScope: "per-user" (Standard) hält das DM-Routing in Matrix absenderspezifisch, sodass mehrere DM-Räume eine Sitzung gemeinsam nutzen können, wenn sie zum selben Peer aufgelöst werden.
• dm.sessionScope: "per-room" isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel und verwendet dabei weiterhin normale DM-Authentifizierungs- und Allowlist-Prüfungen.
• Explizite Matrix-Konversations-Bindings haben weiterhin Vorrang vor dm.sessionScope, sodass gebundene Räume und Threads ihre gewählte Zielsitzung beibehalten.
• threadReplies: "off" hält Antworten auf der obersten Ebene und behält eingehende Thread-Nachrichten in der übergeordneten Sitzung.
• threadReplies: "inbound" antwortet innerhalb eines Threads nur dann, wenn die eingehende Nachricht bereits in diesem Thread war.
• threadReplies: "always" hält Raumantworten in einem Thread mit der auslösenden Nachricht als Wurzel und leitet diese Konversation ab der ersten auslösenden Nachricht über die passende threadbezogene Sitzung.
• dm.threadReplies überschreibt die Einstellung auf oberster Ebene nur für DMs. So kannst du zum Beispiel Raum-Threads isoliert halten und DMs flach halten.
• Eingehende Thread-Nachrichten enthalten die Thread-Wurzel-Nachricht als zusätzlichen Agent-Kontext.
• Sendungen über Message-Tools übernehmen den aktuellen Matrix-Thread automatisch, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, sofern kein explizites threadId angegeben wird.
• Die Wiederverwendung desselben sitzungsbezogenen DM-Benutzerziels greift nur, wenn die Metadaten der aktuellen Sitzung denselben DM-Peer im selben Matrix-Konto nachweisen; andernfalls fällt OpenClaw auf normales benutzerbezogenes Routing zurück.
• Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum in derselben gemeinsamen Matrix-DM-Sitzung kollidiert, veröffentlicht es in diesem Raum einmalig ein m.notice mit dem /focus-Ausweg, wenn Thread-Bindings aktiviert sind, sowie dem Hinweis dm.sessionScope.
• Laufzeit-Thread-Bindings werden für Matrix unterstützt. /focus, /unfocus, /agents, /session idle, /session max-age und threadgebundenes /acp spawn funktionieren in Matrix-Räumen und DMs.
• /focus auf oberster Ebene in Matrix-Räumen/DMs erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn threadBindings.spawnSubagentSessions=true.
• Wenn /focus oder /acp spawn --thread here innerhalb eines vorhandenen Matrix-Threads ausgeführt wird, bindet dies stattdessen diesen aktuellen Thread.

​

ACP-Konversations-Bindings

• Führe /acp spawn codex --bind here innerhalb der Matrix-DM, des Raums oder des vorhandenen Threads aus, den du weiterverwenden möchtest.
• In einer Matrix-DM oder einem Matrix-Raum auf oberster Ebene bleibt die aktuelle DM/der aktuelle Raum die Chat-Oberfläche, und zukünftige Nachrichten werden an die erzeugte ACP-Sitzung weitergeleitet.
• Innerhalb eines vorhandenen 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.

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

​

Thread-Binding-Konfiguration

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

• Setze threadBindings.spawnSubagentSessions: true, um zuzulassen, dass /focus auf oberster Ebene neue Matrix-Threads erstellt und bindet.
• Setze threadBindings.spawnAcpSessions: true, um zuzulassen, dass /acp spawn --thread auto|here ACP-Sitzungen an Matrix-Threads bindet.

​

Reaktionen

• Tooling für ausgehende Reaktionen wird durch channels["matrix"].actions.reactions gesteuert.
• react fügt einem bestimmten Matrix-Ereignis eine Reaktion hinzu.
• reactions listet die aktuelle Reaktionszusammenfassung für ein bestimmtes Matrix-Ereignis auf.
• emoji="" entfernt die eigenen Reaktionen des Bot-Kontos auf diesem Ereignis.
• remove: true entfernt nur die angegebene Emoji-Reaktion vom Bot-Konto.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• Emoji-Fallback der Agent-Identität

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

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

• reactionNotifications: "own" leitet hinzugefügte m.reaction-Ereignisse weiter, wenn sie sich auf vom Bot verfasste Matrix-Nachrichten beziehen.
• reactionNotifications: "off" deaktiviert Reaktions-Systemereignisse.
• Das Entfernen von Reaktionen wird nicht zu Systemereignissen synthetisiert, da Matrix diese als Redaktionen und nicht als eigenständige Entfernungen von m.reaction darstellt.

​

Verlaufs-Kontext

• 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. Setze 0, um dies zu deaktivieren.
• Der Verlauf von Matrix-Räumen ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf.
• Der Verlauf von Matrix-Räumen ist nur für ausstehende Nachrichten: 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ösende Nachricht ist nicht in InboundHistory enthalten; sie bleibt für diesen Turn im Hauptteil der eingehenden Nachricht.
• Wiederholungsversuche desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot wieder, anstatt auf neuere Raumnachrichten weiterzudriften.

​

Kontextsichtbarkeit

• contextVisibility: "all" ist der Standard. Ergänzender Kontext bleibt wie empfangen erhalten.
• contextVisibility: "allowlist" filtert ergänzenden Kontext auf Absender, die durch die aktiven Raum-/Benutzer-Allowlist-Prüfungen zugelassen sind.
• contextVisibility: "allowlist_quote" verhält sich wie allowlist, behält aber dennoch eine explizit zitierte Antwort bei.

​

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

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

Reparatur direkter Räume

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

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

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

​

Exec-Genehmigungen

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (optional; fällt auf channels.matrix.dm.allowFrom zurück)
• channels.matrix.execApprovals.target (dm | channel | both, Standard: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.* steuert den nativen DM-/Channel-Fanout-Modus für Matrix-Genehmigungsaufforderungen.
• Exec-Genehmigungen verwenden die Menge der Exec-Genehmiger aus execApprovals.approvers oder channels.matrix.dm.allowFrom.
• Plugin-Genehmigungen verwenden die DM-Allowlist von Matrix aus channels.matrix.dm.allowFrom.
• Matrix-Reaktionskürzel und Nachrichtenaktualisierungen gelten sowohl für Exec- als auch für Plugin-Genehmigungen.

• target: "dm" sendet Genehmigungsaufforderungen an Genehmiger-DMs
• target: "channel" sendet die Aufforderung zurück an den auslösenden Matrix-Raum oder die auslösende DM
• target: "both" sendet an Genehmiger-DMs und an den auslösenden Matrix-Raum oder die auslösende DM

• ✅ = einmal erlauben
• ❌ = ablehnen
• ♾️ = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Richtlinie zulässig ist

• channels.matrix.accounts.<account>.execApprovals

​

Multi-Account

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

​

Private/LAN-Homeserver

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

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

​

Matrix-Verkehr über einen Proxy leiten

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

​

Zielauflösung

• 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

• Benutzersuchen fragen das Matrix-Benutzerverzeichnis auf diesem Homeserver ab.
• Raumsuchen akzeptieren explizite Raum-IDs und Aliasse direkt und fallen dann auf die Suche nach beigetretenen Raumnamen für dieses Konto zurück.
• Die Suche nach Namen beigetretener Räume erfolgt nach bestem Bemühen. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeit-Allowlist-Auflösung ignoriert.

​

Konfigurationsreferenz

• enabled: den Channel aktivieren oder deaktivieren.
• name: optionales Label für das Konto.
• defaultAccount: bevorzugte Konto-ID, wenn mehrere Matrix-Konten konfiguriert sind.
• homeserver: Homeserver-URL, zum Beispiel https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: erlaubt diesem Matrix-Konto, sich mit privaten/internen Homeservern zu verbinden. Aktiviere dies, wenn der Homeserver zu localhost, einer LAN-/Tailscale-IP oder einem internen Host wie matrix-synapse aufgelöst wird.
• proxy: optionale HTTP(S)-Proxy-URL für Matrix-Verkehr. Benannte Konten können den Standardwert auf oberster Ebene mit ihrem eigenen proxy überschreiben.
• userId: vollständige Matrix-Benutzer-ID, zum Beispiel @bot:example.org.
• accessToken: Access Token für tokenbasierte Authentifizierung. Klartextwerte und SecretRef-Werte werden für channels.matrix.accessToken und channels.matrix.accounts.<id>.accessToken über env-/file-/exec-Provider unterstützt. Siehe Secrets Management.
• password: Passwort für passwortbasierte Anmeldung. Klartextwerte und SecretRef-Werte werden unterstützt.
• deviceId: explizite Matrix-Geräte-ID.
• deviceName: Anzeigename des Geräts für Passwort-Login.
• avatarUrl: gespeicherte Selbst-Avatar-URL für Profilsynchronisierung und profile set-Aktualisierungen.
• initialSyncLimit: maximale Anzahl von Ereignissen, die während der Start-Synchronisierung abgerufen werden.
• encryption: E2EE aktivieren.
• allowlistOnly: wenn true, wird die Raumrichtlinie open auf allowlist hochgestuft und alle aktiven DM-Richtlinien außer disabled (einschließlich pairing und open) werden zu allowlist gezwungen. Wirkt sich nicht auf disabled-Richtlinien aus.
• allowBots: Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten erlauben (true oder "mentions").
• groupPolicy: open, allowlist oder disabled.
• contextVisibility: Sichtbarkeitsmodus für ergänzenden Raumkontext (all, allowlist, allowlist_quote).
• groupAllowFrom: Allowlist von Benutzer-IDs für Raumverkehr. Einträge sollten vollständige Matrix-Benutzer-IDs sein; nicht aufgelöste Namen werden zur Laufzeit ignoriert.
• historyLimit: maximale Anzahl von Raumnachrichten, die als Gruppenverlaufs-Kontext einbezogen werden. Fällt auf messages.groupChat.historyLimit zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert 0. Setze 0, um dies zu deaktivieren.
• replyToMode: off, first, all oder batched.
• markdown: optionale Markdown-Rendering-Konfiguration für ausgehenden Matrix-Text.
• streaming: off (Standard), "partial", "quiet", true oder false. "partial" und true aktivieren Vorschau-zuerst-Entwurfsaktualisierungen mit normalen Matrix-Textnachrichten. "quiet" verwendet nicht benachrichtigende Vorschauhinweise für selbstgehostete Push-Regel-Setups. false entspricht "off".
• blockStreaming: true aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistentenblöcke, während Entwurfsvorschau-Streaming aktiv ist.
• threadReplies: off, inbound oder always.
• threadBindings: kanalbezogene Overrides für threadgebundenes Sitzungsrouting und Lebenszyklus.
• startupVerification: Modus für automatische Selbstverifizierungsanforderungen beim Start (if-unverified, off).
• startupVerificationCooldownHours: Abklingzeit vor einem erneuten Versuch automatischer Start-Verifizierungsanforderungen.
• textChunkLimit: Größe ausgehender Nachrichten-Chunks in Zeichen (gilt, wenn chunkMode length ist).
• chunkMode: length teilt Nachrichten nach Zeichenzahl; newline teilt an Zeilengrenzen.
• responsePrefix: optionale Zeichenfolge, die allen ausgehenden Antworten für diesen Channel vorangestellt wird.
• ackReaction: optionaler Override für Bestätigungsreaktionen für diesen Channel/dieses Konto.
• ackReactionScope: optionaler Override für den Geltungsbereich von Bestätigungsreaktionen (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: Modus für eingehende Reaktionsbenachrichtigungen (own, off).
• mediaMaxMb: Größenlimit für Medien in MB für ausgehende Sendungen und eingehende Medienverarbeitung.
• autoJoin: Richtlinie für automatisches Beitreten zu Einladungen (always, allowlist, off). Standard: off. Gilt für alle Matrix-Einladungen, einschließlich DM-ähnlicher Einladungen.
• autoJoinAllowlist: Räume/Aliasse, die erlaubt sind, wenn autoJoin auf allowlist gesetzt ist. Alias-Einträge werden während der Einladungsverarbeitung zu Raum-IDs aufgelöst; OpenClaw vertraut keinem Alias-Status, den der eingeladene Raum behauptet.
• dm: DM-Richtlinienblock (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: steuert den DM-Zugriff, nachdem OpenClaw dem Raum beigetreten ist und ihn als DM klassifiziert hat. Ändert nicht, ob einer Einladung automatisch beigetreten wird.
• dm.allowFrom: Einträge sollten vollständige Matrix-Benutzer-IDs sein, es sei denn, du hast sie bereits über die Live-Verzeichnissuche aufgelöst.
• dm.sessionScope: per-user (Standard) oder per-room. Verwende per-room, wenn du möchtest, dass jeder Matrix-DM-Raum einen getrennten Kontext behält, selbst wenn der Peer derselbe ist.
• dm.threadReplies: DM-spezifischer Override für Thread-Richtlinien (off, inbound, always). Überschreibt die Einstellung threadReplies auf oberster Ebene sowohl für die Platzierung von Antworten als auch für die Sitzungsisolierung in DMs.
• execApprovals: Matrix-native Zustellung von Exec-Genehmigungen (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: Matrix-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Optional, wenn dm.allowFrom die Genehmiger bereits identifiziert.
• execApprovals.target: dm | channel | both (Standard: dm).
• accounts: benannte kontoabhängige Overrides. Werte auf oberster Ebene unter channels.matrix dienen als Standardwerte für diese Einträge.
• groups: raumbezogene Richtlinienzuordnung. Bevorzuge Raum-IDs oder Aliasse; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID.
• groups.<room>.account: beschränkt einen geerbten Raumeintrag in Multi-Account-Setups auf ein bestimmtes Matrix-Konto.
• groups.<room>.allowBots: raumbezogener Override für Absender aus konfigurierten Bots (true oder "mentions").
• groups.<room>.users: absenderbezogene Allowlist pro Raum.
• groups.<room>.tools: raumbezogene Tool-Allow-/Deny-Overrides.
• groups.<room>.autoReply: raumbezogener Override für Erwähnungs-Gating. true deaktiviert Erwähnungspflichten für diesen Raum; false erzwingt sie wieder.
• groups.<room>.skills: optionaler raumbezogener Skills-Filter.
• groups.<room>.systemPrompt: optionaler raumbezogener System-Prompt-Ausschnitt.
• rooms: Legacy-Alias für groups.
• actions: Tool-Gating pro Aktion (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

Verwandt

• Channels Overview — alle unterstützten Channels
• Pairing — DM-Authentifizierung und Pairing-Ablauf
• Groups — Verhalten in Gruppenchats und Erwähnungs-Gating
• Channel Routing — Sitzungsrouting für Nachrichten
• Security — Zugriffsmodell und Härtung