Matrix (plugin)

Matrix es un protocolo de mensajería abierto y descentralizado. OpenClaw se conecta como un usuario de Matrix en cualquier homeserver, por lo que necesitas una cuenta de Matrix para el bot. Una vez autenticado, puedes enviar un DM al bot directamente o invitarlo a salas (los “grupos” de Matrix). Beeper también es una opción de cliente válida, pero requiere que E2EE esté habilitado.

Estado: compatible vía plugin (@vector-im/matrix-bot-sdk). Mensajes directos, salas, hilos, multimedia, reacciones, encuestas (envío + poll-start como texto), ubicación, y E2EE (con soporte de criptografía).

Plugin requerido

Matrix se distribuye como plugin y no viene incluido en la instalación base.

Instalar vía CLI (registro npm):

openclaw plugins install @openclaw/matrix

Checkout local (cuando se ejecuta desde un repositorio git):

openclaw plugins install ./extensions/matrix

Si eliges Matrix durante la configuración/onboarding y se detecta un checkout de git, OpenClaw ofrecerá la ruta de instalación local automáticamente.

Detalles: Plugins

Configuración

  1. Instala el plugin de Matrix:

    • Desde npm: openclaw plugins install @openclaw/matrix
    • Desde un checkout local: openclaw plugins install ./extensions/matrix

  2. Crea una cuenta de Matrix en un homeserver:

  3. Obtén un token de acceso para la cuenta del bot:

    • Usa la API de login de Matrix con curl en tu 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"
}'
    • Reemplaza matrix.example.org con la URL de tu homeserver.
    • O configura channels.matrix.userId + channels.matrix.password: OpenClaw llama al mismo endpoint de login, almacena el token de acceso en ~/.openclaw/credentials/matrix/credentials.json, y lo reutiliza en el siguiente inicio.

  4. Configura las credenciales:

    • Variable de entorno: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (o MATRIX_USER_ID + MATRIX_PASSWORD)
    • O configuración: channels.matrix.*
    • Si ambos están configurados, la configuración tiene prioridad.
    • Con token de acceso: el ID de usuario se obtiene automáticamente vía /whoami.
    • Cuando se configura, channels.matrix.userId debe ser el ID completo de Matrix (ejemplo: @bot:example.org).

  5. Reinicia el gateway (o termina el onboarding).

  6. Inicia un DM con el bot o invítalo a una sala desde cualquier cliente de Matrix (Element, Beeper, etc.; ver https://matrix.org/ecosystem/clients/). Beeper requiere E2EE, así que configura channels.matrix.encryption: true y verifica el dispositivo.

Configuración mínima (token de acceso, ID de usuario auto-obtenido):

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

Configuración con E2EE (cifrado de extremo a extremo habilitado):

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

Cifrado (E2EE)

El cifrado de extremo a extremo es compatible vía el SDK de criptografía en Rust.

Habilita con channels.matrix.encryption: true:

  • Si el módulo de criptografía carga, las salas cifradas se descifran automáticamente.
  • Los multimedia salientes se cifran al enviar a salas cifradas.
  • En la primera conexión, OpenClaw solicita verificación de dispositivo a tus otras sesiones.
  • Verifica el dispositivo en otro cliente de Matrix (Element, etc.) para habilitar el intercambio de claves.
  • Si el módulo de criptografía no puede cargarse, E2EE se deshabilita y las salas cifradas no se descifrarán; OpenClaw registra una advertencia.
  • Si ves errores de módulo de criptografía faltante (por ejemplo, @matrix-org/matrix-sdk-crypto-nodejs-*), permite los scripts de build para @matrix-org/matrix-sdk-crypto-nodejs y ejecuta pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs o descarga el binario con node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

El estado de criptografía se almacena por cuenta + token de acceso en ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (base de datos SQLite). El estado de sincronización está junto a él en bot-storage.json. Si el token de acceso (dispositivo) cambia, se crea un nuevo almacén y el bot debe ser re-verificado para las salas cifradas.

Verificación de dispositivo: Cuando E2EE está habilitado, el bot solicitará verificación de tus otras sesiones al iniciar. Abre Element (u otro cliente) y aprueba la solicitud de verificación para establecer confianza. Una vez verificado, el bot puede descifrar mensajes en salas cifradas.

Multi-cuenta

Soporte multi-cuenta: usa channels.matrix.accounts con credenciales por cuenta y name opcional. Consulta gateway/configuration para el patrón compartido.

Cada cuenta se ejecuta como un usuario de Matrix separado en cualquier homeserver. La configuración por cuenta hereda de la configuración de nivel superior channels.matrix y puede anular cualquier opción (política de DM, grupos, cifrado, 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"] },
        },
      },
    },
  },
}

Notas:

  • El inicio de 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 aplican a la cuenta default.
  • La configuración base del canal (política de DM, política de grupo, restricción por mención, etc.) aplica a todas las cuentas a menos que se anule por cuenta.
  • Usa bindings[].match.accountId para enrutar cada cuenta a un agente diferente.
  • El estado de criptografía se almacena por cuenta + token de acceso (almacenes de claves separados por cuenta).

Modelo de enrutamiento

  • Las respuestas siempre vuelven a Matrix.
  • Los DMs comparten la sesión principal del agente; las salas se mapean a sesiones de grupo.

