OpenClaw

Canal Matrix de OpenClaw

Descentralizado
Medio

Conecta OpenClaw a Matrix — un protocolo de comunicación abierto y federado. Esta integración permite que tu asistente de IA participe en salas Matrix y mensajes directos a través de cualquier servidor doméstico (matrix.org, Element o auto-alojado). OpenClaw se conecta mediante la API Matrix Client-Server con soporte opcional de cifrado de extremo a extremo (E2EE) a través del SDK de criptografía Rust. El canal Matrix se distribuye como plugin y soporta federación, hilos, reacciones y medios enriquecidos.

Info rápida
DificultadMedio
CategoríaDescentralizado
Funciones compatibles5 / 6

Matrix Funciones compatibles

Mensajes de texto

Compatible

Medios y archivos

Compatible

Reacciones

Compatible

Hilos

Compatible

Mensajes de voz

No compatible

Chat grupal

Compatible

Matrix Requisitos previos

  • Una cuenta Matrix activa en cualquier servidor doméstico (matrix.org, Element o auto-alojado)
  • El plugin Matrix instalado: openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway en ejecución y configurado
  • Node.js 18+ instalado en tu servidor

Matrix Configuración rápida

1

Instalar el plugin Matrix

El canal Matrix se distribuye como plugin separado. Instálalo mediante 'openclaw plugins install @openclaw/matrix'. El plugin se descargará del registro npm y se habilitará automáticamente.

2

Obtener credenciales de Matrix

Necesitas un token de acceso o usuario/contraseña. Para tokens de acceso: usa curl para llamar al endpoint de login de tu servidor doméstico y copia el token. Para usuario/contraseña: el Gateway iniciará sesión automáticamente y almacenará el token en ~/.openclaw/credentials/matrix/credentials.json.

3

Agregar configuración del canal Matrix

Agrega la configuración del canal Matrix a ~/.openclaw/openclaw.json con la URL de tu servidor doméstico y credenciales. También puedes usar variables de entorno MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID y MATRIX_PASSWORD.

4

Iniciar Gateway y probar

Ejecuta 'openclaw gateway' para iniciar el servicio. Envía un mensaje directo al usuario bot Matrix desde otra cuenta. Si usas la política de emparejamiento predeterminada, aprueba al remitente mediante 'openclaw pairing approve matrix <code>' en tu terminal.

Matrix Ejemplo de configuración

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix Documentación Detallada

Descripción general de la arquitectura

OpenClaw se conecta a Matrix a través de la API Client-Server, actuando como un cliente Matrix estándar. La arquitectura está basada en eventos: tu bot recibe eventos (mensajes, reacciones, cambios de membresía) mediante solicitudes de sincronización de polling largo, los procesa con tu IA y envía respuestas a través de la API. Matrix es federado, lo que significa que tu bot puede comunicarse con usuarios en cualquier servidor doméstico de la red global Matrix — no solo en el servidor doméstico donde está registrada la cuenta de tu bot. Esto es fundamentalmente diferente de plataformas centralizadas como WhatsApp o Telegram. El flujo es: Usuario envía mensaje en Matrix → Servidor doméstico enruta a tu Gateway mediante sync → OpenClaw procesa con IA → respuesta enviada mediante API de envío de eventos → mensaje entregado a través de federación.
Federación significa que tu bot en matrix.org puede chatear con usuarios en cualquier servidor doméstico Matrix (por ejemplo, element.io, el servidor de Mozilla o instancias auto-alojadas).
El plugin Matrix usa polling largo por defecto. No se necesitan webhooks ni URLs públicas — el Gateway se conecta de forma saliente a tu servidor doméstico.

Métodos de autenticación

