​

Matrix

​

Plugin incluso

openclaw plugins install @openclaw/matrix

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

​

Configurazione iniziale

1. Assicurati che il plugin Matrix sia disponibile.
   • Le versioni pacchettizzate correnti di OpenClaw lo includono già.
   • Le installazioni più vecchie o personalizzate possono aggiungerlo manualmente con i comandi sopra.
2. Crea un account Matrix sul tuo homeserver.
3. Configura channels.matrix con uno dei seguenti:
   • homeserver + accessToken, oppure
   • homeserver + userId + password.
4. Riavvia il gateway.
5. Avvia un messaggio diretto con il bot o invitalo in una stanza.
   • I nuovi inviti Matrix funzionano solo quando channels.matrix.autoJoin li consente.

openclaw channels add
openclaw configure --section channels

• URL dell’homeserver
• metodo di autenticazione: token di accesso o password
• ID utente (solo autenticazione con password)
• nome dispositivo facoltativo
• se abilitare E2EE
• se configurare l’accesso alle stanze e l’ingresso automatico agli inviti

• Se le variabili d’ambiente di autenticazione Matrix esistono già e quell’account non ha già l’autenticazione salvata nella configurazione, la procedura guidata offre una scorciatoia env per mantenere l’autenticazione nelle variabili d’ambiente.
• I nomi degli account vengono normalizzati all’ID account. Ad esempio, Ops Bot diventa ops-bot.
• Le voci della allowlist dei messaggi diretti accettano direttamente @user:server; i nomi visualizzati funzionano solo quando la ricerca live nella directory trova una corrispondenza esatta.
• Le voci della allowlist delle stanze accettano direttamente ID stanza e alias. Preferisci !room:server o #alias:server; i nomi non risolti vengono ignorati in fase di esecuzione dalla risoluzione della allowlist.
• In modalità allowlist per l’ingresso automatico agli inviti, usa solo destinazioni di invito stabili: !roomId:server, #alias:server o *. I nomi semplici delle stanze vengono rifiutati.
• Per risolvere i nomi delle stanze prima di salvare, usa 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

​

Esempio di configurazione

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

​

Anteprime in streaming

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

• streaming: "off" è l’impostazione predefinita. OpenClaw attende la risposta finale e la invia una sola volta.
• streaming: "partial" crea un messaggio di anteprima modificabile per il blocco corrente dell’assistente usando normali messaggi di testo Matrix. Questo conserva il comportamento legacy di notifica basato sulla prima anteprima di Matrix, quindi i client standard possono notificare il primo testo dell’anteprima in streaming invece del blocco completato.
• streaming: "quiet" crea un’anteprima silenziosa modificabile per il blocco corrente dell’assistente. Usalo solo quando configuri anche regole push del destinatario per le modifiche finalizzate dell’anteprima.
• blockStreaming: true abilita messaggi di avanzamento Matrix separati. Con lo streaming dell’anteprima abilitato, Matrix mantiene la bozza live per il blocco corrente e conserva i blocchi completati come messaggi separati.
• Quando lo streaming dell’anteprima è attivo e blockStreaming è disattivato, Matrix modifica la bozza live sul posto e finalizza quello stesso evento quando il blocco o il turno termina.
• Se l’anteprima non entra più in un singolo evento Matrix, OpenClaw interrompe lo streaming dell’anteprima e torna alla consegna finale normale.
• Le risposte con contenuti multimediali continuano a inviare normalmente gli allegati. Se un’anteprima obsoleta non può più essere riutilizzata in sicurezza, OpenClaw la redige prima di inviare la risposta finale con contenuti multimediali.
• Le modifiche dell’anteprima comportano chiamate API Matrix aggiuntive. Lascia lo streaming disattivato se desideri il comportamento più conservativo rispetto ai limiti di frequenza.

• blockStreaming: true invia ogni blocco completato come normale messaggio Matrix con notifica.
• blockStreaming: false invia solo la risposta finale completata come normale messaggio Matrix con notifica.

​

Regole push self-hosted per anteprime silenziose finalizzate

• utente destinatario = la persona che deve ricevere la notifica
• utente bot = l’account Matrix OpenClaw che invia la risposta
• usa il token di accesso dell’utente destinatario per le chiamate API qui sotto
• fai corrispondere sender nella regola push con l’MXID completo dell’utente bot

