Jak skonfigurować bota Matrix za pomocą Pythona i biblioteki Simple-Matrix-Bot-Lib

Co właściwie wybierasz, budując bota Matrix w ten sposób?

Simple-Matrix-Bot-Lib to wygodna warstwa nałożona na matrix-niobibliotekę klienta Pythona. To czyni ją atrakcyjną, gdy potrzebujesz małego bota poleceń, bota powiadomień lub asystenta pokoju bez konieczności samodzielnego pisania pełnej pętli synchronizacji i obsługi zdarzeń Matrix. Wadą jest to, że akceptujesz abstrakcje i wzorce uwierzytelniania udostępniane przez wrapper, zamiast bezpośrednio kontrolować każdy szczegół klienta Matrix.

Według stanu na 6 października 2026 r. PyPI wymienia simplematrixbotlibwersję 2.13.1, wydaną 29 marca 2026 r., wymagającą Pythona w wersji 3.9 lub nowszej, ale starszej niż Python 4. Na stronie Read the Docs projektu pojawia się ostrzeżenie, że dokumentacja nie jest aktualizowana i może być nieaktualna, dlatego w tym przewodniku głównymi odniesieniami są PyPI i aktualna specyfikacja Matrix, a starsza dokumentacja traktowana jest jako wskazówka implementacyjna, a nie dowód bieżącego działania.

Sam pakiet można znaleźć w projekcie simplematrixbotlib na PyPI . Informacje o działaniu protokołu można znaleźć w aktualnej specyfikacji API Matrix Client-Server .

Simple-Matrix-Bot-Lib, matrix-nio, czy usługa aplikacji?

Jeśli Twoim celem jest „odpowiadanie na polecenia w pokojach jako jedno konto bota”, Simple-Matrix-Bot-Lib to zazwyczaj najkrótsza ścieżka. Jeśli wiesz już, że potrzebujesz niestandardowego uwierzytelniania, nietypowego zachowania synchronizacji, szczegółowej weryfikacji urządzeń lub niskopoziomowej kontroli szyfrowania, rozpoczęcie od matrix-nio może pomóc uniknąć późniejszej walki z wrapperem. W przypadku mostów lub integracji wymagających routingu na poziomie serwera domowego, zapoznaj się z API usługi aplikacji Matrix , zamiast traktować zwykłe konto bota jako substytut.

Krok 1: Wybierz serwer domowy i potwierdź, w jaki sposób bot może się zalogować

Bot Matrix potrzebuje konta użytkownika Matrix na serwerze domowym. Możesz użyć publicznego serwera domowego, który umożliwia tworzenie kont, lub konta na serwerze domowym, którym administrujesz. Oddziel bota od swojej osobistej tożsamości Matrix, aby uprawnienia, członkostwo w pokojach i dane uwierzytelniające mogły być zarządzane niezależnie.

Ważną decyzją jest uwierzytelnianie. Obecna specyfikacja Matrix obsługuje zarówno starsze API uwierzytelniania, jak i OAuth 2.0. Serwer domowy może udostępniać jeden lub oba. Opublikowane przykłady szybkiego startu w bibliotece Simple-Matrix-Bot-Lib wykorzystują adres URL serwera domowego, nazwę użytkownika i hasło, dlatego w tym samouczku zakłada się, że serwer nadal oferuje zgodny sposób logowania za pomocą hasła.

Przed napisaniem kodu sprawdź metody logowania udostępniane przez Twój serwer domowy:

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

Jeśli odpowiedź zawiera przepływ logowania z hasłem, poniższy przykład oparty na poświadczeniach jest odpowiedni. Jeśli serwer obsługuje tylko SSO lub OAuth, nie wymuszaj hasła w przykładzie. W takiej sytuacji sprawdź obsługę uwierzytelniania w aktualnej wersji biblioteki lub użyj klienta niższego poziomu, który obsługuje potrzebny przepływ. Specyfikacja Matrix wyjaśnia wykrywanie logowania i obsługę tokenów w sekcji logowania interfejsu API klient-serwer .

Krok 2: Utwórz odizolowane środowisko Python i zainstaluj bibliotekę

Użyj środowiska wirtualnego, aby oddzielić zależności bota od systemowego Pythona i niezwiązanych z nim projektów. Obecne metadane PyPI wymagają Pythona w wersji 3.9 lub nowszej.

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

W programie Windows PowerShell aktywuj środowisko za pomocą:

.venv\Scripts\Activate.ps1

Sprawdź, co zostało zainstalowane, zamiast zakładać, że jest to wersja ze starego samouczka:

python -m pip show simplematrixbotlib

To sprawdzenie wersji ma znaczenie, ponieważ publiczne strony „Czytaj dokumenty” nadal wyświetlają starszą dokumentację i wyraźnie ostrzegają, że może być ona nieaktualna. Jeśli przykład z tych stron koliduje z zainstalowanym pakietem, sprawdź metadane wydania i aktualne repozytorium przed zmianą kodu, aby był zgodny ze starszą stroną.

