OpenClaw

OpenClaw Matrix Kanal

Dezentral
Mittel

Verbinden Sie OpenClaw mit Matrix — einem offenen, föderierten Kommunikationsprotokoll. Diese Integration ermöglicht es Ihrem KI-Assistenten, in Matrix-Räumen und Direktnachrichten über jeden Homeserver (matrix.org, Element oder selbst gehostet) teilzunehmen. OpenClaw verbindet sich über die Matrix Client-Server-API mit optionaler Ende-zu-Ende-Verschlüsselung (E2EE) Unterstützung durch das Rust Crypto SDK. Der Matrix-Kanal wird als Plugin ausgeliefert und unterstützt Föderation, Threads, Reaktionen und Rich Media.

Kurzinfo
SchwierigkeitsgradMittel
KategorieDezentral
Unterstützte Funktionen5 / 6

Matrix Unterstützte Funktionen

Textnachrichten

Unterstützt

Medien & Dateien

Unterstützt

Reaktionen

Unterstützt

Threads

Unterstützt

Sprachnachrichten

Nicht unterstützt

Gruppenchat

Unterstützt

Matrix Voraussetzungen

  • Ein aktives Matrix-Konto auf einem beliebigen Homeserver (matrix.org, Element oder selbst gehostet)
  • Das Matrix-Plugin installiert: openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway läuft und ist konfiguriert
  • Node.js 18+ auf Ihrem Server installiert

Matrix Schnelleinrichtung

1

Matrix-Plugin installieren

Der Matrix-Kanal wird als separates Plugin ausgeliefert. Installieren Sie es über 'openclaw plugins install @openclaw/matrix'. Das Plugin wird aus dem npm-Registry heruntergeladen und automatisch aktiviert.

2

Matrix-Zugangsdaten erhalten

Sie benötigen entweder ein Access Token oder Benutzername/Passwort. Für Access Tokens: Verwenden Sie curl, um den Login-Endpunkt Ihres Homeservers aufzurufen und kopieren Sie das Token. Für Benutzername/Passwort: Das Gateway meldet sich automatisch an und speichert das Token in ~/.openclaw/credentials/matrix/credentials.json.

3

Matrix-Kanal-Konfiguration hinzufügen

Fügen Sie die Matrix-Kanal-Konfiguration zu ~/.openclaw/openclaw.json mit Ihrer Homeserver-URL und Zugangsdaten hinzu. Sie können auch Umgebungsvariablen MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID und MATRIX_PASSWORD verwenden.

4

Gateway starten und testen

Führen Sie 'openclaw gateway' aus, um den Dienst zu starten. Senden Sie eine Direktnachricht an Ihren Matrix-Bot-Benutzer von einem anderen Konto. Bei Verwendung der Standard-Pairing-Richtlinie genehmigen Sie den Absender über 'openclaw pairing approve matrix <code>' in Ihrem Terminal.

Matrix Konfigurationsbeispiel

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix Detaillierte Dokumentation

Architekturübersicht

OpenClaw verbindet sich mit Matrix über die Client-Server-API und fungiert als Standard-Matrix-Client. Die Architektur ist ereignisgesteuert: Ihr Bot empfängt Ereignisse (Nachrichten, Reaktionen, Mitgliedschaftsänderungen) über Long-Polling-Sync-Anfragen, verarbeitet sie mit Ihrer KI und sendet Antworten über die API zurück. Matrix ist föderiert, was bedeutet, dass Ihr Bot mit Benutzern auf jedem Homeserver im globalen Matrix-Netzwerk kommunizieren kann — nicht nur auf dem Homeserver, auf dem Ihr Bot-Konto registriert ist. Dies unterscheidet sich grundlegend von zentralisierten Plattformen wie WhatsApp oder Telegram. Der Ablauf ist: Benutzer sendet Nachricht in Matrix → Homeserver leitet an Ihr Gateway über Sync weiter → OpenClaw verarbeitet mit KI → Antwort wird über Send-Event-API gesendet → Nachricht wird über Föderation zugestellt.
Föderation bedeutet, dass Ihr Bot auf matrix.org mit Benutzern auf jedem Matrix-Homeserver (z.B. element.io, Mozillas Homeserver oder selbst gehostete Instanzen) chatten kann.
Das Matrix-Plugin verwendet standardmäßig Long-Polling. Es sind keine Webhooks oder öffentlichen URLs erforderlich — das Gateway stellt eine ausgehende Verbindung zu Ihrem Homeserver her.

Authentifizierungsmethoden

