Matrix is een meegeleverde kanaal-Plugin voor OpenClaw. Het gebruikt de officiëleDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
matrix-js-sdk en ondersteunt DM’s, rooms, threads, media, reacties, polls, locatie en E2EE.
Meegeleverde Plugin
Huidige verpakte OpenClaw-releases leveren de Matrix Plugin standaard mee. Je hoeft niets te installeren; het configureren vanchannels.matrix.* (zie Instellen) activeert deze.
Voor oudere builds of aangepaste installaties die Matrix uitsluiten, installeer je een huidig npm-pakket wanneer er een is gepubliceerd:
plugins install registreert en schakelt de Plugin in, dus er is geen aparte stap openclaw plugins enable matrix nodig. De Plugin doet nog steeds niets totdat je het kanaal hieronder configureert. Zie Plugins voor algemeen Plugin-gedrag en installatieregels.
Instellen
- Maak een Matrix-account aan op je homeserver.
- Configureer
channels.matrixmethomeserver+accessToken, ofhomeserver+userId+password. - Herstart de Gateway.
- Start een DM met de bot, of nodig deze uit voor een room (zie automatisch deelnemen — nieuwe uitnodigingen komen alleen binnen wanneer
autoJoinze toestaat).
Interactieve installatie
MATRIX_*-omgevingsvariabelen al bestaan en het geselecteerde account geen opgeslagen authenticatie heeft, biedt de wizard een snelkoppeling via omgevingsvariabelen. Om roomnamen op te lossen voordat je een allowlist opslaat, voer je openclaw channels resolve --channel matrix "Project Room" uit. Wanneer E2EE is ingeschakeld, schrijft de wizard de configuratie en voert dezelfde bootstrap uit als openclaw matrix encryption setup.
Minimale configuratie
Op basis van tokens:Automatisch deelnemen
channels.matrix.autoJoin staat standaard op off. Met de standaardinstelling verschijnt de bot niet in nieuwe rooms of DM’s uit nieuwe uitnodigingen totdat je handmatig deelneemt.
OpenClaw kan op het moment van uitnodigen niet bepalen of een uitgenodigde room een DM of een groep is, dus alle uitnodigingen — inclusief DM-achtige uitnodigingen — gaan eerst door autoJoin. dm.policy wordt pas later toegepast, nadat de bot is toegetreden en de room is geclassificeerd.
autoJoin: "always".
Doelformaten voor allowlists
Allowlists voor DM’s en rooms worden het best gevuld met stabiele ID’s:- DM’s (
dm.allowFrom,groupAllowFrom,groups.<room>.users): gebruik@user:server. Weergavenamen worden alleen opgelost wanneer de homeserver-directory exact één overeenkomst retourneert. - Rooms (
groups,autoJoinAllowlist): gebruik!room:serverof#alias:server. Namen worden naar beste vermogen opgelost tegen rooms waaraan is deelgenomen; niet-opgeloste vermeldingen worden tijdens runtime genegeerd.
Normalisatie van account-ID
De wizard zet een vriendelijke naam om in een genormaliseerde account-ID. Bijvoorbeeld:Ops Bot wordt ops-bot. Interpunctie wordt geëscapet in scoped omgevingsvariabelenamen zodat twee accounts niet kunnen botsen: - → _X2D_, dus ops-prod wordt gekoppeld aan MATRIX_OPS_X2D_PROD_*.
Gecachete referenties
Matrix slaat gecachete referenties op onder~/.openclaw/credentials/matrix/:
- standaardaccount:
credentials.json - benoemde accounts:
credentials-<account>.json
openclaw doctor en kanaalstatusprobes.
Omgevingsvariabelen
Gebruikt wanneer de equivalente configuratiesleutel niet is ingesteld. Het standaardaccount gebruikt namen zonder prefix; benoemde accounts gebruiken de account-ID die vóór het achtervoegsel wordt ingevoegd.| Standaardaccount | Benoemd account (<ID> is de genormaliseerde account-ID) |
|---|---|
MATRIX_HOMESERVER | MATRIX_<ID>_HOMESERVER |
MATRIX_ACCESS_TOKEN | MATRIX_<ID>_ACCESS_TOKEN |
MATRIX_USER_ID | MATRIX_<ID>_USER_ID |
MATRIX_PASSWORD | MATRIX_<ID>_PASSWORD |
MATRIX_DEVICE_ID | MATRIX_<ID>_DEVICE_ID |
MATRIX_DEVICE_NAME | MATRIX_<ID>_DEVICE_NAME |
MATRIX_RECOVERY_KEY | MATRIX_<ID>_RECOVERY_KEY |
ops worden de namen MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN, enzovoort. De omgevingsvariabelen voor de herstelsleutel worden gelezen door herstelbewuste CLI-flows (verify backup restore, verify device, verify bootstrap) wanneer je de sleutel via --recovery-key-stdin invoert.
MATRIX_HOMESERVER kan niet worden ingesteld vanuit een workspace-.env; zie Workspace-.env-bestanden.
Configuratievoorbeeld
Een praktische basis met DM-koppeling, room-allowlist en E2EE:Streamingvoorbeelden
Matrix-antwoordstreaming is opt-in.streaming bepaalt hoe OpenClaw het lopende assistentantwoord aflevert; blockStreaming bepaalt of elk voltooid blok als eigen Matrix-bericht wordt behouden.
streaming | Gedrag |
|---|---|
"off" (standaard) | Wacht op het volledige antwoord en verzend één keer. true ↔ "partial", false ↔ "off". |
"partial" | Bewerk één normaal tekstbericht ter plaatse terwijl het model het huidige blok schrijft. Standaard Matrix-clients kunnen melden bij het eerste voorbeeld, niet bij de laatste bewerking. |
"quiet" | Zelfde als "partial", maar het bericht is een niet-meldende notice. Ontvangers krijgen pas een melding zodra een pushregel per gebruiker overeenkomt met de definitieve bewerking (zie hieronder). |
blockStreaming staat los van streaming:
streaming | blockStreaming: true | blockStreaming: false (standaard) |
|---|---|---|
"partial" / "quiet" | Live concept voor het huidige blok, voltooide blokken behouden als berichten | Live concept voor het huidige blok, ter plaatse afgerond |
"off" | Eén meldend Matrix-bericht per voltooid blok | Eén meldend Matrix-bericht voor het volledige antwoord |
- Als een voorbeeld groter wordt dan de limiet voor Matrix per event, stopt OpenClaw met voorbeeldstreaming en valt terug op aflevering alleen aan het einde.
- Media-antwoorden verzenden bijlagen altijd normaal. Als een verouderd voorbeeld niet langer veilig kan worden hergebruikt, redigeert OpenClaw het voordat het definitieve media-antwoord wordt verzonden.
- Voorbeeldupdates voor toolvoortgang zijn standaard ingeschakeld wanneer Matrix-voorbeeldstreaming actief is. Stel
streaming.preview.toolProgress: falsein om voorbeeldbewerkingen voor antwoordtekst te behouden, maar toolvoortgang op het normale afleverpad te laten. - Voorbeeldbewerkingen kosten extra Matrix-API-aanroepen. Laat
streaming: "off"staan als je het meest conservatieve rate-limitprofiel wilt.
Goedkeuringsmetadata
Native Matrix-goedkeuringsprompts zijn normalem.room.message-events met OpenClaw-specifieke aangepaste eventinhoud onder com.openclaw.approval. Matrix staat aangepaste eventinhoudsleutels toe, dus standaardclients tonen nog steeds de tekstbody terwijl OpenClaw-bewuste clients de gestructureerde goedkeurings-ID, soort, status, beschikbare beslissingen en exec-/Plugin-details kunnen lezen.
Wanneer een goedkeuringsprompt te lang is voor één Matrix-event, splitst OpenClaw de zichtbare tekst in stukken en voegt com.openclaw.approval alleen toe aan het eerste stuk. Reacties voor toestaan/weigeren-beslissingen zijn gebonden aan dat eerste event, zodat lange prompts hetzelfde goedkeuringsdoel behouden als prompts met één event.
Zelfgehoste pushregels voor stille definitieve voorbeelden
streaming: "quiet" meldt ontvangers pas zodra een blok of beurt definitief is — een pushregel per gebruiker moet overeenkomen met de definitieve voorbeeldmarkering. Zie Matrix-pushregels voor stille voorbeelden voor het volledige recept (ontvangertoken, pushercontrole, regelinstallatie, opmerkingen per homeserver).
Bot-naar-bot-rooms
Standaard worden Matrix-berichten van andere geconfigureerde OpenClaw Matrix-accounts genegeerd. GebruikallowBots wanneer je bewust Matrix-verkeer tussen agents wilt:
allowBots: trueaccepteert berichten van andere geconfigureerde Matrix-botaccounts in toegestane rooms en DM’s.allowBots: "mentions"accepteert die berichten alleen wanneer ze deze bot zichtbaar vermelden in rooms. DM’s blijven toegestaan.groups.<room>.allowBotsoverschrijft de instelling op accountniveau voor één room.- OpenClaw negeert nog steeds berichten van dezelfde Matrix-gebruikers-ID om loops met antwoorden aan zichzelf te voorkomen.
- Matrix biedt hier geen native botvlag; OpenClaw behandelt “geschreven door bot” als “verzonden door een ander geconfigureerd Matrix-account op deze OpenClaw-Gateway”.
Versleuteling en verificatie
In versleutelde (E2EE) ruimtes gebruiken uitgaande afbeeldingsgebeurtenissenthumbnail_file, zodat afbeeldingsvoorbeelden samen met de volledige bijlage worden versleuteld. Niet-versleutelde ruimtes gebruiken nog steeds gewone thumbnail_url. Er is geen configuratie nodig — de Plugin detecteert de E2EE-status automatisch.
Alle openclaw matrix-opdrachten accepteren --verbose (volledige diagnostiek), --json (machineleesbare uitvoer) en --account <id> (set-ups met meerdere accounts). De uitvoer is standaard beknopt, met stille interne SDK-logboekregistratie. De voorbeelden hieronder tonen de canonieke vorm; voeg de vlaggen toe wanneer nodig.
Versleuteling inschakelen
--recovery-key <key>pas een herstelsleutel toe vóór het bootstrappen (geef de voorkeur aan de hieronder gedocumenteerde stdin-vorm)--force-reset-cross-signingverwijder de huidige cross-signing-identiteit en maak een nieuwe aan (gebruik dit alleen bewust)
--encryption is een alias voor --enable-e2ee.
Handmatig configuratie-equivalent:
Status- en vertrouwenssignalen
verify status rapporteert drie onafhankelijke vertrouwenssignalen (--verbose toont ze allemaal):
Locally trusted: alleen door deze client vertrouwdCross-signing verified: de SDK rapporteert verificatie via cross-signingSigned by owner: ondertekend door je eigen zelfondertekeningssleutel (alleen diagnostisch)
Verified by owner wordt alleen yes wanneer Cross-signing verified yes is. Lokaal vertrouwen of alleen een handtekening van de eigenaar is niet genoeg.
--allow-degraded-local-state geeft best-effort diagnostiek terug zonder eerst het Matrix-account voor te bereiden; nuttig voor offline of gedeeltelijk geconfigureerde controles.
Dit apparaat verifiëren met een herstelsleutel
De herstelsleutel is gevoelig — pipe deze via stdin in plaats van hem op de opdrachtregel door te geven. StelMATRIX_RECOVERY_KEY in (of MATRIX_<ID>_RECOVERY_KEY voor een benoemd account):
Recovery key accepted: Matrix heeft de sleutel geaccepteerd voor secret storage of apparaatvertrouwen.Backup usable: roomsleutelback-up kan worden geladen met het vertrouwde herstelmateriaal.Device verified by owner: dit apparaat heeft volledig Matrix cross-signing-identiteitsvertrouwen.
verify self wacht op Cross-signing verified: yes voordat de opdracht succesvol afsluit. Gebruik --timeout-ms <ms> om de wachttijd af te stemmen.
De letterlijke sleutelvorm openclaw matrix verify device "<recovery-key>" wordt ook geaccepteerd, maar de sleutel komt dan in je shellgeschiedenis terecht.
Cross-signing bootstrappen of herstellen
verify bootstrap is de herstel- en instellingsopdracht voor versleutelde accounts. In volgorde doet deze het volgende:
- bootstrapt secret storage, waarbij waar mogelijk een bestaande herstelsleutel wordt hergebruikt
- bootstrapt cross-signing en uploadt ontbrekende openbare sleutels
- markeert en cross-signt het huidige apparaat
- maakt een server-side roomsleutelback-up als die nog niet bestaat
m.login.dummy en daarna m.login.password (vereist channels.matrix.password).
Nuttige vlaggen:
--recovery-key-stdin(combineer metprintf '%s\n' "$MATRIX_RECOVERY_KEY" | …) of--recovery-key <key>--force-reset-cross-signingom de huidige cross-signing-identiteit te verwijderen (alleen bewust)
Roomsleutelback-up
backup status toont of er een server-side back-up bestaat en of dit apparaat deze kan ontsleutelen. backup restore importeert geback-upte roomsleutels in de lokale crypto-store; als de herstelsleutel al op schijf staat, kun je --recovery-key-stdin weglaten.
Om een kapotte back-up te vervangen door een nieuwe basislijn (accepteert verlies van onherstelbare oude geschiedenis; kan ook secret storage opnieuw aanmaken als het huidige back-upgeheim niet kan worden geladen):
--rotate-recovery-key alleen toe wanneer je bewust wilt dat de vorige herstelsleutel de nieuwe back-upbasislijn niet meer kan ontgrendelen.
Verificaties weergeven, aanvragen en beantwoorden
--own-user vraagt zelfverificatie aan (je accepteert de prompt in een andere Matrix-client van dezelfde gebruiker); --user-id/--device-id/--room-id richten zich op iemand anders. --own-user kan niet worden gecombineerd met de andere doelvlaggen.
Voor lagere-niveau levenscyclusafhandeling — meestal tijdens het volgen van inkomende verzoeken vanuit een andere client — werken deze opdrachten op een specifiek verzoek <id> (afgedrukt door verify list en verify request):
| Opdracht | Doel |
|---|---|
openclaw matrix verify accept <id> | Een inkomend verzoek accepteren |
openclaw matrix verify start <id> | De SAS-flow starten |
openclaw matrix verify sas <id> | De SAS-emoji of decimalen afdrukken |
openclaw matrix verify confirm-sas <id> | Bevestigen dat de SAS overeenkomt met wat de andere client toont |
openclaw matrix verify mismatch-sas <id> | De SAS afwijzen wanneer de emoji of decimalen niet overeenkomen |
openclaw matrix verify cancel <id> | Annuleren; accepteert optioneel --reason <text> en --code <matrix-code> |
accept, start, sas, confirm-sas, mismatch-sas en cancel accepteren allemaal --user-id en --room-id als DM-opvolghints wanneer de verificatie aan een specifieke direct-message-ruimte is gekoppeld.
Opmerkingen over meerdere accounts
Zonder--account <id> gebruiken Matrix CLI-opdrachten het impliciete standaardaccount. Als je meerdere benoemde accounts hebt en channels.matrix.defaultAccount niet hebt ingesteld, weigeren ze te gokken en vragen ze je om een keuze te maken. Wanneer E2EE is uitgeschakeld of niet beschikbaar is voor een benoemd account, wijzen fouten naar de configuratiesleutel van dat account, bijvoorbeeld channels.matrix.accounts.assistant.encryption.
Startup behavior
Startup behavior
Met
encryption: true is startupVerification standaard "if-unverified". Bij het opstarten vraagt een niet-geverifieerd apparaat om zelfverificatie in een andere Matrix-client, waarbij duplicaten worden overgeslagen en een cooldown wordt toegepast (standaard 24 uur). Stem dit af met startupVerificationCooldownHours of schakel het uit met startupVerification: "off".Bij het opstarten wordt ook een conservatieve crypto-bootstrap-pass uitgevoerd die de huidige secret storage en cross-signing-identiteit hergebruikt. Als de bootstrap-status kapot is, probeert OpenClaw een afgeschermde reparatie, zelfs zonder channels.matrix.password; als de homeserver wachtwoord-UIA vereist, logt startup een waarschuwing en blijft dit niet-fataal. Apparaten die al door de eigenaar zijn ondertekend, blijven behouden.Zie Matrix-migratie voor de volledige upgradeflow.Verification notices
Verification notices
Matrix plaatst verificatielevenscyclusmeldingen in de strikte DM-verificatieruimte als
m.notice-berichten: verzoek, gereed (met begeleiding voor “verifiëren met emoji”), start/voltooiing en SAS-details (emoji/decimaal) wanneer beschikbaar.Inkomende verzoeken van een andere Matrix-client worden gevolgd en automatisch geaccepteerd. Voor zelfverificatie start OpenClaw de SAS-flow automatisch en bevestigt zijn eigen kant zodra emoji-verificatie beschikbaar is — je moet nog steeds vergelijken en “They match” bevestigen in je Matrix-client.Verificatiesysteemmeldingen worden niet doorgestuurd naar de agent-chatpijplijn.Deleted or invalid Matrix device
Deleted or invalid Matrix device
Als Maak voor tokenauthenticatie een nieuw toegangstoken aan in je Matrix-client of beheer-UI en werk daarna OpenClaw bij:Vervang
verify status zegt dat het huidige apparaat niet meer op de homeserver staat, maak dan een nieuw OpenClaw Matrix-apparaat aan. Voor inloggen met wachtwoord:assistant door de account-ID uit de mislukte opdracht, of laat --account weg voor het standaardaccount.Device hygiene
Device hygiene
Oude door OpenClaw beheerde apparaten kunnen zich ophopen. Weergeven en opschonen:
Crypto store
Crypto store
Matrix E2EE gebruikt het officiële
matrix-js-sdk Rust-cryptopad met fake-indexeddb als IndexedDB-shim. Crypto-status blijft bewaard in crypto-idb-snapshot.json (beperkte bestandsrechten).Versleutelde runtimestatus staat onder ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ en omvat de sync-store, crypto-store, herstelsleutel, IDB-snapshot, threadkoppelingen en startup-verificatiestatus. Wanneer het token verandert maar de accountidentiteit gelijk blijft, hergebruikt OpenClaw de beste bestaande root zodat eerdere status zichtbaar blijft.Profielbeheer
Werk het Matrix-zelfprofiel bij voor het geselecteerde account:mxc://-avatar-URL’s rechtstreeks; wanneer je http:// of https:// doorgeeft, uploadt OpenClaw het bestand eerst en slaat het de opgeloste mxc://-URL op in channels.matrix.avatarUrl (of de overschrijving per account).
Threads
Matrix ondersteunt native Matrix-threads voor zowel automatische antwoorden als verzendingen via berichttools. Twee onafhankelijke knoppen sturen het gedrag:Sessieroutering (sessionScope)
dm.sessionScope bepaalt hoe Matrix DM-ruimtes aan OpenClaw-sessies worden gekoppeld:
"per-user"(standaard): alle DM-ruimtes met dezelfde gerouteerde peer delen één sessie."per-room": elke Matrix DM-ruimte krijgt een eigen sessiesleutel, zelfs wanneer de peer dezelfde is.
sessionScope, dus gekoppelde ruimtes en threads behouden hun gekozen doelsessie.
Antwoordthreads (threadReplies)
threadReplies bepaalt waar de bot zijn antwoord plaatst:
"off": antwoorden zijn top-level. Inkomende gethreade berichten blijven op de bovenliggende sessie."inbound": antwoord alleen binnen een thread wanneer het inkomende bericht al in die thread stond."always": antwoord binnen een thread die is geworteld in het triggerende bericht; dat gesprek wordt vanaf de eerste trigger door een overeenkomende thread-gescopeerde sessie gerouteerd.
dm.threadReplies overschrijft dit alleen voor DM’s — houd bijvoorbeeld ruimtethreads geïsoleerd terwijl DM’s vlak blijven.
Thread-overerving en slash-opdrachten
- Inkomende berichten met threads bevatten het rootbericht van de thread als extra agentcontext.
- Verzendingen via berichttools erven automatisch de huidige Matrix-thread wanneer ze op dezelfde ruimte zijn gericht (of op hetzelfde DM-gebruikersdoel), tenzij een expliciete
threadIdis opgegeven. - Hergebruik van DM-gebruikersdoelen treedt alleen in werking wanneer de metadata van de huidige sessie dezelfde DM-peer op hetzelfde Matrix-account bewijst; anders valt OpenClaw terug op normale gebruikersgebonden routering.
/focus,/unfocus,/agents,/session idle,/session max-ageen threadgebonden/acp spawnwerken allemaal in Matrix-ruimten en DM’s.- Een
/focusop topniveau maakt een nieuwe Matrix-thread en bindt die aan de doelsessie wanneerthreadBindings.spawnSubagentSessions: true. - Het uitvoeren van
/focusof/acp spawn --thread herebinnen een bestaande Matrix-thread bindt die thread ter plaatse.
m.notice in die ruimte die verwijst naar de /focus-uitweg en een wijziging van dm.sessionScope voorstelt. De melding verschijnt alleen wanneer threadbindingen zijn ingeschakeld.
ACP-gespreksbindingen
Matrix-ruimten, DM’s en bestaande Matrix-threads kunnen worden omgezet in duurzame ACP-werkruimten zonder het chatoppervlak te wijzigen. Snelle operatorflow:- Voer
/acp spawn codex --bind hereuit binnen de Matrix-DM, ruimte of bestaande thread die je wilt blijven gebruiken. - In een Matrix-DM of -ruimte op topniveau blijft de huidige DM/ruimte het chatoppervlak en worden toekomstige berichten naar de gespawnde ACP-sessie gerouteerd.
- Binnen een bestaande Matrix-thread bindt
--bind heredie huidige thread ter plaatse. /newen/resetresetten dezelfde gebonden ACP-sessie ter plaatse./acp closesluit de ACP-sessie en verwijdert de binding.
--bind heremaakt geen onderliggende Matrix-thread.threadBindings.spawnAcpSessionsis alleen vereist voor/acp spawn --thread auto|here, waarbij OpenClaw een onderliggende Matrix-thread moet maken of binden.
Configuratie voor threadbinding
Matrix erft globale standaardwaarden vansession.threadBindings en ondersteunt ook kanaalspecifieke overschrijvingen:
threadBindings.enabledthreadBindings.idleHoursthreadBindings.maxAgeHoursthreadBindings.spawnSubagentSessionsthreadBindings.spawnAcpSessions
- Stel
threadBindings.spawnSubagentSessions: truein om toe te staan dat/focusop topniveau nieuwe Matrix-threads maakt en bindt. - Stel
threadBindings.spawnAcpSessions: truein om toe te staan dat/acp spawn --thread auto|hereACP-sessies aan Matrix-threads bindt.
Reacties
Matrix ondersteunt uitgaande reacties, inkomende reactiemeldingen en ack-reacties. Tooling voor uitgaande reacties wordt afgeschermd doorchannels.matrix.actions.reactions:
reactvoegt een reactie toe aan een Matrix-event.reactionstoont de huidige reactiesamenvatting voor een Matrix-event.emoji=""verwijdert de eigen reacties van de bot op dat event.remove: trueverwijdert alleen de opgegeven emoji-reactie van de bot.
| Instelling | Volgorde |
|---|---|
ackReaction | per account → kanaal → messages.ackReaction → emoji-fallback voor agentidentiteit |
ackReactionScope | per account → kanaal → messages.ackReactionScope → standaard "group-mentions" |
reactionNotifications | per account → kanaal → standaard "own" |
reactionNotifications: "own" stuurt toegevoegde m.reaction-events door wanneer ze gericht zijn op door de bot geschreven Matrix-berichten; "off" schakelt systeemevents voor reacties uit. Verwijderingen van reacties worden niet gesynthetiseerd tot systeemevents, omdat Matrix die als redacties weergeeft en niet als zelfstandige verwijderingen van m.reaction.
Historiecontext
channels.matrix.historyLimitbepaalt hoeveel recente ruimteberichten worden opgenomen alsInboundHistorywanneer een Matrix-ruimtebericht de agent triggert. Valt terug opmessages.groupChat.historyLimit; als beide niet zijn ingesteld, is de effectieve standaardwaarde0. Stel0in om uit te schakelen.- Matrix-ruimtehistorie is alleen voor ruimten. DM’s blijven normale sessiehistorie gebruiken.
- Matrix-ruimtehistorie is alleen pending: OpenClaw buffert ruimteberichten die nog geen antwoord hebben getriggerd en maakt vervolgens een snapshot van dat venster wanneer een vermelding of andere trigger binnenkomt.
- Het huidige triggerbericht wordt niet opgenomen in
InboundHistory; het blijft in de hoofdinhoud van de inkomende beurt. - Nieuwe pogingen voor hetzelfde Matrix-event hergebruiken de oorspronkelijke historiesnapshot in plaats van vooruit te verschuiven naar nieuwere ruimteberichten.
Contextzichtbaarheid
Matrix ondersteunt het gedeeldecontextVisibility-beheer voor aanvullende ruimtecontext, zoals opgehaalde antwoordtekst, threadroots en pending historie.
contextVisibility: "all"is de standaard. Aanvullende context wordt behouden zoals ontvangen.contextVisibility: "allowlist"filtert aanvullende context tot afzenders die zijn toegestaan door de actieve allowlist-controles voor ruimte/gebruiker.contextVisibility: "allowlist_quote"gedraagt zich alsallowlist, maar behoudt nog steeds één expliciet geciteerd antwoord.
groupPolicy, groups, groupAllowFrom en DM-beleidsinstellingen.
DM- en ruimtebeleid
dm.enabled: false in:
Directe ruimtereparatie
Als de status van directe berichten niet meer synchroon loopt, kan OpenClaw achterblijven met verouderdem.direct-toewijzingen die naar oude soloruimten wijzen in plaats van naar de live-DM. Inspecteer de huidige toewijzing voor een peer:
--account <id> voor multi-accountconfiguraties. De reparatieflow:
- geeft de voorkeur aan een strikte 1:1-DM die al in
m.directis toegewezen - valt terug op elke momenteel gejoinde strikte 1:1-DM met die gebruiker
- maakt een nieuwe directe ruimte en herschrijft
m.directals er geen gezonde DM bestaat
Exec-goedkeuringen
Matrix kan fungeren als een native goedkeuringsclient. Configureer onderchannels.matrix.execApprovals (of channels.matrix.accounts.<account>.execApprovals voor een per-accountoverschrijving):
enabled: lever goedkeuringen via Matrix-native prompts. Wanneer niet ingesteld of"auto", schakelt Matrix automatisch in zodra minstens één goedkeurder kan worden opgelost. Stelfalsein om expliciet uit te schakelen.approvers: Matrix-gebruikers-ID’s (@owner:example.org) die exec-aanvragen mogen goedkeuren. Optioneel — valt terug opchannels.matrix.dm.allowFrom.target: waar prompts naartoe gaan."dm"(standaard) stuurt naar DM’s van goedkeurders;"channel"stuurt naar de oorspronkelijke Matrix-ruimte of DM;"both"stuurt naar beide.agentFilter/sessionFilter: optionele allowlists voor welke agents/sessies Matrix-levering triggeren.
- Exec-goedkeuringen gebruiken
execApprovals.approversen vallen terug opdm.allowFrom. - Plugin-goedkeuringen autoriseren alleen via
dm.allowFrom.
✅eenmaal toestaan❌weigeren♾️altijd toestaan (wanneer het effectieve exec-beleid dit toestaat)
/approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.
Alleen opgeloste goedkeurders kunnen goedkeuren of weigeren. Kanaallevering voor exec-goedkeuringen bevat de opdrachttekst — schakel channel of both alleen in vertrouwde ruimten in.
Gerelateerd: Exec-goedkeuringen.
Slashopdrachten
Slashopdrachten (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve, enzovoort) werken rechtstreeks in DM’s. In ruimten herkent OpenClaw ook opdrachten die zijn voorafgegaan door de eigen Matrix-vermelding van de bot, zodat @bot:server /new het opdrachtpad triggert zonder een aangepaste vermeldingsregex. Dit houdt de bot responsief op ruimtestijlposts met @mention /command die Element en vergelijkbare clients uitsturen wanneer een gebruiker de bot via tabaanvulling invoegt voordat de opdracht wordt getypt.
Autorisatieregels blijven van toepassing: afzenders van opdrachten moeten voldoen aan hetzelfde DM- of ruimtebeleid voor allowlists/eigenaren als gewone berichten.
Multi-account
- Waarden op topniveau van
channels.matrixfungeren als standaardwaarden voor benoemde accounts, tenzij een account ze overschrijft. - Beperk een overgeërfde ruimtevermelding tot een specifiek account met
groups.<room>.account. Vermeldingen zonderaccountworden gedeeld tussen accounts;account: "default"werkt nog steeds wanneer het standaardaccount op topniveau is geconfigureerd.
- Stel
defaultAccountin om het benoemde account te kiezen waaraan impliciete routering, probing en CLI-opdrachten de voorkeur geven. - Als je meerdere accounts hebt en er één letterlijk
defaultheet, gebruikt OpenClaw dat impliciet, zelfs wanneerdefaultAccountniet is ingesteld. - Als je meerdere benoemde accounts hebt en er geen standaard is geselecteerd, weigeren CLI-opdrachten te gokken — stel
defaultAccountin of geef--account <id>door. - Het blok
channels.matrix.*op topniveau wordt alleen behandeld als het implicietedefault-account wanneer de auth volledig is (homeserver+accessToken, ofhomeserver+userId+password). Benoemde accounts blijven vindbaar viahomeserver+userIdzodra gecachete credentials auth afdekken.
- Wanneer OpenClaw een single-accountconfiguratie tijdens reparatie of setup promoveert naar multi-account, behoudt het het bestaande benoemde account als er één bestaat of als
defaultAccountal naar één wijst. Alleen Matrix-auth/bootstrap-sleutels verplaatsen naar het gepromoveerde account; gedeelde sleutels voor leveringsbeleid blijven op topniveau.
Private/LAN-homeservers
Standaard blokkeert OpenClaw private/interne Matrix-homeservers voor SSRF-bescherming, tenzij je expliciet per account opt-in inschakelt. Als je homeserver op localhost, een LAN/Tailscale-IP of een interne hostnaam draait, schakel dannetwork.dangerouslyAllowPrivateNetwork in voor dat Matrix-account:
http://matrix.example.org:8008, blijven geblokkeerd. Geef waar mogelijk de voorkeur aan https://.
Matrix-verkeer via proxy laten verlopen
Als je Matrix-implementatie een expliciete uitgaande HTTP(S)-proxy nodig heeft, stel jechannels.matrix.proxy in:
channels.matrix.accounts.<id>.proxy.
OpenClaw gebruikt dezelfde proxy-instelling voor runtime Matrix-verkeer en statusprobes voor accounts.
Doelresolutie
Matrix accepteert deze doelvormen overal waar OpenClaw je om een kamer- of gebruikersdoel vraagt:- Gebruikers:
@user:server,user:@user:server, ofmatrix:user:@user:server - Kamers:
!room:server,room:!room:server, ofmatrix:room:!room:server - Aliassen:
#alias:server,channel:#alias:server, ofmatrix:channel:#alias:server
- Gebruikersopzoekingen bevragen de Matrix-gebruikersdirectory op die homeserver.
- Kameropzoekingen accepteren expliciete kamer-ID’s en aliassen direct, en vallen daarna terug op zoeken in namen van gekoppelde kamers voor dat account.
- Opzoeking van namen van gekoppelde kamers is best-effort. Als een kamernaam niet naar een ID of alias kan worden herleid, wordt die genegeerd door runtime allowlist-resolutie.
Configuratiereferentie
Allowlist-achtige velden (groupAllowFrom, dm.allowFrom, groups.<room>.users) accepteren volledige Matrix-gebruikers-ID’s (veiligst). Exacte directory-overeenkomsten worden bij het opstarten herleid en telkens wanneer de allowlist verandert terwijl de monitor draait; vermeldingen die niet kunnen worden herleid, worden tijdens runtime genegeerd. Kamer-allowlists geven om dezelfde reden de voorkeur aan kamer-ID’s of aliassen.
Account en verbinding
enabled: schakel het kanaal in of uit.name: optioneel weergavelabel voor het account.defaultAccount: voorkeursaccount-ID wanneer meerdere Matrix-accounts zijn geconfigureerd.accounts: benoemde overschrijvingen per account. Waarden op topniveau vanchannels.matrixworden als standaardwaarden geërfd.homeserver: homeserver-URL, bijvoorbeeldhttps://matrix.example.org.network.dangerouslyAllowPrivateNetwork: sta dit account toe verbinding te maken metlocalhost, LAN-/Tailscale-IP’s of interne hostnamen.proxy: optionele HTTP(S)-proxy-URL voor Matrix-verkeer. Overschrijving per account wordt ondersteund.userId: volledige Matrix-gebruikers-ID (@bot:example.org).accessToken: toegangstoken voor tokengebaseerde authenticatie. Plaintext- en SecretRef-waarden worden ondersteund via env/file/exec-providers (Geheimenbeheer).password: wachtwoord voor wachtwoordgebaseerde login. Plaintext- en SecretRef-waarden worden ondersteund.deviceId: expliciete Matrix-apparaat-ID.deviceName: weergavenaam van apparaat die wordt gebruikt tijdens wachtwoordlogin.avatarUrl: opgeslagen URL van eigen avatar voor profielsync en updates metprofile set.initialSyncLimit: maximumaantal events dat tijdens opstartsync wordt opgehaald.
Encryptie
encryption: schakel E2EE in. Standaard:false.startupVerification:"if-unverified"(standaard wanneer E2EE aan staat) of"off". Vraagt automatisch zelfverificatie aan bij het opstarten wanneer dit apparaat niet is geverifieerd.startupVerificationCooldownHours: afkoelperiode vóór de volgende automatische opstartaanvraag. Standaard:24.
Toegang en beleid
groupPolicy:"open","allowlist", of"disabled". Standaard:"allowlist".groupAllowFrom: allowlist van gebruikers-ID’s voor kamerverkeer.dm.enabled: wanneerfalse, negeer alle DM’s. Standaard:true.dm.policy:"pairing"(standaard),"allowlist","open", of"disabled". Wordt toegepast nadat de bot is toegetreden en de kamer als DM heeft geclassificeerd; dit heeft geen invloed op uitnodigingsafhandeling.dm.allowFrom: allowlist van gebruikers-ID’s voor DM-verkeer.dm.sessionScope:"per-user"(standaard) of"per-room".dm.threadReplies: DM-only overschrijving voor reply-threading ("off","inbound","always").allowBots: accepteer berichten van andere geconfigureerde Matrix-botaccounts (trueof"mentions").allowlistOnly: wanneertrue, dwingt alle actieve DM-beleidsregels (behalve"disabled") en"open"groepsbeleidsregels naar"allowlist". Wijzigt"disabled"-beleidsregels niet.autoJoin:"always","allowlist", of"off". Standaard:"off". Geldt voor elke Matrix-uitnodiging, inclusief DM-achtige uitnodigingen.autoJoinAllowlist: kamers/aliassen die zijn toegestaan wanneerautoJoin"allowlist"is. Aliasvermeldingen worden herleid via de homeserver, niet via status die door de uitgenodigde kamer wordt geclaimd.contextVisibility: aanvullende contextzichtbaarheid ("all"standaard,"allowlist","allowlist_quote").
Antwoordgedrag
replyToMode:"off","first","all", of"batched".threadReplies:"off","inbound", of"always".threadBindings: overschrijvingen per kanaal voor thread-gebonden sessierouting en lifecycle.streaming:"off"(standaard),"partial","quiet", of objectvorm{ mode, preview: { toolProgress } }.true↔"partial",false↔"off".blockStreaming: wanneertrue, worden voltooide assistentblokken als afzonderlijke voortgangsberichten behouden.markdown: optionele Markdown-renderingconfiguratie voor uitgaande tekst.responsePrefix: optionele string die voor uitgaande antwoorden wordt geplaatst.textChunkLimit: uitgaande chunkgrootte in tekens wanneerchunkMode: "length". Standaard:4000.chunkMode:"length"(standaard, splitst op aantal tekens) of"newline"(splitst op regelgrenzen).historyLimit: aantal recente kamerberichten dat alsInboundHistorywordt opgenomen wanneer een kamerbericht de agent triggert. Valt terug opmessages.groupChat.historyLimit; effectieve standaard0(uitgeschakeld).mediaMaxMb: maximale mediagrootte in MB voor uitgaande verzendingen en inkomende verwerking.
Reactie-instellingen
ackReaction: overschrijving van ack-reactie voor dit kanaal/account.ackReactionScope: scope-overschrijving ("group-mentions"standaard,"group-all","direct","all","none","off").reactionNotifications: modus voor meldingen over inkomende reacties ("own"standaard,"off").
Tooling en overschrijvingen per kamer
actions: tool-gating per actie (messages,reactions,pins,profile,memberInfo,channelInfo,verification).groups: beleidsmap per kamer. Sessie-identiteit gebruikt de stabiele kamer-ID na resolutie. (roomsis een legacy-alias.)groups.<room>.account: beperk één geërfde kamerinvoer tot een specifiek account.groups.<room>.allowBots: overschrijving per kamer van de instelling op kanaalniveau (trueof"mentions").groups.<room>.users: allowlist van afzenders per kamer.groups.<room>.tools: overschrijvingen per kamer om tools toe te staan of te weigeren.groups.<room>.autoReply: overschrijving per kamer voor mention-gating.trueschakelt mention-vereisten voor die kamer uit;falsedwingt ze weer af.groups.<room>.skills: skillfilter per kamer.groups.<room>.systemPrompt: system-promptfragment per kamer.
Instellingen voor exec-goedkeuring
execApprovals.enabled: lever exec-goedkeuringen via Matrix-native prompts.execApprovals.approvers: Matrix-gebruikers-ID’s die mogen goedkeuren. Valt terug opdm.allowFrom.execApprovals.target:"dm"(standaard),"channel", of"both".execApprovals.agentFilter/execApprovals.sessionFilter: optionele allowlists voor agents/sessies voor bezorging.
Gerelateerd
- Kanalenoverzicht — alle ondersteunde kanalen
- Koppelen — DM-authenticatie en koppelingsflow
- Groepen — groepschatgedrag en mention-gating
- Kanaalroutering — sessierouting voor berichten
- Beveiliging — toegangsmodel en hardening