Matrix (plugin)

Matrix is een open, gedecentraliseerd berichtenprotocol. OpenClaw maakt verbinding als Matrix-gebruiker op elke homeserver, dus je hebt een Matrix-account nodig voor de bot. Zodra de bot is ingelogd, kun je hem een DM sturen of uitnodigen in kamers (Matrix-”groepen”). Beeper is ook een geldige clientoptie, maar vereist dat E2EE is ingeschakeld.

Status: ondersteund via plugin (@vector-im/matrix-bot-sdk). Directe berichten, kamers, threads, media, reacties, polls (versturen + poll-start als tekst), locatie en E2EE (met crypto-ondersteuning).

Plugin vereist

Matrix wordt als plugin geleverd en is niet gebundeld met de kerninstallatie.

Installeren via CLI (npm-register):

openclaw plugins install @openclaw/matrix

Lokale checkout (vanuit een git-repo):

openclaw plugins install ./extensions/matrix

Als je Matrix kiest tijdens configureren/onboarding en een git-checkout wordt gedetecteerd, biedt OpenClaw automatisch het lokale installatiepad aan.

Details: Plugins

Installatie

Installeer de Matrix-plugin:
- Vanuit npm: openclaw plugins install @openclaw/matrix
- Vanuit een lokale checkout: openclaw plugins install ./extensions/matrix
Maak een Matrix-account aan op een homeserver:
- Bekijk hostingopties op https://matrix.org/ecosystem/hosting/
- Of host het zelf.
Verkrijg een access token voor het botaccount:
- Gebruik de Matrix login-API met curl op je homeserver:
```
curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
```
- Vervang matrix.example.org door je homeserver-URL.
- Of stel channels.matrix.userId + channels.matrix.password in: OpenClaw roept hetzelfde login-eindpunt aan, slaat het access token op in ~/.openclaw/credentials/matrix/credentials.json en hergebruikt het bij de volgende start.
Configureer credentials:
- Omgevingsvariabelen: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (of MATRIX_USER_ID + MATRIX_PASSWORD)
- Of config: channels.matrix.*
- Als beide zijn ingesteld, heeft config voorrang.
- Met access token: gebruikers-ID wordt automatisch opgehaald via /whoami.
- Wanneer ingesteld, moet channels.matrix.userId het volledige Matrix-ID zijn (voorbeeld: @bot:example.org).
Herstart de gateway (of voltooi de onboarding).
Start een DM met de bot of nodig hem uit in een kamer vanuit elke Matrix-client (Element, Beeper, etc.; zie https://matrix.org/ecosystem/clients/). Beeper vereist E2EE, dus stel channels.matrix.encryption: true in en verifieer het apparaat.

Minimale configuratie (access token, gebruikers-ID automatisch opgehaald):

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

E2EE-configuratie (end-to-end-versleuteling ingeschakeld):

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

Versleuteling (E2EE)

End-to-end-versleuteling wordt ondersteund via de Rust crypto-SDK.

Inschakelen met channels.matrix.encryption: true:

Als de cryptomodule laadt, worden versleutelde kamers automatisch ontsleuteld.
Uitgaande media wordt versleuteld bij het versturen naar versleutelde kamers.
Bij de eerste verbinding vraagt OpenClaw apparaatverificatie aan bij je andere sessies.
Verifieer het apparaat in een andere Matrix-client (Element, etc.) om sleuteldeling in te schakelen.
Als de cryptomodule niet kan worden geladen, wordt E2EE uitgeschakeld en worden versleutelde kamers niet ontsleuteld; OpenClaw logt een waarschuwing.
Als je fouten ziet over ontbrekende cryptomodules (bijv. @matrix-org/matrix-sdk-crypto-nodejs-*), sta dan build-scripts toe voor @matrix-org/matrix-sdk-crypto-nodejs en voer pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs uit of haal de binary op met node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Cryptostatus wordt per account + access token opgeslagen in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite-database). Syncstatus staat ernaast in bot-storage.json. Als het access token (apparaat) verandert, wordt een nieuwe opslag aangemaakt en moet de bot opnieuw worden geverifieerd voor versleutelde kamers.

