Matrix (plugin)

Matrix e un protocollo di messaggistica aperto e decentralizzato. OpenClaw si connette come utente Matrix su qualsiasi homeserver, quindi serve un account Matrix per il bot. Una volta effettuato il login, puoi inviare DM direttamente al bot o invitarlo nelle stanze (i “gruppi” di Matrix). Beeper e un’opzione client valida, ma richiede l’abilitazione di E2EE.

Stato: supportato via plugin (@vector-im/matrix-bot-sdk). Messaggi diretti, stanze, thread, media, reazioni, sondaggi (invio + poll-start come testo), posizione e E2EE (con supporto crypto).

Plugin necessario

Matrix e distribuito come plugin e non e incluso nell’installazione core.

Installa da CLI (registro npm):

openclaw plugins install @openclaw/matrix

Da checkout locale (se stai lavorando da un repo git):

openclaw plugins install ./extensions/matrix

Se scegli Matrix durante la configurazione/onboarding e viene rilevato un checkout git, OpenClaw offrira automaticamente il percorso di installazione locale.

Dettagli: Plugin

Setup

  1. Installa il plugin Matrix:

    • Da npm: openclaw plugins install @openclaw/matrix
    • Da checkout locale: openclaw plugins install ./extensions/matrix

  2. Crea un account Matrix su un homeserver:

  3. Ottieni un access token per l’account bot:

    • Usa l’API di login Matrix con curl sul tuo 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"
}'
    • Sostituisci matrix.example.org con l’URL del tuo homeserver.
    • Oppure imposta channels.matrix.userId + channels.matrix.password: OpenClaw chiama lo stesso endpoint di login, salva l’access token in ~/.openclaw/credentials/matrix/credentials.json e lo riusa al prossimo avvio.

  4. Configura le credenziali:

    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (o MATRIX_USER_ID + MATRIX_PASSWORD)
    • Oppure config: channels.matrix.*
    • Se entrambi sono impostati, il config ha la precedenza.
    • Con access token: lo user ID viene recuperato automaticamente via /whoami.
    • Quando impostato, channels.matrix.userId dovrebbe essere l’ID Matrix completo (esempio: @bot:example.org).

  5. Riavvia il gateway (o completa l’onboarding).

  6. Avvia un DM con il bot o invitalo in una stanza da qualsiasi client Matrix (Element, Beeper, ecc.; vedi https://matrix.org/ecosystem/clients/). Beeper richiede E2EE, quindi imposta channels.matrix.encryption: true e verifica il dispositivo.

Configurazione minimale (access token, user ID recuperato automaticamente):

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

Configurazione E2EE (crittografia end-to-end abilitata):

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

Crittografia (E2EE)

La crittografia end-to-end e supportata tramite l’SDK crypto Rust.

Abilita con channels.matrix.encryption: true:

  • Se il modulo crypto si carica, le stanze crittografate sono decrittate automaticamente.
  • I media in uscita sono crittografati quando si inviano a stanze crittografate.
  • Alla prima connessione, OpenClaw richiede la verifica del dispositivo dalle altre tue sessioni.
  • Verifica il dispositivo in un altro client Matrix (Element, ecc.) per abilitare la condivisione delle chiavi.
  • Se il modulo crypto non puo essere caricato, E2EE e disabilitato e le stanze crittografate non saranno decrittate; OpenClaw registra un avviso.
  • Se vedi errori di modulo crypto mancante (ad esempio @matrix-org/matrix-sdk-crypto-nodejs-*), consenti gli script di build per @matrix-org/matrix-sdk-crypto-nodejs e esegui pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs o scarica il binario con node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Lo stato crypto e salvato per account + access token in ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (database SQLite). Lo stato di sincronizzazione si trova accanto in bot-storage.json. Se l’access token (dispositivo) cambia, viene creato un nuovo store e il bot deve essere ri-verificato per le stanze crittografate.

Verifica del dispositivo: Quando E2EE e abilitato, il bot richiedera la verifica dalle altre tue sessioni all’avvio. Apri Element (o un altro client) e approva la richiesta di verifica per stabilire la fiducia. Una volta verificato, il bot puo decrittare i messaggi nelle stanze crittografate.

Multi-account

Supporto multi-account: usa channels.matrix.accounts con credenziali per account e name opzionale. Vedi gateway/configuration per il pattern condiviso.

Ogni account funziona come un utente Matrix separato su qualsiasi homeserver. La configurazione per account eredita dalle impostazioni di livello superiore channels.matrix e puo sovrascrivere qualsiasi opzione (policy DM, gruppi, crittografia, ecc.).

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

Note:

  • L’avvio degli account e serializzato per evitare race condition con import concorrenti dei moduli.
  • Le variabili env (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, ecc.) si applicano solo all’account predefinito.
  • Le impostazioni base del canale (policy DM, policy gruppi, gating menzione, ecc.) si applicano a tutti gli account a meno che non vengano sovrascritte per account.
  • Usa bindings[].match.accountId per instradare ogni account a un agent diverso.
  • Lo stato crypto e salvato per account + access token (store di chiavi separati per account).

Modello di routing

  • Le risposte tornano sempre a Matrix.
  • I DM condividono la sessione principale dell’agent; le stanze mappano a sessioni di gruppo.

Controllo degli accessi (DM)

  • Predefinito: channels.matrix.dm.policy = "pairing". I mittenti sconosciuti ricevono un codice di pairing.
  • Approvazione tramite:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • DM pubblici: channels.matrix.dm.policy="open" piu channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom accetta ID utente Matrix completi (esempio: @user:server). Il wizard risolve i nomi visualizzati in ID utente quando la ricerca nella directory trova una corrispondenza esatta unica.
  • Non usare nomi visualizzati o localpart semplici (esempio: "Alice" o "alice"). Sono ambigui e vengono ignorati per il matching dell’allowlist. Usa ID completi @user:server.

Stanze (gruppi)

  • Predefinito: channels.matrix.groupPolicy = "allowlist" (gating menzione). Usa channels.defaults.groupPolicy per sovrascrivere il valore predefinito quando non impostato.
  • Nota runtime: se channels.matrix e completamente assente, il runtime torna a groupPolicy="allowlist" per i controlli delle stanze (anche se channels.defaults.groupPolicy e impostato).
  • Allowlist stanze con channels.matrix.groups (ID stanza o alias; i nomi vengono risolti in ID quando la ricerca nella directory trova una corrispondenza esatta unica):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false abilita la risposta automatica in quella stanza.
  • groups."*" puo impostare i valori predefiniti per il gating menzione tra le stanze.
  • groupAllowFrom limita quali mittenti possono attivare il bot nelle stanze (ID utente Matrix completi).
  • Le allowlist users per stanza possono ulteriormente limitare i mittenti all’interno di una stanza specifica (usa ID utente Matrix completi).
  • Il wizard di configurazione chiede le allowlist delle stanze (ID stanza, alias o nomi) e risolve i nomi solo con corrispondenza esatta e unica.
  • All’avvio, OpenClaw risolve i nomi di stanza/utente nelle allowlist in ID e registra la mappatura; le voci non risolte sono ignorate per il matching dell’allowlist.
  • Gli inviti vengono accettati automaticamente per impostazione predefinita; controlla con channels.matrix.autoJoin e channels.matrix.autoJoinAllowlist.
  • Per non consentire nessuna stanza, imposta channels.matrix.groupPolicy: "disabled" (o mantieni un’allowlist vuota).
  • Chiave legacy: channels.matrix.rooms (stessa struttura di groups).

Thread

  • Il threading delle risposte e supportato.
  • channels.matrix.threadReplies controlla se le risposte restano nei thread:
    • off, inbound (predefinito), always
  • channels.matrix.replyToMode controlla i metadati reply-to quando non si risponde in un thread:
    • off (predefinito), first, all

Funzionalita

FunzionalitaStato
Messaggi direttiSupportati
StanzeSupportate
ThreadSupportati
MediaSupportati
E2EESupportata (modulo crypto necessario)
ReazioniSupportate (invio/lettura tramite strumenti)
SondaggiInvio supportato; i poll-start in ingresso sono convertiti in testo (risposte/fine ignorati)
PosizioneSupportata (geo URI; altitudine ignorata)
Comandi nativiSupportati

Risoluzione problemi

Esegui questa scaletta prima:

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

Poi conferma lo stato del pairing DM se necessario:

openclaw pairing list matrix

Problemi comuni:

  • Login effettuato ma messaggi delle stanze ignorati: stanza bloccata da groupPolicy o allowlist delle stanze.
  • DM ignorati: mittente in attesa di approvazione quando channels.matrix.dm.policy="pairing".
  • Stanze crittografate non funzionanti: supporto crypto o impostazioni di crittografia non corrispondenti.

Per il flusso di triage: /channels/troubleshooting.

Riferimento configurazione (Matrix)

Configurazione completa: Configurazione

Opzioni del provider:

  • channels.matrix.enabled: abilita/disabilita l’avvio del canale.
  • channels.matrix.homeserver: URL dell’homeserver.
  • channels.matrix.userId: ID utente Matrix (opzionale con access token).
  • channels.matrix.accessToken: access token.
  • channels.matrix.password: password per il login (token salvato).
  • channels.matrix.deviceName: nome visualizzato del dispositivo.
  • channels.matrix.encryption: abilita E2EE (predefinito: false).
  • channels.matrix.initialSyncLimit: limite di sincronizzazione iniziale.
  • channels.matrix.threadReplies: off | inbound | always (predefinito: inbound).
  • channels.matrix.textChunkLimit: dimensione segmento testo in uscita (caratteri).
  • channels.matrix.chunkMode: length (predefinito) o newline per dividere sulle righe vuote (confini di paragrafo) prima della segmentazione per lunghezza.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (predefinito: pairing).
  • channels.matrix.dm.allowFrom: allowlist DM (ID utente Matrix completi). open richiede "*". Il wizard risolve i nomi in ID quando possibile.
  • channels.matrix.groupPolicy: allowlist | open | disabled (predefinito: allowlist).
  • channels.matrix.groupAllowFrom: mittenti in allowlist per i messaggi di gruppo (ID utente Matrix completi).
  • channels.matrix.allowlistOnly: forza le regole allowlist per DM + stanze.
  • channels.matrix.groups: allowlist gruppi + mappa impostazioni per stanza.
  • channels.matrix.rooms: allowlist/config gruppi legacy.
  • channels.matrix.replyToMode: modalita reply-to per thread/tag.
  • channels.matrix.mediaMaxMb: limite media in ingresso/uscita (MB).
  • channels.matrix.autoJoin: gestione inviti (always | allowlist | off, predefinito: always).
  • channels.matrix.autoJoinAllowlist: ID stanza/alias consentiti per l’auto-join.
  • channels.matrix.accounts: configurazione multi-account con chiave per ID account (ogni account eredita le impostazioni di livello superiore).
  • channels.matrix.actions: gating strumenti per azione (reazioni/messaggi/pin/memberInfo/channelInfo).
arrow_back
Precedente
Line
Successivo
Mattermost
arrow_forward