Matrix (plugin)

Matrix to otwarty, zdecentralizowany protokol wiadomosci. OpenClaw laczy sie jako uzytkownik Matrix na dowolnym serwerze domowym, wiec potrzebujesz konta Matrix dla bota. Po zalogowaniu mozesz wyslac DM bezposrednio do bota lub zaprosic go do pokoi (Matrix “grupy”). Beeper jest rowniez prawidlowa opcja klienta, ale wymaga wlaczenia E2EE.

Status: obslugiwany przez plugin (@vector-im/matrix-bot-sdk). Wiadomosci bezposrednie, pokoje, watki, media, reakcje, ankiety (wysylanie + poll-start jako tekst), lokalizacja i E2EE (z obsluga kryptografii).

Wymagany plugin

Matrix jest dostarczany jako plugin i nie jest dolaczony do instalacji podstawowej.

Instalacja przez CLI (rejestr npm):

openclaw plugins install @openclaw/matrix

Lokalny checkout (przy uruchomieniu z repozytorium git):

openclaw plugins install ./extensions/matrix

Jesli wybierzesz Matrix podczas konfiguracji/onboardingu i zostanie wykryty checkout git, OpenClaw automatycznie zaproponuje sciezke instalacji lokalnej.

Szczegoly: Pluginy

