​

Matrix (wtyczka)

​

Wymagana wtyczka

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Konfiguracja

1. Zainstaluj wtyczkę Matrix:
   • Z npm: openclaw plugins install @openclaw/matrix
   • Z lokalnego checkoutu: openclaw plugins install ./extensions/matrix
2. Utwórz konto Matrix na homeserverze:
   • Przeglądaj opcje hostingu na https://matrix.org/ecosystem/hosting/
   • Lub hostuj samodzielnie.
3. Uzyskaj token dostępu dla konta bota:
   • Użyj API logowania Matrix z curl na swoim homeserverze:
   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"
   }'
   
   • Zastąp matrix.example.org adresem URL swojego homeservera.
   • Albo ustaw channels.matrix.userId + channels.matrix.password: OpenClaw wywołuje ten sam endpoint logowania, zapisuje token dostępu w ~/.openclaw/credentials/matrix/credentials.json i ponownie używa go przy następnym uruchomieniu.
4. Skonfiguruj poświadczenia:
   • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (lub MATRIX_USER_ID + MATRIX_PASSWORD)
   • Albo config: channels.matrix.*
   • Jeśli oba są ustawione, konfiguracja ma pierwszeństwo.
   • Przy użyciu tokenu dostępu: ID użytkownika jest pobierane automatycznie przez /whoami.
   • Gdy ustawione, channels.matrix.userId powinno być pełnym ID Matrix (przykład: @bot:example.org).
5. Zrestartuj gateway (lub zakończ onboarding).
6. Rozpocznij DM z botem lub zaproś go do pokoju z dowolnego klienta Matrix (Element, Beeper itd.; zob. https://matrix.org/ecosystem/clients/). Beeper wymaga E2EE, więc ustaw channels.matrix.encryption: true i zweryfikuj urządzenie.

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

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

​

Szyfrowanie (E2EE)

• Jeśli moduł crypto się załaduje, zaszyfrowane pokoje są odszyfrowywane automatycznie.
• Wychodzące media są szyfrowane przy wysyłaniu do zaszyfrowanych pokoi.
• Przy pierwszym połączeniu OpenClaw żąda weryfikacji urządzenia z innych sesji.
• Zweryfikuj urządzenie w innym kliencie Matrix (Element itd.), aby włączyć udostępnianie kluczy. aby włączyć udostępnianie kluczy.
• Jeśli moduł crypto nie może zostać załadowany, E2EE jest wyłączone, a zaszyfrowane pokoje nie będą odszyfrowywane; OpenClaw zapisze ostrzeżenie w logach.
• Jeśli pojawiają się błędy braku modułu crypto (np. @matrix-org/matrix-sdk-crypto-nodejs-*), zezwól na skrypty budowania dla @matrix-org/matrix-sdk-crypto-nodejs i uruchom pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs lub pobierz binarium za pomocą node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

Wiele kont

{
  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"] },
        },
      },
    },
  },
}

• Uruchamianie kont jest serializowane, aby uniknąć warunków wyścigu przy równoczesnym imporcie modułów.
• Zmienne środowiskowe (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN itp.) mają zastosowanie tylko do konta default.
• Podstawowe ustawienia kanału (polityka DM, polityka grup, ograniczenia wzmianek itp.) mają zastosowanie do wszystkich kont, chyba że zostaną nadpisane dla konkretnego konta.
• Użyj bindings[].match.accountId, aby kierować każde konto do innego agenta.
• Stan kryptograficzny jest przechowywany osobno dla każdego konta + access token (oddzielne magazyny kluczy dla każdego konta).

​

Model routingu

• Odpowiedzi zawsze wracają do Matrix.
• DM-y współdzielą główną sesję agenta; pokoje mapują się na sesje grupowe.

​

Kontrola dostępu (DM-y)

• Domyślnie: channels.matrix.dm.policy = "pairing". Nieznani nadawcy otrzymują kod parowania.
• Zatwierdzanie przez:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• Publiczne DM-y: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom akceptuje pełne ID użytkowników Matrix (przykład: @user:server). Kreator rozwiązuje nazwy wyświetlane do ID użytkowników, gdy wyszukiwanie w katalogu znajdzie jedno dokładne dopasowanie.
• Nie używaj nazw wyświetlanych ani samych localpartów (np.: “Alice” lub “alice”). Są one niejednoznaczne i są ignorowane przy dopasowywaniu listy dozwolonych. Używaj pełnych identyfikatorów @user:server.

​

Pokoje (grupy)

• Domyślnie: channels.matrix.groupPolicy = "allowlist" (wymagane wzmianki). Użyj channels.defaults.groupPolicy, aby nadpisać domyślne zachowanie, gdy nieustawione.
• Zezwalaj na pokoje przez listę dozwolonych za pomocą channels.matrix.groups (ID pokoi lub aliasy; nazwy są rozwiązywane do ID, gdy wyszukiwanie w katalogu znajdzie jedno dokładne dopasowanie):

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