Apparaatverificatie: Wanneer E2EE is ingeschakeld, vraagt de bot bij opstart verificatie aan bij je andere sessies. Open Element (of een andere client) en keur het verificatieverzoek goed om vertrouwen te vestigen. Eenmaal geverifieerd kan de bot berichten ontsleutelen in versleutelde kamers.

Multi-account

Multi-account-ondersteuning: gebruik channels.matrix.accounts met per-account credentials en optionele name. Zie gateway/configuration voor het gedeelde patroon.

Elk account draait als een aparte Matrix-gebruiker op elke homeserver. Per-account-configuratie erft van de instellingen op het hoogste niveau van channels.matrix en kan elke optie overschrijven (DM-beleid, groepen, versleuteling, etc.).

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

Opmerkingen:

Accountopstart is geserialiseerd om race-condities bij gelijktijdige module-imports te voorkomen.
Omgevingsvariabelen (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) gelden alleen voor het standaardaccount.
Basiskanaalinstellingen (DM-beleid, groepsbeleid, mention-gating, etc.) gelden voor alle accounts tenzij per account overschreven.
Gebruik bindings[].match.accountId om elk account naar een andere agent te routeren.
Cryptostatus wordt per account + access token opgeslagen (aparte sleutelopslag per account).

Routeringsmodel

Antwoorden gaan altijd terug naar Matrix.
DM’s delen de hoofdsessie van de agent; kamers worden gekoppeld aan groepssessies.

Toegangscontrole (DM’s)

Standaard: channels.matrix.dm.policy = "pairing". Onbekende afzenders krijgen een koppelingscode.
Goedkeuren via:
- openclaw pairing list matrix
- openclaw pairing approve matrix <CODE>
Openbare DM’s: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
channels.matrix.dm.allowFrom accepteert volledige Matrix-gebruikers-ID’s (voorbeeld: @user:server). De wizard lost weergavenamen op naar gebruikers-ID’s wanneer een zoekopdracht in de directory precies een match oplevert.
Gebruik geen weergavenamen of kale localparts (voorbeeld: "Alice" of "alice"). Ze zijn ambigu en worden genegeerd voor allowlist-matching. Gebruik volledige @user:server-ID’s.

Kamers (groepen)

Standaard: channels.matrix.groupPolicy = "allowlist" (mention-gated). Gebruik channels.defaults.groupPolicy om de standaard te overschrijven wanneer niet ingesteld.
Runtime-opmerking: als channels.matrix volledig ontbreekt, valt de runtime terug op groupPolicy="allowlist" voor kamercontroles (zelfs als channels.defaults.groupPolicy is ingesteld).
Sta kamers toe met channels.matrix.groups (kamer-ID’s of aliassen; namen worden opgelost naar ID’s wanneer een zoekopdracht precies een match oplevert):

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

requireMention: false schakelt automatisch antwoorden in die kamer in.
groups."*" kan standaarden instellen voor mention-gating over kamers.
groupAllowFrom beperkt welke afzenders de bot in kamers kunnen triggeren (volledige Matrix-gebruikers-ID’s).
Per-kamer users-allowlists kunnen afzenders binnen een specifieke kamer verder beperken (gebruik volledige Matrix-gebruikers-ID’s).
De configuratiewizard vraagt om kamer-allowlists (kamer-ID’s, aliassen of namen) en lost namen alleen op bij een exacte, unieke match.
Bij opstart lost OpenClaw kamer-/gebruikersnamen in allowlists op naar ID’s en logt de mapping; niet-opgeloste vermeldingen worden genegeerd voor allowlist-matching.
Uitnodigingen worden standaard automatisch geaccepteerd; beheer met channels.matrix.autoJoin en channels.matrix.autoJoinAllowlist.
Om geen kamers toe te staan, stel je channels.matrix.groupPolicy: "disabled" in (of houd een lege allowlist).
Legacy-sleutel: channels.matrix.rooms (dezelfde structuur als groups).

