Wie man einen Matrix-Bot mit Python und Simple-Matrix-Bot-Lib einrichtet

Was genau wählt man aus, wenn man auf diese Weise einen Matrix-Bot erstellt?

Simple-Matrix-Bot-Lib ist eine Komfortschicht für die Python- matrix-nioClientbibliothek. Sie eignet sich besonders für kleine Befehls-, Benachrichtigungs- oder Raumhelfer, die ohne eigene Implementierung der vollständigen Matrix-Synchronisierungs- und Ereignisbehandlungsschleife auskommen. Im Gegenzug akzeptiert man die Abstraktionen und Authentifizierungsmuster der Wrapper-Bibliothek, anstatt jedes Detail des Matrix-Clients direkt zu steuern.

PyPI listet am 6. Oktober 2026 simplematrixbotlibVersion 2.13.1, veröffentlicht am 29. März 2026, die Python 3.9 oder neuer, aber älter als Python 4, voraussetzt. Die zugehörige Dokumentationsseite (Read the Docs) weist darauf hin, dass sie nicht mehr gepflegt wird und möglicherweise veraltet ist. Daher verwendet dieser Leitfaden PyPI und die aktuelle Matrix-Spezifikation als primäre Referenzen und betrachtet ältere Dokumentationen als Implementierungshinweise und nicht als Beleg für das aktuelle Verhalten.

Das Paket selbst finden Sie im Projekt simplematrixbotlib auf PyPI . Informationen zum Protokollverhalten entnehmen Sie bitte der aktuellen Matrix Client-Server API-Spezifikation .

Simple-Matrix-Bot-Lib, matrix-nio oder ein Anwendungsdienst?

Wenn Ihr Ziel darin besteht, „als ein Bot-Konto auf Befehle in Räumen zu antworten“, ist Simple-Matrix-Bot-Lib meist der kürzeste Weg. Falls Sie bereits wissen, dass Sie benutzerdefinierte Authentifizierung, ungewöhnliches Synchronisierungsverhalten, detaillierte Geräteverifizierung oder eine tiefgreifende Verschlüsselungskontrolle benötigen, kann der Einsatz von matrix-nio spätere Probleme mit einem Wrapper vermeiden. Für Bridges oder Integrationen, die Routing auf Homeserver-Ebene erfordern, sollten Sie die Matrix Application Service API konsultieren, anstatt ein normales Bot-Konto als Ersatz zu verwenden.

Schritt 1: Wählen Sie einen Homeserver und bestätigen Sie, wie sich der Bot anmelden kann.

Ein Matrix-Bot benötigt ein Matrix-Benutzerkonto auf einem Homeserver. Sie können einen öffentlichen Homeserver verwenden, der die Kontoerstellung erlaubt, oder ein Konto auf einem von Ihnen verwalteten Homeserver. Trennen Sie den Bot von Ihrer persönlichen Matrix-Identität, damit Berechtigungen, Raumzugehörigkeiten und Anmeldeinformationen unabhängig verwaltet werden können.

Die wichtigste Entscheidung betrifft die Authentifizierung. Die aktuelle Matrix-Spezifikation unterstützt sowohl die ältere Authentifizierungs-API als auch OAuth 2.0. Ein Homeserver kann eine oder beide dieser APIs bereitstellen. Die veröffentlichten Schnellstartbeispiele der Simple-Matrix-Bot-Lib verwenden eine Homeserver-URL, einen Benutzernamen und ein Passwort. Daher setzt dieses Tutorial voraus, dass Ihr Server weiterhin einen kompatiblen Anmeldevorgang mit Passwort anbietet.

Bevor Sie Code schreiben, prüfen Sie die von Ihrem Homeserver bereitgestellten Anmeldemethoden:

curl https://matrix.example.com/_matrix/client/v3/login