Control de acceso (DMs)

  • Predeterminado: channels.matrix.dm.policy = "pairing". Los remitentes desconocidos reciben un código de emparejamiento.
  • Aprobar vía:
    • 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 para mostrar a IDs de usuario cuando la búsqueda de directorio encuentra una coincidencia exacta única.
  • No uses nombres para mostrar o localparts sin formato (ejemplo: "Alice" o "alice"). Son ambiguos y se ignoran para la coincidencia de lista de acceso. Usa IDs completos @user:server.

Salas (grupos)

  • Predeterminado: channels.matrix.groupPolicy = "allowlist" (restricción por mención). Usa channels.defaults.groupPolicy para anular el predeterminado cuando no está configurado.
  • Nota de ejecución: si channels.matrix falta completamente, el runtime recurre a groupPolicy="allowlist" para verificaciones de salas (incluso si channels.defaults.groupPolicy está configurado).
  • Configura la lista de acceso de salas con channels.matrix.groups (IDs de sala o alias; los nombres se resuelven a IDs cuando la búsqueda de 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 auto-respuesta en esa sala.
  • groups."*" puede establecer valores predeterminados para la restricción por mención en todas las salas.
  • groupAllowFrom restringe qué remitentes pueden activar el bot en salas (IDs completos de usuario de Matrix).
  • Las listas de acceso users por sala pueden restringir aún más los remitentes dentro de una sala específica (usa IDs completos de usuario de Matrix).
  • El asistente de configuración solicita listas de acceso de salas (IDs de sala, alias o nombres) y resuelve nombres solo con coincidencia exacta y única.
  • Al inicio, OpenClaw resuelve nombres de sala/usuario en las listas de acceso a IDs y registra el mapeo; las entradas no resueltas se ignoran para la coincidencia de lista de acceso.
  • Las invitaciones se aceptan automáticamente por defecto; controla con channels.matrix.autoJoin y channels.matrix.autoJoinAllowlist.
  • Para no permitir ninguna sala, configura channels.matrix.groupPolicy: "disabled" (o mantén una lista de acceso vacía).
  • Clave legacy: channels.matrix.rooms (misma estructura que groups).

Hilos

  • Las respuestas en hilo son compatibles.
  • channels.matrix.threadReplies controla si las respuestas permanecen en hilos:
    • off, inbound (predeterminado), always
  • channels.matrix.replyToMode controla los metadatos de reply-to cuando no se responde en un hilo:
    • off (predeterminado), first, all

Capacidades

CaracterísticaEstado
Mensajes directosSoportado
SalasSoportado
HilosSoportado
MultimediaSoportado
E2EESoportado (módulo de criptografía requerido)
ReaccionesSoportado (envío/lectura vía herramientas)
EncuestasEnvío soportado; los poll-start entrantes se convierten a texto (respuestas/finales ignorados)
UbicaciónSoportado (geo URI; altitud ignorada)
Comandos nativosSoportado

Resolución de problemas

Ejecuta esta secuencia primero:

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

Luego confirma el estado de emparejamiento de DM si es necesario:

openclaw pairing list matrix

Fallos comunes:

  • Autenticado pero los mensajes de sala se ignoran: sala bloqueada por groupPolicy o lista de acceso de salas.
  • DMs ignorados: remitente pendiente de aprobación cuando channels.matrix.dm.policy="pairing".
  • Las salas cifradas fallan: soporte de criptografía o configuración de cifrado no coinciden.

Para el flujo de diagnóstico: /channels/troubleshooting.

Referencia de configuración (Matrix)

Configuración completa: Configuración

Opciones del proveedor:

  • channels.matrix.enabled: habilitar/deshabilitar 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 login (token almacenado).
  • channels.matrix.deviceName: nombre de dispositivo para mostrar.
  • channels.matrix.encryption: habilitar E2EE (predeterminado: false).
  • channels.matrix.initialSyncLimit: límite de sincronización inicial.
  • channels.matrix.threadReplies: off | inbound | always (predeterminado: inbound).
  • 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 del fragmentado por longitud.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (predeterminado: pairing).
  • channels.matrix.dm.allowFrom: lista de acceso de DM (IDs completos de usuario de Matrix). open requiere "*". El asistente resuelve nombres a IDs cuando es posible.
  • channels.matrix.groupPolicy: allowlist | open | disabled (predeterminado: allowlist).
  • channels.matrix.groupAllowFrom: remitentes permitidos para mensajes de grupo (IDs completos de usuario de Matrix).
  • channels.matrix.allowlistOnly: forzar reglas de lista de acceso para DMs + salas.
  • channels.matrix.groups: lista de acceso de grupo + mapa de configuración por sala.
  • channels.matrix.rooms: lista de acceso/configuración de grupo legacy.
  • channels.matrix.replyToMode: modo reply-to para hilos/etiquetas.
  • channels.matrix.mediaMaxMb: límite de multimedia entrante/saliente (MB).
  • channels.matrix.autoJoin: manejo de invitaciones (always | allowlist | off, predeterminado: always).
  • channels.matrix.autoJoinAllowlist: IDs/alias de sala permitidos para auto-join.
  • channels.matrix.accounts: configuración multi-cuenta por ID de cuenta (cada cuenta hereda la configuración de nivel superior).
  • channels.matrix.actions: control por acción de herramientas (reactions/messages/pins/memberInfo/channelInfo).
arrow_back
Anterior
Line
Siguiente
Mattermost
arrow_forward