​

Matrix

​

Dołączona wtyczka

openclaw plugins install @openclaw/matrix

openclaw plugins install ./path/to/local/matrix-plugin

​

Konfiguracja

1. Upewnij się, że wtyczka Matrix jest dostępna.
   • Aktualne spakowane wydania OpenClaw już ją zawierają.
   • Starsze/niestandardowe instalacje mogą dodać ją ręcznie za pomocą powyższych poleceń.
2. Utwórz konto Matrix na swoim homeserverze.
3. Skonfiguruj channels.matrix, używając jednego z wariantów:
   • homeserver + accessToken, lub
   • homeserver + userId + password.
4. Uruchom ponownie gateway.
5. Rozpocznij wiadomość prywatną z botem albo zaproś go do pokoju.
   • Nowe zaproszenia Matrix działają tylko wtedy, gdy channels.matrix.autoJoin na to pozwala.

openclaw channels add
openclaw configure --section channels

• URL homeservera
• metoda uwierzytelniania: token dostępu 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 pokojów Matrix
• czy skonfigurować teraz automatyczne dołączanie do zaproszeń Matrix
• gdy automatyczne dołączanie do zaproszeń jest włączone, czy ma mieć wartość allowlist, always czy off

• 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 do env, dzięki czemu konfiguracja może pozostawić uwierzytelnianie w zmiennych środowiskowych zamiast kopiować sekrety do konfiguracji.
• 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 Bot staje się ops-bot.
• Monity listy dozwolonych dla wiadomości prywatnych od razu akceptują pełne wartości @user:server. Nazwy wyświetlane działają tylko wtedy, gdy wyszukiwanie w katalogu na żywo znajdzie jedno dokładne dopasowanie; w przeciwnym razie kreator poprosi o ponowną próbę z pełnym identyfikatorem Matrix.
• Monity listy dozwolonych dla pokojów bezpośrednio akceptują identyfikatory pokojów i aliasy. Mogą też na żywo rozwiązywać nazwy dołączonych pokojów, ale nierozwiązane nazwy są podczas konfiguracji zachowywane tylko w postaci wpisanej i później są ignorowane przez runtime przy rozwiązywaniu listy dozwolonych. Preferuj !room:server lub #alias:server.
• Kreator wyświetla teraz jawne ostrzeżenie przed krokiem automatycznego dołączania do zaproszeń, ponieważ domyślna wartość channels.matrix.autoJoin to off; agenty nie dołączą do zaproszonych pokojów ani nowych zaproszeń w stylu wiadomości prywatnej, dopóki tego nie ustawisz.
• W trybie listy dozwolonych dla automatycznego dołączania do zaproszeń używaj wyłącznie stabilnych celów zaproszeń: !roomId:server, #alias:server lub *. Zwykłe nazwy pokojów są odrzucane.
• Tożsamość pokoju/sesji w runtime używa stabilnego identyfikatora pokoju Matrix. Aliasy zadeklarowane przez pokój 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 pokojów przed ich zapisaniem, użyj openclaw channels resolve --channel matrix "Project Room".

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

Przykład konfiguracji

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

​

Podglądy streamingu

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

