Matrix (Plugin)

Matrix ist ein offenes, dezentrales Messaging-Protokoll. OpenClaw verbindet sich als Matrix-Benutzer auf einem beliebigen Homeserver, daher benötigen Sie ein Matrix-Konto für den Bot. Nach der Anmeldung können Sie dem Bot direkt eine DM schicken oder ihn in Räume (Matrix-„Gruppen“) einladen. Beeper ist ebenfalls eine gültige Client-Option, erfordert aber aktivierte E2EE. Status: unterstützt über 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) werden unterstützt.

Plugin erforderlich

Matrix wird als Plugin ausgeliefert und ist nicht im Core-Install enthalten. Installation über CLI (npm-Registry):


openclaw plugins install @openclaw/matrix

Lokaler Checkout (bei Ausführung aus einem Git-Repo):


openclaw plugins install ./extensions/matrix

Wenn Sie während configure/onboarding Matrix wählen und ein Git-Checkout erkannt wird, bietet OpenClaw den lokalen Installationspfad automatisch an. Details: Plugins

Einrichtung

Matrix-Plugin installieren:
- Von npm: openclaw plugins install @openclaw/matrix
- Aus lokalem Checkout: openclaw plugins install ./extensions/matrix
Matrix-Konto auf einem Homeserver erstellen:
- Hosting-Optionen unter https://matrix.org/ecosystem/hosting/ ansehen
- Oder selbst hosten.
Access Token für das Bot-Konto besorgen:
- Matrix-Login-API mit curl auf Ihrem Home-Server nutzen:


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"
}'

matrix.example.org durch Ihre Homeserver-URL ersetzen.
Oder channels.matrix.userId + channels.matrix.password setzen: OpenClaw ruft denselben Login-Endpunkt auf, speichert den Access Token in ~/.clawdbot/credentials/matrix/credentials.json und nutzt ihn beim nächsten Start wieder.

Anmeldedaten konfigurieren:
- Umgebung: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (oder MATRIX_USER_ID + MATRIX_PASSWORD)
- Oder Konfig: channels.matrix.*
- Wenn beide gesetzt sind, hat Konfiguration Vorrang.
- Mit Access Token: Benutzer-ID wird automatisch über /whoami abgerufen.
- Wenn gesetzt, sollte channels.matrix.userId die vollständige Matrix-ID sein (Beispiel: @bot:example.org).
Gateway neu starten (oder Onboarding abschließen).
DM mit dem Bot starten oder ihn aus einem Matrix-Client (Element, Beeper usw.; siehe https://matrix.org/ecosystem/clients/ ) in einen Raum einladen. Beeper erfordert E2EE, also channels.matrix.encryption: true setzen und das Gerät verifizieren.

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-Crypto-SDK unterstützt. Aktivieren mit channels.matrix.encryption: true:

Wenn das Crypto-Modul lädt, 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 Geräteverifizierung von Ihren anderen Sitzungen an.
Gerät in einem anderen Matrix-Client (Element usw.) verifizieren, um Schlüsselaustausch zu aktivieren.
Wenn das Crypto-Modul nicht geladen werden kann, ist E2EE deaktiviert und verschlüsselte Räume werden nicht entschlüsselt; OpenClaw protokolliert eine Warnung.
Bei fehlenden Crypto-Modul-Fehlern (z. B. @matrix-org/matrix-sdk-crypto-nodejs-*) Build-Skripte für @matrix-org/matrix-sdk-crypto-nodejs erlauben und pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs ausführen oder das Binary mit node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js abrufen.

Crypto-Zustand wird pro Konto + Access Token in ~/.clawdbot/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite-Datenbank) gespeichert. Sync-Zustand daneben in bot-storage.json. Bei geändertem Access Token (Gerät) 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 die Verifizierung von Ihren anderen Sitzungen an. Element (oder einen anderen Client) öffnen und die Verifizierungsanfrage bestätigen, um Vertrauen herzustellen. Nach der Verifizierung kann der Bot Nachrichten in verschlüsselten Räumen entschlüsseln.

Routing-Modell

Antworten gehen immer zurück zu Matrix.
DMs teilen die Hauptsitzung des Agenten; Räume werden Gruppen-Sitzungen zugeordnet.