Konfiguracja

  1. Zainstaluj plugin Matrix:

    • Z npm: openclaw plugins install @openclaw/matrix
    • Z lokalnego checkoutu: openclaw plugins install ./extensions/matrix

  2. Utworz konto Matrix na serwerze domowym:

  3. Uzyskaj token dostepu dla konta bota:

    • Uzyj API logowania Matrix z curl na swoim serwerze domowym:
    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"
}'
    • Zastap matrix.example.org URL-em twojego serwera domowego.
    • Lub ustaw channels.matrix.userId + channels.matrix.password: OpenClaw wywola ten sam endpoint logowania, przechowa token dostepu w ~/.openclaw/credentials/matrix/credentials.json i uzyje go ponownie przy nastepnym starcie.

  4. Skonfiguruj dane logowania:

    • Zmienne: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (lub MATRIX_USER_ID + MATRIX_PASSWORD)
    • Lub konfiguracja: channels.matrix.*
    • Jesli oba sa ustawione, konfiguracja ma pierwszenstwo.
    • Z tokenem dostepu: ID uzytkownika jest pobierane automatycznie przez /whoami.
    • Gdy ustawione, channels.matrix.userId powinno byc pelnym ID Matrix (przyklad: @bot:example.org).

  5. Zrestartuj gateway (lub zakoncz onboarding).

  6. Zacznij DM z botem lub zapros go do pokoju z dowolnego klienta Matrix (Element, Beeper itp.; zobacz https://matrix.org/ecosystem/clients/). Beeper wymaga E2EE, wiec ustaw channels.matrix.encryption: true i zweryfikuj urzadzenie.

Minimalna konfiguracja (token dostepu, ID uzytkownika pobierany automatycznie):

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

Konfiguracja E2EE (szyfrowanie end-to-end wlaczone):

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

Szyfrowanie (E2EE)

Szyfrowanie end-to-end jest obslugiwane przez Rust crypto SDK.

Wlacz z channels.matrix.encryption: true:

  • Jesli modul kryptograficzny sie zaladuje, zaszyfrowane pokoje sa automatycznie deszyfrowane.
  • Media wychodzace sa szyfrowane podczas wysylania do zaszyfrowanych pokoi.
  • Przy pierwszym polaczeniu OpenClaw prosi o weryfikacje urzadzenia z twoich pozostalych sesji.
  • Zweryfikuj urzadzenie w innym kliencie Matrix (Element itp.) aby wlaczyc wspoldzielenie kluczy.
  • Jesli modul kryptograficzny nie moze zostac zaladowany, E2EE jest wylaczone i zaszyfrowane pokoje nie beda deszyfrowane; OpenClaw loguje ostrzezenie.
  • Jesli widzisz bledy brakujacego modulu kryptograficznego (np. @matrix-org/matrix-sdk-crypto-nodejs-*), zezwol na skrypty budowania dla @matrix-org/matrix-sdk-crypto-nodejs i uruchom pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs lub pobierz plik binarny przez node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Stan kryptografii jest przechowywany per konto + token dostepu w ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (baza SQLite). Stan synchronizacji jest obok w bot-storage.json. Jesli token dostepu (urzadzenie) sie zmieni, tworzony jest nowy magazyn i bot musi byc ponownie zweryfikowany dla zaszyfrowanych pokoi.

Weryfikacja urzadzenia: Gdy E2EE jest wlaczone, bot prosi o weryfikacje z twoich pozostalych sesji przy starcie. Otworz Element (lub innego klienta) i zatwierdz zadanie weryfikacji, aby ustanowic zaufanie. Po weryfikacji bot moze deszyfrowac wiadomosci w zaszyfrowanych pokojach.

Wiele kont

Obsluga wielu kont: uzyj channels.matrix.accounts z danymi logowania per konto i opcjonalnym name. Zobacz gateway/configuration dla wspolnego wzorca.

Kazde konto dziala jako oddzielny uzytkownik Matrix na dowolnym serwerze domowym. Konfiguracja per konto dziedziczy z ustawien najwyzszego poziomu channels.matrix i moze nadpisac dowolna opcje (polityke DM, grupy, szyfrowanie itp.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Uwagi:

  • Start kont jest serializowany aby unikac wyscigów z jednoczesnym importem modulow.
  • Zmienne srodowiskowe (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN itp.) dotycza tylko konta default.
  • Bazowe ustawienia kanalu (polityka DM, polityka grupowa, bramkowanie wzmiankami itp.) dotycza wszystkich kont, chyba ze nadpisane per konto.
  • Uzyj bindings[].match.accountId aby routowac kazde konto do innego agenta.
  • Stan kryptografii jest przechowywany per konto + token dostepu (oddzielne magazyny kluczy per konto).

Model routingu

  • Odpowiedzi zawsze wracaja do Matrix.
  • DM wspoldziela glowna sesje agenta; pokoje mapuja sie na sesje grupowe.

Kontrola dostepu (DM)

  • Domyslnie: channels.matrix.dm.policy = "pairing". Nieznani nadawcy otrzymuja kod parowania.
  • Zatwierdzanie przez:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • Publiczne DM: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom akceptuje pelne ID uzytkownikow Matrix (przyklad: @user:server). Kreator rozwiazuje nazwy wyswietlane na ID uzytkownikow gdy wyszukiwanie katalogowe znajdzie dokladnie jedno dopasowanie.
  • Nie uzywaj nazw wyswietlanych ani samych czesci lokalnych (przyklad: "Alice" lub "alice"). Sa niejednoznaczne i sa ignorowane przy dopasowywaniu list dozwolonych. Uzywaj pelnych ID @user:server.

Pokoje (grupy)

  • Domyslnie: channels.matrix.groupPolicy = "allowlist" (bramkowane wzmiankami). Uzyj channels.defaults.groupPolicy aby nadpisac domyslne gdy nie ustawione.
  • Uwaga runtime: jesli channels.matrix calkowicie brakuje, runtime stosuje zastepczym groupPolicy="allowlist" dla sprawdzen pokoi (nawet jesli channels.defaults.groupPolicy jest ustawione).
  • Dodaj pokoje do listy dozwolonych przez channels.matrix.groups (ID pokoi lub aliasy; nazwy sa rozwiazywane na ID gdy wyszukiwanie katalogowe znajdzie dokladnie jedno dopasowanie):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false wlacza automatyczne odpowiedzi w tym pokoju.
  • groups."*" moze ustawiac domyslne bramkowania wzmiankami miedzy pokojami.
  • groupAllowFrom ogranicza, ktorzy nadawcy moga wyzwalac bota w pokojach (pelne ID uzytkownikow Matrix).
  • Listy dozwolonych users per pokoj moga dodatkowo ograniczac nadawcow wewnatrz konkretnego pokoju (uzyj pelnych ID uzytkownikow Matrix).
  • Kreator konfiguracji pyta o listy dozwolonych pokoi (ID pokoi, aliasy lub nazwy) i rozwiazuje nazwy tylko przy dokladnym, unikalnym dopasowaniu.
  • Przy starcie OpenClaw rozwiazuje nazwy pokoi/uzytkownikow w listach dozwolonych na ID i loguje mapowanie; nierozwiazane wpisy sa ignorowane przy dopasowywaniu list dozwolonych.
  • Zaproszenia sa domyslnie automatycznie akceptowane; kontroluj przez channels.matrix.autoJoin i channels.matrix.autoJoinAllowlist.
  • Aby nie zezwalac na zadne pokoje, ustaw channels.matrix.groupPolicy: "disabled" (lub zachowaj pusta liste dozwolonych).
  • Stary klucz: channels.matrix.rooms (ten sam ksztalt co groups).

Watki

  • Odpowiedzi w watkach sa obslugiwane.
  • channels.matrix.threadReplies kontroluje, czy odpowiedzi pozostaja w watkach:
    • off, inbound (domyslnie), always
  • channels.matrix.replyToMode kontroluje metadane reply-to gdy nie odpowiadamy w watku:
    • off (domyslnie), first, all

Mozliwosci

FunkcjaStatus
Wiadomosci bezposrednieObslugiwane
PokojeObslugiwane
WatkiObslugiwane
MediaObslugiwane
E2EEObslugiwane (wymagany modul kryptograficzny)
ReakcjeObslugiwane (wysylanie/odczyt przez narzedzia)
AnkietyWysylanie obslugiwane; przychodzace poll-start sa konwertowane na tekst (odpowiedzi/konce ignorowane)
LokalizacjaObslugiwane (geo URI; wysokosc ignorowana)
Natywne poleceniaObslugiwane

Rozwiazywanie problemow

Najpierw uruchom te polecenia:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Nastepnie potwierdz stan parowania DM jesli potrzeba:

openclaw pairing list matrix

Czeste bledy:

  • Zalogowany, ale wiadomosci pokoju ignorowane: pokoj zablokowany przez groupPolicy lub liste dozwolonych pokoi.
  • DM ignorowane: nadawca oczekuje na zatwierdzenie parowania gdy channels.matrix.dm.policy="pairing".
  • Zaszyfrowane pokoje nie dzialaja: niezgodnosc obslugi kryptografii lub ustawien szyfrowania.

Przeplyw diagnostyczny: /channels/troubleshooting.

Referencja konfiguracji (Matrix)

Pelna konfiguracja: Konfiguracja

Opcje dostawcy:

  • channels.matrix.enabled: wlaczenie/wylaczenie startu kanalu.
  • channels.matrix.homeserver: URL serwera domowego.
  • channels.matrix.userId: ID uzytkownika Matrix (opcjonalne z tokenem dostepu).
  • channels.matrix.accessToken: token dostepu.
  • channels.matrix.password: haslo do logowania (token przechowywany).
  • channels.matrix.deviceName: wyswietlana nazwa urzadzenia.
  • channels.matrix.encryption: wlaczenie E2EE (domyslnie: false).
  • channels.matrix.initialSyncLimit: limit poczatkowej synchronizacji.
  • channels.matrix.threadReplies: off | inbound | always (domyslnie: inbound).
  • channels.matrix.textChunkLimit: rozmiar kawalka tekstu wychodzacego (znaki).
  • channels.matrix.chunkMode: length (domyslnie) lub newline aby dzielic na pustych liniach (granice akapitow) przed dzieleniem wedlug dlugosci.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (domyslnie: pairing).
  • channels.matrix.dm.allowFrom: lista dozwolonych DM (pelne ID uzytkownikow Matrix). open wymaga "*". Kreator rozwiazuje nazwy na ID gdy to mozliwe.
  • channels.matrix.groupPolicy: allowlist | open | disabled (domyslnie: allowlist).
  • channels.matrix.groupAllowFrom: dozwoleni nadawcy dla wiadomosci grupowych (pelne ID uzytkownikow Matrix).
  • channels.matrix.allowlistOnly: wymuszenie regul listy dozwolonych dla DM + pokoi.
  • channels.matrix.groups: lista dozwolonych grup + mapa ustawien per pokoj.
  • channels.matrix.rooms: stara lista dozwolonych/konfiguracja grup.
  • channels.matrix.replyToMode: tryb reply-to dla watkow/tagow.
  • channels.matrix.mediaMaxMb: limit mediow przychodzacych/wychodzacych (MB).
  • channels.matrix.autoJoin: obsluga zaproszen (always | allowlist | off, domyslnie: always).
  • channels.matrix.autoJoinAllowlist: dozwolone ID/aliasy pokoi do automatycznego dolaczenia.
  • channels.matrix.accounts: konfiguracja wielokontowa z kluczem ID konta (kazde konto dziedziczy ustawienia najwyzszego poziomu).
  • channels.matrix.actions: bramkowanie narzedzi per akcje (reakcje/wiadomosci/piny/memberInfo/channelInfo).
arrow_back
Poprzedni
Line
Następny
Mattermost
arrow_forward