• streaming: "off" to ustawienie domyślne. OpenClaw czeka na końcową odpowiedź i wysyła ją jednorazowo.
• streaming: "partial" tworzy jedną edytowalną wiadomość podglądu dla bieżącego bloku odpowiedzi asystenta, używając zwykłych wiadomości tekstowych Matrix. Zachowuje to starsze zachowanie Matrix polegające na powiadamianiu najpierw o podglądzie, więc standardowe klienty mogą powiadamiać na podstawie pierwszego przesłanego tekstu podglądu zamiast gotowego bloku.
• streaming: "quiet" tworzy jedno edytowalne ciche powiadomienie podglądu dla bieżącego bloku odpowiedzi asystenta. Używaj tego tylko wtedy, gdy skonfigurujesz też reguły push odbiorcy dla sfinalizowanych edycji podglądu.
• blockStreaming: true włącza osobne wiadomości postępu Matrix. Gdy streaming podglądu jest włączony, Matrix zachowuje wersję roboczą na żywo dla bieżącego bloku i zachowuje ukończone bloki jako oddzielne wiadomości.
• Gdy streaming podglądu jest włączony, a blockStreaming jest wyłączone, Matrix edytuje wersję roboczą na żywo na miejscu i finalizuje to samo zdarzenie po zakończeniu bloku lub tury.
• Jeśli podgląd przestaje mieścić się w jednym zdarzeniu Matrix, OpenClaw zatrzymuje streaming podglądu i wraca do normalnego końcowego dostarczenia.
• Odpowiedzi z multimediami nadal wysyłają załączniki normalnie. Jeśli starego podglądu nie da się już bezpiecznie ponownie użyć, OpenClaw usuwa go przed wysłaniem końcowej odpowiedzi z multimediami.
• Edycje podglądu generują dodatkowe wywołania API Matrix. Pozostaw streaming wyłączony, jeśli chcesz zachować najbardziej ostrożne zachowanie względem limitów szybkości.

• blockStreaming: true wysyła każdy ukończony blok jako zwykłą powiadamiającą wiadomość Matrix.
• blockStreaming: false wysyła tylko końcową ukończoną odpowiedź jako zwykłą powiadamiającą wiadomość Matrix.

​

Samodzielnie hostowane reguły push dla cichych sfinalizowanych podglądów

• użytkownik odbiorca = osoba, która ma otrzymywać powiadomienie
• użytkownik bota = konto Matrix OpenClaw wysyłające odpowiedź
• do poniższych wywołań API użyj tokena dostępu użytkownika odbiorcy
• dopasuj sender w regule push do pełnego MXID użytkownika bota

1. Skonfiguruj OpenClaw tak, aby używał cichych podglądów:

{
  channels: {
    matrix: {
      streaming: "quiet",
    },
  },
}

2. Upewnij się, że konto odbiorcy już otrzymuje zwykłe powiadomienia push Matrix. Reguły cichych podglądów działają tylko wtedy, gdy ten użytkownik ma już działające pushery/urządzenia.
3. Pobierz token dostępu użytkownika odbiorcy.
   • Użyj tokena użytkownika odbierającego, a nie tokena bota.
   • Najłatwiej zwykle ponownie użyć tokena istniejącej sesji klienta.
   • Jeśli musisz wygenerować nowy token, możesz zalogować się przez standardowe API Matrix Client-Server:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. Zweryfikuj, że konto odbiorcy ma już pushery:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. Utwórz regułę push typu override dla każdego konta odbiorcy, które ma otrzymywać te powiadomienia:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: bazowy URL twojego homeservera
• $USER_ACCESS_TOKEN: token dostępu użytkownika odbierającego
• openclaw-finalized-preview-botname: identyfikator reguły unikalny dla tego bota dla tego użytkownika odbierającego
• @bot:example.org: MXID twojego bota Matrix OpenClaw, a nie MXID użytkownika odbierającego

• Reguły push są kluczowane przez ruleId. Ponowne uruchomienie PUT względem tego samego identyfikatora reguły aktualizuje tę jedną regułę.
• Jeśli jeden użytkownik odbierający ma otrzymywać powiadomienia od wielu kont botów Matrix OpenClaw, utwórz jedną regułę na bota z unikalnym identyfikatorem reguły dla każdego dopasowania nadawcy.
• Prostym wzorcem jest openclaw-finalized-preview-<botname>, na przykład openclaw-finalized-preview-ops lub openclaw-finalized-preview-support.

• uwierzytelnij się tokenem użytkownika odbierającego
• dopasuj sender do MXID bota OpenClaw