OpenClaw unterstützt zwei Authentifizierungsansätze für Matrix: 1. **Access Token (empfohlen)** — Erhalten Sie ein Token durch Aufruf der Login-API Ihres Homeservers mit curl oder einem Matrix-Client. Setzen Sie channels.matrix.accessToken in Ihrer Konfiguration. Das System ruft automatisch Ihre Benutzer-ID über den /whoami-Endpunkt ab. 2. **Benutzername/Passwort** — Setzen Sie channels.matrix.userId und channels.matrix.password. OpenClaw ruft automatisch den Login-Endpunkt auf und speichert das Access Token in ~/.openclaw/credentials/matrix/credentials.json. Umgebungsvariablen haben Vorrang vor Konfigurationsdateien: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json
# Access Token Methode
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# Benutzername/Passwort Methode
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
Committen Sie niemals Access Tokens oder Passwörter in die Versionskontrolle. Verwenden Sie Umgebungsvariablen für Produktionsumgebungen. Wenn Ihr Token kompromittiert wurde, melden Sie alle Geräte über Ihren Matrix-Client ab, um alle Tokens zu invalidieren, und generieren Sie dann ein neues.

DM-Richtlinien

DM (Direct Message) Richtlinien steuern, wer mit Ihrem KI-Assistenten interagieren kann. OpenClaw unterstützt vier Richtlinien: • pairing (Standard) — Unbekannte Benutzer erhalten beim ersten Kontakt einen Pairing-Code. Genehmigen Sie über 'openclaw pairing approve matrix <CODE>', um Zugriff zu gewähren. Nach der Genehmigung kann der Benutzer frei chatten. • allowlist — Nur Matrix-Benutzer-IDs, die explizit in channels.matrix.dm.allowFrom aufgelistet sind, können dem Bot Nachrichten senden. Alle anderen werden stillschweigend ignoriert. • open — Jeder, der dem Bot schreibt, erhält eine Antwort. Erfordert allowFrom: ["*"]. Mit Vorsicht verwenden. • disabled — DM-Verarbeitung ist vollständig deaktiviert. Allowlists akzeptieren vollständige Matrix-Benutzer-IDs im Format @user:server (z.B. @alice:matrix.org).
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

Gruppenchat (Raum) Unterstützung