1. Configura OpenClaw per usare anteprime silenziose:

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

2. Assicurati che l’account destinatario riceva già le normali notifiche push Matrix. Le regole per le anteprime silenziose funzionano solo se quell’utente ha già pusher/dispositivi funzionanti.
3. Ottieni il token di accesso dell’utente destinatario.
   • Usa il token dell’utente ricevente, non quello del bot.
   • Riutilizzare un token di sessione client esistente è di solito il modo più semplice.
   • Se devi generare un nuovo token, puoi effettuare il login tramite la API standard Client-Server di Matrix:

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. Verifica che l’account destinatario abbia già dei pusher:

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

{
  "com.openclaw.finalized_preview": true
}

5. Crea una regola push di override per ogni account destinatario che deve ricevere queste notifiche:

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: URL di base del tuo homeserver
• $USER_ACCESS_TOKEN: token di accesso dell’utente ricevente
• openclaw-finalized-preview-botname: un ID regola univoco per questo bot per questo utente ricevente
• @bot:example.org: l’MXID del tuo bot Matrix OpenClaw, non l’MXID dell’utente ricevente

• Le regole push sono indicizzate da ruleId. Eseguire di nuovo PUT sullo stesso ID regola aggiorna quella singola regola.
• Se un utente ricevente deve ricevere notifiche da più account bot Matrix OpenClaw, crea una regola per bot con un ID regola univoco per ogni corrispondenza di sender.
• Un modello semplice è openclaw-finalized-preview-<botname>, ad esempio openclaw-finalized-preview-ops o openclaw-finalized-preview-support.

• autentica con il token dell’utente ricevente
• fai corrispondere sender all’MXID del bot OpenClaw

6. Verifica che la regola esista:

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

7. Prova una risposta in streaming. In modalità silenziosa, la stanza dovrebbe mostrare una bozza di anteprima silenziosa e la modifica finale sul posto dovrebbe notificare quando il blocco o il turno termina.

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

• Crea la regola con il token di accesso dell’utente ricevente, non con quello del bot.
• Le nuove regole override definite dall’utente vengono inserite prima delle regole di soppressione predefinite, quindi non serve alcun parametro di ordinamento aggiuntivo.
• Questo influisce solo sulle modifiche dell’anteprima di solo testo che OpenClaw può finalizzare sul posto in sicurezza. I fallback per i contenuti multimediali e per le anteprime obsolete usano ancora la consegna Matrix normale.
• Se GET /_matrix/client/v3/pushers non mostra pusher, l’utente non ha ancora una consegna push Matrix funzionante per questo account/dispositivo.

​

Synapse

• Non è richiesta alcuna modifica speciale a homeserver.yaml per le notifiche delle anteprime OpenClaw finalizzate.
• Se la tua distribuzione Synapse invia già normali notifiche push Matrix, il token utente + la chiamata pushrules sopra sono il passaggio principale di configurazione.
• Se esegui Synapse dietro un reverse proxy o worker, assicurati che /_matrix/client/.../pushrules/ raggiunga Synapse correttamente.
• Se esegui worker Synapse, assicurati che i pusher siano in buono stato. La consegna push è gestita dal processo principale o da synapse.app.pusher / worker pusher configurati.

​

Tuwunel

• Non è richiesta alcuna configurazione specifica di Tuwunel per il marcatore di anteprima finalizzata stesso.
• Se le normali notifiche Matrix funzionano già per quell’utente, il token utente + la chiamata pushrules sopra sono il passaggio principale di configurazione.
• Se le notifiche sembrano scomparire mentre l’utente è attivo su un altro dispositivo, verifica se suppress_push_when_active è abilitato. Tuwunel ha aggiunto questa opzione in Tuwunel 1.4.2 il 12 settembre 2025 e può sopprimere intenzionalmente le notifiche push verso altri dispositivi mentre un dispositivo è attivo.

​

Stanze bot-to-bot

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

