​

Matrix (plugin)

​

Plugin vereist

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Installatie

1. Installeer de Matrix-plugin:
   • Vanuit npm: openclaw plugins install @openclaw/matrix
   • Vanuit een lokale checkout: openclaw plugins install ./extensions/matrix
2. Maak een Matrix-account aan op een homeserver:
   • Bekijk hostingopties op https://matrix.org/ecosystem/hosting/
   • Of host het zelf.
3. 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 de URL van je homeserver.
   • 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 dit bij de volgende start.
4. Configureer referenties:
   • Env: 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.
   • Indien ingesteld, moet channels.matrix.userId de volledige Matrix-ID zijn (voorbeeld: @bot:example.org).
5. Herstart de Gateway (of rond onboarding af).
6. Start een DM met de bot of nodig hem uit in een kamer vanuit een Matrix-client (Element, Beeper, enz.; zie https://matrix.org/ecosystem/clients/). Beeper vereist E2EE, dus stel channels.matrix.encryption: true in en verifieer het apparaat.

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

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

​

Encryptie (E2EE)

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

​

Multi-account

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

• Het opstarten van accounts gebeurt geserialiseerd om racecondities bij gelijktijdige module-imports te voorkomen.
• Omgevingsvariabelen (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, enz.) zijn alleen van toepassing op het standaard account.
• Basis kanaalinstellingen (DM-beleid, groepsbeleid, mention-gating, enz.) zijn van toepassing op alle accounts, tenzij per account overschreven.
• Gebruik bindings[].match.accountId om elk account naar een andere agent te routeren.
• De cryptostatus wordt per account + access token opgeslagen (afzonderlijke key stores per account).

​

Routeringsmodel

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

​

Toegangsbeheer (DM’s)

• Standaard: channels.matrix.dm.policy = "pairing". Onbekende afzenders krijgen een koppelcode.
• 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 zet weergavenamen om naar gebruikers-ID’s wanneer de directoryzoekactie één exacte match vindt.
• Gebruik geen display names of losse localparts (voorbeeld: "Alice" of "alice"). Deze zijn dubbelzinnig en worden genegeerd bij 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.
• Sta kamers toe met channels.matrix.groups (kamer-ID’s of aliassen; namen worden omgezet naar ID’s wanneer de directoryzoekactie één exacte match vindt):

{
  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 standaardinstellingen voor mention-gating over kamers heen instellen.
• groupAllowFrom beperkt welke afzenders de bot in kamers kunnen activeren (volledige Matrix-gebruikers-ID’s).
• Per-kamer users-toegestane lijsten kunnen afzenders binnen een specifieke kamer verder beperken (gebruik volledige Matrix-gebruikers-ID’s).
• De configuratiewizard vraagt om kamer-toegestane lijsten (kamer-ID’s, aliassen of namen) en zet namen alleen om bij een exacte, unieke match.
• Bij het opstarten zet OpenClaw kamer-/gebruikersnamen in toegestane lijsten om naar ID’s en logt de mapping; niet-opgeloste items worden genegeerd bij het matchen van toegestane lijsten.
• Uitnodigingen worden standaard automatisch geaccepteerd; beheer dit met channels.matrix.autoJoin en channels.matrix.autoJoinAllowlist.
• Om geen kamers toe te staan, stel channels.matrix.groupPolicy: "disabled" in (of houd een lege toegestane lijst).
• Verouderde sleutel: channels.matrix.rooms (zelfde vorm als groups).

​

Threads

• Antwoord-threading wordt 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

​

Problemen oplossen

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

openclaw pairing list matrix

• Ingelogd maar kamerberichten genegeerd: kamer geblokkeerd door groupPolicy of kamer-toegestane lijst.
• DM’s genegeerd: afzender wacht op goedkeuring wanneer channels.matrix.dm.policy="pairing".
• Versleutelde kamers falen: mismatch in crypto-ondersteuning of encryptie-instellingen.

​

Configuratiereferentie (Matrix)

• channels.matrix.enabled: kanaalstart in-/uitschakelen.
• 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 opgeslagen).
• channels.matrix.deviceName: weergavenaam van het apparaat.
• channels.matrix.encryption: E2EE inschakelen (standaard: false).
• channels.matrix.initialSyncLimit: initiële sync-limiet.
• channels.matrix.threadReplies: off | inbound | always (standaard: inbound).
• channels.matrix.textChunkLimit: uitgaande tekst-chunkgrootte (tekens).
• channels.matrix.chunkMode: length (standaard) of newline om op lege regels (paragraafgrenzen) te splitsen vóór lengte-chunking.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (standaard: pairing).
• channels.matrix.dm.allowFrom: DM-toegestane lijst (volledige Matrix-gebruikers-ID’s). open vereist "*". De wizard zet namen waar mogelijk om naar ID’s.
• channels.matrix.groupPolicy: allowlist | open | disabled (standaard: allowlist).
• channels.matrix.groupAllowFrom: toegestane afzenders voor groepsberichten (volledige Matrix-gebruikers-ID’s).
• channels.matrix.allowlistOnly: afdwingen van allowlist-regels voor DM’s + kamers.
• channels.matrix.groups: groeps-allowlist + per-kamerinstellingenkaart.
• channels.matrix.rooms: verouderde groeps-allowlist/config.
• channels.matrix.replyToMode: reply-to-modus voor threads/tags.
• channels.matrix.mediaMaxMb: inbound/outbound media-limiet (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-accountconfiguratie gesleuteld op account-ID (elk account erft instellingen op topniveau).
• channels.matrix.actions: per-actie tool-gating (reactions/messages/pins/memberInfo/channelInfo).