Conecta OpenClaw a Matrix: Guía de configuración rápida

Matrix (plugin)

Matrix es el plugin de canal de Matrix para OpenClaw. Utiliza el matrix-js-sdk oficial y soporta DMs, salas, hilos, archivos multimedia, reacciones, encuestas, ubicación y E2EE.

Plugin requerido

Matrix es un plugin y no viene incluido en el core de OpenClaw.

Instálalo desde npm:

openclaw plugins install @openclaw/matrix

Instálalo desde un checkout local:

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

Consulta Plugins para conocer el comportamiento de los plugins y las reglas de instalación.

Configuración

Instala el plugin.
Crea una cuenta de Matrix en tu homeserver.
Configura channels.matrix con:
- homeserver + accessToken, o
- homeserver + userId + password.
Reinicia el Gateway.
Inicia un DM con el bot o invítalo a una sala.

Rutas de configuración interactiva:

openclaw channels add
openclaw configure --section channels

Lo que el asistente de Matrix te pedirá exactamente:

URL del homeserver
método de autenticación: access token o password
user ID solo cuando elijas autenticación por password
nombre de dispositivo opcional
si quieres activar E2EE
si quieres configurar el acceso a salas de Matrix ahora

Comportamiento del asistente que importa:

Si las variables de entorno de autenticación de Matrix ya existen para la cuenta seleccionada, y esa cuenta aún no tiene la autenticación guardada en la configuración, el asistente ofrece un acceso directo por variables de entorno y solo escribe enabled: true para esa cuenta.
Cuando añades otra cuenta de Matrix de forma interactiva, el nombre de cuenta introducido se normaliza en el ID de cuenta utilizado en la configuración y en las variables de entorno. Por ejemplo, Ops Bot se convierte en ops-bot.
Los avisos de la lista de permitidos (allowlist) de DM aceptan valores completos @user:server de inmediato. Los nombres de pantalla solo funcionan cuando la búsqueda en el directorio en vivo encuentra una coincidencia exacta; de lo contrario, el asistente te pedirá que lo intentes de nuevo con un ID de Matrix completo.
Los avisos de la lista de permitidos de salas aceptan IDs de sala y alias directamente. También pueden resolver nombres de salas unidas en vivo, pero los nombres no resueltos solo se mantienen tal como se escribieron durante la configuración y se ignoran más tarde en la resolución de la lista de permitidos en tiempo de ejecución. Prefiere !room:server o #alias:server.
La identidad de la sala/sesión en tiempo de ejecución utiliza el ID de sala estable de Matrix. Los alias declarados en la sala solo se usan como entradas de búsqueda, no como clave de sesión a largo plazo o identidad de grupo estable.
Para resolver nombres de salas antes de guardarlos, usa openclaw channels resolve --channel matrix "Project Room".

Configuración mínima basada en token:

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

Configuración basada en password (el token se guarda en caché tras el login):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

Matrix guarda las credenciales en caché en ~/.openclaw/credentials/matrix/. La cuenta por defecto usa credentials.json; las cuentas con nombre usan credentials-<account>.json.

Equivalentes en variables de entorno (usadas cuando la clave de configuración no está establecida):

MATRIX_HOMESERVER
MATRIX_ACCESS_TOKEN
MATRIX_USER_ID
MATRIX_PASSWORD
MATRIX_DEVICE_ID
MATRIX_DEVICE_NAME

Para cuentas que no sean la predeterminada, usa variables de entorno con el scope de la cuenta:

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

Ejemplo para la cuenta ops:

MATRIX_OPS_HOMESERVER
MATRIX_OPS_ACCESS_TOKEN

Para el ID de cuenta normalizado ops-bot, usa:

MATRIX_OPS_BOT_HOMESERVER
MATRIX_OPS_BOT_ACCESS_TOKEN

El asistente interactivo solo ofrece el acceso directo por variables de entorno cuando dichas variables ya están presentes y la cuenta seleccionada no tiene aún la autenticación de Matrix guardada en la configuración.

Ejemplo de configuración

Esta es una configuración base práctica con emparejamiento de DM, lista de permitidos para salas y E2EE activado:

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        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",
    },
  },
}

Previsualizaciones en streaming

El streaming de respuestas en Matrix es opcional.