OpenClaw soporta dos enfoques de autenticación para Matrix: 1. **Token de acceso (recomendado)** — Obtén un token llamando a la API de login de tu servidor doméstico usando curl o un cliente Matrix. Configura channels.matrix.accessToken en tu configuración. El sistema obtiene automáticamente tu ID de usuario mediante el endpoint /whoami. 2. **Usuario/Contraseña** — Configura channels.matrix.userId y channels.matrix.password. OpenClaw llama automáticamente al endpoint de login y almacena el token de acceso en ~/.openclaw/credentials/matrix/credentials.json. Las variables de entorno tienen precedencia sobre los archivos de configuración: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json
# Método con token de acceso
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# Método con usuario/contraseña
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
Nunca incluyas tokens de acceso o contraseñas en control de versiones. Usa variables de entorno para despliegues de producción. Si tu token está comprometido, cierra sesión en todos los dispositivos mediante tu cliente Matrix para invalidar todos los tokens, luego genera uno nuevo.

Políticas de mensajes directos

Las políticas de mensajes directos controlan quién puede interactuar con tu asistente de IA. OpenClaw soporta cuatro políticas: • pairing (predeterminada) — Usuarios desconocidos reciben un código de emparejamiento en el primer contacto. Aprueba mediante 'openclaw pairing approve matrix <CODE>' para otorgar acceso. Una vez aprobado, el usuario puede chatear libremente. • allowlist — Solo los IDs de usuario Matrix listados explícitamente en channels.matrix.dm.allowFrom pueden enviar mensajes al bot. Todos los demás son ignorados silenciosamente. • open — Cualquiera que envíe mensaje al bot recibe una respuesta. Requiere allowFrom: ["*"]. Usar con precaución. • disabled — El manejo de mensajes directos está completamente desactivado. Las allowlists aceptan IDs de usuario Matrix completos en el formato @user:server (por ejemplo, @alice:matrix.org).
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

Soporte para chat grupal (salas)