Wenn die Antwort einen Anmeldevorgang mit Passwort beinhaltet, ist das unten stehende Beispiel mit Anmeldeinformationen geeignet. Wenn der Server ausschließlich SSO oder OAuth unterstützt, sollte im Beispiel kein Passwort erzwungen werden. Prüfen Sie in diesem Fall, ob die aktuelle Bibliotheksversion die Authentifizierung unterstützt, oder verwenden Sie einen Client mit niedrigerer Ebene, der den benötigten Ablauf unterstützt. Die Matrix-Spezifikation erläutert die Anmeldeerkennung und die Token-Verwaltung im Abschnitt „Anmeldung“ der Client-Server-API .

Schritt 2: Erstellen Sie eine isolierte Python-Umgebung und installieren Sie die Bibliothek.

Verwenden Sie eine virtuelle Umgebung, um die Abhängigkeiten des Bots vom System-Python und von anderen Projekten zu trennen. Die aktuellen PyPI-Metadaten erfordern Python 3.9 oder höher.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

Aktivieren Sie die Umgebung in Windows PowerShell mit folgendem Befehl:

.venv\Scripts\Activate.ps1

Prüfen Sie, was tatsächlich installiert wurde, anstatt eine Version aus einem alten Tutorial anzunehmen:

python -m pip show simplematrixbotlib

Diese Versionsprüfung ist wichtig, da die öffentlichen Read the Docs-Seiten noch ältere Dokumentationen enthalten und ausdrücklich darauf hinweisen, dass diese möglicherweise veraltet sind. Falls ein Beispiel von diesen Seiten mit dem installierten Paket in Konflikt steht, überprüfen Sie die Metadaten der Version und das aktuelle Repository, bevor Sie Ihren Code an die ältere Seite anpassen.

Benötigen Sie eine Ende-zu-Ende-Verschlüsselung?

Nicht jeder Bot tut dies. Ein Bot, der nur unverschlüsselten Operationsräumen beitritt, ist einfacher einzusetzen und muss keinen Verschlüsselungsstatus verwalten. Ein Bot, der in verschlüsselten Räumen lesen und antworten soll, benötigt zusätzliche Abhängigkeiten und einen persistenten Kryptostatus.

Die Dokumentation von Simple-Matrix-Bot-Lib und die aktuelle Dokumentation von matrix-nio weisen beide darauf hin, dass E2EE auf der Verschlüsselungsunterstützung von matrix-nio und libolm basiert. Unter Debian oder Ubuntu dokumentiert matrix-nio die Installation libolm-devund anschließend das E2EE-Extra.

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

Aktivieren Sie E2EE nicht nur, weil Matrix es unterstützt. Verwenden Sie es nur, wenn die Räume Verschlüsselung erfordern und Sie bereit sind, den Bot-Speicher zu speichern und die Gerätevertrauenswürdigkeit zu verwalten. Die Matrix-NIO-Dokumentation weist darauf hin, dass Verschlüsselungsstatus, Schlüssel und Gerätevertrauenswürdigkeit lokal gespeichert werden, wenn E2EE aktiviert ist.

Schritt 3: Erstellen Sie das Bot-Konto und halten Sie die Zugangsdaten vom Quellcode fern.

Erstellen Sie ein dediziertes Matrix-Konto mithilfe eines Clients oder der Kontoverwaltung Ihres Homeservers. Die genaue Benutzeroberfläche für die Registrierung variiert je nach Anbieter. Diese Anleitung geht daher nicht von einer bestimmten Element-Oberfläche aus und behauptet auch nicht, dass eine offene Registrierung überall möglich ist.

Für die Entwicklung müssen drei Umgebungsvariablen exportiert werden:

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

Umgebungsvariablen sind für ein lokales Tutorial praktisch, stellen aber kein produktionsreifes Geheimnisverwaltungssystem dar. Auf einem VPS oder einer Containerplattform sollten Sie den plattformeigenen Geheimnisspeicher, eine geschützte Umgebungsdatei außerhalb der Quellcodeverwaltung oder einen dedizierten Geheimnismanager bevorzugen. Speichern Sie niemals ein Matrix-Passwort oder einen Zugriffstoken in Git.

Laden Sie den Bot-Account in einen Testraum ein und nehmen Sie die Einladung mit einem Matrix-Client an, falls Ihr Server oder Ihre Bot-Konfiguration Einladungen nicht automatisch annimmt. Beginnen Sie mit einem privaten Testraum. Dadurch wird die versehentliche Ausführung von Befehlen eingeschränkt, während Sie das Verhalten des Bots überprüfen.

