​

Matrix (plugin)

​

Plugin requerido

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Configuración

1. Instale el plugin de Matrix:
   • Desde npm: openclaw plugins install @openclaw/matrix
   • Desde un checkout local: openclaw plugins install ./extensions/matrix
2. Cree una cuenta de Matrix en un homeserver:
   • Explore opciones de alojamiento en https://matrix.org/ecosystem/hosting/
   • O alójelo usted mismo.
3. Obtenga un token de acceso para la cuenta del bot:
   • Use la API de inicio de sesión de Matrix con curl en su 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"
   }'
   
   • Reemplace matrix.example.org con la URL de su homeserver.
   • O configure channels.matrix.userId + channels.matrix.password: OpenClaw llama al mismo endpoint de inicio de sesión, almacena el token de acceso en ~/.openclaw/credentials/matrix/credentials.json, y lo reutiliza en el siguiente inicio.
4. Configure las credenciales:
   • Variables de entorno: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (o MATRIX_USER_ID + MATRIX_PASSWORD)
   • O configuración: channels.matrix.*
   • Si ambos están definidos, la configuración tiene prioridad.
   • Con token de acceso: el ID de usuario se obtiene automáticamente vía /whoami.
   • Cuando se establece, channels.matrix.userId debe ser el ID completo de Matrix (ejemplo: @bot:example.org).