Establece channels.matrix.streaming en "partial" cuando quieras que OpenClaw envíe una única respuesta en borrador, edite ese borrador mientras el modelo genera el texto y luego lo finalice cuando la respuesta esté lista:

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

streaming: "off" es el valor por defecto. OpenClaw espera a la respuesta final y la envía una sola vez.
streaming: "partial" crea un único mensaje de previsualización editable en lugar de enviar múltiples mensajes parciales.
Si la previsualización ya no cabe en un solo evento de Matrix, OpenClaw detiene el streaming de previsualización y vuelve a la entrega final normal.
Las respuestas con archivos multimedia siguen enviando los adjuntos de forma normal. Si una previsualización antigua ya no se puede reutilizar de forma segura, OpenClaw la elimina (redact) antes de enviar la respuesta multimedia final.
Las ediciones de previsualización consumen llamadas extra a la API de Matrix. Deja el streaming desactivado si prefieres un comportamiento más conservador con los límites de velocidad (rate-limit).

AI Setup Assistant

Siguientes pasos

Cifrado y verificación

En las salas con cifrado de extremo a extremo (E2EE), los eventos de imagen de salida utilizan thumbnail_file para que las vistas previas se cifren junto con el archivo adjunto completo. Las salas sin cifrar siguen utilizando thumbnail_url. No necesitas realizar ninguna configuración; el plugin detecta el estado E2EE automáticamente.

Salas de bot a bot

Por defecto, se ignoran los mensajes de Matrix que provienen de otras cuentas de Matrix configuradas en OpenClaw.

Usa allowBots cuando quieras permitir intencionadamente el tráfico de Matrix entre agentes:

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

allowBots: true acepta mensajes de otras cuentas de bot de Matrix configuradas en salas permitidas y DMs.
allowBots: "mentions" acepta esos mensajes solo cuando mencionan visiblemente a este bot en las salas. Los DMs siguen estando permitidos.
groups.<room>.allowBots anula la configuración a nivel de cuenta para una sala específica.
OpenClaw sigue ignorando los mensajes del mismo User ID de Matrix para evitar bucles de autorrespuesta.
Matrix no expone un flag de bot nativo aquí; OpenClaw trata lo “escrito por un bot” como “enviado por otra cuenta de Matrix configurada en este Gateway de OpenClaw”.

Usa listas de permitidos de salas estrictas y requisitos de mención cuando habilites el tráfico de bot a bot en salas compartidas.

Activa el cifrado:

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

Consulta el estado de verificación:

openclaw matrix verify status

Estado detallado (diagnóstico completo):

openclaw matrix verify status --verbose

Incluye la clave de recuperación almacenada en la salida legible por máquina:

openclaw matrix verify status --include-recovery-key --json

Prepara (bootstrap) el estado de cross-signing y verificación:

openclaw matrix verify bootstrap

Soporte multicuenta: usa channels.matrix.accounts con credenciales por cuenta y un name opcional. Consulta la Configuration reference para ver el patrón compartido.

Diagnóstico detallado del bootstrap:

openclaw matrix verify bootstrap --verbose

Fuerza un reinicio de la identidad de cross-signing antes del bootstrap:

openclaw matrix verify bootstrap --force-reset-cross-signing

Verifica este dispositivo con una clave de recuperación:

openclaw matrix verify device "<your-recovery-key>"

Detalles detallados de la verificación del dispositivo:

openclaw matrix verify device "<your-recovery-key>" --verbose

Comprueba el estado de la copia de seguridad de las claves de sala (room-key backup):

openclaw matrix verify backup status

Diagnóstico detallado del estado de la copia de seguridad:

openclaw matrix verify backup status --verbose

Restaura las claves de sala desde la copia de seguridad del servidor:

openclaw matrix verify backup restore

Diagnóstico detallado de la restauración:

openclaw matrix verify backup restore --verbose

Elimina la copia de seguridad actual del servidor y crea una nueva base de referencia:

openclaw matrix verify backup reset --yes

Todos los comandos de verify son concisos por defecto (incluyendo los logs internos del SDK) y muestran diagnósticos detallados solo con --verbose. Usa --json para obtener una salida completa legible por máquina cuando utilices scripts.