Las conversaciones grupales de Matrix se llaman "salas". Por defecto, OpenClaw usa una política de allowlist para salas, requiriendo activación basada en menciones. Puedes configurar en qué salas participa el bot y cómo responde. Las salas se identifican por IDs de sala (!roomId:server) o alias de sala (#alias:server). Puedes configurar ajustes específicos por sala como comportamiento de unión automática, requisitos de mención y allowlists de usuarios por sala.
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
Configura autoJoin a 'always' para aceptar automáticamente todas las invitaciones de sala, 'allowlist' para unirse solo a salas configuradas, u 'off' para ignorar invitaciones.
Usa requireMention: false para habilitar respuestas automáticas sin mencionar al bot. Ten precaución en salas de alto tráfico.

Cifrado de extremo a extremo (E2EE)

Matrix soporta cifrado de extremo a extremo (E2EE) mediante los protocolos Olm y Megolm. OpenClaw puede participar en salas cifradas cuando habilitas el cifrado mediante el SDK de criptografía Rust. Cuando está habilitado, el sistema descifra automáticamente mensajes cifrados, cifra medios salientes en salas aseguradas y almacena el estado criptográfico en ~/.openclaw/matrix/accounts/ (SQLite). Se requiere verificación de dispositivo en la primera conexión — aprueba la solicitud de verificación en Element u otro cliente Matrix para habilitar el intercambio de claves. Si los módulos criptográficos no se cargan, E2EE se desactiva y las salas cifradas permanecen inaccesibles.
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
Cambiar tokens de acceso requiere re-verificación de dispositivo. Mantén copias de seguridad de tu directorio de estado criptográfico (~/.openclaw/matrix/accounts/) para prevenir la pérdida de acceso al historial de mensajes cifrados.

Federación y selección de servidor doméstico

Matrix es un protocolo federado — no hay un único servidor central. Puedes elegir registrar tu bot en cualquier servidor doméstico: • **matrix.org** — El servidor doméstico insignia gestionado por la Fundación Matrix. Registro abierto, alta confiabilidad, pero puede ser más lento debido al alto tráfico. • **Element Matrix Services** — Servidores domésticos alojados profesionalmente en element.io con características premium y soporte. • **Auto-alojado** — Ejecuta tu propio servidor doméstico para máximo control y privacidad. Synapse es la opción más madura y activamente desarrollada. Dendrite (Go) y Conduit (Rust) son alternativas más ligeras adecuadas para despliegues pequeños, aunque ambos se encuentran ahora en modo de mantenimiento o desarrollo limitado. Tu bot puede comunicarse con usuarios en cualquier servidor doméstico independientemente de dónde esté registrado, gracias a la federación.
Para despliegues de producción, considera usar un servidor doméstico auto-alojado o Element Matrix Services para mejor control y rendimiento.
La federación funciona transparentemente — los usuarios no necesitan saber en qué servidor doméstico está tu bot.

Hilos y modos de respuesta

Matrix soporta conversaciones en hilos mediante el tipo de relación m.thread. OpenClaw puede participar en hilos y controlar cómo maneja las respuestas. La configuración threadReplies controla el comportamiento de hilos: 'off' desactiva el soporte de hilos, 'inbound' solo lee el contexto de hilos, y 'always' lee y crea respuestas en hilos. La configuración replyToMode controla el adjunto de metadatos para relaciones de respuesta.
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

Manejo de medios y carga de archivos

Matrix soporta medios enriquecidos incluyendo imágenes, videos, audio y documentos. OpenClaw maneja automáticamente las cargas de medios — los archivos se cargan al repositorio de medios de tu servidor doméstico y se referencian en eventos de mensaje. Puedes configurar tamaños máximos de archivo mediante la configuración mediaMaxMb. El valor predeterminado es 50 MB para medios entrantes, con optimización JPEG automática y redimensionamiento para imágenes sobredimensionadas en envíos salientes.
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
Las cargas de medios se almacenan en tu servidor doméstico. Si usas un servidor doméstico público como matrix.org, ten en cuenta los límites de almacenamiento y términos de servicio.

Reacciones y características enriquecidas

OpenClaw soporta reacciones Matrix (respuestas emoji a mensajes), encuestas, compartir ubicación (formato geo URI) y otras características enriquecidas. Las reacciones se pueden enviar y leer mediante herramientas si están habilitadas. Puedes restringir operaciones específicas mediante la configuración actions, limitando lo que tu agente de IA puede hacer (reacciones, mensajes, pines, información de miembros/canal).
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

¿Por qué Matrix para IA auto-alojada?

Matrix es una excelente elección para asistentes de IA auto-alojados porque: • **Verdaderamente abierto** — Especificación abierta, sin dependencia de proveedor, múltiples implementaciones de cliente y servidor. • **Federado** — Sin punto único de control o falla. Tu bot puede comunicarse a través de la red global Matrix. • **Enfocado en privacidad** — Soporte E2EE, opciones auto-alojadas y sin recopilación centralizada de datos. • **Características enriquecidas** — Hilos, reacciones, medios, encuestas y tipos de eventos extensibles. • **No requiere número telefónico** — A diferencia de WhatsApp o Signal, Matrix no requiere un número telefónico para el registro. El compromiso es la complejidad: el modelo de federación de Matrix y la configuración E2EE pueden ser más complejos que las plataformas centralizadas. Para usuarios y equipos conscientes de la privacidad, este compromiso vale la pena.

Matrix Referencia de Configuración

enabled
Type: booleanDefault: true

Habilitar o deshabilitar el canal Matrix

homeserver
Type: stringDefault: "https://matrix.org"

URL del servidor doméstico Matrix (por ejemplo, https://matrix.org, https://element.io)

accessToken
Type: stringDefault: ""

Token de acceso Matrix para autenticación (método recomendado)

userId
Type: stringDefault: ""

ID de usuario Matrix (por ejemplo, @bot:matrix.org) — usado con autenticación por contraseña

password
Type: stringDefault: ""

Contraseña de cuenta Matrix — usado con userId para login

encryption
Type: booleanDefault: false

Habilitar cifrado de extremo a extremo mediante SDK de criptografía Rust

dmPolicy
Type: stringDefault: "pairing"

Política de acceso a mensajes directos: pairing, allowlist, open o disabled

dm.allowFrom
Type: arrayDefault: []

IDs de usuario Matrix permitidos para mensajes directos (por ejemplo, [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

Política de salas: allowlist o disabled

groups
Type: objectDefault: {}

Configuración específica por sala (ID o alias de sala como clave)

groups.<roomId>.allow
Type: booleanDefault: false

Permitir al bot participar en esta sala

groups.<roomId>.requireMention
Type: booleanDefault: true

Requerir mención del bot para activar respuestas en esta sala

groups.<roomId>.users
Type: arrayDefault: []

Allowlist de usuarios específica por sala (IDs de usuario Matrix)

autoJoin
Type: stringDefault: "allowlist"

Unirse automáticamente a invitaciones de sala: always, allowlist u off

textChunkLimit
Type: numberDefault: 4096

Máximo de caracteres por mensaje saliente

chunkMode
Type: stringDefault: "length"

Cómo dividir respuestas largas: length (límite duro) o newline (límites de párrafo)

threadReplies
Type: stringDefault: "inbound"

Comportamiento de hilos: off, inbound (solo lectura) o always (leer + crear)

replyToMode
Type: stringDefault: "reference"

Modo de adjunto de metadatos de respuesta

mediaMaxMb
Type: numberDefault: 50

Tamaño máximo de archivo de medios en megabytes

actions.reactions
Type: booleanDefault: true

Permitir al agente enviar/leer reacciones

actions.messages
Type: booleanDefault: true

Permitir al agente leer/enviar/editar/eliminar mensajes

actions.pins
Type: booleanDefault: true

Permitir al agente fijar/desfijar mensajes

actions.memberInfo
Type: booleanDefault: true

Permitir al agente consultar información de miembros de sala

actions.channelInfo
Type: booleanDefault: true

Permitir al agente obtener información de sala/canal

Matrix Preguntas Frecuentes

Matrix Solución de Problemas

El bot no recibe mensajes

Política de mensajes directos bloqueando mensajes, o bot no está en la sala

Verifica las configuraciones channels.matrix.dmPolicy y dm.allowFrom. Para salas, asegúrate de que la sala esté en tu allowlist de groups y que el bot haya sido invitado y se haya unido.
Las salas cifradas E2EE no muestran mensajes

Dispositivo no verificado o módulos criptográficos no se cargaron

Verifica el dispositivo de tu bot en Element u otro cliente Matrix. Revisa los logs para errores de carga de módulos criptográficos. Asegúrate de que channels.matrix.encryption esté configurado a true.
Token de acceso inválido o expirado

El token fue revocado o invalidado en el servidor doméstico

Genera un nuevo token de acceso iniciando sesión nuevamente. Si usas usuario/contraseña, elimina ~/.openclaw/credentials/matrix/credentials.json y reinicia el Gateway.
El bot se une a la sala pero no responde

Sala no está en allowlist o requireMention está habilitado

Agrega la sala a channels.matrix.groups con allow: true. Si requireMention es true, los usuarios deben mencionar al bot para obtener una respuesta.
Errores de federación con otros servidores domésticos

Problemas de conectividad o federación del servidor doméstico

Verifica el estado de federación de tu servidor doméstico en federationtester.matrix.org. Verifica registros DNS SRV y certificados SSL si es auto-alojado.
La instalación del plugin falla

Acceso al registro npm o incompatibilidad de versión de Node.js

Asegúrate de que Node.js 18+ esté instalado. Intenta 'openclaw plugins install @openclaw/matrix --verbose' para logs de error detallados. Verifica la conectividad de red al registro npm.
Ver documentación completaVolver a todos los canales

Canales relacionados

Nostr

Advanced

OpenClaw integración descentralizada NIP-04 DM

Guía de configuración

Tlon

Advanced

OpenClaw integración con mensajero Urbit

Guía de configuración