5. Reinicie el Gateway (o finalice el onboarding).
6. Inicie un mensaje directo con el bot o invítelo a una sala desde cualquier cliente de Matrix (Element, Beeper, etc.; consulte https://matrix.org/ecosystem/clients/). Beeper requiere E2EE, así que configure channels.matrix.encryption: true y verifique el dispositivo.

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

​

Cifrado (E2EE)

• Si el módulo criptográfico se carga, las salas cifradas se descifran automáticamente.
• Los medios salientes se cifran cuando se envían a salas cifradas.
• En la primera conexión, OpenClaw solicita verificación del dispositivo desde sus otras sesiones.
• Verifique el dispositivo en otro cliente de Matrix (Element, etc.) para habilitar el intercambio de claves.
• Si el módulo criptográfico no puede cargarse, E2EE se deshabilita y las salas cifradas no se descifrarán; OpenClaw registra una advertencia.
• Si ve errores de módulo criptográfico faltante (por ejemplo, @matrix-org/matrix-sdk-crypto-nodejs-*), permita los scripts de compilación para @matrix-org/matrix-sdk-crypto-nodejs y ejecute pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs o obtenga el binario con node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

Multi-cuenta

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

• El inicio de las cuentas se serializa para evitar condiciones de carrera con importaciones de módulos concurrentes.
• Las variables de entorno (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) solo se aplican a la cuenta predeterminada.
• Los ajustes base del canal (política de MD, política de grupo, control por menciones, etc.) se aplican a todas las cuentas salvo que se sobrescriban por cuenta.
• Usa bindings[].match.accountId para enrutar cada cuenta a un agente diferente.
• El estado criptográfico se almacena por cuenta + token de acceso (almacenes de claves separados por cuenta).

​

Modelo de enrutamiento

• Las respuestas siempre regresan a Matrix.
• Los mensajes directos comparten la sesión principal del agente; las salas se asignan a sesiones de grupo.

​

Control de acceso (DMs)

• Predeterminado: channels.matrix.dm.policy = "pairing". Los remitentes desconocidos reciben un código de emparejamiento.
• Aprobar mediante:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• DMs públicos: channels.matrix.dm.policy="open" más channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom acepta IDs completos de usuario de Matrix (ejemplo: @user:server). El asistente resuelve nombres visibles a IDs cuando la búsqueda en el directorio encuentra una coincidencia exacta única.
• No uses nombres para mostrar ni localparts simples (ejemplo: "Alice" o "alice"). Son ambiguos y se ignoran para la coincidencia con la lista de permitidos. Usa identificadores completos @user:server.

​

Salas (grupos)

• Predeterminado: channels.matrix.groupPolicy = "allowlist" (restringido por mención). Use channels.defaults.groupPolicy para anular el valor predeterminado cuando no esté definido.
• Permita salas con channels.matrix.groups (IDs o alias de sala; los nombres se resuelven a IDs cuando la búsqueda en el directorio encuentra una coincidencia exacta única):

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

• requireMention: false habilita la respuesta automática en esa sala.
• groups."*" puede establecer valores predeterminados para la restricción por mención entre salas.
• groupAllowFrom restringe qué remitentes pueden activar el bot en salas (IDs completos de usuario de Matrix).
• Las listas de permitidos por sala users pueden restringir aún más los remitentes dentro de una sala específica (use IDs completos de usuario de Matrix).
• El asistente de configuración solicita listas de permitidos de salas (IDs, alias o nombres) y resuelve nombres solo con una coincidencia exacta y única.
• Al iniciar, OpenClaw resuelve nombres de salas/usuarios en listas de permitidos a IDs y registra el mapeo; las entradas no resueltas se ignoran para la coincidencia de listas de permitidos.
• Las invitaciones se aceptan automáticamente de forma predeterminada; contrólelo con channels.matrix.autoJoin y channels.matrix.autoJoinAllowlist.
• Para permitir ninguna sala, configure channels.matrix.groupPolicy: "disabled" (o mantenga una lista de permitidos vacía).
• Clave heredada: channels.matrix.rooms (misma estructura que groups).

​

Hilos

• Se admite la respuesta en hilos.
• channels.matrix.threadReplies controla si las respuestas permanecen en hilos:
  • off, inbound (predeterminado), always
• channels.matrix.replyToMode controla los metadatos de respuesta cuando no se responde en un hilo:
  • off (predeterminado), first, all

​

Capacidades

​

Solución de problemas

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

openclaw pairing list matrix

• Con sesión iniciada pero mensajes de sala ignorados: sala bloqueada por groupPolicy o por la lista de permitidos de salas.
• DMs ignorados: remitente pendiente de aprobación cuando channels.matrix.dm.policy="pairing".
• Fallos en salas cifradas: soporte criptográfico o desajuste en la configuración de cifrado.

​

Referencia de configuración (Matrix)

• channels.matrix.enabled: habilitar/deshabilitar el inicio del canal.
• channels.matrix.homeserver: URL del homeserver.
• channels.matrix.userId: ID de usuario de Matrix (opcional con token de acceso).
• channels.matrix.accessToken: token de acceso.
• channels.matrix.password: contraseña para inicio de sesión (se almacena el token).
• channels.matrix.deviceName: nombre visible del dispositivo.
• channels.matrix.encryption: habilitar E2EE (predeterminado: false).
• channels.matrix.initialSyncLimit: límite de sincronización inicial.
• channels.matrix.threadReplies: off | inbound | always (predeterminado: entrante).
• channels.matrix.textChunkLimit: tamaño de fragmento de texto saliente (caracteres).
• channels.matrix.chunkMode: length (predeterminado) o newline para dividir en líneas en blanco (límites de párrafo) antes de fragmentar por longitud.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (predeterminado: emparejamiento).
• channels.matrix.dm.allowFrom: lista de permitidos de DMs (IDs completos de usuario de Matrix). open requiere "*". El asistente resuelve nombres a IDs cuando es posible.
• channels.matrix.groupPolicy: allowlist | open | disabled (predeterminado: lista de permitidos).
• channels.matrix.groupAllowFrom: remitentes permitidos para mensajes de grupo (IDs completos de usuario de Matrix).
• channels.matrix.allowlistOnly: forzar reglas de lista de permitidos para DMs + salas.
• channels.matrix.groups: lista de permitidos de grupos + mapa de configuraciones por sala.
• channels.matrix.rooms: lista/configuración heredada de grupos.
• channels.matrix.replyToMode: modo de respuesta para hilos/etiquetas.
• channels.matrix.mediaMaxMb: límite de medios entrantes/salientes (MB).
• channels.matrix.autoJoin: manejo de invitaciones (always | allowlist | off, predeterminado: siempre).
• channels.matrix.autoJoinAllowlist: IDs/alias de salas permitidas para unión automática.
• channels.matrix.accounts: configuración multi-cuenta indexada por ID de cuenta (cada cuenta hereda los ajustes de nivel superior).
• channels.matrix.actions: control de herramientas por acción (reacciones/mensajes/pines/memberInfo/channelInfo).