En configuraciones multicuenta, los comandos de la CLI de Matrix usan la cuenta predeterminada implícita a menos que pases --account <id>. Si configuras varias cuentas con nombre, establece primero channels.matrix.defaultAccount o esas operaciones implícitas de la CLI se detendrán y te pedirán que elijas una cuenta explícitamente. Usa --account siempre que quieras que las operaciones de verificación o de dispositivo se dirijan a una cuenta con nombre específica:

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

Cuando el cifrado está desactivado o no está disponible para una cuenta con nombre, las advertencias de Matrix y los errores de verificación apuntarán a la clave de configuración de esa cuenta, por ejemplo, channels.matrix.accounts.assistant.encryption.

Qué significa “verificado”

OpenClaw considera que este dispositivo de Matrix está verificado solo cuando ha sido verificado por tu propia identidad de cross-signing. En la práctica, openclaw matrix verify status --verbose expone estas señales de confianza:

Locally trusted: este dispositivo es de confianza solo para el cliente actual.
Cross-signing verified: el SDK informa que el dispositivo está verificado mediante cross-signing.
Signed by owner: el dispositivo está firmado por tu propia clave de autofirma (self-signing key).
Verified by owner: se marca como yes solo cuando existe verificación por cross-signing o firma del propietario.

La confianza local por sí sola no es suficiente para que OpenClaw trate al dispositivo como totalmente verificado.

Qué hace el bootstrap

openclaw matrix verify bootstrap es el comando de reparación y configuración para cuentas de Matrix cifradas. Realiza todas las siguientes acciones en orden:

Prepara el almacenamiento de secretos, reutilizando una clave de recuperación existente cuando es posible.
Prepara el cross-signing y sube las claves públicas de cross-signing que falten.
Intenta marcar y firmar (cross-sign) el dispositivo actual.
Crea una nueva copia de seguridad de claves de sala en el servidor si no existe una.

Si el homeserver requiere autenticación interactiva para subir las claves de cross-signing, OpenClaw intenta la subida primero sin autenticación, luego con m.login.dummy y después con m.login.password cuando channels.matrix.password está configurado.

Usa --force-reset-cross-signing solo cuando quieras descartar intencionadamente la identidad de cross-signing actual y crear una nueva.

Si quieres descartar la copia de seguridad de claves de sala actual y comenzar una nueva base para mensajes futuros, usa openclaw matrix verify backup reset --yes. Haz esto solo si aceptas que el historial cifrado antiguo que no sea recuperable dejará de estar disponible.

Nueva base de copia de seguridad

Si quieres que los futuros mensajes cifrados funcionen y aceptas perder el historial antiguo no recuperable, ejecuta estos comandos en orden:

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

Añade --account <id> a cada comando cuando quieras dirigirte a una cuenta de Matrix con nombre específica.

Comportamiento al inicio

Cuando encryption: true, Matrix establece por defecto startupVerification en "if-unverified". Al iniciar, si este dispositivo aún no está verificado, Matrix solicitará la autoverificación en otro cliente de Matrix, omitirá solicitudes duplicadas si ya hay una pendiente y aplicará un tiempo de espera local antes de reintentar tras los reinicios. Los intentos de solicitud fallidos se reintentan antes que la creación de una solicitud exitosa por defecto. Configura startupVerification: "off" para desactivar las solicitudes automáticas al inicio, o ajusta startupVerificationCooldownHours si quieres una ventana de reintento más corta o más larga.

El inicio también realiza automáticamente una fase conservadora de bootstrap criptográfico. Esa fase intenta reutilizar primero el almacenamiento de secretos y la identidad de cross-signing actuales, y evita reiniciar el cross-signing a menos que ejecutes un flujo explícito de reparación con bootstrap.

Si el inicio encuentra un estado de bootstrap dañado y channels.matrix.password está configurado, OpenClaw puede intentar una ruta de reparación más estricta. Si el dispositivo actual ya está firmado por el propietario, OpenClaw conserva esa identidad en lugar de reiniciarla automáticamente.

Actualización desde el plugin público de Matrix anterior:

OpenClaw reutiliza automáticamente la misma cuenta de Matrix, el token de acceso y la identidad del dispositivo cuando es posible.
Antes de que se ejecute cualquier cambio de migración de Matrix, OpenClaw crea o reutiliza una instantánea de recuperación en ~/Backups/openclaw-migrations/.
Si usas varias cuentas de Matrix, configura channels.matrix.defaultAccount antes de actualizar desde el diseño antiguo de almacenamiento plano para que OpenClaw sepa qué cuenta debe recibir ese estado heredado compartido.
Si el plugin anterior almacenaba localmente una clave de descifrado de copia de seguridad de claves de sala de Matrix, el inicio o openclaw doctor --fix la importarán automáticamente al nuevo flujo de clave de recuperación.
Si el token de acceso de Matrix cambió después de preparar la migración, el inicio ahora escanea las raíces de almacenamiento de hashes de tokens hermanos en busca de estados de restauración heredados pendientes antes de desistir en la restauración automática de la copia de seguridad.
Si el token de acceso de Matrix cambia más tarde para la misma cuenta, homeserver y usuario, OpenClaw prefiere reutilizar la raíz de almacenamiento de hash de token existente más completa en lugar de empezar desde un directorio de estado de Matrix vacío.
En el siguiente inicio del Gateway, las claves de sala respaldadas se restauran automáticamente en el nuevo almacén criptográfico.
Si el plugin antiguo tenía claves de sala solo locales que nunca se respaldaron, OpenClaw avisará claramente. Esas claves no se pueden exportar automáticamente desde el almacén criptográfico de Rust anterior, por lo que parte del historial cifrado antiguo podría seguir sin estar disponible hasta que se recupere manualmente.
Consulta Matrix migration para ver el flujo completo de actualización, límites, comandos de recuperación y mensajes comunes de migración.

El estado de ejecución cifrado se organiza bajo raíces de hash de tokens por cuenta y por usuario en ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/. Ese directorio contiene el almacén de sincronización (bot-storage.json), el almacén criptográfico (crypto/), el archivo de clave de recuperación (recovery-key.json), la instantánea de IndexedDB (crypto-idb-snapshot.json), las vinculaciones de hilos (thread-bindings.json) y el estado de verificación de inicio (startup-verification.json) cuando se utilizan esas funciones. Cuando el token cambia pero la identidad de la cuenta permanece igual, OpenClaw reutiliza la mejor raíz existente para esa combinación de cuenta/homeserver/usuario para que el estado de sincronización previo, el estado criptográfico, las vinculaciones de hilos y el estado de verificación de inicio sigan siendo visibles.

Modelo de almacén criptográfico de Node

Matrix E2EE en este plugin utiliza la ruta criptográfica oficial de Rust de matrix-js-sdk en Node. Esa ruta requiere persistencia respaldada por IndexedDB cuando quieres que el estado criptográfico sobreviva a los reinicios.

OpenClaw proporciona esto actualmente en Node mediante:

El uso de fake-indexeddb como el shim de la API de IndexedDB que espera el SDK.
La restauración de los contenidos de IndexedDB de la criptografía de Rust desde crypto-idb-snapshot.json antes de initRustCrypto.
La persistencia de los contenidos actualizados de IndexedDB de vuelta a crypto-idb-snapshot.json después de la inicialización y durante el tiempo de ejecución.

Esto es una infraestructura de compatibilidad y almacenamiento, no una implementación criptográfica personalizada. El archivo de instantánea es un estado de ejecución sensible y se almacena con permisos de archivo restrictivos. Bajo el modelo de seguridad de OpenClaw, el host del Gateway y el directorio de estado local de OpenClaw ya están dentro del límite de confianza del operador, por lo que esto es principalmente una cuestión de durabilidad operativa más que un límite de confianza remoto separado.

Mejora planificada:

Añadir soporte de SecretRef para material de claves de Matrix persistente, de modo que las claves de recuperación y los secretos de cifrado del almacén relacionados puedan obtenerse de proveedores de secretos de OpenClaw en lugar de solo archivos locales.

Gestión del perfil

Actualiza el perfil de Matrix para la cuenta seleccionada con:

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

Añade --account <id> cuando quieras dirigirte a una cuenta de Matrix con nombre específica.

Matrix acepta URLs de avatar mxc:// directamente. Cuando pasas una URL de avatar http:// o https://, OpenClaw la sube primero a Matrix y almacena la URL mxc:// resuelta en channels.matrix.avatarUrl (o en la anulación de la cuenta seleccionada).

Avisos de verificación automática