6. Zweryfikuj, że reguła istnieje:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. Przetestuj odpowiedź strumieniowaną. W trybie quiet pokój powinien pokazać cichy podgląd wersji roboczej, a końcowa edycja na miejscu powinna wysłać powiadomienie po zakończeniu bloku lub tury.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• Utwórz regułę z użyciem tokena dostępu użytkownika odbierającego, a nie bota.
• Nowe reguły override zdefiniowane przez użytkownika są wstawiane przed domyślnymi regułami wyciszającymi, więc nie jest potrzebny dodatkowy parametr kolejności.
• Dotyczy to tylko edycji podglądu tylko tekstowego, które OpenClaw może bezpiecznie sfinalizować na miejscu. Fallbacki dla multimediów i starych podglądów nadal używają normalnego dostarczania Matrix.
• Jeśli GET /_matrix/client/v3/pushers nie pokazuje żadnych pusherów, użytkownik nie ma jeszcze działającego dostarczania powiadomień push Matrix dla tego konta/urządzenia.

​

Synapse

• Żadna specjalna zmiana w homeserver.yaml nie jest wymagana dla sfinalizowanych powiadomień o podglądzie OpenClaw.
• Jeśli twoje wdrożenie Synapse już wysyła zwykłe powiadomienia push Matrix, token użytkownika + wywołanie pushrules powyżej to główny krok konfiguracji.
• Jeśli uruchamiasz Synapse za reverse proxy lub workerami, upewnij się, że /_matrix/client/.../pushrules/ trafia poprawnie do Synapse.
• Jeśli używasz workerów Synapse, upewnij się, że pushery są sprawne. Dostarczanie push jest obsługiwane przez proces główny lub synapse.app.pusher / skonfigurowane workery pusherów.

​

Tuwunel

• Żadna konfiguracja specyficzna dla Tuwunel nie jest wymagana dla samego znacznika sfinalizowanego podglądu.
• Jeśli zwykłe powiadomienia Matrix już działają dla tego użytkownika, token użytkownika + wywołanie pushrules powyżej to główny krok konfiguracji.
• Jeśli wydaje się, że powiadomienia znikają, gdy użytkownik jest aktywny na innym urządzeniu, sprawdź, czy włączono suppress_push_when_active. Tuwunel dodał tę opcję w Tuwunel 1.4.2 12 września 2025 r. i może ona celowo wyciszać powiadomienia push na innych urządzeniach, gdy jedno urządzenie jest aktywne.

​

Szyfrowanie i weryfikacja

​

Pokoje bot-bot

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true akceptuje wiadomości od innych skonfigurowanych kont botów Matrix w dozwolonych pokojach i wiadomościach prywatnych.
• allowBots: "mentions" akceptuje te wiadomości tylko wtedy, gdy w pokojach wyraźnie wspominają tego bota. Wiadomości prywatne są nadal dozwolone.
• groups.<room>.allowBots nadpisuje ustawienie na poziomie konta dla jednego pokoju.
• OpenClaw nadal ignoruje wiadomości od 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 gatewayu OpenClaw”.

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

openclaw matrix verify status

openclaw matrix verify status --verbose

openclaw matrix verify status --include-recovery-key --json

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

openclaw matrix verify bootstrap --force-reset-cross-signing

openclaw matrix verify device "<your-recovery-key>"

openclaw matrix verify device "<your-recovery-key>" --verbose

openclaw matrix verify backup status

openclaw matrix verify backup status --verbose

openclaw matrix verify backup restore

openclaw matrix verify backup restore --verbose

openclaw matrix verify backup reset --yes

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

​

Co oznacza „zweryfikowane”

• Locally trusted: to urządzenie jest zaufane tylko przez bieżącego klienta
• Cross-signing verified: SDK zgłasza urządzenie jako zweryfikowane przez cross-signing
• Signed by owner: urządzenie jest podpisane przez twój własny klucz self-signing

​

Co robi bootstrap

• inicjalizuje magazyn sekretów, 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 pokojów po stronie serwera, jeśli jeszcze nie istnieje

​

Nowa baza kopii zapasowej

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

​

Zachowanie przy uruchamianiu

