Matrix
Matrix to dołączona wtyczka kanału Matrix dla OpenClaw. Korzysta z oficjalnegomatrix-js-sdk i obsługuje DM-y, pokoje, wątki, multimedia, reakcje, ankiety, lokalizację oraz E2EE.
Dołączona wtyczka
Matrix jest dostarczany jako dołączona wtyczka w bieżących wydaniach OpenClaw, więc zwykłe spakowane kompilacje nie wymagają osobnej instalacji. Jeśli używasz starszej kompilacji lub niestandardowej instalacji, która nie zawiera Matrix, zainstaluj go ręcznie: Zainstaluj z npm:Konfiguracja
- Upewnij się, że wtyczka Matrix jest dostępna.
- Bieżące spakowane wydania OpenClaw już ją zawierają.
- Starsze/niestandardowe instalacje mogą dodać ją ręcznie za pomocą powyższych poleceń.
- Utwórz konto Matrix na swoim homeserverze.
- Skonfiguruj
channels.matrix, używając jednego z wariantów:homeserver+accessToken, lubhomeserver+userId+password.
- Uruchom ponownie gateway.
- Rozpocznij DM z botem lub zaproś go do pokoju.
- adres URL homeservera
- metoda uwierzytelniania: access token lub hasło
- identyfikator użytkownika tylko wtedy, gdy wybierzesz uwierzytelnianie hasłem
- opcjonalna nazwa urządzenia
- czy włączyć E2EE
- czy skonfigurować teraz dostęp do pokoi Matrix
- Jeśli zmienne środowiskowe uwierzytelniania Matrix już istnieją dla wybranego konta, a to konto nie ma jeszcze zapisanego uwierzytelniania w konfiguracji, kreator oferuje skrót przez env i zapisuje dla tego konta tylko
enabled: true. - Gdy interaktywnie dodajesz kolejne konto Matrix, wprowadzona nazwa konta jest normalizowana do identyfikatora konta używanego w konfiguracji i zmiennych środowiskowych. Na przykład
Ops Botstaje sięops-bot. - Monity allowlisty DM akceptują od razu pełne wartości
@user:server. Same nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie jedno dokładne dopasowanie; w przeciwnym razie kreator prosi o ponowną próbę z pełnym identyfikatorem Matrix. - Monity allowlisty pokoi akceptują bezpośrednio identyfikatory pokoi i aliasy. Mogą także rozwiązywać nazwy dołączonych pokoi na żywo, ale nierozwiązane nazwy są podczas konfiguracji zachowywane tylko w formie wpisanej i później są ignorowane przez rozwiązywanie allowlisty w runtime. Preferuj
!room:serverlub#alias:server. - Tożsamość pokoju/sesji w runtime używa stabilnego identyfikatora pokoju Matrix. Aliasy zadeklarowane dla pokoju są używane tylko jako dane wejściowe do wyszukiwania, a nie jako długoterminowy klucz sesji lub stabilna tożsamość grupy.
- Aby rozwiązać nazwy pokoi przed ich zapisaniem, użyj
openclaw channels resolve --channel matrix "Project Room".
~/.openclaw/credentials/matrix/.
Konto domyślne używa credentials.json; nazwane konta używają credentials-<account>.json.
Odpowiedniki zmiennych środowiskowych (używane, gdy klucz konfiguracji nie jest ustawiony):
MATRIX_HOMESERVERMATRIX_ACCESS_TOKENMATRIX_USER_IDMATRIX_PASSWORDMATRIX_DEVICE_IDMATRIX_DEVICE_NAME
MATRIX_<ACCOUNT_ID>_HOMESERVERMATRIX_<ACCOUNT_ID>_ACCESS_TOKENMATRIX_<ACCOUNT_ID>_USER_IDMATRIX_<ACCOUNT_ID>_PASSWORDMATRIX_<ACCOUNT_ID>_DEVICE_IDMATRIX_<ACCOUNT_ID>_DEVICE_NAME
ops:
MATRIX_OPS_HOMESERVERMATRIX_OPS_ACCESS_TOKEN
ops-bot użyj:
MATRIX_OPS_X2D_BOT_HOMESERVERMATRIX_OPS_X2D_BOT_ACCESS_TOKEN
- staje się _X2D_, więc ops-prod mapuje się na MATRIX_OPS_X2D_PROD_*.
Interaktywny kreator oferuje skrót przez zmienne środowiskowe tylko wtedy, gdy te zmienne uwierzytelniania są już obecne i wybrane konto nie ma już zapisanego uwierzytelniania Matrix w konfiguracji.
Przykład konfiguracji
To praktyczna konfiguracja bazowa z parowaniem DM, allowlistą pokoi i włączonym E2EE:Podglądy strumieniowania
Strumieniowanie odpowiedzi Matrix jest opcjonalne. Ustawchannels.matrix.streaming na "partial", jeśli chcesz, aby OpenClaw wysłał jedną roboczą odpowiedź,
edytował ją w miejscu podczas generowania tekstu przez model, a następnie sfinalizował ją po
zakończeniu odpowiedzi:
streaming: "off"to ustawienie domyślne. OpenClaw czeka na końcową odpowiedź i wysyła ją tylko raz.streaming: "partial"tworzy jedną edytowalną wiadomość podglądu dla bieżącego bloku asystenta zamiast wysyłać wiele częściowych wiadomości.blockStreaming: truewłącza osobne wiadomości postępu Matrix. Przystreaming: "partial"Matrix zachowuje roboczy podgląd na żywo dla bieżącego bloku i pozostawia ukończone bloki jako osobne wiadomości.- Gdy
streaming: "partial"jest włączone, ablockStreamingwyłączone, Matrix tylko edytuje podgląd na żywo i wysyła ukończoną odpowiedź po zakończeniu tego bloku lub tury. - Jeśli podgląd przestaje mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje strumieniowanie podglądu i wraca do zwykłego dostarczenia końcowego.
- Odpowiedzi multimedialne nadal wysyłają załączniki normalnie. Jeśli nieaktualnego podglądu nie da się już bezpiecznie ponownie użyć, OpenClaw redaguje go przed wysłaniem końcowej odpowiedzi multimedialnej.
- Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw strumieniowanie wyłączone, jeśli chcesz zachować najbardziej konserwatywne zachowanie względem limitów szybkości.
blockStreaming samo w sobie nie włącza roboczych podglądów.
Użyj streaming: "partial" dla edycji podglądu, a następnie dodaj blockStreaming: true tylko wtedy, gdy chcesz także, aby ukończone bloki asystenta pozostawały widoczne jako osobne wiadomości postępu.
Szyfrowanie i weryfikacja
W zaszyfrowanych pokojach (E2EE) wychodzące zdarzenia obrazów używająthumbnail_file, dzięki czemu podglądy obrazów są szyfrowane razem z pełnym załącznikiem. Pokoje nieszyfrowane nadal używają zwykłego thumbnail_url. Konfiguracja nie jest wymagana — wtyczka automatycznie wykrywa stan E2EE.
Pokoje bot-bot
Domyślnie wiadomości Matrix z innych skonfigurowanych kont Matrix OpenClaw są ignorowane. UżyjallowBots, jeśli celowo chcesz dopuścić ruch Matrix między agentami:
allowBots: trueakceptuje wiadomości z innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i DM-ach.allowBots: "mentions"akceptuje te wiadomości tylko wtedy, gdy w pokojach wyraźnie wspominają tego bota. DM-y nadal są dozwolone.groups.<room>.allowBotsnadpisuje ustawienie na poziomie konta dla jednego pokoju.- OpenClaw nadal ignoruje wiadomości z tego samego identyfikatora użytkownika Matrix, aby uniknąć pętli odpowiedzi do samego siebie.
- Matrix nie udostępnia tu natywnej flagi bota; OpenClaw traktuje „napisane przez bota” jako „wysłane przez inne skonfigurowane konto Matrix na tym gateway OpenClaw”.
channels.matrix.accounts z poświadczeniami per konto i opcjonalnym name. Zobacz Dokumentacja konfiguracji, aby poznać wspólny wzorzec.
Szczegółowa diagnostyka bootstrap:
verify są domyślnie zwięzłe (łącznie z cichym wewnętrznym logowaniem SDK) i pokazują szczegółową diagnostykę tylko z --verbose.
Do skryptów użyj --json, aby uzyskać pełne wyjście czytelne maszynowo.
W konfiguracjach wielokontowych polecenia Matrix CLI używają domyślnego niejawnego konta Matrix, chyba że przekażesz --account <id>.
Jeśli skonfigurujesz wiele nazwanych kont, najpierw ustaw channels.matrix.defaultAccount, w przeciwnym razie te niejawne operacje CLI zatrzymają się i poproszą o jawny wybór konta.
Używaj --account, gdy chcesz, aby operacje weryfikacji lub urządzeń były jawnie kierowane do nazwanego konta:
channels.matrix.accounts.assistant.encryption.
Co oznacza „zweryfikowane”
OpenClaw traktuje to urządzenie Matrix jako zweryfikowane tylko wtedy, gdy zostało zweryfikowane przez własną tożsamość cross-signing. W praktyceopenclaw matrix verify status --verbose pokazuje trzy sygnały zaufania:
Locally trusted: to urządzenie jest zaufane tylko przez bieżącego klientaCross-signing verified: SDK zgłasza urządzenie jako zweryfikowane przez cross-signingSigned by owner: urządzenie jest podpisane przez Twój własny klucz self-signing
Verified by owner przyjmuje wartość yes tylko wtedy, gdy obecna jest weryfikacja cross-signing lub podpis właściciela.
Samo lokalne zaufanie nie wystarcza, aby OpenClaw traktował urządzenie jako w pełni zweryfikowane.
Co robi bootstrap
openclaw matrix verify bootstrap to polecenie naprawy i konfiguracji dla zaszyfrowanych kont Matrix.
Wykonuje ono po kolei wszystkie poniższe czynności:
- inicjalizuje sekretne przechowywanie, ponownie używając istniejącego klucza odzyskiwania, gdy to możliwe
- inicjalizuje cross-signing i wysyła brakujące publiczne klucze cross-signing
- próbuje oznaczyć i podpisać bieżące urządzenie przez cross-signing
- tworzy nową kopię zapasową kluczy pokoju po stronie serwera, jeśli jeszcze nie istnieje
m.login.dummy, a następnie z m.login.password, gdy skonfigurowane jest channels.matrix.password.
Używaj --force-reset-cross-signing tylko wtedy, gdy celowo chcesz odrzucić bieżącą tożsamość cross-signing i utworzyć nową.
Jeśli celowo chcesz odrzucić bieżącą kopię zapasową kluczy pokoju i rozpocząć nową
bazową kopię zapasową dla przyszłych wiadomości, użyj openclaw matrix verify backup reset --yes.
Rób to tylko wtedy, gdy akceptujesz, że nieodwracalnie utracona stara zaszyfrowana historia pozostanie
niedostępna i że OpenClaw może odtworzyć sekretne przechowywanie, jeśli bieżącego sekretu
kopii zapasowej nie da się bezpiecznie załadować.
Nowa bazowa kopia zapasowa
Jeśli chcesz zachować działanie przyszłych zaszyfrowanych wiadomości i akceptujesz utratę nieodzyskiwalnej starej historii, uruchom te polecenia po kolei:--account <id> do każdego polecenia, gdy chcesz jawnie wskazać nazwane konto Matrix.
Zachowanie przy uruchamianiu
Gdyencryption: true, Matrix domyślnie ustawia startupVerification na "if-unverified".
Przy uruchamianiu, jeśli to urządzenie nadal nie jest zweryfikowane, Matrix poprosi o self-verification w innym kliencie Matrix,
pominie duplikaty żądań, gdy jedno jest już oczekujące, i zastosuje lokalny cooldown przed ponowną próbą po restartach.
Nieudane próby żądań są domyślnie ponawiane szybciej niż udane utworzenie żądania.
Ustaw startupVerification: "off", aby wyłączyć automatyczne żądania przy uruchamianiu, albo dostosuj startupVerificationCooldownHours,
jeśli chcesz krótsze lub dłuższe okno ponawiania.
Przy uruchamianiu automatycznie wykonywany jest również konserwatywny przebieg bootstrap kryptograficznego.
Ten przebieg najpierw próbuje ponownie użyć bieżącego sekretnego przechowywania i tożsamości cross-signing oraz unika resetowania cross-signing, chyba że uruchomisz jawny przepływ naprawy bootstrap.
Jeśli podczas uruchamiania zostanie wykryty uszkodzony stan bootstrap i skonfigurowane jest channels.matrix.password, OpenClaw może spróbować bardziej rygorystycznej ścieżki naprawy.
Jeśli bieżące urządzenie jest już podpisane przez właściciela, OpenClaw zachowuje tę tożsamość zamiast resetować ją automatycznie.
Aktualizacja z poprzedniej publicznej wtyczki Matrix:
- OpenClaw automatycznie ponownie używa tego samego konta Matrix, access tokena i tożsamości urządzenia, gdy to możliwe.
- Zanim zostaną wykonane jakiekolwiek działania migracyjne Matrix, OpenClaw tworzy lub ponownie używa migawki odzyskiwania w
~/Backups/openclaw-migrations/. - Jeśli używasz wielu kont Matrix, ustaw
channels.matrix.defaultAccountprzed aktualizacją ze starego układu flat-store, aby OpenClaw wiedział, które konto ma otrzymać ten współdzielony stan legacy. - Jeśli poprzednia wtyczka przechowywała lokalnie klucz odszyfrowywania kopii zapasowej kluczy pokoju Matrix, uruchomienie lub
openclaw doctor --fixzaimportuje go automatycznie do nowego przepływu klucza odzyskiwania. - Jeśli access token Matrix zmienił się po przygotowaniu migracji, uruchomienie skanuje teraz sąsiednie katalogi główne przechowywania hashy tokenów w poszukiwaniu oczekującego stanu przywracania legacy, zanim zrezygnuje z automatycznego przywracania kopii zapasowej.
- Jeśli access token Matrix zmieni się później dla tego samego konta, homeservera i użytkownika, OpenClaw preferuje teraz ponowne użycie najbardziej kompletnego istniejącego katalogu głównego przechowywania z hashem tokena zamiast rozpoczynania od pustego katalogu stanu Matrix.
- Przy następnym uruchomieniu gateway klucze pokoju z kopii zapasowej zostaną automatycznie przywrócone do nowego magazynu kryptograficznego.
- Jeśli stara wtyczka miała tylko lokalne klucze pokoju, które nigdy nie zostały zbackupowane, OpenClaw wyświetli wyraźne ostrzeżenie. Tych kluczy nie da się automatycznie wyeksportować z poprzedniego rust crypto store, więc część starej zaszyfrowanej historii może pozostać niedostępna do czasu ręcznego odzyskania.
- Zobacz Migracja Matrix, aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne.
~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/.
Ten katalog zawiera sync store (bot-storage.json), crypto store (crypto/),
plik klucza odzyskiwania (recovery-key.json), migawkę IndexedDB (crypto-idb-snapshot.json),
powiązania wątków (thread-bindings.json) oraz stan weryfikacji przy uruchamianiu (startup-verification.json),
gdy te funkcje są używane.
Gdy token się zmienia, ale tożsamość konta pozostaje taka sama, OpenClaw ponownie używa najlepszego istniejącego
katalogu głównego dla tej krotki konto/homeserver/użytkownik, dzięki czemu wcześniejszy stan synchronizacji, stan kryptograficzny, powiązania wątków
i stan weryfikacji przy uruchamianiu pozostają widoczne.
Model Node crypto store
Matrix E2EE w tej wtyczce korzysta w Node z oficjalnej ścieżki Rust crypto zmatrix-js-sdk.
Ta ścieżka oczekuje trwałości opartej na IndexedDB, jeśli chcesz, aby stan kryptograficzny przetrwał restarty.
OpenClaw obecnie zapewnia to w Node przez:
- używanie
fake-indexeddbjako shima API IndexedDB oczekiwanego przez SDK - przywracanie zawartości Rust crypto IndexedDB z
crypto-idb-snapshot.jsonprzedinitRustCrypto - utrwalanie zaktualizowanej zawartości IndexedDB z powrotem do
crypto-idb-snapshot.jsonpo inicjalizacji i w czasie działania - serializowanie przywracania i utrwalania migawki względem
crypto-idb-snapshot.jsonza pomocą doradczego blokowania pliku, tak aby utrwalanie w runtime gateway i utrzymanie CLI nie ścigały się o ten sam plik migawki
- dodać obsługę SecretRef dla trwałego materiału kluczy Matrix, tak aby klucze odzyskiwania i powiązane sekrety szyfrowania magazynu mogły pochodzić od dostawców sekretów OpenClaw zamiast wyłącznie z lokalnych plików
Zarządzanie profilem
Zaktualizuj self-profile Matrix dla wybranego konta za pomocą:--account <id>, gdy chcesz jawnie wskazać nazwane konto Matrix.
Matrix akceptuje bezpośrednio adresy URL awatarów mxc://. Gdy przekażesz adres URL awatara http:// lub https://, OpenClaw najpierw prześle go do Matrix, a następnie zapisze rozpoznany adres URL mxc:// z powrotem do channels.matrix.avatarUrl (lub nadpisania wybranego konta).
Automatyczne powiadomienia o weryfikacji
Matrix publikuje teraz powiadomienia o cyklu życia weryfikacji bezpośrednio w ścisłym pokoju DM weryfikacji jako wiadomościm.notice.
Obejmuje to:
- powiadomienia o żądaniach weryfikacji
- powiadomienia o gotowości do weryfikacji (z wyraźną wskazówką „Zweryfikuj za pomocą emoji”)
- powiadomienia o rozpoczęciu i zakończeniu weryfikacji
- szczegóły SAS (emoji i liczby dziesiętne), gdy są dostępne
NO_REPLY.
Higiena urządzeń
Stare urządzenia Matrix zarządzane przez OpenClaw mogą gromadzić się na koncie i utrudniać ocenę zaufania w zaszyfrowanych pokojach. Wyświetl je za pomocą:Naprawa Direct Room
Jeśli stan wiadomości bezpośrednich się rozjedzie, OpenClaw może skończyć ze starymi mapowaniamim.direct, które wskazują stare pokoje solo zamiast aktywnego DM. Aby sprawdzić bieżące mapowanie dla peera, użyj:
- preferuje ścisły DM 1:1, który jest już zmapowany w
m.direct - w przeciwnym razie wraca do dowolnego aktualnie dołączonego ścisłego DM 1:1 z tym użytkownikiem
- jeśli nie istnieje żaden zdrowy DM, tworzy nowy direct room i przepisuje
m.direct, aby wskazywał na niego
Wątki
Matrix obsługuje natywne wątki Matrix zarówno dla odpowiedzi automatycznych, jak i wysyłek narzędzia wiadomości.threadReplies: "off"utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości w wątkach w sesji nadrzędnej.threadReplies: "inbound"odpowiada wewnątrz wątku tylko wtedy, gdy przychodząca wiadomość już w nim była.threadReplies: "always"utrzymuje odpowiedzi w pokoju w wątku zakorzenionym w wiadomości wyzwalającej i kieruje tę rozmowę przez odpowiadającą jej sesję z zakresem wątku od pierwszej wiadomości wyzwalającej.dm.threadRepliesnadpisuje ustawienie najwyższego poziomu tylko dla DM. Na przykład możesz izolować wątki w pokojach, pozostawiając DM płaskie.- Przychodzące wiadomości w wątkach zawierają wiadomość główną wątku jako dodatkowy kontekst agenta.
- Wysyłki narzędzia wiadomości dziedziczą teraz automatycznie bieżący wątek Matrix, gdy celem jest ten sam pokój lub ten sam użytkownik docelowy DM, chyba że podano jawne
threadId. - Powiązania wątków w runtime są obsługiwane dla Matrix.
/focus,/unfocus,/agents,/session idle,/session max-ageoraz związane z wątkiem/acp spawndziałają teraz w pokojach i DM-ach Matrix. - Główne
/focusw pokoju/DM Matrix tworzy nowy wątek Matrix i wiąże go z sesją docelową, gdythreadBindings.spawnSubagentSessions=true. - Uruchomienie
/focuslub/acp spawn --thread herewewnątrz istniejącego wątku Matrix wiąże zamiast tego bieżący wątek.
Powiązania rozmów ACP
Pokoje Matrix, DM-y i istniejące wątki Matrix można przekształcić w trwałe przestrzenie robocze ACP bez zmiany powierzchni czatu. Szybki przepływ operatora:- Uruchom
/acp spawn codex --bind herewewnątrz DM, pokoju lub istniejącego wątku Matrix, którego chcesz dalej używać. - W głównym DM lub pokoju Matrix bieżący DM/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do utworzonej sesji ACP.
- Wewnątrz istniejącego wątku Matrix
--bind herewiąże ten bieżący wątek na miejscu. /newi/resetresetują tę samą powiązaną sesję ACP na miejscu./acp closezamyka sesję ACP i usuwa powiązanie.
--bind herenie tworzy podrzędnego wątku Matrix.threadBindings.spawnAcpSessionsjest wymagane tylko dla/acp spawn --thread auto|here, gdy OpenClaw musi utworzyć lub powiązać podrzędny wątek Matrix.
Konfiguracja powiązań wątków
Matrix dziedziczy globalne wartości domyślne zsession.threadBindings, a także obsługuje nadpisania per kanał:
threadBindings.enabledthreadBindings.idleHoursthreadBindings.maxAgeHoursthreadBindings.spawnSubagentSessionsthreadBindings.spawnAcpSessions
- Ustaw
threadBindings.spawnSubagentSessions: true, aby pozwolić, by główne/focustworzyło i wiązało nowe wątki Matrix. - Ustaw
threadBindings.spawnAcpSessions: true, aby pozwolić, by/acp spawn --thread auto|herewiązało sesje ACP z wątkami Matrix.
Reakcje
Matrix obsługuje wychodzące akcje reakcji, przychodzące powiadomienia o reakcjach oraz przychodzące reakcje potwierdzeń.- Narzędzia wychodzących reakcji są kontrolowane przez
channels["matrix"].actions.reactions. reactdodaje reakcję do określonego zdarzenia Matrix.reactionswyświetla bieżące podsumowanie reakcji dla określonego zdarzenia Matrix.emoji=""usuwa własne reakcje konta bota dla tego zdarzenia.remove: trueusuwa tylko wskazaną reakcję emoji z konta bota.
channels["matrix"].accounts.<accountId>.ackReactionchannels["matrix"].ackReactionmessages.ackReaction- zastępcze emoji tożsamości agenta
channels["matrix"].accounts.<accountId>.ackReactionScopechannels["matrix"].ackReactionScopemessages.ackReactionScope
channels["matrix"].accounts.<accountId>.reactionNotificationschannels["matrix"].reactionNotifications- domyślnie:
own
reactionNotifications: "own"przekazuje dodane zdarzeniam.reaction, gdy są skierowane do wiadomości Matrix napisanych przez bota.reactionNotifications: "off"wyłącza systemowe zdarzenia reakcji.- Usunięcia reakcji nadal nie są syntetyzowane do zdarzeń systemowych, ponieważ Matrix udostępnia je jako redakcje, a nie jako osobne usunięcia
m.reaction.
Kontekst historii
channels.matrix.historyLimitkontroluje, ile ostatnich wiadomości z pokoju jest dołączanych jakoInboundHistory, gdy wiadomość w pokoju Matrix wyzwala agenta.- Wartość zapasowa pochodzi z
messages.groupChat.historyLimit. Ustaw0, aby wyłączyć. - Historia pokoju Matrix dotyczy tylko pokoju. DM-y nadal używają zwykłej historii sesji.
- Historia pokoju Matrix jest tylko oczekująca: OpenClaw buforuje wiadomości z pokoju, które jeszcze nie wywołały odpowiedzi, a następnie zapisuje migawkę tego okna, gdy nadejdzie wzmianka lub inny wyzwalacz.
- Bieżąca wiadomość wyzwalająca nie jest dołączana do
InboundHistory; pozostaje w głównej treści przychodzącej dla tej tury. - Ponowienia tego samego zdarzenia Matrix wykorzystują ponownie oryginalną migawkę historii zamiast przesuwać się do nowszych wiadomości z pokoju.
Widoczność kontekstu
Matrix obsługuje współdzieloną kontrolęcontextVisibility dla uzupełniającego kontekstu pokoju, takiego jak pobrany tekst odpowiedzi, główne wiadomości wątków i oczekująca historia.
contextVisibility: "all"to ustawienie domyślne. Uzupełniający kontekst jest zachowywany w otrzymanej postaci.contextVisibility: "allowlist"filtruje uzupełniający kontekst do nadawców dozwolonych przez aktywne sprawdzenia allowlisty pokoju/użytkownika.contextVisibility: "allowlist_quote"działa jakallowlist, ale nadal zachowuje jedną jawną cytowaną odpowiedź.
groupPolicy, groups, groupAllowFrom i zasad DM.
Przykład zasad DM i pokoi
Zatwierdzenia exec
Matrix może działać jako klient zatwierdzeń exec dla konta Matrix.channels.matrix.execApprovals.enabledchannels.matrix.execApprovals.approvers(opcjonalnie; wartość zapasowa pochodzi zchannels.matrix.dm.allowFrom)channels.matrix.execApprovals.target(dm|channel|both, domyślnie:dm)channels.matrix.execApprovals.agentFilterchannels.matrix.execApprovals.sessionFilter
@owner:example.org. Matrix automatycznie włącza natywne zatwierdzenia exec, gdy enabled nie jest ustawione lub ma wartość "auto" i można rozwiązać co najmniej jednego zatwierdzającego, albo z execApprovals.approvers, albo z channels.matrix.dm.allowFrom. Ustaw enabled: false, aby jawnie wyłączyć Matrix jako natywnego klienta zatwierdzeń. W przeciwnym razie żądania zatwierdzenia wracają do innych skonfigurowanych ścieżek zatwierdzania lub zasad zapasowych zatwierdzeń exec.
Natywne routowanie Matrix dotyczy dziś tylko exec:
channels.matrix.execApprovals.*kontroluje natywne routowanie DM/kanału tylko dla zatwierdzeń exec.- Zatwierdzenia wtyczek nadal używają współdzielonego
/approvew tym samym czacie oraz ewentualnie skonfigurowanego przekazywaniaapprovals.plugin. - Matrix nadal może ponownie używać
channels.matrix.dm.allowFromdo autoryzacji zatwierdzeń wtyczek, gdy może bezpiecznie wywnioskować zatwierdzających, ale nie udostępnia osobnej natywnej ścieżki rozsyłania zatwierdzeń wtyczek przez DM/kanał.
target: "dm"wysyła monity o zatwierdzenie do DM-ów zatwierdzającychtarget: "channel"odsyła monit z powrotem do źródłowego pokoju Matrix lub DMtarget: "both"wysyła do DM-ów zatwierdzających oraz do źródłowego pokoju Matrix lub DM
/approve <id> allow-once, /approve <id> allow-always lub /approve <id> deny.
Tylko rozpoznani zatwierdzający mogą zatwierdzać lub odrzucać. Dostarczanie do kanału zawiera tekst polecenia, więc channel lub both włączaj tylko w zaufanych pokojach.
Monity zatwierdzeń Matrix ponownie używają współdzielonego planera zatwierdzeń z core. Natywna powierzchnia specyficzna dla Matrix jest jedynie transportem dla zatwierdzeń exec: routowaniem pokoju/DM oraz zachowaniem wysyłania/aktualizacji/usuwania wiadomości.
Nadpisanie per konto:
channels.matrix.accounts.<account>.execApprovals
Przykład wielu kont
channels.matrix działają jako wartości domyślne dla nazwanych kont, chyba że konto je nadpisze.
Możesz ograniczyć dziedziczone wpisy pokoi do jednego konta Matrix za pomocą groups.<room>.account (lub starszego rooms.<room>.account).
Wpisy bez account pozostają współdzielone przez wszystkie konta Matrix, a wpisy z account: "default" nadal działają, gdy konto domyślne jest skonfigurowane bezpośrednio na najwyższym poziomie channels.matrix.*.
Częściowe współdzielone domyślne ustawienia uwierzytelniania same w sobie nie tworzą osobnego niejawnego konta domyślnego. OpenClaw syntetyzuje konto najwyższego poziomu default tylko wtedy, gdy to konto domyślne ma świeże uwierzytelnianie (homeserver plus accessToken, lub homeserver plus userId i password); nazwane konta mogą nadal pozostać wykrywalne z homeserver plus userId, gdy zbuforowane poświadczenia później spełnią wymagania uwierzytelniania.
Jeśli Matrix ma już dokładnie jedno nazwane konto albo defaultAccount wskazuje istniejący klucz nazwanego konta, naprawa/promocja z jednego konta do wielu zachowuje to konto zamiast tworzyć nowy wpis accounts.default. Do promowanego konta przenoszone są tylko klucze uwierzytelniania/bootstrap Matrix; współdzielone klucze zasad dostarczania pozostają na najwyższym poziomie.
Ustaw defaultAccount, jeśli chcesz, aby OpenClaw preferował jedno nazwane konto Matrix do niejawnego routowania, sondowania i operacji CLI.
Jeśli skonfigurujesz wiele nazwanych kont, ustaw defaultAccount lub przekazuj --account <id> dla poleceń CLI, które polegają na niejawnym wyborze konta.
Przekazuj --account <id> do openclaw matrix verify ... i openclaw matrix devices ..., gdy chcesz nadpisać ten niejawny wybór dla jednego polecenia.
Prywatne/LAN homeservery
Domyślnie OpenClaw blokuje prywatne/wewnętrzne homeservery Matrix dla ochrony SSRF, chyba że jawnie włączysz tę możliwość dla konta. Jeśli Twój homeserver działa na localhost, adresie IP LAN/Tailscale lub wewnętrznej nazwie hosta, włączallowPrivateNetwork dla tego konta Matrix:
http://matrix.example.org:8008, nadal pozostają zablokowane. Jeśli to możliwe, preferuj https://.
Proxy dla ruchu Matrix
Jeśli Twoje wdrożenie Matrix wymaga jawnego wychodzącego proxy HTTP(S), ustawchannels.matrix.proxy:
channels.matrix.accounts.<id>.proxy.
OpenClaw używa tego samego ustawienia proxy dla ruchu Matrix w runtime i sond stanu konta.
Rozwiązywanie celów
Matrix akceptuje następujące formy celu wszędzie tam, gdzie OpenClaw prosi o pokój lub cel użytkownika:- Użytkownicy:
@user:server,user:@user:serverlubmatrix:user:@user:server - Pokoje:
!room:server,room:!room:serverlubmatrix:room:!room:server - Aliasy:
#alias:server,channel:#alias:serverlubmatrix:channel:#alias:server
- Wyszukiwania użytkowników odpytują katalog użytkowników Matrix na tym homeserverze.
- Wyszukiwania pokoi akceptują bezpośrednio jawne identyfikatory pokoi i aliasy, a następnie wracają do przeszukiwania nazw dołączonych pokoi dla tego konta.
- Wyszukiwanie po nazwie dołączonego pokoju ma charakter best-effort. Jeśli nazwy pokoju nie da się rozwiązać do identyfikatora lub aliasu, jest ona ignorowana przez rozwiązywanie allowlisty w runtime.
Dokumentacja konfiguracji
enabled: włącza lub wyłącza kanał.name: opcjonalna etykieta konta.defaultAccount: preferowany identyfikator konta, gdy skonfigurowanych jest wiele kont Matrix.homeserver: adres URL homeservera, na przykładhttps://matrix.example.org.allowPrivateNetwork: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz to, gdy homeserver rozwiązuje się dolocalhost, adresu IP LAN/Tailscale lub wewnętrznego hosta, takiego jakmatrix-synapse.proxy: opcjonalny adres URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisywać domyślne ustawienie najwyższego poziomu własnymproxy.userId: pełny identyfikator użytkownika Matrix, na przykład@bot:example.org.accessToken: access token do uwierzytelniania opartego na tokenie. Dlachannels.matrix.accessTokenichannels.matrix.accounts.<id>.accessTokenobsługiwane są wartości w postaci jawnego tekstu i SecretRef w dostawcach env/file/exec. Zobacz Zarządzanie sekretami.password: hasło do logowania opartego na haśle. Obsługiwane są wartości w postaci jawnego tekstu i SecretRef.deviceId: jawny identyfikator urządzenia Matrix.deviceName: nazwa wyświetlana urządzenia przy logowaniu hasłem.avatarUrl: zapisany adres URL własnego awatara do synchronizacji profilu i aktualizacjiset-profile.initialSyncLimit: limit zdarzeń synchronizacji przy uruchamianiu.encryption: włącza E2EE.allowlistOnly: wymusza zachowanie wyłącznie z allowlistą dla DM-ów i pokoi.allowBots: pozwala na wiadomości z innych skonfigurowanych kont Matrix OpenClaw (truelub"mentions").groupPolicy:open,allowlistlubdisabled.contextVisibility: tryb widoczności uzupełniającego kontekstu pokoju (all,allowlist,allowlist_quote).groupAllowFrom: allowlista identyfikatorów użytkowników dla ruchu w pokojach.- Wpisy
groupAllowFrompowinny być pełnymi identyfikatorami użytkowników Matrix. Nierozwiązane nazwy są ignorowane w runtime. historyLimit: maksymalna liczba wiadomości z pokoju do uwzględnienia jako kontekst historii grupy. Wartość zapasowa pochodzi zmessages.groupChat.historyLimit. Ustaw0, aby wyłączyć.replyToMode:off,firstluball.markdown: opcjonalna konfiguracja renderowania Markdown dla wychodzącego tekstu Matrix.streaming:off(domyślnie),partial,truelubfalse.partialitruewłączają robocze podglądy w pojedynczej wiadomości z aktualizacjami przez edycję w miejscu.blockStreaming:truewłącza osobne wiadomości postępu dla ukończonych bloków asystenta, gdy aktywne jest strumieniowanie roboczego podglądu.threadReplies:off,inboundlubalways.threadBindings: nadpisania per kanał dla routowania i cyklu życia sesji związanych z wątkami.startupVerification: tryb automatycznego żądania self-verification przy uruchamianiu (if-unverified,off).startupVerificationCooldownHours: cooldown przed ponowną próbą automatycznych żądań weryfikacji przy uruchamianiu.textChunkLimit: rozmiar fragmentu wychodzącej wiadomości.chunkMode:lengthlubnewline.responsePrefix: opcjonalny prefiks wiadomości dla odpowiedzi wychodzących.ackReaction: opcjonalne nadpisanie reakcji potwierdzenia dla tego kanału/konta.ackReactionScope: opcjonalne nadpisanie zakresu reakcji potwierdzenia (group-mentions,group-all,direct,all,none,off).reactionNotifications: tryb przychodzących powiadomień o reakcjach (own,off).mediaMaxMb: limit rozmiaru multimediów w MB dla obsługi multimediów Matrix. Dotyczy wysyłek wychodzących i przetwarzania multimediów przychodzących.autoJoin: zasada automatycznego dołączania do zaproszeń (always,allowlist,off). Domyślnie:off.autoJoinAllowlist: pokoje/aliasy dozwolone, gdyautoJoinma wartośćallowlist. Wpisy aliasów są rozwiązywane do identyfikatorów pokoi podczas obsługi zaproszeń; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zapraszający pokój.dm: blok zasad DM (enabled,policy,allowFrom,threadReplies).- Wpisy
dm.allowFrompowinny być pełnymi identyfikatorami użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogu na żywo. dm.threadReplies: nadpisanie zasad wątków tylko dla DM (off,inbound,always). Nadpisuje ustawienie najwyższego poziomuthreadReplieszarówno dla umieszczania odpowiedzi, jak i izolacji sesji w DM-ach.execApprovals: natywne dostarczanie zatwierdzeń exec w Matrix (enabled,approvers,target,agentFilter,sessionFilter).execApprovals.approvers: identyfikatory użytkowników Matrix, którzy mogą zatwierdzać żądania exec. Opcjonalne, gdydm.allowFromjuż identyfikuje zatwierdzających.execApprovals.target:dm | channel | both(domyślnie:dm).accounts: nazwane nadpisania per konto. Wartości najwyższego poziomuchannels.matrixdziałają jako wartości domyślne dla tych wpisów.groups: mapa zasad per pokój. Preferuj identyfikatory pokoi lub aliasy; nierozwiązane nazwy pokoi są ignorowane w runtime. Tożsamość sesji/grupy po rozwiązaniu używa stabilnego identyfikatora pokoju, natomiast etykiety czytelne dla człowieka nadal pochodzą z nazw pokoi.groups.<room>.account: ogranicza jeden dziedziczony wpis pokoju do określonego konta Matrix w konfiguracjach wielokontowych.groups.<room>.allowBots: nadpisanie na poziomie pokoju dla nadawców będących skonfigurowanymi botami (truelub"mentions").groups.<room>.users: allowlista nadawców per pokój.groups.<room>.tools: nadpisania zezwolenia/zabronienia narzędzi per pokój.groups.<room>.autoReply: nadpisanie bramkowania wzmiankami na poziomie pokoju.truewyłącza wymagania wzmianki dla tego pokoju;falseponownie je wymusza.groups.<room>.skills: opcjonalny filtr Skills na poziomie pokoju.groups.<room>.systemPrompt: opcjonalny fragment systemPrompt na poziomie pokoju.rooms: starszy alias dlagroups.actions: kontrola narzędzi per akcja (messages,reactions,pins,profile,memberInfo,channelInfo,verification).
Powiązane
- Przegląd kanałów — wszystkie obsługiwane kanały
- Parowanie — uwierzytelnianie DM i przepływ parowania
- Grupy — zachowanie czatu grupowego i bramkowanie wzmiankami
- Routowanie kanałów — routowanie sesji dla wiadomości
- Bezpieczeństwo — model dostępu i utwardzanie