Matrix (Plugin)

Matrix ist ein offenes, dezentrales Messaging-Protokoll. OpenClaw verbindet sich als Matrix-Benutzer auf einem beliebigen Homeserver, sodass du ein Matrix-Konto für den Bot benötigst. Nach dem Login kannst du dem Bot direkt schreiben oder ihn in Räume einladen (Matrix-„Gruppen”). Beeper ist ebenfalls eine gültige Client-Option, erfordert aber aktivierte E2EE.

Status: Unterstützt via Plugin (@vector-im/matrix-bot-sdk). Direktnachrichten, Räume, Threads, Medien, Reaktionen, Umfragen (Senden + Poll-Start als Text), Standort und E2EE (mit Krypto-Unterstützung).

Plugin erforderlich

Matrix wird als Plugin ausgeliefert und ist nicht in der Kerninstallation enthalten.

Installation über CLI (npm-Registry):

openclaw plugins install @openclaw/matrix

Lokaler Checkout (wenn aus einem Git-Repo ausgeführt):

openclaw plugins install ./extensions/matrix

Wenn du Matrix während der Konfiguration/des Onboardings auswählst und ein Git-Checkout erkannt wird, bietet OpenClaw automatisch den lokalen Installationspfad an.

Details: Plugins

Einrichtung

Installiere das Matrix-Plugin:
- Von npm: openclaw plugins install @openclaw/matrix
- Aus einem lokalen Checkout: openclaw plugins install ./extensions/matrix
Erstelle ein Matrix-Konto auf einem Homeserver:
- Hosting-Optionen unter https://matrix.org/ecosystem/hosting/
- Oder betreibe deinen eigenen.
Hole einen Access Token für das Bot-Konto:
- Verwende die Matrix-Login-API mit curl an deinem Homeserver:
```
curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
```
- Ersetze matrix.example.org durch deine Homeserver-URL.
- Oder setze channels.matrix.userId + channels.matrix.password: OpenClaw ruft denselben Login-Endpunkt auf, speichert den Access Token in ~/.openclaw/credentials/matrix/credentials.json und verwendet ihn beim nächsten Start wieder.
Zugangsdaten konfigurieren:
- Umgebungsvariablen: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (oder MATRIX_USER_ID + MATRIX_PASSWORD)
- Oder Konfiguration: channels.matrix.*
- Wenn beides gesetzt ist, hat die Konfiguration Vorrang.
- Mit Access Token: Die Benutzer-ID wird automatisch via /whoami abgerufen.
- Wenn gesetzt, sollte channels.matrix.userId die vollständige Matrix-ID sein (Beispiel: @bot:example.org).
Starte das Gateway neu (oder schließe das Onboarding ab).
Starte eine DM mit dem Bot oder lade ihn aus einem Matrix-Client in einen Raum ein (Element, Beeper usw.; siehe https://matrix.org/ecosystem/clients/). Beeper erfordert E2EE, also setze channels.matrix.encryption: true und verifiziere das Gerät.

Minimale Konfiguration (Access Token, Benutzer-ID automatisch abgerufen):

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

E2EE-Konfiguration (Ende-zu-Ende-Verschlüsselung aktiviert):

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

Verschlüsselung (E2EE)

Ende-zu-Ende-Verschlüsselung wird über das Rust-Krypto-SDK unterstützt.

Aktiviere mit channels.matrix.encryption: true:

Wenn das Krypto-Modul geladen wird, werden verschlüsselte Räume automatisch entschlüsselt.
Ausgehende Medien werden beim Senden in verschlüsselte Räume verschlüsselt.
Bei der ersten Verbindung fordert OpenClaw eine Geräteverifizierung von deinen anderen Sessions an.
Verifiziere das Gerät in einem anderen Matrix-Client (Element usw.), um Key-Sharing zu ermöglichen.
Wenn das Krypto-Modul nicht geladen werden kann, wird E2EE deaktiviert und verschlüsselte Räume werden nicht entschlüsselt; OpenClaw protokolliert eine Warnung.
Wenn du Fehler wegen fehlendem Krypto-Modul siehst (z. B. @matrix-org/matrix-sdk-crypto-nodejs-*), erlaube Build-Skripte für @matrix-org/matrix-sdk-crypto-nodejs und führe pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs aus oder hole das Binary mit node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Der Krypto-Status wird pro Konto + Access Token gespeichert in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite-Datenbank). Der Sync-Status liegt daneben in bot-storage.json. Wenn sich der Access Token (Gerät) ändert, wird ein neuer Store erstellt und der Bot muss für verschlüsselte Räume erneut verifiziert werden.