• OpenClaw automatycznie ponownie używa tego samego konta Matrix, tokena dostępu i tożsamości urządzenia, gdy to możliwe.
• Zanim zostaną uruchomione jakiekolwiek istotne zmiany migracyjne Matrix, OpenClaw tworzy lub ponownie używa migawki odzyskiwania w ~/Backups/openclaw-migrations/.
• Jeśli używasz wielu kont Matrix, ustaw channels.matrix.defaultAccount przed aktualizacją ze starego płaskiego układu store, aby OpenClaw wiedział, które konto ma otrzymać ten współdzielony stan legacy.
• Jeśli poprzednia wtyczka przechowywała lokalnie klucz deszyfrujący kopii zapasowej kluczy pokojów Matrix, uruchamianie lub openclaw doctor --fix automatycznie zaimportuje go do nowego przepływu klucza odzyskiwania.
• Jeśli token dostępu Matrix zmienił się po przygotowaniu migracji, uruchamianie teraz skanuje sąsiednie katalogi główne przechowywania według skrótu tokena w poszukiwaniu oczekującego stanu przywracania legacy, zanim zrezygnuje z automatycznego przywracania kopii zapasowej.
• Jeśli token dostępu Matrix zmieni się później dla tego samego konta, homeservera i użytkownika, OpenClaw woli teraz ponownie użyć najbardziej kompletnego istniejącego katalogu głównego według skrótu tokena zamiast rozpoczynać od pustego katalogu stanu Matrix.
• Przy następnym uruchomieniu gatewaya klucze pokojów z kopii zapasowej zostaną automatycznie przywrócone do nowego store kryptograficznego.
• Jeśli stara wtyczka miała lokalne klucze pokojów, których nigdy nie zarchiwizowano, OpenClaw wyświetli wyraźne ostrzeżenie. Tych kluczy nie można automatycznie wyeksportować z poprzedniego rust crypto store, więc część starej zaszyfrowanej historii może pozostać niedostępna, dopóki nie zostanie odzyskana ręcznie.
• Zobacz Migracja Matrix, aby poznać pełny przepływ aktualizacji, ograniczenia, polecenia odzyskiwania i typowe komunikaty migracyjne.

​

Model Node crypto store

• używanie fake-indexeddb jako shimu API IndexedDB oczekiwanego przez SDK
• przywracanie zawartości IndexedDB Rust crypto z crypto-idb-snapshot.json przed initRustCrypto
• utrwalanie zaktualizowanej zawartości IndexedDB z powrotem do crypto-idb-snapshot.json po inicjalizacji i podczas runtime
• serializowanie przywracania i utrwalania migawki względem crypto-idb-snapshot.json za pomocą doradczego blokowania pliku, aby utrwalanie runtime gatewaya i konserwacja CLI nie ścigały się o ten sam plik migawki

• dodać obsługę SecretRef dla trwałego materiału kluczy Matrix, aby klucze odzyskiwania i powiązane sekrety szyfrowania store mogły pochodzić od dostawców sekretów OpenClaw zamiast wyłącznie z plików lokalnych

​

Zarządzanie profilem

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

​

Automatyczne powiadomienia o weryfikacji

• powiadomienia o żądaniu weryfikacji
• powiadomienia o gotowości do weryfikacji (z jawną wskazówką „Zweryfikuj przez emoji”)
• powiadomienia o rozpoczęciu i zakończeniu weryfikacji
• szczegóły SAS (emoji i liczby dziesiętne), gdy są dostępne

​

Higiena urządzeń

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Naprawa pokoju bezpośredniego

openclaw matrix direct inspect --user-id @alice:example.org

openclaw matrix direct repair --user-id @alice:example.org

• preferuje ścisłą wiadomość prywatną 1:1, która jest już zmapowana w m.direct
• w przeciwnym razie przechodzi do dowolnej aktualnie dołączonej ścisłej wiadomości prywatnej 1:1 z tym użytkownikiem
• jeśli nie istnieje zdrowa wiadomość prywatna, tworzy nowy pokój bezpośredni i przepisuje m.direct, aby wskazywało na niego

​

Wątki