Czy potrzebujesz szyfrowania typu end-to-end?

Nie każdy bot to robi. Bot, który dołącza tylko do niezaszyfrowanych sal operacyjnych, jest prostszy do wdrożenia i nie musi utrzymywać stanu szyfrowania. Bot, który ma odczytywać i odpowiadać w zaszyfrowanych salach, potrzebuje dodatkowych zależności i trwałego stanu szyfrowania.

Zarówno dokumentacja Simple-Matrix-Bot-Lib, jak i aktualna dokumentacja matrix-nio wskazują, że E2EE opiera się na obsłudze szyfrowania matrix-nio i libolm. W systemach Debian lub Ubuntu należy zainstalować dokumenty matrix-nio, libolm-deva następnie zainstalować dodatek E2EE:

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

Nie włączaj E2EE tylko dlatego, że Matrix to obsługuje. Użyj go, gdy pokoje wymagają szyfrowania i jesteś gotowy na zapisanie pamięci bota i obsługę zaufania do urządzenia. Dokumentacja Matrix-nio informuje, że stan szyfrowania, klucze i zaufanie do urządzenia są przechowywane lokalnie po włączeniu E2EE.

Krok 3: Utwórz konto bota i nie udostępniaj danych uwierzytelniających w kodzie źródłowym

Utwórz dedykowane konto Matrix za pomocą klienta lub procesu zarządzania kontem udostępnianego przez serwer domowy. Dokładny interfejs użytkownika różni się w zależności od dostawcy, dlatego niniejszy przewodnik nie zakłada konkretnego ekranu Element ani nie twierdzi, że otwarta rejestracja jest dostępna wszędzie.

Na potrzeby rozwoju wyeksportuj trzy zmienne środowiskowe:

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

Zmienne środowiskowe są wygodne w przypadku lokalnego samouczka, ale nie stanowią automatycznie systemu zarządzania sekretami klasy produkcyjnej. Na platformie VPS lub kontenerowej preferuj magazyn sekretów platformy, chroniony plik środowiska poza kontrolą kodu źródłowego lub dedykowany menedżer sekretów. Nigdy nie wprowadzaj hasła ani tokena dostępu do Matrixa w Git.

Zaproś konto bota do pokoju testowego i zaakceptuj zaproszenie za pomocą klienta Matrix, jeśli konfiguracja serwera lub bota nie obsługuje automatycznego dołączania do zaproszeń. Zacznij od prywatnego pokoju testowego. Ograniczy to ryzyko przypadkowego wykonania polecenia podczas walidacji zachowania bota.

Krok 4: Napisz, uruchom i przetestuj minimalnego bota poleceń

Utwórz bot.pyza pomocą krótkiego !pingpolecenia. Poniższa struktura jest zgodna z przykładem pakietu publicznego: create Creds, create Bot, dodaj asynchroniczny nasłuchiwacz wiadomości, use MessageMatchi wyślij wiadomość tekstową przez 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()

Uruchom go z aktywowanego środowiska wirtualnego:

python bot.py

W sali testowej należy wysłać:

!ping

Sukces jest prosty: bot pozostaje połączony, widzi zdarzenie w pokoju i odpowiada Pong!. Należy również upewnić się, że nie odpowiada na własną odpowiedź. To is_not_from_this_bot()sprawdzenie jest ważne, ponieważ naiwny bot typu echo może w przeciwnym razie tworzyć pętle sprzężenia zwrotnego.

Kiedy należy dodać listę dozwolonych?

Dodaj jeden, zanim bot będzie mógł uruchomić cokolwiek wrażliwego. Polecenie, które zwraca jedynie „Pong!”, ma niewielki wpływ, ale polecenie uruchamiające zadania wdrożeniowe, wysyłające zapytania do systemów wewnętrznych lub publikujące poufne dane, nie powinno być wykonywane dla każdego użytkownika w każdym dołączonym pokoju.

Simple-Matrix-Bot-Lib reklamuje zarządzanie dostępem użytkowników i konfigurację listy dozwolonych/blokowanych jako funkcje. W przypadku bota produkcyjnego autoryzację należy traktować jako logikę aplikacji, a nie jako opcjonalny krok dopracowujący. Ograniczaj dostęp według identyfikatora użytkownika, identyfikatora pokoju lub obu, a uprawnienia po stronie serwera w systemach podrzędnych zachowaj jako drugą linię obrony.

Logowanie hasłem kontra tokeny dostępu: jaki jest praktyczny kompromis?

Logowanie za pomocą hasła jest łatwe do zrozumienia i zgodne z opublikowanym minimalnym przykładem pakietu. Wadą jest to, że długo działający bot musi znać hasło do konta, a niektóre nowoczesne wdrożenia Matrix mogą preferować przepływy SSO lub OAuth.