Zugriffskontrolle (DMs)

Standard: channels.matrix.dm.policy = "pairing". Unbekannte Absender erhalten einen Kopplungscode.
Freigabe ü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 Benutzer-IDs oder Anzeigenamen. Der Assistent löst Anzeigenamen in Benutzer-IDs auf, wenn Verzeichnissuche verfügbar ist.

Räume (Gruppen)

Standard: channels.matrix.groupPolicy = "allowlist" (erwähnungsgesteuert). Nutzen Sie channels.defaults.groupPolicy, um den Standard zu überschreiben, wenn nicht gesetzt.
Räume in Zulassen-Liste mit channels.matrix.groups (Raum-IDs, Aliase oder Namen):


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

requireMention: false aktiviert Auto-Antwort in diesem Raum.
groups."*" kann Standardeinstellungen für Erwähnungs-Steuerung über Räume setzen.
groupAllowFrom schränkt ein, welche Absender den Bot in Räumen auslösen können (optional).
Pro-Raum-users-Zulassen-Listen können Absender in einem bestimmten Raum weiter einschränken.
Der Konfigurations-Assistent fragt nach Raum-Zulassen-Listen (Raum-IDs, Aliase oder Namen) und löst Namen auf, wenn möglich.
Beim Start löst OpenClaw Raum-/Benutzernamen in Zulassen-Listen in IDs auf und protokolliert die Zuordnung; nicht auflösbare Einträge bleiben wie eingegeben.
Einladungen werden standardmäßig automatisch angenommen; Steuerung über channels.matrix.autoJoin und channels.matrix.autoJoinAllowlist.
Keine Räume zulassen: channels.matrix.groupPolicy: "disabled" setzen (oder Zulassen-Liste leer lassen).
Legacy-Key: channels.matrix.rooms (gleiche Form 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

Funktionen

Feature	Status
Direct messages	✅ Supported
Rooms	✅ Supported
Threads	✅ Supported
Media	✅ Supported
E2EE	✅ Supported (crypto module required)
Reactions	✅ Supported (send/read via tools)
Polls	✅ Send supported; inbound poll starts are converted to text (responses/ends ignored)
Location	✅ Supported (geo URI; altitude ignored)
Native commands	✅ Supported

Konfigurationsreferenz (Matrix)

Vollständige Konfiguration: Konfiguration. Provider-Optionen:

channels.matrix.enabled: Kanalstart 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: Initial-Sync-Limit.
channels.matrix.threadReplies: off | inbound | always (Standard: inbound).
channels.matrix.textChunkLimit: ausgehende Text-Chunk-Größe (Zeichen).
channels.matrix.chunkMode: length (Standard) oder newline zum Teilen an Leerzeilen (Absatzgrenzen) vor Längen-Chunking.
channels.matrix.dm.policy: pairing | allowlist | open | disabled (Standard: pairing).
channels.matrix.dm.allowFrom: DM-Zulassen-Liste (Benutzer-IDs oder Anzeigenamen). open erfordert "*". Der Assistent löst Namen in IDs auf, wenn möglich.
channels.matrix.groupPolicy: allowlist | open | disabled (Standard: allowlist).
channels.matrix.groupAllowFrom: zugelassene Absender für Gruppennachrichten.
channels.matrix.allowlistOnly: Zulassen-Listen-Regeln für DMs + Räume erzwingen.
channels.matrix.groups: Gruppen-Zulassen-Liste + Pro-Raum-Einstellungs-Map.
channels.matrix.rooms: Legacy-Gruppen-Zulassen-Liste/Konfiguration.
channels.matrix.replyToMode: Reply-To-Modus für Threads/Tags.
channels.matrix.mediaMaxMb: eingehendes/ausgehendes Medien-Limit (MB).
channels.matrix.autoJoin: Einladungsbehandlung (always | allowlist | off, Standard: always).
channels.matrix.autoJoinAllowlist: erlaubte Raum-IDs/Aliase für Auto-Join.
channels.matrix.actions: Pro-Aktion-Tool-Steuerung (reactions/messages/pins/memberInfo/channelInfo).