Matrix ahora publica avisos del ciclo de vida de verificación directamente en la sala de verificación de DM estricta como mensajes m.notice. Esto incluye:

Avisos de solicitud de verificación.
Avisos de verificación lista (con guía explícita de “Verificar mediante emoji”).
Avisos de inicio y finalización de verificación.
Detalles de SAS (emoji y decimal) cuando están disponibles.

OpenClaw rastrea y acepta automáticamente las solicitudes de verificación entrantes de otro cliente de Matrix. Para los flujos de autoverificación, OpenClaw también inicia el flujo SAS automáticamente cuando la verificación por emoji está disponible y confirma su propia parte. Para las solicitudes de verificación de otro usuario o dispositivo de Matrix, OpenClaw acepta automáticamente la solicitud y luego espera a que el flujo SAS proceda normalmente. Todavía tienes que comparar el emoji o el SAS decimal en tu cliente de Matrix y confirmar que coinciden allí para completar la verificación.

OpenClaw no acepta automáticamente flujos duplicados iniciados por uno mismo de forma ciega. El inicio omite la creación de una nueva solicitud cuando ya hay una solicitud de autoverificación pendiente.

Los avisos del sistema o protocolo de verificación no se reenvían al pipeline de chat del agente, por lo que no producen un NO_REPLY.

Higiene del dispositivo

Los dispositivos de Matrix antiguos gestionados por OpenClaw pueden acumularse en la cuenta y dificultar la comprensión de la confianza en las salas cifradas. Lístalos con:

openclaw matrix devices list

Elimina los dispositivos gestionados por OpenClaw que estén obsoletos con:

openclaw matrix devices prune-stale

Reparación directa de salas

Si el estado de los mensajes directos se desincroniza, OpenClaw puede acabar con mapeos m.direct obsoletos que apuntan a salas individuales antiguas en lugar de al DM activo. Inspecciona el mapeo actual para un par con:

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

Repáralo con:

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

La reparación mantiene la lógica específica de Matrix dentro del plugin:

Prefiere un DM 1:1 estricto que ya esté mapeado en m.direct.
De lo contrario, recurre a cualquier DM 1:1 estricto al que se haya unido actualmente con ese usuario.
Si no existe un DM saludable, crea una nueva sala directa y reescribe m.direct para que apunte a ella.

El flujo de reparación no elimina las salas antiguas automáticamente. Solo elige el DM saludable y desarrolla el mapeo para que los nuevos envíos de Matrix, avisos de verificación y otros flujos de mensajes directos se dirijan de nuevo a la sala correcta.

Threads (Hilos)

Matrix soporta hilos nativos de Matrix tanto para respuestas automáticas como para envíos de herramientas de mensajes.

threadReplies: "off" mantiene las respuestas en el nivel superior y mantiene los mensajes entrantes con hilos en la sesión principal.
threadReplies: "inbound" responde dentro de un hilo solo cuando el mensaje entrante ya estaba en ese hilo.
threadReplies: "always" mantiene las respuestas de la sala en un hilo originado en el mensaje que las activó y dirige esa conversación a través de la sesión con alcance de hilo correspondiente desde el primer mensaje activador.
dm.threadReplies anula la configuración de nivel superior solo para los DMs. Por ejemplo, puedes mantener los hilos de las salas aislados mientras mantienes los DMs planos.
Los mensajes entrantes con hilos incluyen el mensaje raíz del hilo como contexto adicional para el agente.
Los envíos de herramientas de mensajes ahora heredan automáticamente el hilo de Matrix actual cuando el objetivo es la misma sala, o el mismo usuario de DM, a menos que se proporcione un threadId explícito.
Se admiten vinculaciones de hilos en tiempo de ejecución para Matrix. /focus, /unfocus, /agents, /session idle, /session max-age y /acp spawn vinculado a hilos ahora funcionan en salas y DMs de Matrix.
El comando /focus en una sala o DM de Matrix de nivel superior crea un nuevo hilo de Matrix y lo vincula a la sesión de destino cuando threadBindings.spawnSubagentSessions=true.
Ejecutar /focus o /acp spawn --thread here dentro de un hilo de Matrix existente vincula ese hilo actual en su lugar.

AI Setup Assistant

Siguientes pasos

Vinculaciones de conversación de ACP