Schritt 4: Einen minimalen Befehlsbot schreiben, ausführen und testen

Erstellen Sie dies bot.pymit einem kleinen !pingBefehl. Die folgende Struktur folgt dem Beispiel des öffentlichen Pakets: Erstellen Creds, Erstellen Bot, Hinzufügen eines asynchronen Nachrichten-Listeners, Verwenden MessageMatchund Senden einer Textnachricht über bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

Führen Sie es in der aktivierten virtuellen Umgebung aus:

python bot.py

Im Testraum senden Sie Folgendes:

!ping

Ein erfolgreiches Ergebnis ist einfach: Der Bot bleibt verbunden, erkennt das Raumereignis und antwortet Pong!. Stellen Sie außerdem sicher, dass er nicht auf seine eigene Antwort reagiert. Diese is_not_from_this_bot()Prüfung ist wichtig, da ein einfacher Echo-Bot sonst Rückkopplungsschleifen erzeugen kann.

Wann sollte man eine Zulassungsliste hinzufügen?

Fügen Sie eine Sicherheitsabfrage hinzu, bevor der Bot sensible Aktionen auslösen kann. Ein Befehl, der lediglich „Pong!“ zurückgibt, hat kaum Auswirkungen, aber ein Befehl, der Bereitstellungsaufträge ausführt, interne Systeme abfragt oder vertrauliche Daten veröffentlicht, sollte nicht für jeden Benutzer in jedem beigetretenen Raum ausgeführt werden.

Simple-Matrix-Bot-Lib bewirbt Benutzerzugriffsverwaltung und die Konfiguration von Zulassungs-/Sperrlisten als Funktionen. Bei einem produktiven Bot sollte die Autorisierung als Anwendungslogik und nicht als optionaler Feinschliff behandelt werden. Beschränken Sie den Zugriff anhand der Benutzer-ID, der Raum-ID oder beider und verwenden Sie serverseitige Berechtigungen auf den nachgelagerten Systemen als zweite Sicherheitsebene.

Passwortbasierte Anmeldung versus Zugriffstoken: Was ist der praktische Kompromiss?

Die Passwortanmeldung ist leicht verständlich und entspricht dem veröffentlichten Minimalbeispiel des Pakets. Der Nachteil besteht darin, dass ein dauerhaft laufender Bot das Kontopasswort kennen muss, und einige moderne Matrix-Implementierungen bevorzugen möglicherweise SSO- oder OAuth-Abläufe.

Zugriffstoken reduzieren die wiederholte Passwortverwendung, ihre Lebensdauer ist jedoch vom Authentifizierungssystem abhängig. Laut Matrix-Spezifikation sollten Zugriffstoken als undurchsichtige Anmeldeinformationen behandelt und über HTTP übertragen werden Authorization: Bearer. Aktuelle Matrix-Versionen unterstützen in bestimmten Abläufen auch ablaufende Zugriffstoken und Aktualisierungstoken. Gehen Sie nicht davon aus, dass ein Beispiel für Passwortanmeldeinformationen Aktualisierung, Widerruf oder OAuth automatisch berücksichtigt.

Wenn Token-Lebenszyklus, SSO, OAuth oder die Authentifizierung über Dienstkonten für Ihre Bereitstellung zentral sind, überprüfen Sie diese Funktionalität in der exakten Version der Simple-Matrix-Bot-Lib, die Sie installieren. Falls der Wrapper nicht genügend Kontrolle bietet, ist die direkte Verwendung von matrix-nio die technisch sauberere Lösung.

Sollte der Bot auf einem Laptop, einem VPS, einem Container oder Kubernetes ausgeführt werden?

Für einen unverschlüsselten, ressourcenschonenden Bot genügt in der Regel eine kleine VM oder ein Container. Bei einem verschlüsselten Bot ist Persistenz hingegen eine Designvoraussetzung: Der Verlust des lokalen Kryptospeichers kann die Geräteidentität verändern und das Vertrauen untergraben. Die E2EE-Beispiele von matrix-nio betonen die Wichtigkeit, die Geräte-ID und den Kryptospeicher auch nach Neustarts beizubehalten.

