Matrix (Plugin)

Matrix ist ein offenes, dezentrales Messaging-Protokoll. OpenClaw verbindet sich als Matrix-User auf einem beliebigen Homeserver – du brauchst also einen Matrix-Account für den Bot. Sobald er eingeloggt ist, kannst du dem Bot direkt schreiben (DM) oder ihn in Räume einladen (Matrix-”Gruppen”). Beeper funktioniert auch als Client, erfordert aber aktivierte E2EE.

Status: Unterstützt via Plugin (@vector-im/matrix-bot-sdk). Direct Messages, Räume, Threads, Medien, Reactions, Polls (senden + poll-start als Text), Standort und E2EE (mit Crypto-Support).

Plugin erforderlich

Matrix wird als Plugin ausgeliefert und ist nicht im Core-Install enthalten.

Installation via CLI (npm Registry):

openclaw plugins install @openclaw/matrix

Lokaler Checkout (wenn du aus einem Git-Repo arbeitest):

openclaw plugins install ./extensions/matrix

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

Details: Plugins

Setup

1. Installiere das Matrix-Plugin:

   • Von npm: openclaw plugins install @openclaw/matrix
   • Von einem lokalen Checkout: openclaw plugins install ./extensions/matrix

2. Erstelle einen Matrix-Account auf einem Homeserver:

   • Hosting-Optionen findest du unter https://matrix.org/ecosystem/hosting/
   • Oder hoste ihn selbst.

3. Hol dir ein Access Token für den Bot-Account:

   • Nutze die Matrix Login API mit curl auf 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-Endpoint auf, speichert das Access Token in ~/.openclaw/credentials/matrix/credentials.json und verwendet es beim nächsten Start wieder.

4. Konfiguriere die Credentials:

   • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (oder MATRIX_USER_ID + MATRIX_PASSWORD)
   • Oder Config: channels.matrix.*
   • Wenn beides gesetzt ist, hat die Config Vorrang.
   • Mit Access Token: User-ID wird automatisch via /whoami abgerufen.
   • Wenn gesetzt, sollte channels.matrix.userId die vollständige Matrix-ID sein (Beispiel: @bot:example.org).

5. Starte den Gateway neu (oder schließe das Onboarding ab).

6. Starte einen DM mit dem Bot oder lade ihn in einen Raum ein – von jedem Matrix-Client aus (Element, Beeper, etc.; siehe https://matrix.org/ecosystem/clients/). Beeper erfordert E2EE, also setze channels.matrix.encryption: true und verifiziere das Gerät.

Minimale Config (Access Token, User-ID wird automatisch abgerufen):

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

E2EE-Config (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 unterstützt via Rust Crypto SDK.

Aktiviere sie 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 eine Geräteverifizierung von deinen anderen Sessions an.
• Verifiziere das Gerät in einem anderen Matrix-Client (Element, etc.), um Key-Sharing zu aktivieren.
• Wenn das Crypto-Modul nicht geladen werden kann, ist E2EE deaktiviert und verschlüsselte Räume werden nicht entschlüsselt; OpenClaw loggt eine Warnung.
• Wenn du Fehler wegen fehlendem Crypto-Modul siehst (z. B. @matrix-org/matrix-sdk-crypto-nodejs-*), erlaube Build-Scripts für @matrix-org/matrix-sdk-crypto-nodejs und führe pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs aus oder hole die Binary mit node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Der Crypto-State wird pro Account + Access Token gespeichert in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite-Datenbank). Der Sync-State liegt daneben in bot-storage.json. Wenn sich das Access Token (Gerät) ändert, wird ein neuer Store erstellt und der Bot muss für verschlüsselte Räume neu 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 bestätige die Verifizierungsanfrage, 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 sich die Haupt-Session des Agents; Räume werden auf Group-Sessions gemappt.

Zugriffskontrolle (DMs)

• Standard: channels.matrix.dm.policy = "pairing". Unbekannte Absender bekommen einen Pairing-Code.
• Freigabe via:
  • 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 User-IDs oder Display-Namen. Der Wizard löst Display-Namen zu User-IDs auf, wenn Directory-Search verfügbar ist.

Räume (Gruppen)

• Standard: channels.matrix.groupPolicy = "allowlist" (Mention-gated). Nutze channels.defaults.groupPolicy, um den Standard zu überschreiben, wenn nicht gesetzt.
• Allowlist-Räume mit channels.matrix.groups (Raum-IDs, Aliases 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-Reply in diesem Raum.
• groups."*" kann Defaults für Mention-Gating über alle Räume setzen.
• groupAllowFrom beschränkt, welche Absender den Bot in Räumen triggern können (optional).
• Per-Raum-users-Allowlists können Absender innerhalb eines bestimmten Raums weiter einschränken.
• Der Configure-Wizard fragt nach Raum-Allowlists (Raum-IDs, Aliases oder Namen) und löst Namen auf, wenn möglich.
• Beim Start löst OpenClaw Raum-/User-Namen in Allowlists zu IDs auf und loggt das Mapping; nicht aufgelöste Einträge bleiben wie eingegeben.
• Invites werden standardmäßig automatisch angenommen; steuerbar 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-Key: channels.matrix.rooms (gleiche Form wie groups).

Threads

• Reply-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

Konfigurationsreferenz (Matrix)

Vollständige Konfiguration: Configuration

Provider-Optionen:

• channels.matrix.enabled: Channel-Startup aktivieren/deaktivieren.
• channels.matrix.homeserver: Homeserver-URL.
• channels.matrix.userId: Matrix-User-ID (optional mit Access Token).
• channels.matrix.accessToken: Access Token.
• channels.matrix.password: Passwort für Login (Token wird gespeichert).
• channels.matrix.deviceName: Geräteanzeigename.
• 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, um bei Leerzeilen (Absatzgrenzen) vor Length-Chunking zu splitten.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (Standard: pairing).
• channels.matrix.dm.allowFrom: DM-Allowlist (User-IDs oder Display-Namen). open erfordert "*". Der Wizard löst Namen zu IDs auf, wenn möglich.
• channels.matrix.groupPolicy: allowlist | open | disabled (Standard: allowlist).
• channels.matrix.groupAllowFrom: Allowlist-Absender für Gruppennachrichten.
• channels.matrix.allowlistOnly: Allowlist-Regeln für DMs + Räume erzwingen.
• channels.matrix.groups: Gruppen-Allowlist + Per-Raum-Einstellungen-Map.
• channels.matrix.rooms: Legacy-Gruppen-Allowlist/Config.
• channels.matrix.replyToMode: Reply-to-Modus für Threads/Tags.
• channels.matrix.mediaMaxMb: Eingehende/ausgehende Medien-Obergrenze (MB).
• channels.matrix.autoJoin: Invite-Handling (always | allowlist | off, Standard: always).
• channels.matrix.autoJoinAllowlist: Erlaubte Raum-IDs/Aliases für Auto-Join.
• channels.matrix.actions: Per-Action-Tool-Gating (reactions/messages/pins/memberInfo/channelInfo).