• requireMention: false włącza automatyczną odpowiedź w danym pokoju.
• groups."*" może ustawić domyślne reguły wymagania wzmianek dla pokoi.
• groupAllowFrom ogranicza, którzy nadawcy mogą wyzwalać bota w pokojach (pełne ID użytkowników Matrix).
• Listy dozwolonych per pokój users mogą dodatkowo ograniczać nadawców w konkretnym pokoju (używaj pełnych ID użytkowników Matrix).
• Kreator konfiguracji pyta o listy dozwolonych pokoi (ID pokoi, aliasy lub nazwy) i rozwiązuje nazwy tylko przy dokładnym, unikalnym dopasowaniu.
• Przy starcie OpenClaw rozwiązuje nazwy pokoi/użytkowników na listach dozwolonych do ID i loguje mapowanie; nierozwiązane wpisy są ignorowane przy dopasowywaniu list dozwolonych.
• Zaproszenia są domyślnie automatycznie akceptowane; steruj za pomocą channels.matrix.autoJoin i channels.matrix.autoJoinAllowlist.
• Aby nie zezwalać na żadne pokoje, ustaw channels.matrix.groupPolicy: "disabled" (lub pozostaw pustą listę dozwolonych).
• Klucz legacy: channels.matrix.rooms (taki sam kształt jak groups).

​

Wątki

• Odpowiedzi w wątkach są obsługiwane.
• channels.matrix.threadReplies kontroluje, czy odpowiedzi pozostają w wątkach:
  • off, inbound (domyślnie), always
• channels.matrix.replyToMode kontroluje metadane reply-to, gdy odpowiedź nie jest w wątku:
  • off (domyślnie), first, all

​

Możliwości

​

Rozwiązywanie problemów

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

openclaw pairing list matrix

• Zalogowany, ale wiadomości z pokoi są ignorowane: pokój zablokowany przez groupPolicy lub listę dozwolonych pokoi.
• DM-y ignorowane: nadawca oczekuje na zatwierdzenie, gdy channels.matrix.dm.policy="pairing".
• Problemy z zaszyfrowanymi pokojami: brak obsługi crypto lub niezgodność ustawień szyfrowania.

​

Referencja konfiguracji (Matrix)

• channels.matrix.enabled: włącz/wyłącz uruchamianie kanału.
• channels.matrix.homeserver: URL homeservera.
• channels.matrix.userId: ID użytkownika Matrix (opcjonalne przy tokenie dostępu).
• channels.matrix.accessToken: token dostępu.
• channels.matrix.password: hasło do logowania (token jest zapisywany).
• channels.matrix.deviceName: nazwa wyświetlana urządzenia.
• channels.matrix.encryption: włącz E2EE (domyślnie: false).
• channels.matrix.initialSyncLimit: limit początkowej synchronizacji.
• channels.matrix.threadReplies: off | inbound | always (domyślnie: inbound).
• channels.matrix.textChunkLimit: rozmiar fragmentów tekstu wychodzącego (znaki).
• channels.matrix.chunkMode: length (domyślnie) lub newline w celu dzielenia po pustych liniach (granice akapitów) przed dzieleniem według długości.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (domyślnie: parowanie).
• channels.matrix.dm.allowFrom: lista dozwolonych DM (pełne ID użytkowników Matrix). open wymaga "*". Kreator rozwiązuje nazwy do ID, gdy to możliwe.
• channels.matrix.groupPolicy: allowlist | open | disabled (domyślnie: lista dozwolonych).
• channels.matrix.groupAllowFrom: dozwoleni nadawcy dla wiadomości grupowych (pełne ID użytkowników Matrix).
• channels.matrix.allowlistOnly: wymuś reguły list dozwolonych dla DM-ów i pokoi.
• channels.matrix.groups: lista dozwolonych grup + mapa ustawień per pokój.
• channels.matrix.rooms: legacy lista dozwolonych grup/konfiguracja.
• channels.matrix.replyToMode: tryb reply-to dla wątków/tagów.
• channels.matrix.mediaMaxMb: limit mediów przychodzących/wychodzących (MB).
• channels.matrix.autoJoin: obsługa zaproszeń (always | allowlist | off, domyślnie: zawsze).
• channels.matrix.autoJoinAllowlist: dozwolone ID/aliasy pokoi dla automatycznego dołączania.
• channels.matrix.accounts: konfiguracja wielu kont kluczowana identyfikatorem konta (każde konto dziedziczy ustawienia z najwyższego poziomu).
• channels.matrix.actions: bramkowanie narzędzi per akcja (reakcje/wiadomości/piny/memberInfo/channelInfo).