• dm.sessionScope: "per-user" (domyślnie) utrzymuje routowanie wiadomości prywatnych Matrix w zakresie nadawcy, dzięki czemu wiele pokojów wiadomości prywatnych może współdzielić jedną sesję, jeśli rozwiążą się do tego samego partnera.
• dm.sessionScope: "per-room" izoluje każdy pokój wiadomości prywatnych Matrix we własnym kluczu sesji, nadal używając zwykłych kontroli uwierzytelniania i list dozwolonych dla wiadomości prywatnych.
• Jawne powiązania konwersacji Matrix nadal mają pierwszeństwo przed dm.sessionScope, więc powiązane pokoje i wątki zachowują wybrany docelowy identyfikator sesji.
• threadReplies: "off" utrzymuje odpowiedzi na poziomie głównym i zachowuje przychodzące wiadomości wątkowane na sesji nadrzędnej.
• threadReplies: "inbound" odpowiada wewnątrz wątku tylko wtedy, gdy wiadomość przychodząca była już w tym wątku.
• threadReplies: "always" utrzymuje odpowiedzi pokojów we wątku zakorzenionym w wiadomości wyzwalającej i prowadzi tę konwersację przez odpowiadającą jej sesję o zakresie wątku od pierwszej wiadomości wyzwalającej.
• dm.threadReplies nadpisuje ustawienie najwyższego poziomu tylko dla wiadomości prywatnych. Na przykład możesz izolować wątki w pokojach, a jednocześnie zachować płaskie wiadomości prywatne.
• Przychodzące wiadomości wątkowane zawierają wiadomość główną wątku jako dodatkowy kontekst agenta.
• Wysyłki narzędzia wiadomości teraz automatycznie dziedziczą bieżący wątek Matrix, gdy celem jest ten sam pokój lub ten sam użytkownik docelowy wiadomości prywatnej, chyba że jawnie podano threadId.
• Ponowne użycie celu użytkownika wiadomości prywatnej dla tej samej sesji działa tylko wtedy, gdy bieżące metadane sesji potwierdzają tego samego partnera wiadomości prywatnej na tym samym koncie Matrix; w przeciwnym razie OpenClaw wraca do normalnego routowania w zakresie użytkownika.
• Gdy OpenClaw zauważy, że pokój wiadomości prywatnych Matrix koliduje z innym pokojem wiadomości prywatnych w tej samej współdzielonej sesji Matrix DM, publikuje w tym pokoju jednorazowe m.notice z furtką awaryjną /focus, gdy powiązania wątków są włączone, oraz wskazówką dm.sessionScope.
• Powiązania wątków w runtime są obsługiwane dla Matrix. /focus, /unfocus, /agents, /session idle, /session max-age i powiązane z wątkiem /acp spawn działają teraz w pokojach i wiadomościach prywatnych Matrix.
• Główne /focus w pokoju/wiadomości prywatnej Matrix tworzy nowy wątek Matrix i wiąże go z docelową sesją, gdy threadBindings.spawnSubagentSessions=true.
• Uruchomienie /focus lub /acp spawn --thread here wewnątrz istniejącego wątku Matrix wiąże zamiast tego bieżący wątek.

​

Powiązania konwersacji ACP

• Uruchom /acp spawn codex --bind here wewnątrz wiadomości prywatnej, pokoju lub istniejącego wątku Matrix, którego chcesz nadal używać.
• W głównej wiadomości prywatnej lub pokoju Matrix bieżąca wiadomość prywatna/pokój pozostaje powierzchnią czatu, a przyszłe wiadomości są kierowane do uruchomionej sesji ACP.
• W istniejącym wątku Matrix --bind here wiąże ten bieżący wątek na miejscu.
• /new i /reset resetują tę samą powiązaną sesję ACP na miejscu.
• /acp close zamyka sesję ACP i usuwa powiązanie.

• --bind here nie tworzy podrzędnego wątku Matrix.
• threadBindings.spawnAcpSessions jest 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

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

• Ustaw threadBindings.spawnSubagentSessions: true, aby pozwolić głównemu /focus tworzyć i wiązać nowe wątki Matrix.
• Ustaw threadBindings.spawnAcpSessions: true, aby pozwolić /acp spawn --thread auto|here wiązać sesje ACP z wątkami Matrix.

​

Reakcje