Häufige Konfigurationsfehler und ihre übliche Bedeutung

• Die Anmeldung schlägt sofort fehl: Überprüfen Sie die URL des Homeservers und untersuchen Sie diese /_matrix/client/v3/login. Ein Server, der keine Passwortanmeldung anbietet, funktioniert möglicherweise nicht mit einem passwortbasierten Schnellstart.
• Der Bot startet, empfängt aber keine Nachrichten: Bitte überprüfen Sie, ob das Bot-Konto tatsächlich dem Raum beigetreten ist und ob Sie mit einem normalen Textereignis testen.
• Der Bot antwortet wiederholt: Stellen Sie sicher, dass der Handler Ereignisse ignoriert, die vom Bot selbst gesendet werden.
• Verschlüsselte Räume sind unlesbar: Die Installation des Basispakets reicht nicht aus. Fügen Sie die Matrix-NIO-E2EE-Abhängigkeiten hinzu, aktivieren Sie die Verschlüsselung gemäß der Bibliothekskonfiguration und sichern Sie den Kryptospeicher.
• Ein älteres Beispiel führt zu einem API-Fehler: Überprüfen Sie Ihre installierte Paketversion. Die öffentliche Dokumentation der Simple-Matrix-Bot-Lib weist derzeit darauf hin, dass sie nicht mehr gepflegt wird; daher können die Beispiele hinter der PyPI-Version zurückbleiben.

Welchen Weg solltest du wählen?

Wählen Sie Simple-Matrix-Bot-Lib, wenn Ihr Bot nur einen Matrix-Benutzer hat, Ihre Befehle einfach sind und Sie Wert auf prägnanten Python-Code legen, anstatt auf detaillierte Protokollsteuerung. Es eignet sich besonders für Prototypen, Benachrichtigungs-Bots, Raum-Utilities und kleine interne Automatisierungen.

Entscheiden Sie sich direkt für matrix-nio, wenn Verschlüsselung, Geräteverifizierung, benutzerdefinierte Authentifizierung, Ereignistypen, Synchronisierungsverhalten oder Token-Verwaltung zentrale Anforderungen sind. Sie werden zwar mehr Code schreiben müssen, aber die Abstraktionsebene ist niedriger und die Komplexität für fortgeschrittene Matrix-Anwendungen leichter nachvollziehbar.

Wählen Sie einen Anwendungsdienst, wenn Ihre Integration eher eine Homeserver-Erweiterung, eine Brücke oder ein Gateway als ein einzelner Benutzer-Bot ist. Die Anwendungsdienst-API ist für dieses serverbasierte Modell konzipiert und erfordert eine Homeserver-Konfiguration.

Für einen ersten Matrix-Bot !pingist das Minimalbeispiel ein guter Prüfpunkt: Wenn er sich authentifizieren, dem richtigen Raum beitreten, seine eigenen Ereignisse ignorieren und zuverlässig antworten kann, haben Sie den grundlegenden Weg validiert. Fügen Sie Verschlüsselung, Autorisierung, externe APIs und Bereitstellungsautomatisierung erst hinzu, wenn diese Grundlage stabil ist.

Primärquellen

• Simple-Matrix-Bot-Lib auf PyPI – aktuelle Paketmetadaten, Python-Anforderungen, Versionshistorie und einfaches Beispiel.
• Die Dokumentation der Simple-Matrix-Bot-Lib ist eine nützliche historische Referenz zur Verwendung; die Website weist jedoch darauf hin, dass sie möglicherweise veraltet ist.
• matrix-nio Dokumentation – zugrundeliegende Clientbibliothek, E2EE-Abhängigkeiten, Speicherung und Beispiele.
• Matrix Client-Server API – aktuelles Verhalten bei Authentifizierung, Anmeldung, Token, Räumen und Ereignisprotokollen.
• Matrix Application Service API – serverintegrierte Alternative für Brücken und größere Integrationen.