Puedes convertir salas de Matrix, DMs e hilos existentes en workspaces de ACP duraderos sin necesidad de cambiar la interfaz del chat.

Flujo rápido para operadores:

Ejecuta /acp spawn codex --bind here dentro del DM de Matrix, sala o hilo existente que quieras seguir usando.
En un DM o sala de nivel superior, el DM/sala actual se mantiene como la interfaz de chat y los mensajes futuros se dirigen a la sesión de ACP creada.
Dentro de un hilo de Matrix existente, --bind here vincula ese hilo actual en su lugar.
/new y /reset reinician la misma sesión de ACP vinculada en el mismo sitio.
/acp close cierra la sesión de ACP y elimina la vinculación.

Notas:

--bind here no crea un hilo de Matrix hijo.
threadBindings.spawnAcpSessions solo es necesario para /acp spawn --thread auto|here, donde OpenClaw necesita crear o vincular un hilo de Matrix hijo.

Configuración de vinculación de hilos

Matrix hereda los valores predeterminados globales de session.threadBindings y también admite anulaciones por canal:

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

Los flags de creación vinculados a hilos de Matrix requieren activación explícita:

Configura threadBindings.spawnSubagentSessions: true para permitir que un /focus de nivel superior cree y vincule nuevos hilos de Matrix.
Configura threadBindings.spawnAcpSessions: true para permitir que /acp spawn --thread auto|here vincule sesiones de ACP a hilos de Matrix.

Reacciones

Matrix admite acciones de reacción de salida, notificaciones de reacción de entrada y reacciones de ack (confirmación) de entrada.

Las herramientas de reacción de salida están controladas por channels["matrix"].actions.reactions.
react añade una reacción a un evento de Matrix específico.
reactions enumera el resumen de reacciones actuales para un evento de Matrix específico.
emoji="" elimina las reacciones propias de la cuenta del bot en ese evento.
remove: true elimina solo la reacción de emoji especificada de la cuenta del bot.

Las reacciones de ack usan el orden de resolución estándar de OpenClaw:

channels["matrix"].accounts.<accountId>.ackReaction
channels["matrix"].ackReaction
messages.ackReaction
emoji de identidad del agente como alternativa (fallback)

El alcance de la reacción de ack se resuelve en este orden:

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

El modo de notificación de reacciones se resuelve en este orden:

channels["matrix"].accounts.<accountId>.reactionNotifications
channels["matrix"].reactionNotifications
por defecto: own

Comportamiento actual:

reactionNotifications: "own" reenvía eventos m.reaction añadidos cuando se dirigen a mensajes de Matrix escritos por el bot.
reactionNotifications: "off" desactiva los eventos de sistema de reacciones.
Las eliminaciones de reacciones aún no se sintetizan en eventos del sistema porque Matrix las muestra como redacciones y no como eliminaciones de m.reaction independientes.

Contexto de historial

channels.matrix.historyLimit controla cuántos mensajes recientes de la sala se incluyen como InboundHistory cuando un mensaje de sala de Matrix activa al agente.
Si no se define, usa messages.groupChat.historyLimit. Configura 0 para desactivarlo.
El historial de sala de Matrix es solo para salas. Los DMs siguen usando el historial de sesión normal.
El historial de sala de Matrix es solo para mensajes pendientes: OpenClaw almacena en el buffer los mensajes de la sala que aún no han activado una respuesta y luego toma una captura de esa ventana cuando llega una mención u otro activador.
El mensaje activador actual no se incluye en InboundHistory; se mantiene en el cuerpo principal de entrada para ese turno.
Los reintentos del mismo evento de Matrix reutilizan la captura de historial original en lugar de avanzar hacia mensajes de sala más nuevos.
El contexto de sala obtenido (incluyendo búsquedas de contexto de hilos y respuestas) se filtra mediante listas de permitidos de remitentes (groupAllowFrom), por lo que los mensajes que no estén en la lista se excluyen del contexto del agente.

Ejemplo de política de DM y salas

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

Consulta Groups para ver el comportamiento de restricción por mención y listas de permitidos.

Ejemplo de emparejamiento (pairing) para DMs de Matrix:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

Si un usuario de Matrix no aprobado sigue enviándote mensajes antes de la aprobación, OpenClaw reutiliza el mismo código de emparejamiento pendiente y puede enviar una respuesta de recordatorio tras un breve tiempo de espera en lugar de generar un código nuevo.