• Narzędzia wychodzących reakcji są kontrolowane przez channels["matrix"].actions.reactions.
• react dodaje reakcję do konkretnego zdarzenia Matrix.
• reactions wyświetla bieżące podsumowanie reakcji dla konkretnego zdarzenia Matrix.
• emoji="" usuwa własne reakcje konta bota na tym zdarzeniu.
• remove: true usuwa z konta bota tylko wskazaną reakcję emoji.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• zapasowe emoji tożsamości agenta

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• domyślnie: own

• reactionNotifications: "own" przekazuje dodane zdarzenia m.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 samodzielne usunięcia m.reaction.

​

Kontekst historii

• channels.matrix.historyLimit kontroluje liczbę ostatnich wiadomości z pokoju dołączanych jako InboundHistory, gdy wiadomość z pokoju Matrix wyzwala agenta.
• Wartość zapasowa pochodzi z messages.groupChat.historyLimit. Jeśli obie wartości nie są ustawione, efektywna wartość domyślna to 0, więc wiadomości z pokoju wymagające wzmianki nie są buforowane. Ustaw 0, aby wyłączyć.
• Historia pokoju Matrix dotyczy tylko pokoju. Wiadomości prywatne nadal używają zwykłej historii sesji.
• Historia pokoju Matrix obejmuje tylko stan oczekujący: OpenClaw buforuje wiadomości z pokoju, które nie wywołały jeszcze odpowiedzi, a następnie robi 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 tej tury.
• Ponowienia dla tego samego zdarzenia Matrix używają pierwotnej migawki historii zamiast przesuwać się do przodu do nowszych wiadomości z pokoju.

​

Widoczność kontekstu

• 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 sprawdzanie list dozwolonych pokoju/użytkownika.
• contextVisibility: "allowlist_quote" działa jak allowlist, ale nadal zachowuje jedną jawną cytowaną odpowiedź.

​

Przykład zasad wiadomości prywatnych i pokojów

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

