Matrix

Matrix es un protocolo de mensajería descentralizado abierto. OpenClaw se conecta a cualquier homeserver como un usuario de Matrix, así que necesitas preparar una cuenta Matrix para el bot. Después de iniciar sesión, puedes enviar DM al bot directamente o invitarlo a salas ("chats grupales"/salas de Matrix). Beeper también puede usarse como cliente, pero típicamente requiere E2EE habilitado.

Estado: Soportado vía plugin (@vector-im/matrix-bot-sdk). Soporta DMs, salas, hilos, media, reacciones, encuestas (envío + inicio de encuesta entrante a texto), ubicación, y encriptación de extremo a extremo (E2EE) con soporte criptográfico.

Matrix se proporciona como plugin y no viene incluido con la instalación core.

Instalar vía CLI (registro npm):

openclaw plugins install @openclaw/matrix

Instalación local (cuando se ejecuta desde un repositorio git):

openclaw plugins install ./extensions/matrix

Si seleccionas Matrix en configure/onboarding y se detecta un checkout git, OpenClaw proporcionará automáticamente la ruta de instalación local.

Detalles: ''/plugin''

1. Instalar el plugin Matrix:

- npm: openclaw plugins install @openclaw/matrix

- checkout local: openclaw plugins install ./extensions/matrix

2. Crear una cuenta Matrix en un homeserver:

- Para opciones alojadas, ver: <https://matrix.org/ecosystem/hosting/>

- O auto-alojar

3. Obtener el token de acceso de la cuenta del bot:

- Usar la API de login Matrix del homeserver (curl):

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

La encriptación de extremo a extremo está soportada (usando Rust crypto SDK).

Después de establecer channels.matrix.encryption: true:

- Cuando el módulo crypto carga exitosamente, las salas encriptadas se desencriptan automáticamente.

- El media enviado a salas encriptadas se encripta.

- En la primera conexión, OpenClaw iniciará solicitudes de verificación de dispositivo a tus otras sesiones.

- Aprueba la solicitud de verificación en otro cliente Matrix (ej., Element) para habilitar compartir claves.

- Si el módulo crypto no puede cargar, E2EE se deshabilita y las salas encriptadas no serán desencriptadas; OpenClaw registrará una advertencia.

- Si ves errores sobre módulos crypto faltantes (ej., @matrix-org/matrix-sdk-crypto-nodejs-*), necesitas permitir scripts de build para @matrix-org/matrix-sdk-crypto-nodejs y ejecutar:

- pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs, o

- node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js (para obtener binarios)

El estado crypto se almacena por cuenta + token de acceso en:

~/.openclaw/matrix/accounts/<cuenta>/<homeserver>__<usuario>/<hash-token>/crypto/

(base de datos SQLite). El estado de sync se guarda en bot-storage.json en el mismo directorio.

Si el token de acceso (dispositivo) cambia, se crea un nuevo almacén y el bot necesita ser re-verificado para leer mensajes de salas encriptadas.

Verificación de dispositivo:

Después de habilitar E2EE, el bot solicitará verificación de tus otras sesiones al inicio. Aprueba la solicitud en Element (u otro cliente) para establecer confianza. Solo después de completar la verificación puede el bot desencriptar mensajes de salas encriptadas.

- Las respuestas siempre van de vuelta a Matrix.

- Los DMs comparten la sesión principal del agente; las salas mapean a sesiones grupales (clave de sesión independiente).

- Por defecto: channels.matrix.dm.policy = "pairing". Los remitentes desconocidos reciben un código de emparejamiento.

- Aprobar:

- openclaw pairing list matrix

- openclaw pairing approve matrix <CÓDIGO>

- DMs públicos: channels.matrix.dm.policy="open" y channels.matrix.dm.allowFrom=["*"].

- channels.matrix.dm.allowFrom soporta IDs de usuario o nombres para mostrar. Cuando la búsqueda de directorio está disponible, el asistente resolverá nombres para mostrar a IDs de usuario.

- Por defecto: channels.matrix.groupPolicy = "allowlist" (y la restricción de mención está habilitada por defecto). Si no se establece, channels.defaults.groupPolicy puede usarse para sobrescribir el valor por defecto.