Consulta Pairing para ver el flujo de emparejamiento de DM compartido y el diseño del almacenamiento.

Ejemplo de multicuentas

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

Los valores en el nivel superior de channels.matrix funcionan como valores por defecto para las cuentas con nombre, a menos que una cuenta específica los sobrescriba.

Puedes limitar las entradas de salas heredadas a una cuenta de Matrix concreta usando groups.<room>.account (o la opción antigua rooms.<room>.account). Las entradas que no tengan account se comparten entre todas las cuentas de Matrix. Además, las entradas con account: "default" siguen funcionando si configuras la cuenta por defecto directamente en la raíz de channels.matrix.*.

Tener valores de autenticación compartidos de forma parcial no crea una cuenta por defecto implícita por sí sola. OpenClaw solo genera la cuenta default de nivel superior cuando esa cuenta tiene credenciales nuevas (homeserver junto a accessToken, o homeserver con userId y password). Las cuentas con nombre pueden seguir siendo detectables mediante homeserver y userId si las credenciales en caché permiten la autenticación más tarde.

Configura defaultAccount cuando quieras que OpenClaw prefiera una cuenta de Matrix específica para el enrutamiento implícito y las operaciones de la CLI. Si usas varias cuentas con nombre, establece defaultAccount o pasa el flag --account <id> en los comandos de la CLI que necesiten seleccionar una cuenta automáticamente.

Usa --account <id> en comandos como openclaw matrix verify ... y openclaw matrix devices ... cuando necesites sobrescribir esa selección implícita para una ejecución concreta.

Homeservers privados o en LAN

Por defecto, OpenClaw bloquea los homeservers de Matrix que sean privados o internos para protegerte de ataques SSRF. Tienes que activar el acceso de forma explícita en cada cuenta.

Si tu homeserver corre en localhost, en una IP de LAN, redes Tailscale o usa un hostname interno, activa allowPrivateNetwork en esa cuenta de Matrix:

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}

Ejemplo de configuración por CLI:

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

Esta opción solo permite objetivos privados o internos en los que confíes. Los homeservers públicos que usen texto plano, como http://matrix.example.org:8008, seguirán bloqueados. Te recomiendo usar https:// siempre que sea posible.

AI Setup Assistant

Configurar el proxy para el tráfico de Matrix

Si tu despliegue de Matrix necesita un proxy HTTP(S) de salida explícito, configura channels.matrix.proxy:

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

Las cuentas con nombre pueden sobrescribir el valor predeterminado global con channels.matrix.accounts.<id>.proxy. OpenClaw usa la misma configuración de proxy para el tráfico de Matrix en runtime y para las comprobaciones de estado de la cuenta.

Resolución de destinos

Matrix acepta estos formatos de destino en cualquier lugar donde OpenClaw te pida un destino de sala o usuario:

Usuarios: @user:server, user:@user:server, o matrix:user:@user:server
Salas: !room:server, room:!room:server, o matrix:room:!room:server
Alias: #alias:server, channel:#alias:server, o matrix:channel:#alias:server

La búsqueda en el directorio en vivo utiliza la cuenta de Matrix con la que has iniciado sesión:

Las búsquedas de usuarios consultan el directorio de usuarios de Matrix en ese homeserver.
Las búsquedas de salas aceptan IDs de sala y alias directamente; si no hay coincidencia, buscan nombres de salas donde la cuenta esté presente.
La búsqueda por nombre de sala unida se basa en el principio de “mejor esfuerzo”. Si un nombre de sala no se puede resolver a un ID o alias, la resolución de la allowlist en runtime lo ignora.

Referencia de configuración