Tokeny dostępu redukują konieczność wielokrotnego użycia haseł, ale zasady cyklu życia tokenów zależą od systemu uwierzytelniania. Specyfikacja Matrix stanowi, że tokeny dostępu powinny być traktowane jako nieprzezroczyste dane uwierzytelniające i przesyłane za pomocą Authorization: Bearerprotokołu HTTP. Aktualne wersje Matrix obsługują również wygasające tokeny dostępu i tokeny odświeżania w niektórych przepływach. Nie należy zakładać, że przykład napisany dla danych uwierzytelniających hasła automatycznie obsługuje odświeżanie, unieważnianie lub uwierzytelnianie OAuth.

Jeśli cykl życia tokena, SSO, OAuth lub uwierzytelnianie w stylu konta usługi są kluczowe dla Twojego wdrożenia, sprawdź tę funkcjonalność w konkretnej wersji Simple-Matrix-Bot-Lib, którą instalujesz. Jeśli wrapper nie zapewnia wystarczającej kontroli, użycie matrix-nio bezpośrednio jest bardziej przejrzystym wyborem inżynieryjnym.

Czy powinieneś uruchomić bota na laptopie, serwerze VPS, kontenerze czy Kubernetesie?

W przypadku niezaszyfrowanego, lekkiego bota zazwyczaj wystarczy mała maszyna wirtualna lub kontener. W przypadku zaszyfrowanego bota trwałość staje się wymogiem projektowym: utrata lokalnego magazynu kryptograficznego może zmienić tożsamość urządzenia i zniweczyć zaufanie. Przykłady E2EE firmy Matrix-nio kładą nacisk na zachowanie identyfikatora urządzenia i magazynu szyfrującego po ponownym uruchomieniu.

Typowe błędy konfiguracji i ich znaczenie

• Logowanie natychmiast kończy się niepowodzeniem: sprawdź adres URL serwera domowego i sprawdź /_matrix/client/v3/login. Serwer, który nie reklamuje logowania hasłem, może nie działać z szybkim startem opartym na haśle.
• Bot uruchamia się, ale nigdy nie widzi wiadomości: sprawdź, czy konto bota jest rzeczywiście dołączone do pokoju i czy przeprowadzasz test przy użyciu zwykłego zdarzenia tekstowego.
• Bot odpowiada wielokrotnie: upewnij się, że obsługujący ignoruje zdarzenia wysyłane przez samego bota.
• Zaszyfrowane pokoje są nieczytelne: instalacja pakietu bazowego nie wystarczy. Dodaj zależności E2EE matrix-nio, włącz szyfrowanie zgodnie z konfiguracją biblioteki i zachowaj magazyn kryptograficzny.
• Stary przykład zgłasza błąd API: sprawdź zainstalowaną wersję pakietu. Publiczna dokumentacja Simple-Matrix-Bot-Lib ostrzega obecnie, że nie jest rozwijana, więc przykłady mogą być opóźnione w stosunku do wydania PyPI.

Którą ścieżkę powinieneś wybrać?

Wybierz Simple-Matrix-Bot-Lib, jeśli Twój bot jest jednym użytkownikiem Matrix, Twoje polecenia są proste, a zwięzły kod Pythona cenisz bardziej niż niskopoziomową kontrolę protokołu. Jest to szczególnie przydatne w prototypach, botach powiadomień, narzędziach pokojowych i małych automatyzacjach wewnętrznych.

Wybierz Matrix-nio bezpośrednio, gdy szyfrowanie, weryfikacja urządzeń, niestandardowe uwierzytelnianie, typy zdarzeń, zachowanie synchronizacji lub zarządzanie tokenami są kluczowymi wymaganiami. Będziesz pisać więcej kodu, ale granica abstrakcji jest niższa i łatwiejsza do uwzględnienia w zaawansowanych pracach z Matrix.

Wybierz usługę aplikacji, jeśli Twoja integracja jest rozszerzeniem, mostem lub bramą serwera domowego, a nie botem dla pojedynczego użytkownika. Interfejs API usługi aplikacji jest zaprojektowany dla tego modelu połączenia z serwerem i wymaga konfiguracji serwera domowego.

W przypadku pierwszego bota Matrix, minimalnym !pingprzykładem jest dobry punkt kontrolny: jeśli potrafi się uwierzytelnić, dołączyć do właściwego pokoju, zignorować własne zdarzenia i niezawodnie odpowiedzieć, podstawowa ścieżka została zweryfikowana. Dodaj szyfrowanie, autoryzację, zewnętrzne API i automatyzację wdrażania dopiero po ustabilizowaniu się fundamentu.

Główne odniesienia

• Simple-Matrix-Bot-Lib na PyPI — aktualne metadane pakietu, wymagania Pythona, historia wydań i podstawowy przykład.
• Dokumentacja Simple-Matrix-Bot-Lib — przydatne odniesienie do historii wykorzystania; witryna ostrzega, że ​​dokumentacja może być nieaktualna.
• Dokumentacja matrix-nio — podstawowa biblioteka kliencka, zależności E2EE, magazyn i przykłady.
• Matrix Client-Server API — aktualne zachowanie protokołu uwierzytelniania, logowania, tokenów, pomieszczeń i zdarzeń.
• Matrix Application Service API — zintegrowana z serwerem alternatywa dla mostów i większych integracji.