• allowBots: true accetta messaggi da altri account bot Matrix configurati in stanze e messaggi diretti consentiti.
• allowBots: "mentions" accetta quei messaggi solo quando menzionano visibilmente questo bot nelle stanze. I messaggi diretti restano consentiti.
• groups.<room>.allowBots sovrascrive l’impostazione a livello account per una stanza.
• OpenClaw continua a ignorare i messaggi provenienti dallo stesso ID utente Matrix per evitare loop di autorisposta.
• Matrix qui non espone un flag bot nativo; OpenClaw considera “scritto da bot” come “inviato da un altro account Matrix configurato su questo gateway OpenClaw”.

​

Crittografia e verifica

{
  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

​

Cosa significa “verificato”

• Locally trusted: questo dispositivo è attendibile solo dal client corrente
• Cross-signing verified: l’SDK segnala il dispositivo come verificato tramite cross-signing
• Signed by owner: il dispositivo è firmato dalla tua stessa chiave di self-signing

​

Cosa fa il bootstrap

• inizializza lo storage segreto, riutilizzando una chiave di recupero esistente quando possibile
• inizializza il cross-signing e carica le chiavi pubbliche di cross-signing mancanti
• tenta di contrassegnare e firmare tramite cross-signing il dispositivo corrente
• crea un nuovo backup lato server delle chiavi della stanza se non ne esiste già uno

​

Nuova baseline di backup

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

​

Comportamento all’avvio

​

Avvisi di verifica

• avvisi di richiesta di verifica
• avvisi di verifica pronta (con istruzioni esplicite “Verifica tramite emoji”)
• avvisi di inizio e completamento della verifica
• dettagli SAS (emoji e decimali) quando disponibili

​

Igiene dei dispositivi

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Archivio crittografico

​

Gestione del profilo

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

​

Thread

• dm.sessionScope: "per-user" (predefinito) mantiene l’instradamento dei DM Matrix nell’ambito del mittente, quindi più stanze DM possono condividere una sessione quando si risolvono allo stesso interlocutore.
• dm.sessionScope: "per-room" isola ogni stanza DM Matrix nella propria chiave di sessione continuando però a usare i normali controlli di autenticazione DM e allowlist.
• I binding espliciti delle conversazioni Matrix hanno comunque la precedenza su dm.sessionScope, quindi stanze e thread associati mantengono la sessione di destinazione scelta.
• threadReplies: "off" mantiene le risposte al livello superiore e mantiene i messaggi in arrivo nei thread sulla sessione padre.
• threadReplies: "inbound" risponde all’interno di un thread solo quando il messaggio in ingresso era già in quel thread.
• threadReplies: "always" mantiene le risposte delle stanze in un thread radicato nel messaggio che ha attivato l’azione e instrada quella conversazione tramite la sessione con ambito thread corrispondente a partire dal primo messaggio di attivazione.
• dm.threadReplies sovrascrive l’impostazione di livello superiore solo per i messaggi diretti. Ad esempio, puoi mantenere isolati i thread delle stanze mantenendo piatti i messaggi diretti.
• I messaggi in arrivo nei thread includono il messaggio radice del thread come contesto aggiuntivo per l’agente.
• Gli invii degli strumenti di messaggistica ereditano automaticamente il thread Matrix corrente quando la destinazione è la stessa stanza, o lo stesso utente DM di destinazione, a meno che non venga fornito un threadId esplicito.
• Il riutilizzo della stessa sessione per destinazione utente DM si attiva solo quando i metadati della sessione corrente dimostrano lo stesso interlocutore DM sullo stesso account Matrix; altrimenti OpenClaw torna al normale instradamento con ambito utente.
• Quando OpenClaw vede una stanza DM Matrix entrare in collisione con un’altra stanza DM sulla stessa sessione DM Matrix condivisa, pubblica in quella stanza un m.notice una sola volta con la via di fuga /focus quando i binding dei thread sono abilitati e con l’indicazione dm.sessionScope.
• I binding runtime dei thread sono supportati per Matrix. /focus, /unfocus, /agents, /session idle, /session max-age e /acp spawn associato a thread funzionano nelle stanze e nei DM Matrix.
• /focus di primo livello in stanza/DM Matrix crea un nuovo thread Matrix e lo associa alla sessione di destinazione quando threadBindings.spawnSubagentSessions=true.
• Eseguire /focus o /acp spawn --thread here all’interno di un thread Matrix esistente associa invece quel thread corrente.

​

Binding delle conversazioni ACP

• Esegui /acp spawn codex --bind here all’interno del DM Matrix, della stanza o del thread esistente che vuoi continuare a usare.
• In un DM o in una stanza Matrix di primo livello, il DM/stanza corrente resta la superficie della chat e i messaggi futuri vengono instradati alla sessione ACP generata.
• All’interno di un thread Matrix esistente, --bind here associa quel thread corrente sul posto.
• /new e /reset reimpostano sul posto la stessa sessione ACP associata.
• /acp close chiude la sessione ACP e rimuove il binding.

• --bind here non crea un thread Matrix figlio.
• threadBindings.spawnAcpSessions è richiesto solo per /acp spawn --thread auto|here, dove OpenClaw deve creare o associare un thread Matrix figlio.

​

Configurazione del binding dei thread

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

• Imposta threadBindings.spawnSubagentSessions: true per consentire a /focus di primo livello di creare e associare nuovi thread Matrix.
• Imposta threadBindings.spawnAcpSessions: true per consentire a /acp spawn --thread auto|here di associare sessioni ACP ai thread Matrix.

​

Reazioni

• Gli strumenti di reazione in uscita sono controllati da channels["matrix"].actions.reactions.
• react aggiunge una reazione a uno specifico evento Matrix.
• reactions elenca il riepilogo corrente delle reazioni per uno specifico evento Matrix.
• emoji="" rimuove le reazioni dell’account bot stesso su quell’evento.
• remove: true rimuove solo la reazione emoji specificata dall’account bot.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• fallback all’emoji dell’identità dell’agente

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

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• predefinito: own

• reactionNotifications: "own" inoltra gli eventi m.reaction aggiunti quando hanno come destinazione messaggi Matrix scritti dal bot.
• reactionNotifications: "off" disabilita gli eventi di sistema delle reazioni.
• Le rimozioni delle reazioni non vengono sintetizzate in eventi di sistema perché Matrix le espone come redazioni, non come rimozioni m.reaction autonome.

​

Contesto della cronologia

• channels.matrix.historyLimit controlla quanti messaggi recenti della stanza vengono inclusi come InboundHistory quando un messaggio in una stanza Matrix attiva l’agente. Fa fallback a messages.groupChat.historyLimit; se entrambi non sono impostati, il valore effettivo predefinito è 0. Imposta 0 per disabilitare.
• La cronologia delle stanze Matrix è limitata alla stanza. I DM continuano a usare la normale cronologia della sessione.
• La cronologia delle stanze Matrix è solo pending: OpenClaw mette in buffer i messaggi della stanza che non hanno ancora attivato una risposta, poi cattura quello stato quando arriva una menzione o un altro trigger.
• Il messaggio trigger corrente non è incluso in InboundHistory; resta nel corpo principale in ingresso per quel turno.
• I tentativi ripetuti sullo stesso evento Matrix riutilizzano lo snapshot originale della cronologia invece di spostarsi in avanti verso messaggi più recenti della stanza.

​

Visibilità del contesto

• contextVisibility: "all" è il valore predefinito. Il contesto supplementare viene mantenuto così come ricevuto.
• contextVisibility: "allowlist" filtra il contesto supplementare ai mittenti consentiti dai controlli di allowlist attivi della stanza/utente.
• contextVisibility: "allowlist_quote" si comporta come allowlist, ma mantiene comunque una risposta citata esplicita.

​

Policy per DM e stanze

{
  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>

​

Riparazione della stanza diretta

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

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

• preferisce un DM stretto 1:1 già mappato in m.direct
• in fallback usa qualsiasi DM stretto 1:1 attualmente unito con quell’utente
• crea una nuova stanza diretta e riscrive m.direct se non esiste alcun DM integro

​

Approvazioni exec

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (facoltativo; fa fallback a channels.matrix.dm.allowFrom)
• channels.matrix.execApprovals.target (dm | channel | both, predefinito: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.* controlla la modalità nativa di fanout DM/canale per i prompt di approvazione Matrix.
• Le approvazioni exec usano l’insieme degli approvatori exec da execApprovals.approvers o channels.matrix.dm.allowFrom.
• Le approvazioni plugin usano la allowlist DM Matrix da channels.matrix.dm.allowFrom.
• Le scorciatoie con reazioni Matrix e gli aggiornamenti dei messaggi si applicano sia alle approvazioni exec sia a quelle plugin.

• target: "dm" invia i prompt di approvazione ai DM degli approvatori
• target: "channel" rimanda il prompt alla stanza Matrix o al DM di origine
• target: "both" invia agli approvatori nei DM e alla stanza Matrix o al DM di origine

• ✅ = consenti una volta
• ❌ = nega
• ♾️ = consenti sempre quando quella decisione è permessa dalla policy exec effettiva

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

​

Multi-account

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

​

Homeserver privati/LAN

{
  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

​

Proxy del traffico Matrix

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

​

Risoluzione delle destinazioni

• Utenti: @user:server, user:@user:server o matrix:user:@user:server
• Stanze: !room:server, room:!room:server o matrix:room:!room:server
• Alias: #alias:server, channel:#alias:server o matrix:channel:#alias:server

• Le ricerche utente interrogano la directory utenti Matrix su quell’homeserver.
• Le ricerche stanza accettano direttamente ID stanza e alias espliciti, poi fanno fallback alla ricerca nei nomi delle stanze unite per quell’account.
• La ricerca per nome nelle stanze unite è best-effort. Se il nome di una stanza non può essere risolto in un ID o alias, viene ignorato dalla risoluzione della allowlist in fase di esecuzione.

​

Riferimento della configurazione

• enabled: abilita o disabilita il canale.
• name: etichetta facoltativa per l’account.
• defaultAccount: ID account preferito quando sono configurati più account Matrix.
• homeserver: URL dell’homeserver, ad esempio https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: consente a questo account Matrix di connettersi a homeserver privati/interni. Abilitalo quando l’homeserver si risolve in localhost, un IP LAN/Tailscale o un host interno come matrix-synapse.
• proxy: URL facoltativo del proxy HTTP(S) per il traffico Matrix. Gli account con nome possono sovrascrivere il valore predefinito di livello superiore con il proprio proxy.
• userId: ID utente Matrix completo, ad esempio @bot:example.org.
• accessToken: token di accesso per l’autenticazione basata su token. I valori in chiaro e i valori SecretRef sono supportati per channels.matrix.accessToken e channels.matrix.accounts.<id>.accessToken nei provider env/file/exec. Vedi Gestione dei segreti.
• password: password per il login basato su password. Sono supportati valori in chiaro e valori SecretRef.
• deviceId: ID dispositivo Matrix esplicito.
• deviceName: nome visualizzato del dispositivo per il login con password.
• avatarUrl: URL dell’avatar personale memorizzato per la sincronizzazione del profilo e gli aggiornamenti di profile set.
• initialSyncLimit: numero massimo di eventi recuperati durante la sincronizzazione di avvio.
• encryption: abilita E2EE.
• allowlistOnly: quando è true, aggiorna la policy delle stanze open a allowlist e forza tutte le policy DM attive eccetto disabled (incluse pairing e open) a allowlist. Non influisce sulle policy disabled.
• allowBots: consente messaggi da altri account Matrix OpenClaw configurati (true o "mentions").
• groupPolicy: open, allowlist o disabled.
• contextVisibility: modalità di visibilità del contesto supplementare della stanza (all, allowlist, allowlist_quote).
• groupAllowFrom: allowlist di ID utente per il traffico nelle stanze. Le voci dovrebbero essere ID utente Matrix completi; i nomi non risolti vengono ignorati in fase di esecuzione.
• historyLimit: numero massimo di messaggi della stanza da includere come contesto della cronologia di gruppo. Fa fallback a messages.groupChat.historyLimit; se entrambi non sono impostati, il valore effettivo predefinito è 0. Imposta 0 per disabilitare.
• replyToMode: off, first, all o batched.
• markdown: configurazione facoltativa del rendering Markdown per il testo Matrix in uscita.
• streaming: off (predefinito), "partial", "quiet", true o false. "partial" e true abilitano aggiornamenti di bozza basati sulla prima anteprima con normali messaggi di testo Matrix. "quiet" usa avvisi di anteprima senza notifica per configurazioni self-hosted con regole push. false equivale a "off".
• blockStreaming: true abilita messaggi di avanzamento separati per i blocchi completati dell’assistente mentre lo streaming della bozza di anteprima è attivo.
• threadReplies: off, inbound o always.
• threadBindings: override per canale per l’instradamento e il ciclo di vita delle sessioni associate ai thread.
• startupVerification: modalità di richiesta automatica di autoverifica all’avvio (if-unverified, off).
• startupVerificationCooldownHours: cooldown prima di ritentare richieste automatiche di verifica all’avvio.
• textChunkLimit: dimensione del chunk dei messaggi in uscita in caratteri (si applica quando chunkMode è length).
• chunkMode: length divide i messaggi per numero di caratteri; newline li divide ai confini di riga.
• responsePrefix: stringa facoltativa anteposta a tutte le risposte in uscita per questo canale.
• ackReaction: override facoltativo della reazione di conferma per questo canale/account.
• ackReactionScope: override facoltativo dell’ambito della reazione di conferma (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: modalità delle notifiche di reazione in ingresso (own, off).
• mediaMaxMb: limite di dimensione dei contenuti multimediali in MB per gli invii in uscita e l’elaborazione dei contenuti multimediali in ingresso.
• autoJoin: policy di ingresso automatico agli inviti (always, allowlist, off). Predefinito: off. Si applica a tutti gli inviti Matrix, inclusi gli inviti in stile messaggio diretto.
• autoJoinAllowlist: stanze/alias consentiti quando autoJoin è allowlist. Le voci alias vengono risolte in ID stanza durante la gestione dell’invito; OpenClaw non si fida dello stato dell’alias dichiarato dalla stanza invitata.
• dm: blocco della policy DM (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: controlla l’accesso ai messaggi diretti dopo che OpenClaw è entrato nella stanza e l’ha classificata come DM. Non cambia se un invito viene accettato automaticamente.
• dm.allowFrom: le voci dovrebbero essere ID utente Matrix completi, a meno che tu non li abbia già risolti tramite ricerca live nella directory.
• dm.sessionScope: per-user (predefinito) o per-room. Usa per-room quando vuoi che ogni stanza DM Matrix mantenga un contesto separato anche se l’interlocutore è lo stesso.
• dm.threadReplies: override della policy dei thread solo per DM (off, inbound, always). Sovrascrive l’impostazione threadReplies di livello superiore sia per il posizionamento delle risposte sia per l’isolamento delle sessioni nei DM.
• execApprovals: consegna nativa Matrix delle approvazioni exec (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: ID utente Matrix autorizzati ad approvare richieste exec. Facoltativo quando dm.allowFrom identifica già gli approvatori.
• execApprovals.target: dm | channel | both (predefinito: dm).
• accounts: override con nome per account. I valori di livello superiore di channels.matrix agiscono come valori predefiniti per queste voci.
• groups: mappa delle policy per stanza. Preferisci ID stanza o alias; i nomi delle stanze non risolti vengono ignorati in fase di esecuzione. L’identità di sessione/gruppo usa l’ID stanza stabile dopo la risoluzione.
• groups.<room>.account: limita una voce di stanza ereditata a uno specifico account Matrix nelle configurazioni multi-account.
• groups.<room>.allowBots: override a livello stanza per mittenti bot configurati (true o "mentions").
• groups.<room>.users: allowlist dei mittenti per stanza.
• groups.<room>.tools: override di allow/deny degli strumenti per stanza.
• groups.<room>.autoReply: override a livello stanza del requisito di menzione. true disabilita i requisiti di menzione per quella stanza; false li riattiva forzatamente.
• groups.<room>.skills: filtro facoltativo delle Skills a livello stanza.
• groups.<room>.systemPrompt: snippet facoltativo di system prompt a livello stanza.
• rooms: alias legacy per groups.
• actions: gating degli strumenti per azione (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

Correlati

• Panoramica dei canali — tutti i canali supportati
• Pairing — autenticazione DM e flusso di pairing
• Groups — comportamento delle chat di gruppo e gating delle menzioni
• Instradamento del canale — instradamento della sessione per i messaggi
• Sicurezza — modello di accesso e hardening