enabled: activa o desactiva el canal.
name: etiqueta opcional para la cuenta.
defaultAccount: ID de cuenta preferida cuando hay varias cuentas de Matrix configuradas.
homeserver: URL del homeserver, por ejemplo https://matrix.example.org.
allowPrivateNetwork: permite que esta cuenta de Matrix se conecte a homeservers privados o internos. Actívalo cuando el homeserver apunte a localhost, una IP de LAN/Tailscale o un host interno como matrix-synapse.
proxy: URL opcional de un proxy HTTP(S) para el tráfico de Matrix. Las cuentas con nombre pueden sobrescribir el valor predeterminado global con su propio proxy.
userId: ID de usuario de Matrix completo, por ejemplo @bot:example.org.
accessToken: token de acceso para autenticación basada en tokens. Se admiten valores en texto plano y valores SecretRef para channels.matrix.accessToken y channels.matrix.accounts.<id>.accessToken en proveedores de entorno, archivos o ejecución. Consulta Secrets Management.
password: contraseña para el inicio de sesión basado en contraseña. Se admiten valores en texto plano y SecretRef.
deviceId: ID de dispositivo de Matrix explícito.
deviceName: nombre visible del dispositivo para el inicio de sesión con contraseña.
avatarUrl: URL del avatar guardada para la sincronización del perfil y las actualizaciones de set-profile.
initialSyncLimit: límite de eventos de sincronización al iniciar.
encryption: activa E2EE.
allowlistOnly: fuerza el comportamiento de solo lista de permitidos para DMs y salas.
groupPolicy: open, allowlist o disabled.
groupAllowFrom: lista de permitidos de IDs de usuario para el tráfico de las salas.
groupAllowFrom: las entradas deben ser IDs de usuario de Matrix completos. Los nombres no resueltos se ignoran en tiempo de ejecución.
historyLimit: máximo de mensajes de la sala para incluir como contexto del historial del grupo. Si no se define, usa messages.groupChat.historyLimit. Ponlo en 0 para desactivarlo.
replyToMode: off, first o all.
streaming: off (por defecto) o partial. partial activa las vistas previas de borradores de un solo mensaje con actualizaciones de edición en el lugar.
threadReplies: off, inbound o always.
threadBindings: sobrescrituras por canal para el enrutamiento de sesiones vinculadas a hilos y su ciclo de vida.
startupVerification: modo de solicitud de autoverificación automática al iniciar (if-unverified, off).
startupVerificationCooldownHours: tiempo de espera antes de reintentar las solicitudes de autoverificación automática al iniciar.
textChunkLimit: tamaño de los fragmentos de mensajes salientes.
chunkMode: length o newline.
responsePrefix: prefijo de mensaje opcional para las respuestas salientes.
ackReaction: sobrescritura opcional de la reacción de confirmación (ack) para este canal o cuenta.
ackReactionScope: sobrescritura opcional del alcance de la reacción de confirmación (group-mentions, group-all, direct, all, none, off).
reactionNotifications: modo de notificación de reacciones entrantes (own, off).
mediaMaxMb: límite de tamaño de archivos multimedia en MB para el manejo de medios en Matrix. Se aplica tanto a envíos salientes como al procesamiento de medios entrantes.
autoJoin: política de unión automática a invitaciones (always, allowlist, off). Por defecto: off.
autoJoinAllowlist: salas o alias permitidos cuando autoJoin es allowlist. Los alias se resuelven a IDs de sala durante el manejo de la invitación; OpenClaw no confía en el estado del alias declarado por la sala invitada.
dm: bloque de política de DM (enabled, policy, allowFrom, threadReplies).
dm.allowFrom: las entradas deben ser IDs de usuario de Matrix completos, a menos que ya los hayas resuelto mediante una búsqueda en el directorio en vivo.
dm.threadReplies: sobrescritura de la política de hilos solo para DM (off, inbound, always). Sobrescribe el ajuste global de threadReplies tanto para la ubicación de las respuestas como para el aislamiento de la sesión en los DM.
accounts: sobrescrituras con nombre por cuenta. Los valores globales de channels.matrix actúan como valores por defecto para estas entradas.
groups: mapa de políticas por sala. Es preferible usar IDs de sala o alias; los nombres de sala no resueltos se ignoran en tiempo de ejecución. La identidad de la sesión o grupo usa el ID de sala estable tras la resolución, mientras que las etiquetas legibles siguen viniendo de los nombres de las salas.
rooms: alias antiguo para groups.
actions: restricción de herramientas por acción (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

Relacionado

Vista general de canales — todos los canales compatibles
Vinculación — flujo de autenticación y vinculación de DM
Grupos — comportamiento de chats grupales y restricción de menciones
Enrutamiento de canales — enrutamiento de sesiones para mensajes
Seguridad — modelo de acceso y endurecimiento

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.