Threads

Thread-antwoorden worden ondersteund.
channels.matrix.threadReplies bepaalt of antwoorden in threads blijven:
- off, inbound (standaard), always
channels.matrix.replyToMode bepaalt reply-to-metadata wanneer niet in een thread wordt geantwoord:
- off (standaard), first, all

Mogelijkheden

Functie	Status
Directe berichten	Ondersteund
Kamers	Ondersteund
Threads	Ondersteund
Media	Ondersteund
E2EE	Ondersteund (cryptomodule vereist)
Reacties	Ondersteund (versturen/lezen via tools)
Polls	Versturen ondersteund; inkomende poll-starts worden omgezet naar tekst (antwoorden/einden genegeerd)
Locatie	Ondersteund (geo-URI; hoogte genegeerd)
Native commando’s	Ondersteund

Probleemoplossing

Voer eerst deze commandoladder uit:

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

Bevestig vervolgens de DM-koppelingsstatus indien nodig:

openclaw pairing list matrix

Veelvoorkomende fouten:

Ingelogd maar kamerberichten genegeerd: kamer geblokkeerd door groupPolicy of kamer-allowlist.
DM’s genegeerd: afzender wacht op goedkeuring bij channels.matrix.dm.policy="pairing".
Versleutelde kamers werken niet: cryptoondersteuning of versleutelingsinstellingen komen niet overeen.

Voor triageflow: /channels/troubleshooting.

Configuratiereferentie (Matrix)

Volledige configuratie: Configuratie

Provideropties:

channels.matrix.enabled: kanaal in-/uitschakelen bij opstart.
channels.matrix.homeserver: homeserver-URL.
channels.matrix.userId: Matrix-gebruikers-ID (optioneel met access token).
channels.matrix.accessToken: access token.
channels.matrix.password: wachtwoord voor login (token wordt opgeslagen).
channels.matrix.deviceName: weergavenaam van het apparaat.
channels.matrix.encryption: E2EE inschakelen (standaard: false).
channels.matrix.initialSyncLimit: initiële synclimiet.
channels.matrix.threadReplies: off | inbound | always (standaard: inbound).
channels.matrix.textChunkLimit: uitgaande tekstchunkgrootte (tekens).
channels.matrix.chunkMode: length (standaard) of newline om te splitsen op lege regels (alineagrenzen) voor lengteopsplitsing.
channels.matrix.dm.policy: pairing | allowlist | open | disabled (standaard: pairing).
channels.matrix.dm.allowFrom: DM-allowlist (volledige Matrix-gebruikers-ID’s). open vereist "*". De wizard lost namen op naar ID’s wanneer mogelijk.
channels.matrix.groupPolicy: allowlist | open | disabled (standaard: allowlist).
channels.matrix.groupAllowFrom: toegestane afzenders voor groepsberichten (volledige Matrix-gebruikers-ID’s).
channels.matrix.allowlistOnly: forceer allowlist-regels voor DM’s + kamers.
channels.matrix.groups: groeps-allowlist + per-kamerinstellingenmap.
channels.matrix.rooms: legacy groeps-allowlist/config.
channels.matrix.replyToMode: reply-to-modus voor threads/tags.
channels.matrix.mediaMaxMb: inkomende/uitgaande medialimiet (MB).
channels.matrix.autoJoin: uitnodigingsafhandeling (always | allowlist | off, standaard: always).
channels.matrix.autoJoinAllowlist: toegestane kamer-ID’s/aliassen voor auto-join.
channels.matrix.accounts: multi-account-configuratie per account-ID (elk account erft instellingen op het hoogste niveau).
channels.matrix.actions: per-actie toolbeheer (reactions/messages/pins/memberInfo/channelInfo).