- Usar channels.matrix.groups para listas permitidas de salas (se pueden usar IDs de sala, aliases, o nombres):

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

- requireMention: false hace que la sala responda automáticamente.

- groups."*" puede establecer el comportamiento de mención por defecto para todas las salas.

- groupAllowFrom (opcional) limita qué remitentes pueden activar el bot en salas.

- Las listas permitidas users por sala pueden limitar aún más los activadores dentro de una sala.

- configure/onboarding preguntará por listas permitidas de salas y resolverá nombres cuando sea posible.

- Al inicio, OpenClaw intentará resolver nombres de sala/usuario en listas permitidas a IDs y registrará los mapeos; las entradas fallidas permanecen como están.

- Las invitaciones se unen automáticamente por defecto; usar channels.matrix.autoJoin y channels.matrix.autoJoinAllowlist para controlar.

- Para deshabilitar completamente las salas, establecer channels.matrix.groupPolicy: "disabled" (o mantener la lista permitida vacía).

- Clave legacy: channels.matrix.rooms (misma estructura que groups).

- El hilado de respuestas está soportado.

- channels.matrix.threadReplies controla si las respuestas permanecen en hilos:

- off, inbound (por defecto), always

- channels.matrix.replyToMode controla metadatos reply-to al responder fuera de hilos:

- off (por defecto), first, all

| Característica | Estado |

| ----- |

| DMs | ✅ Soportado |

| Salas | ✅ Soportado |

| Hilos | ✅ Soportado |

| Media | ✅ Soportado |

| E2EE | ✅ Soportado (requiere módulo crypto) |

| Reacciones | ✅ Soportado (enviar/leer vía herramientas) |

| Encuestas | ✅ Envío soportado; inicio de encuesta entrante convertido a texto (respuestas/finales ignorados) |

| Ubicación | ✅ Soportado (geo URI; altitud ignorada) |

| Comandos nativos | ✅ Soportado |

Configuración completa: ''/gateway/configuration''

Opciones de proveedor:

- channels.matrix.enabled: Si habilitar el canal

- channels.matrix.homeserver: URL del Homeserver

- channels.matrix.userId: ID de usuario Matrix (opcional cuando se usa token de acceso)

- channels.matrix.accessToken: Token de acceso

- channels.matrix.password: Contraseña para login (el token será persistido)

- channels.matrix.deviceName: Nombre para mostrar del dispositivo

- channels.matrix.encryption: Si habilitar E2EE (por defecto false)

- channels.matrix.initialSyncLimit: Límite de sync inicial

- channels.matrix.threadReplies: off | inbound | always (por defecto inbound)

- channels.matrix.textChunkLimit: Tamaño de chunk de texto saliente (caracteres)

- channels.matrix.chunkMode: length (por defecto) o newline (dividir por líneas en blanco primero, luego por longitud)

- channels.matrix.dm.policy: pairing | allowlist | open | disabled (por defecto pairing)

- channels.matrix.dm.allowFrom: Lista permitida DM (IDs de usuario o nombres para mostrar); open requiere "*"; auto-convertido a IDs cuando es resoluble

- channels.matrix.groupPolicy: allowlist | open | disabled (por defecto allowlist)

- channels.matrix.groupAllowFrom: Lista permitida de remitentes de mensajes grupales

- channels.matrix.allowlistOnly: Forzar reglas de lista permitida para DMs y salas

- channels.matrix.groups: Lista permitida de salas + configuración por sala

- channels.matrix.rooms: Lista permitida/config de salas legacy

- channels.matrix.replyToMode: Modo reply-to para hilos/etiquetas

- channels.matrix.mediaMaxMb: Límite de media entrante/saliente (MB)

- channels.matrix.autoJoin: Estrategia de auto-unión a invitaciones (always | allowlist | off, por defecto always)

- channels.matrix.autoJoinAllowlist: IDs/aliases de salas permitidos para auto-unirse

- channels.matrix.actions: Interruptores de herramienta por acción (reactions/messages/pins/memberInfo/channelInfo)