Geräteverifizierung: Wenn E2EE aktiviert ist, fordert der Bot beim Start eine Verifizierung von deinen anderen Sessions an. Öffne Element (oder einen anderen Client) und genehmige die Verifizierungsanfrage, um Vertrauen herzustellen. Nach der Verifizierung kann der Bot Nachrichten in verschlüsselten Räumen entschlüsseln.

Multi-Account

Multi-Account-Unterstützung: Verwende channels.matrix.accounts mit Pro-Konto-Zugangsdaten und optionalem name. Siehe gateway/configuration für das gemeinsame Muster.

Jedes Konto läuft als separater Matrix-Benutzer auf einem beliebigen Homeserver. Pro-Konto-Konfiguration erbt von den Top-Level-channels.matrix-Einstellungen und kann jede Option überschreiben (DM-Richtlinie, Gruppen, Verschlüsselung usw.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Hinweise:

Der Konto-Start ist serialisiert, um Race-Conditions bei gleichzeitigen Modulimporten zu vermeiden.
Umgebungsvariablen (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN usw.) gelten nur für das Standard-Konto.
Basis-Kanaleinstellungen (DM-Richtlinie, Gruppenrichtlinie, Mention-Gating usw.) gelten für alle Konten, sofern nicht pro Konto überschrieben.
Verwende bindings[].match.accountId, um jedes Konto einem anderen Agent zuzuordnen.
Der Krypto-Status wird pro Konto + Access Token gespeichert (separate Key-Stores pro Konto).

Routing-Modell

Antworten gehen immer zurück zu Matrix.
DMs teilen die Haupt-Session des Agenten; Räume werden auf Gruppen-Sessions abgebildet.

Zugriffssteuerung (DMs)

Standard: channels.matrix.dm.policy = "pairing". Unbekannte Absender erhalten einen Pairing-Code.
Genehmigung über:
- openclaw pairing list matrix
- openclaw pairing approve matrix <CODE>
Öffentliche DMs: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
channels.matrix.dm.allowFrom akzeptiert vollständige Matrix-Benutzer-IDs (Beispiel: @user:server). Der Assistent löst Anzeigenamen zu Benutzer-IDs auf, wenn die Verzeichnissuche eine einzelne exakte Übereinstimmung findet.
Verwende keine Anzeigenamen oder bloße Localparts (Beispiel: "Alice" oder "alice"). Sie sind mehrdeutig und werden beim Allowlist-Matching ignoriert. Verwende vollständige @user:server-IDs.

Räume (Gruppen)

Standard: channels.matrix.groupPolicy = "allowlist" (Mention-gated). Verwende channels.defaults.groupPolicy, um den Standard zu überschreiben, wenn nicht gesetzt.
Laufzeithinweis: Wenn channels.matrix vollständig fehlt, fällt die Laufzeit für Raumprüfungen auf groupPolicy="allowlist" zurück (auch wenn channels.defaults.groupPolicy gesetzt ist).
Räume auf die Allowlist setzen mit channels.matrix.groups (Raum-IDs oder Aliase; Namen werden zu IDs aufgelöst, wenn die Verzeichnissuche eine einzelne exakte Übereinstimmung findet):

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

requireMention: false aktiviert automatische Antworten in diesem Raum.
groups."*" kann Standards für Mention-Gating über Räume hinweg setzen.
groupAllowFrom schränkt ein, welche Absender den Bot in Räumen auslösen können (vollständige Matrix-Benutzer-IDs).
Pro-Raum-users-Allowlists können Absender innerhalb eines bestimmten Raums weiter einschränken (verwende vollständige Matrix-Benutzer-IDs).
Der Konfigurationsassistent fragt nach Raum-Allowlists (Raum-IDs, Aliase oder Namen) und löst Namen nur bei einer exakten, eindeutigen Übereinstimmung auf.
Beim Start löst OpenClaw Raum-/Benutzernamen in Allowlists zu IDs auf und protokolliert die Zuordnung; nicht aufgelöste Einträge werden beim Allowlist-Matching ignoriert.
Einladungen werden standardmäßig automatisch angenommen; steuere mit channels.matrix.autoJoin und channels.matrix.autoJoinAllowlist.
Um keine Räume zu erlauben, setze channels.matrix.groupPolicy: "disabled" (oder behalte eine leere Allowlist).
Legacy-Schlüssel: channels.matrix.rooms (gleiche Struktur wie groups).

Threads

Antwort-Threading wird unterstützt.
channels.matrix.threadReplies steuert, ob Antworten in Threads bleiben:
- off, inbound (Standard), always
channels.matrix.replyToMode steuert Reply-to-Metadaten, wenn nicht in einem Thread geantwortet wird:
- off (Standard), first, all

Fähigkeiten

Feature	Status
Direktnachrichten	Unterstützt
Räume	Unterstützt
Threads	Unterstützt
Medien	Unterstützt
E2EE	Unterstützt (Krypto-Modul erforderlich)
Reaktionen	Unterstützt (Senden/Lesen via Tools)
Umfragen	Senden unterstützt; eingehende Poll-Starts werden in Text konvertiert (Antworten/Ende ignoriert)
Standort	Unterstützt (Geo-URI; Höhe wird ignoriert)
Native Befehle	Unterstützt

Fehlerbehebung

Führe zuerst diese Befehle aus:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Dann bestätige bei Bedarf den DM-Pairing-Status:

openclaw pairing list matrix

Häufige Fehler:

Eingeloggt, aber Raumnachrichten ignoriert: Raum durch groupPolicy oder Raum-Allowlist blockiert.
DMs ignoriert: Absender wartet auf Genehmigung, wenn channels.matrix.dm.policy="pairing".
Verschlüsselte Räume schlagen fehl: Krypto-Unterstützung oder Verschlüsselungseinstellungen passen nicht.

Für den Triage-Ablauf: /channels/troubleshooting.

Konfigurationsreferenz (Matrix)

Vollständige Konfiguration: Configuration

Provider-Optionen:

channels.matrix.enabled: Kanal-Start aktivieren/deaktivieren.
channels.matrix.homeserver: Homeserver-URL.
channels.matrix.userId: Matrix-Benutzer-ID (optional mit Access Token).
channels.matrix.accessToken: Access Token.
channels.matrix.password: Passwort für Login (Token wird gespeichert).
channels.matrix.deviceName: Geräte-Anzeigename.
channels.matrix.encryption: E2EE aktivieren (Standard: false).
channels.matrix.initialSyncLimit: Initiales Sync-Limit.
channels.matrix.threadReplies: off | inbound | always (Standard: inbound).
channels.matrix.textChunkLimit: Ausgehende Textblockgröße (Zeichen).
channels.matrix.chunkMode: length (Standard) oder newline, um an Leerzeilen (Absatzgrenzen) vor dem Längen-Chunking aufzuteilen.
channels.matrix.dm.policy: pairing | allowlist | open | disabled (Standard: pairing).
channels.matrix.dm.allowFrom: DM-Allowlist (vollständige Matrix-Benutzer-IDs). open erfordert "*". Der Assistent löst Namen zu IDs auf, wenn möglich.
channels.matrix.groupPolicy: allowlist | open | disabled (Standard: allowlist).
channels.matrix.groupAllowFrom: Erlaubte Absender für Gruppennachrichten (vollständige Matrix-Benutzer-IDs).
channels.matrix.allowlistOnly: Allowlist-Regeln für DMs + Räume erzwingen.
channels.matrix.groups: Gruppen-Allowlist + Pro-Raum-Einstellungs-Map.
channels.matrix.rooms: Legacy-Gruppen-Allowlist/-Konfiguration.
channels.matrix.replyToMode: Reply-to-Modus für Threads/Tags.
channels.matrix.mediaMaxMb: Medien-Obergrenze ein-/ausgehend (MB).
channels.matrix.autoJoin: Einladungsbehandlung (always | allowlist | off, Standard: always).
channels.matrix.autoJoinAllowlist: Erlaubte Raum-IDs/Aliase für Auto-Join.
channels.matrix.accounts: Multi-Account-Konfiguration nach Konto-ID (jedes Konto erbt Top-Level-Einstellungen).
channels.matrix.actions: Pro-Aktions-Tool-Gating (Reaktionen/Nachrichten/Pins/memberInfo/channelInfo).