Matrix-Gruppenkonversationen werden "Räume" genannt. Standardmäßig verwendet OpenClaw eine Allowlist-Richtlinie für Räume, die eine erwähnungsbasierte Aktivierung erfordert. Sie können konfigurieren, in welchen Räumen der Bot teilnimmt und wie er antwortet. Räume werden durch Raum-IDs (!roomId:server) oder Raum-Aliase (#alias:server) identifiziert. Sie können raumspezifische Einstellungen wie automatisches Beitrittsverhalten, Erwähnungsanforderungen und raumspezifische Benutzer-Allowlists konfigurieren.
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
Setzen Sie autoJoin auf 'always', um automatisch alle Raumeinladungen anzunehmen, 'allowlist', um nur konfigurierte Räume beizutreten, oder 'off', um Einladungen zu ignorieren.
Verwenden Sie requireMention: false, um automatische Antworten ohne Erwähnung des Bots zu aktivieren. Seien Sie vorsichtig in Räumen mit hohem Nachrichtenaufkommen.

Ende-zu-Ende-Verschlüsselung (E2EE)

Matrix unterstützt Ende-zu-Ende-Verschlüsselung (E2EE) über die Olm- und Megolm-Protokolle. OpenClaw kann an verschlüsselten Räumen teilnehmen, wenn Sie die Verschlüsselung über das Rust Crypto SDK aktivieren. Wenn aktiviert, entschlüsselt das System automatisch verschlüsselte Nachrichten, verschlüsselt ausgehende Medien in gesicherten Räumen und speichert den Krypto-Status in ~/.openclaw/matrix/accounts/ (SQLite). Bei der ersten Verbindung ist eine Geräteverifizierung erforderlich — genehmigen Sie die Verifizierungsanfrage in Element oder einem anderen Matrix-Client, um den Schlüsselaustausch zu aktivieren. Wenn Krypto-Module nicht geladen werden können, wird E2EE deaktiviert und verschlüsselte Räume bleiben unzugänglich.
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
Das Ändern von Access Tokens erfordert eine erneute Geräteverifizierung. Erstellen Sie Backups Ihres Krypto-Status-Verzeichnisses (~/.openclaw/matrix/accounts/), um den Zugriff auf verschlüsselte Nachrichtenverläufe nicht zu verlieren.

Föderation & Homeserver-Auswahl

Matrix ist ein föderiertes Protokoll — es gibt keinen einzelnen zentralen Server. Sie können Ihren Bot auf jedem Homeserver registrieren: • **matrix.org** — Der Flagship-Homeserver der Matrix Foundation. Offene Registrierung, hohe Zuverlässigkeit, aber kann aufgrund hohen Traffics langsamer sein. • **Element Matrix Services** — Professionell gehostete Homeserver auf element.io mit Premium-Funktionen und Support. • **Selbst gehostet** — Betreiben Sie Ihren eigenen Homeserver für maximale Kontrolle und Privatsphäre. Synapse ist die ausgereifteste und aktiv weiterentwickelte Option. Dendrite (Go) und Conduit (Rust) sind leichtere Alternativen für kleinere Deployments, befinden sich aber mittlerweile im Wartungs- oder eingeschränkten Entwicklungsmodus. Ihr Bot kann mit Benutzern auf jedem Homeserver kommunizieren, unabhängig davon, wo er registriert ist, dank Föderation.
Für Produktionsumgebungen sollten Sie erwägen, einen selbst gehosteten Homeserver oder Element Matrix Services für bessere Kontrolle und Performance zu verwenden.
Föderation funktioniert transparent — Benutzer müssen nicht wissen, auf welchem Homeserver Ihr Bot sich befindet.

Threading & Antwortmodi

Matrix unterstützt Thread-Konversationen über den m.thread-Beziehungstyp. OpenClaw kann an Threads teilnehmen und steuern, wie Antworten behandelt werden. Die threadReplies-Einstellung steuert das Thread-Verhalten: 'off' deaktiviert Thread-Unterstützung, 'inbound' liest nur Thread-Kontext, und 'always' liest und erstellt Thread-Antworten. Die replyToMode-Einstellung steuert das Anhängen von Metadaten für Antwortbeziehungen.
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

Medienverarbeitung & Datei-Uploads

Matrix unterstützt Rich Media einschließlich Bilder, Videos, Audio und Dokumente. OpenClaw verarbeitet Medien-Uploads automatisch — Dateien werden in das Medien-Repository Ihres Homeservers hochgeladen und in Nachrichtenereignissen referenziert. Sie können maximale Dateigrößen über die mediaMaxMb-Einstellung konfigurieren. Der Standard ist 50 MB für eingehende Medien, mit automatischer JPEG-Optimierung und Größenanpassung für überdimensionierte Bilder bei ausgehenden Sendungen.
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
Medien-Uploads werden auf Ihrem Homeserver gespeichert. Wenn Sie einen öffentlichen Homeserver wie matrix.org verwenden, achten Sie auf Speicherlimits und Nutzungsbedingungen.

Reaktionen & Rich Features

OpenClaw unterstützt Matrix-Reaktionen (Emoji-Antworten auf Nachrichten), Umfragen, Standortfreigabe (Geo-URI-Format) und andere Rich Features. Reaktionen können über Tools gesendet und gelesen werden, wenn aktiviert. Sie können bestimmte Operationen über die actions-Konfiguration einschränken und festlegen, was Ihr KI-Agent tun kann (Reaktionen, Nachrichten, Pins, Mitglieds-/Kanalinformationen).
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

Warum Matrix für selbst gehostete KI?

Matrix ist eine ausgezeichnete Wahl für selbst gehostete KI-Assistenten, weil: • **Wirklich offen** — Offene Spezifikation, keine Vendor-Lock-in, mehrere Client- und Server-Implementierungen. • **Föderiert** — Kein einzelner Kontroll- oder Ausfallpunkt. Ihr Bot kann über das globale Matrix-Netzwerk kommunizieren. • **Datenschutzorientiert** — E2EE-Unterstützung, selbst gehostete Optionen und keine zentralisierte Datenerfassung. • **Rich Features** — Threads, Reaktionen, Medien, Umfragen und erweiterbare Ereignistypen. • **Keine Telefonnummer erforderlich** — Im Gegensatz zu WhatsApp oder Signal benötigt Matrix keine Telefonnummer für die Registrierung. Der Kompromiss ist Komplexität: Das Föderationsmodell von Matrix und die E2EE-Einrichtung können komplexer sein als zentralisierte Plattformen. Für datenschutzbewusste Benutzer und Teams ist dieser Kompromiss lohnenswert.

Matrix Konfigurationsreferenz

enabled
Type: booleanDefault: true

Matrix-Kanal aktivieren oder deaktivieren

homeserver
Type: stringDefault: "https://matrix.org"

Matrix-Homeserver-URL (z.B. https://matrix.org, https://element.io)

accessToken
Type: stringDefault: ""

Matrix-Access-Token für Authentifizierung (empfohlene Methode)

userId
Type: stringDefault: ""

Matrix-Benutzer-ID (z.B. @bot:matrix.org) — verwendet mit Passwort-Authentifizierung

password
Type: stringDefault: ""

Matrix-Konto-Passwort — verwendet mit userId für Login

encryption
Type: booleanDefault: false

Ende-zu-Ende-Verschlüsselung über Rust Crypto SDK aktivieren

dmPolicy
Type: stringDefault: "pairing"

DM-Zugriffsrichtlinie: pairing, allowlist, open oder disabled

dm.allowFrom
Type: arrayDefault: []

Erlaubte Matrix-Benutzer-IDs für DMs (z.B. [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

Raum-Richtlinie: allowlist oder disabled

groups
Type: objectDefault: {}

Raumspezifische Konfiguration (Raum-ID oder Alias als Schlüssel)

groups.<roomId>.allow
Type: booleanDefault: false

Bot erlauben, an diesem Raum teilzunehmen

groups.<roomId>.requireMention
Type: booleanDefault: true

Bot-Erwähnung erforderlich, um Antworten in diesem Raum auszulösen

groups.<roomId>.users
Type: arrayDefault: []

Raumspezifische Benutzer-Allowlist (Matrix-Benutzer-IDs)

autoJoin
Type: stringDefault: "allowlist"

Automatisch Raumeinladungen beitreten: always, allowlist oder off

textChunkLimit
Type: numberDefault: 4096

Maximale Zeichen pro ausgehender Nachricht

chunkMode
Type: stringDefault: "length"

Wie lange Antworten aufgeteilt werden: length (harte Grenze) oder newline (Absatzgrenzen)

threadReplies
Type: stringDefault: "inbound"

Thread-Verhalten: off, inbound (nur lesen) oder always (lesen + erstellen)

replyToMode
Type: stringDefault: "reference"

Antwort-Metadaten-Anhangsmodus

mediaMaxMb
Type: numberDefault: 50

Maximale Medien-Dateigröße in Megabyte

actions.reactions
Type: booleanDefault: true

Agent erlauben, Reaktionen zu senden/lesen

actions.messages
Type: booleanDefault: true

Agent erlauben, Nachrichten zu lesen/senden/bearbeiten/löschen

actions.pins
Type: booleanDefault: true

Agent erlauben, Nachrichten anzuheften/abzuheften

actions.memberInfo
Type: booleanDefault: true

Agent erlauben, Raummitgliederinformationen abzurufen

actions.channelInfo
Type: booleanDefault: true

Agent erlauben, Raum-/Kanalinformationen abzurufen

Matrix Häufig gestellte Fragen

Matrix Fehlerbehebung

Bot empfängt keine Nachrichten

DM-Richtlinie blockiert Nachrichten oder Bot ist nicht im Raum

Überprüfen Sie die Einstellungen channels.matrix.dmPolicy und dm.allowFrom. Für Räume stellen Sie sicher, dass der Raum in Ihrer groups-Allowlist ist und der Bot eingeladen wurde und beigetreten ist.
E2EE-verschlüsselte Räume zeigen keine Nachrichten

Gerät nicht verifiziert oder Krypto-Module konnten nicht geladen werden

Verifizieren Sie das Gerät Ihres Bots in Element oder einem anderen Matrix-Client. Überprüfen Sie die Logs auf Fehler beim Laden von Krypto-Modulen. Stellen Sie sicher, dass channels.matrix.encryption auf true gesetzt ist.
Access Token ungültig oder abgelaufen

Token wurde auf dem Homeserver widerrufen oder invalidiert

Generieren Sie ein neues Access Token, indem Sie sich erneut anmelden. Bei Verwendung von Benutzername/Passwort löschen Sie ~/.openclaw/credentials/matrix/credentials.json und starten Sie das Gateway neu.
Bot tritt Raum bei, antwortet aber nicht

Raum nicht in Allowlist oder requireMention ist aktiviert

Fügen Sie den Raum zu channels.matrix.groups mit allow: true hinzu. Wenn requireMention true ist, müssen Benutzer den Bot erwähnen, um eine Antwort zu erhalten.
Föderationsfehler mit anderen Homeservern

Homeserver-Konnektivität oder Föderationsprobleme

Überprüfen Sie den Föderationsstatus Ihres Homeservers unter federationtester.matrix.org. Überprüfen Sie DNS-SRV-Einträge und SSL-Zertifikate bei selbst gehosteten Servern.
Plugin-Installation schlägt fehl

npm-Registry-Zugriff oder Node.js-Versionskompatibilität

Stellen Sie sicher, dass Node.js 18+ installiert ist. Versuchen Sie 'openclaw plugins install @openclaw/matrix --verbose' für detaillierte Fehlerprotokolle. Überprüfen Sie die Netzwerkverbindung zum npm-Registry.
Vollständige Dokumentation anzeigenZurück zu allen Kanälen

Verwandte Kanäle

Nostr

Advanced

OpenClaw dezentrale NIP-04 DM-Integration

Einrichtungsanleitung

Tlon

Advanced

OpenClaw Urbit-Messenger-Integration

Einrichtungsanleitung