Zatwierdzenia exec

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (opcjonalne; wartość zapasowa pochodzi z channels.matrix.dm.allowFrom)
• channels.matrix.execApprovals.target (dm | channel | both, domyślnie: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.* kontroluje natywny tryb fanoutu wiadomości prywatnych/kanałów dla promptów zatwierdzeń Matrix.
• Zatwierdzenia exec używają zbioru zatwierdzających exec z execApprovals.approvers lub channels.matrix.dm.allowFrom.
• Zatwierdzenia wtyczek używają listy dozwolonych wiadomości prywatnych Matrix z channels.matrix.dm.allowFrom.
• Skróty reakcji Matrix i aktualizacje wiadomości dotyczą zarówno zatwierdzeń exec, jak i zatwierdzeń wtyczek.

• target: "dm" wysyła prompty zatwierdzeń do wiadomości prywatnych zatwierdzających
• target: "channel" wysyła prompt z powrotem do źródłowego pokoju lub wiadomości prywatnej Matrix
• target: "both" wysyła do wiadomości prywatnych zatwierdzających oraz do źródłowego pokoju lub wiadomości prywatnej Matrix

• ✅ = zezwól jednorazowo
• ❌ = odmów
• ♾️ = zezwól zawsze, gdy taka decyzja jest dozwolona przez efektywną politykę exec

• channels.matrix.accounts.<account>.execApprovals

​

Przykład wielu kont

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

​

Prywatne/LAN homeservery

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

​

Ruch Matrix przez proxy

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

​

Rozwiązywanie celów

• Użytkownicy: @user:server, user:@user:server lub matrix:user:@user:server
• Pokoje: !room:server, room:!room:server lub matrix:room:!room:server
• Aliasy: #alias:server, channel:#alias:server lub matrix:channel:#alias:server

• Wyszukiwania użytkowników odpytyją katalog użytkowników Matrix na tym homeserverze.
• Wyszukiwania pokojów bezpośrednio akceptują jawne identyfikatory pokojów i aliasy, a następnie wracają do przeszukiwania nazw pokojów dołączonych dla tego konta.
• Wyszukiwanie nazw dołączonych pokojów jest realizowane najlepiej jak się da. Jeśli nazwy pokoju nie da się rozwiązać do identyfikatora ani aliasu, jest ignorowana przez runtime przy rozwiązywaniu listy dozwolonych.

​

Dokumentacja konfiguracji

• enabled: włącza lub wyłącza kanał.
• name: opcjonalna etykieta konta.
• defaultAccount: preferowany identyfikator konta, gdy skonfigurowano wiele kont Matrix.
• homeserver: URL homeservera, na przykład https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: pozwala temu kontu Matrix łączyć się z prywatnymi/wewnętrznymi homeserverami. Włącz tę opcję, gdy homeserver rozwiązuje się do localhost, adresu LAN/Tailscale albo wewnętrznego hosta, takiego jak matrix-synapse.
• proxy: opcjonalny URL proxy HTTP(S) dla ruchu Matrix. Nazwane konta mogą nadpisać domyślną wartość najwyższego poziomu własnym proxy.
• userId: pełny identyfikator użytkownika Matrix, na przykład @bot:example.org.
• accessToken: token dostępu dla uwierzytelniania opartego na tokenie. Dla channels.matrix.accessToken i channels.matrix.accounts.<id>.accessToken obsługiwane są zarówno wartości jawne, jak i SecretRef, w dostawcach env/file/exec. Zobacz Zarządzanie sekretami.
• password: hasło do logowania hasłem. Obsługiwane są zarówno wartości jawne, jak i SecretRef.
• deviceId: jawny identyfikator urządzenia Matrix.
• deviceName: wyświetlana nazwa urządzenia przy logowaniu hasłem.
• avatarUrl: zapisany URL własnego awatara do synchronizacji profilu i aktualizacji set-profile.
• initialSyncLimit: limit zdarzeń synchronizacji przy uruchamianiu.
• encryption: włącza E2EE.
• allowlistOnly: wymusza zachowanie tylko według listy dozwolonych dla wiadomości prywatnych i pokojów.
• allowBots: pozwala na wiadomości od innych skonfigurowanych kont Matrix OpenClaw (true lub "mentions").
• groupPolicy: open, allowlist albo disabled.
• contextVisibility: tryb widoczności uzupełniającego kontekstu pokoju (all, allowlist, allowlist_quote).
• groupAllowFrom: lista dozwolonych identyfikatorów użytkowników dla ruchu w pokojach.
• Wpisy groupAllowFrom powinny być pełnymi identyfikatorami użytkowników Matrix. Nierozwiązane nazwy są ignorowane w runtime.
• historyLimit: maksymalna liczba wiadomości z pokoju do dołączenia jako kontekst historii grupy. Wartość zapasowa pochodzi z messages.groupChat.historyLimit; jeśli obie wartości nie są ustawione, efektywna wartość domyślna to 0. Ustaw 0, aby wyłączyć.
• replyToMode: off, first, all albo batched.
• markdown: opcjonalna konfiguracja renderowania Markdown dla wychodzącego tekstu Matrix.
• streaming: off (domyślnie), partial, quiet, true lub false. partial i true włączają aktualizacje wersji roboczej „najpierw podgląd” przy użyciu zwykłych wiadomości tekstowych Matrix. quiet używa niepowiadamiających powiadomień podglądu dla samodzielnie hostowanych konfiguracji z regułami push.
• blockStreaming: true włącza osobne wiadomości postępu dla ukończonych bloków asystenta, gdy aktywny jest streaming wersji roboczej podglądu.
• threadReplies: off, inbound albo always.
• threadBindings: nadpisania per kanał dla routowania i cyklu życia sesji powiązanych z wątkami.
• startupVerification: tryb automatycznego żądania samoweryfikacji przy uruchamianiu (if-unverified, off).
• startupVerificationCooldownHours: czas karencji przed ponowieniem automatycznych żądań weryfikacji przy uruchamianiu.
• textChunkLimit: rozmiar fragmentu wiadomości wychodzącej.
• chunkMode: length lub newline.
• responsePrefix: opcjonalny prefiks wiadomości dla odpowiedzi wychodzących.
• ackReaction: opcjonalne nadpisanie reakcji potwierdzającej dla tego kanału/konta.
• ackReactionScope: opcjonalne nadpisanie zakresu reakcji potwierdzającej (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: polityka automatycznego dołączania do zaproszeń (always, allowlist, off). Domyślnie: off. Dotyczy ogólnie zaproszeń Matrix, w tym zaproszeń w stylu wiadomości prywatnej, a nie tylko zaproszeń do pokojów/grup. OpenClaw podejmuje tę decyzję w momencie zaproszenia, zanim może wiarygodnie sklasyfikować dołączony pokój jako wiadomość prywatną lub grupę.
• autoJoinAllowlist: pokoje/aliasy dozwolone, gdy autoJoin ma wartość allowlist. Wpisy aliasów są rozwiązywane do identyfikatorów pokojów podczas obsługi zaproszenia; OpenClaw nie ufa stanowi aliasu deklarowanemu przez zaproszony pokój.
• dm: blok polityki wiadomości prywatnych (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: kontroluje dostęp do wiadomości prywatnych po tym, jak OpenClaw dołączył do pokoju i sklasyfikował go jako wiadomość prywatną. Nie zmienia tego, czy do zaproszenia nastąpi automatyczne dołączenie.
• Wpisy dm.allowFrom powinny być pełnymi identyfikatorami użytkowników Matrix, chyba że zostały już rozwiązane przez wyszukiwanie katalogu na żywo.
• dm.sessionScope: per-user (domyślnie) albo per-room. Użyj per-room, jeśli chcesz, aby każdy pokój wiadomości prywatnych Matrix zachowywał osobny kontekst, nawet jeśli partner jest ten sam.
• dm.threadReplies: nadpisanie polityki wątków tylko dla wiadomości prywatnych (off, inbound, always). Nadpisuje najwyższego poziomu ustawienie threadReplies zarówno dla umieszczania odpowiedzi, jak i izolacji sesji w wiadomościach prywatnych.
• execApprovals: natywne dostarczanie zatwierdzeń exec przez Matrix (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: identyfikatory użytkowników Matrix uprawnionych do zatwierdzania żądań exec. Opcjonalne, gdy dm.allowFrom już identyfikuje zatwierdzających.
• execApprovals.target: dm | channel | both (domyślnie: dm).
• accounts: nazwane nadpisania per konto. Wartości najwyższego poziomu channels.matrix działają jako wartości domyślne dla tych wpisów.
• groups: mapa zasad per pokój. Preferuj identyfikatory pokojów lub aliasy; nierozwiązane nazwy pokojów są ignorowane w runtime. Tożsamość sesji/grupy po rozwiązaniu używa stabilnego identyfikatora pokoju, podczas gdy etykiety czytelne dla ludzi nadal pochodzą z nazw pokojów.
• groups.<room>.account: ogranicza jeden odziedziczony wpis pokoju do konkretnego konta Matrix w konfiguracjach z wieloma kontami.
• groups.<room>.allowBots: nadpisanie na poziomie pokoju dla nadawców będących skonfigurowanymi botami (true lub "mentions").
• groups.<room>.users: lista dozwolonych nadawców dla pokoju.
• groups.<room>.tools: nadpisania dozwolenia/odmowy narzędzi dla pokoju.
• groups.<room>.autoReply: nadpisanie wymuszania wzmianki na poziomie pokoju. true wyłącza wymaganie wzmianki dla tego pokoju; false wymusza je ponownie.
• groups.<room>.skills: opcjonalny filtr Skills na poziomie pokoju.
• groups.<room>.systemPrompt: opcjonalny fragment promptu systemowego na poziomie pokoju.
• rooms: starszy alias dla groups.
• actions: kontrola narzędzi per działanie (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

Powiązane

• Przegląd kanałów — wszystkie obsługiwane kanały
• Parowanie — uwierzytelnianie wiadomości prywatnych i przepływ parowania
• Grupy — zachowanie czatu grupowego i wymuszanie wzmianki
• Routowanie kanałów — routowanie sesji dla wiadomości
• Bezpieczeństwo — model dostępu i utwardzanie