​

Matrix

​

Plugin incluido

openclaw plugins install @openclaw/matrix

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

​

Configuración inicial

1. Asegúrate de que el plugin de Matrix esté disponible.
   • Las versiones empaquetadas actuales de OpenClaw ya lo incluyen.
   • Las instalaciones antiguas o personalizadas pueden añadirlo manualmente con los comandos anteriores.
2. Crea una cuenta de Matrix en tu homeserver.
3. Configura channels.matrix con una de estas opciones:
   • homeserver + accessToken, o
   • homeserver + userId + password.
4. Reinicia el Gateway.
5. Inicia un mensaje directo con el bot o invítalo a una sala.
   • Las invitaciones nuevas de Matrix solo funcionan cuando channels.matrix.autoJoin las permite.

openclaw channels add
openclaw configure --section channels

• URL del homeserver
• método de autenticación: token de acceso o contraseña
• ID de usuario (solo autenticación con contraseña)
• nombre de dispositivo opcional
• si se debe habilitar E2EE
• si se debe configurar el acceso a salas y la unión automática por invitación

• Si las variables de entorno de autenticación de Matrix ya existen y esa cuenta todavía no tiene autenticación guardada en la configuración, el asistente ofrece un acceso directo con variables de entorno para mantener la autenticación en variables de entorno.
• Los nombres de cuenta se normalizan al ID de la cuenta. Por ejemplo, Ops Bot pasa a ser ops-bot.
• Las entradas de lista de permitidos para mensajes directos aceptan @user:server directamente; los nombres visibles solo funcionan cuando la búsqueda en vivo del directorio encuentra una coincidencia exacta.
• Las entradas de lista de permitidos para salas aceptan directamente IDs y alias de sala. Se prefiere !room:server o #alias:server; los nombres sin resolver se ignoran en tiempo de ejecución durante la resolución de la lista de permitidos.
• En el modo de lista de permitidos para unión automática por invitación, usa solo destinos de invitación estables: !roomId:server, #alias:server o *. Los nombres de sala simples se rechazan.
• Para resolver nombres de sala antes de guardar, usa openclaw channels resolve --channel matrix "Project Room".

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

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

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

• 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

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

Ejemplo de configuración

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

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

​

Vistas previas de streaming

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

• streaming: "off" es el valor predeterminado. OpenClaw espera la respuesta final y la envía una sola vez.
• streaming: "partial" crea un mensaje de vista previa editable para el bloque actual del asistente usando mensajes de texto normales de Matrix. Esto conserva el comportamiento heredado de Matrix de notificación primero sobre la vista previa, por lo que los clientes estándar pueden notificar sobre el primer texto transmitido de la vista previa en lugar del bloque finalizado.
• streaming: "quiet" crea un aviso silencioso de vista previa editable para el bloque actual del asistente. Usa esto solo cuando también configures reglas push del destinatario para ediciones finalizadas de la vista previa.
• blockStreaming: true habilita mensajes de progreso separados de Matrix. Con el streaming de vista previa habilitado, Matrix mantiene el borrador en vivo del bloque actual y conserva los bloques completados como mensajes separados.
• Cuando el streaming de vista previa está activado y blockStreaming está desactivado, Matrix edita el borrador en vivo en el mismo lugar y finaliza ese mismo evento cuando termina el bloque o el turno.
• Si la vista previa ya no cabe en un solo evento de Matrix, OpenClaw detiene el streaming de vista previa y vuelve a la entrega final normal.
• Las respuestas multimedia siguen enviando los archivos adjuntos con normalidad. Si una vista previa obsoleta ya no puede reutilizarse de forma segura, OpenClaw la elimina antes de enviar la respuesta multimedia final.
• Las ediciones de vista previa generan llamadas adicionales a la API de Matrix. Deja el streaming desactivado si quieres el comportamiento más conservador respecto a límites de velocidad.

• blockStreaming: true envía cada bloque terminado como un mensaje normal de Matrix con notificación.
• blockStreaming: false envía solo la respuesta final completada como un mensaje normal de Matrix con notificación.

​

Reglas push autohospedadas para vistas previas silenciosas finalizadas

• usuario destinatario = la persona que debe recibir la notificación
• usuario bot = la cuenta de Matrix de OpenClaw que envía la respuesta
• usa el token de acceso del usuario destinatario para las llamadas a la API a continuación
• haz coincidir sender en la regla push con el MXID completo del usuario bot

1. Configura OpenClaw para usar vistas previas silenciosas:

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

2. Asegúrate de que la cuenta del destinatario ya reciba notificaciones push normales de Matrix. Las reglas de vista previa silenciosa solo funcionan si ese usuario ya tiene pushers/dispositivos en funcionamiento.
3. Obtén el token de acceso del usuario destinatario.
   • Usa el token del usuario receptor, no el token del bot.
   • Reutilizar un token de sesión existente del cliente suele ser lo más sencillo.
   • Si necesitas generar un token nuevo, puedes iniciar sesión mediante la API estándar Client-Server de Matrix:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. Verifica que la cuenta del destinatario ya tenga pushers:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. Crea una regla push de anulación para cada cuenta destinataria que deba recibir estas notificaciones:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: la URL base de tu homeserver
• $USER_ACCESS_TOKEN: el token de acceso del usuario receptor
• openclaw-finalized-preview-botname: un ID de regla único para este bot para este usuario receptor
• @bot:example.org: el MXID de tu bot de Matrix de OpenClaw, no el MXID del usuario receptor

• Las reglas push se indexan por ruleId. Volver a ejecutar PUT sobre el mismo ID de regla actualiza esa misma regla.
• Si un mismo usuario receptor debe recibir notificaciones de varias cuentas de bot de Matrix de OpenClaw, crea una regla por bot con un ID de regla único para cada coincidencia de remitente.
• Un patrón sencillo es openclaw-finalized-preview-<botname>, por ejemplo openclaw-finalized-preview-ops o openclaw-finalized-preview-support.

• autentícate con el token del usuario receptor
• haz coincidir sender con el MXID del bot de OpenClaw

6. Verifica que la regla exista:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. Prueba una respuesta transmitida. En modo silencioso, la sala debería mostrar un borrador silencioso de vista previa y la edición final en el mismo lugar debería notificar una vez que termine el bloque o el turno.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• Crea la regla con el token de acceso del usuario receptor, no con el del bot.
• Las nuevas reglas override definidas por el usuario se insertan antes de las reglas predeterminadas de supresión, así que no se necesita ningún parámetro adicional de orden.
• Esto solo afecta a las ediciones de vista previa de solo texto que OpenClaw puede finalizar de forma segura en el mismo lugar. Los respaldos para multimedia y para vistas previas obsoletas siguen usando la entrega normal de Matrix.
• Si GET /_matrix/client/v3/pushers no muestra pushers, el usuario todavía no tiene una entrega push de Matrix funcional para esta cuenta o dispositivo.

​

Synapse

• No se requiere ningún cambio especial en homeserver.yaml para las notificaciones de vista previa finalizada de OpenClaw.
• Si tu implementación de Synapse ya envía notificaciones push normales de Matrix, el token de usuario + la llamada a pushrules anterior es el paso principal de configuración.
• Si ejecutas Synapse detrás de un proxy inverso o de workers, asegúrate de que /_matrix/client/.../pushrules/ llegue correctamente a Synapse.
• Si ejecutas workers de Synapse, asegúrate de que los pushers estén en buen estado. La entrega push la gestiona el proceso principal o synapse.app.pusher / los workers de pusher configurados.

​

Tuwunel

• No se requiere ninguna configuración específica de Tuwunel para el marcador de vista previa finalizada en sí.
• Si las notificaciones normales de Matrix ya funcionan para ese usuario, el token de usuario + la llamada a pushrules anterior es el paso principal de configuración.
• Si parece que las notificaciones desaparecen mientras el usuario está activo en otro dispositivo, comprueba si suppress_push_when_active está habilitado. Tuwunel añadió esta opción en Tuwunel 1.4.2 el 12 de septiembre de 2025, y puede suprimir intencionadamente los envíos push a otros dispositivos mientras uno está activo.

​

Salas de bot a bot

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

• allowBots: true acepta mensajes de otras cuentas configuradas de bot de Matrix en salas y mensajes directos permitidos.
• allowBots: "mentions" acepta esos mensajes solo cuando mencionan visiblemente a este bot en salas. Los mensajes directos siguen permitidos.
• groups.<room>.allowBots sobrescribe la configuración de nivel de cuenta para una sala.
• OpenClaw sigue ignorando los mensajes del mismo ID de usuario de Matrix para evitar bucles de autorrespuesta.
• Matrix no expone aquí una marca nativa de bot; OpenClaw trata “escrito por bot” como “enviado por otra cuenta de Matrix configurada en este Gateway de OpenClaw”.

​

Cifrado y verificación

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

openclaw matrix verify status

openclaw matrix verify status --verbose

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

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

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

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

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

openclaw matrix verify backup status

openclaw matrix verify backup status --verbose

openclaw matrix verify backup restore

openclaw matrix verify backup restore --verbose

openclaw matrix verify backup reset --yes

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

​

Qué significa “verificado”

• Locally trusted: este dispositivo solo es de confianza para el cliente actual
• Cross-signing verified: el SDK informa que el dispositivo está verificado mediante firma cruzada
• Signed by owner: el dispositivo está firmado por tu propia clave de autofirma

​

Qué hace bootstrap

• inicializa el almacenamiento de secretos, reutilizando una clave de recuperación existente cuando es posible
• inicializa la firma cruzada y sube las claves públicas de firma cruzada que falten
• intenta marcar y firmar cruzadamente el dispositivo actual
• crea una nueva copia de seguridad de claves de sala en el servidor si todavía no existe una

​

Base nueva de copia de seguridad

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

​

Comportamiento de inicio

​

Avisos de verificación

• avisos de solicitud de verificación
• avisos de verificación lista (con orientación explícita de “Verificar con emoji”)
• avisos de inicio y finalización de verificación
• detalles SAS (emoji y decimal) cuando estén disponibles

​

Higiene de dispositivos

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Almacén criptográfico

​

Gestión de perfil

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

​

Hilos

• dm.sessionScope: "per-user" (predeterminado) mantiene el enrutamiento de mensajes directos de Matrix con alcance por remitente, por lo que varias salas de mensajes directos pueden compartir una sesión cuando se resuelven al mismo par.
• dm.sessionScope: "per-room" aísla cada sala de mensajes directos de Matrix en su propia clave de sesión, mientras sigue usando autenticación normal de mensajes directos y comprobaciones de lista de permitidos.
• Los enlaces explícitos de conversación de Matrix siguen teniendo prioridad sobre dm.sessionScope, por lo que las salas e hilos enlazados conservan su sesión de destino elegida.
• threadReplies: "off" mantiene las respuestas en el nivel superior y conserva los mensajes entrantes en hilo 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 sala en un hilo con raíz en el mensaje que las activó y enruta esa conversación mediante la sesión correspondiente con alcance de hilo desde el primer mensaje activador.
• dm.threadReplies sobrescribe la configuración de nivel superior solo para mensajes directos. Por ejemplo, puedes mantener aislados los hilos de sala mientras mantienes planos los mensajes directos.
• Los mensajes entrantes en hilo incluyen el mensaje raíz del hilo como contexto adicional para el agente.
• Los envíos con herramientas de mensajes heredan automáticamente el hilo actual de Matrix cuando el destino es la misma sala o el mismo destino de usuario de mensaje directo, a menos que se proporcione un threadId explícito.
• La reutilización del destino de usuario de mensaje directo de la misma sesión solo se activa cuando los metadatos de la sesión actual demuestran el mismo par de mensaje directo en la misma cuenta de Matrix; de lo contrario, OpenClaw recurre al enrutamiento normal con alcance por usuario.
• Cuando OpenClaw detecta que una sala de mensaje directo de Matrix entra en conflicto con otra sala de mensaje directo en la misma sesión compartida de mensaje directo de Matrix, publica un m.notice de una sola vez en esa sala con la vía de escape /focus cuando los enlaces de hilos están habilitados y la sugerencia dm.sessionScope.
• Se admiten enlaces de hilos en tiempo de ejecución para Matrix. /focus, /unfocus, /agents, /session idle, /session max-age y /acp spawn enlazado a hilo funcionan en salas y mensajes directos de Matrix.
• /focus de nivel superior en sala o mensaje directo de Matrix crea un nuevo hilo de Matrix y lo enlaza a la sesión de destino cuando threadBindings.spawnSubagentSessions=true.
• Ejecutar /focus o /acp spawn --thread here dentro de un hilo de Matrix existente enlaza ese hilo actual en su lugar.

​

Enlaces de conversación de ACP

• Ejecuta /acp spawn codex --bind here dentro del mensaje directo, sala o hilo existente de Matrix que quieras seguir usando.
• En un mensaje directo o sala de Matrix de nivel superior, el mensaje directo o sala actual sigue siendo la superficie de chat y los mensajes futuros se enrutan a la sesión ACP generada.
• Dentro de un hilo existente de Matrix, --bind here enlaza ese hilo actual en su lugar.
• /new y /reset reinician en su lugar la misma sesión ACP enlazada.
• /acp close cierra la sesión ACP y elimina el enlace.

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

​

Configuración de enlaces de hilos

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

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

​

Reacciones

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

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• emoji de respaldo de la identidad del agente

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

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• predeterminado: own

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

​

Contexto del historial

• channels.matrix.historyLimit controla cuántos mensajes recientes de sala se incluyen como InboundHistory cuando un mensaje de sala de Matrix activa al agente. Recurre a messages.groupChat.historyLimit; si ambos no están definidos, el valor efectivo predeterminado es 0. Configura 0 para desactivar.
• El historial de salas de Matrix es solo de sala. Los mensajes directos siguen usando el historial normal de sesión.
• El historial de salas de Matrix es solo pendiente: OpenClaw almacena en búfer los mensajes de sala que todavía no activaron una respuesta y luego toma una instantánea de esa ventana cuando llega una mención u otro activador.
• El mensaje activador actual no se incluye en InboundHistory; permanece en el cuerpo principal entrante para ese turno.
• Los reintentos del mismo evento de Matrix reutilizan la instantánea original del historial en lugar de desplazarse hacia mensajes más recientes de la sala.

​

Visibilidad del contexto

• contextVisibility: "all" es el valor predeterminado. El contexto adicional se conserva tal como se recibe.
• contextVisibility: "allowlist" filtra el contexto adicional a remitentes permitidos por las comprobaciones activas de lista de permitidos de sala o usuario.
• contextVisibility: "allowlist_quote" se comporta como allowlist, pero sigue conservando una respuesta citada explícita.

​

Política de mensajes directos 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,
        },
      },
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

Reparación de sala directa

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

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

• prefiere un mensaje directo estricto 1:1 que ya esté asignado en m.direct
• recurre a cualquier mensaje directo estricto 1:1 unido actualmente con ese usuario
• crea una nueva sala directa y reescribe m.direct si no existe un mensaje directo sano

​

Aprobaciones de ejecución

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (opcional; recurre a channels.matrix.dm.allowFrom)
• channels.matrix.execApprovals.target (dm | channel | both, predeterminado: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.* controla el modo nativo de difusión a mensajes directos/canales para solicitudes de aprobación de Matrix.
• Las aprobaciones de ejecución usan el conjunto de aprobadores de ejecución de execApprovals.approvers o channels.matrix.dm.allowFrom.
• Las aprobaciones de plugins usan la lista de permitidos de mensajes directos de Matrix de channels.matrix.dm.allowFrom.
• Los atajos mediante reacciones de Matrix y las actualizaciones de mensajes se aplican tanto a aprobaciones de ejecución como de plugins.

• target: "dm" envía las solicitudes de aprobación a los mensajes directos de los aprobadores
• target: "channel" envía la solicitud de vuelta a la sala o mensaje directo original de Matrix
• target: "both" envía a los mensajes directos de los aprobadores y a la sala o mensaje directo original de Matrix

• ✅ = permitir una vez
• ❌ = denegar
• ♾️ = permitir siempre cuando esa decisión esté permitida por la política efectiva de ejecución

• channels.matrix.accounts.<account>.execApprovals

​

Comandos slash

​

Varias cuentas

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

​

Homeservers privados/LAN

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

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

​

Uso de proxy para el tráfico de Matrix

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

​

Resolución de destino

• 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

• Las búsquedas de usuarios consultan el directorio de usuarios de Matrix en ese homeserver.
• Las búsquedas de salas aceptan directamente IDs y alias de sala explícitos y luego recurren a buscar nombres de salas unidas para esa cuenta.
• La búsqueda por nombre de sala unida es de mejor esfuerzo. Si un nombre de sala no puede resolverse a un ID o alias, se ignora en la resolución de la lista de permitidos en tiempo de ejecución.

​

Referencia de configuración

• enabled: habilita o deshabilita el canal.
• name: etiqueta opcional para la cuenta.
• defaultAccount: ID de cuenta preferido cuando hay varias cuentas de Matrix configuradas.
• homeserver: URL del homeserver, por ejemplo https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: permite que esta cuenta de Matrix se conecte a homeservers privados/internos. Habilítalo cuando el homeserver se resuelva a localhost, una IP de LAN/Tailscale o un host interno como matrix-synapse.
• proxy: URL opcional de proxy HTTP(S) para el tráfico de Matrix. Las cuentas con nombre pueden sobrescribir el valor predeterminado de nivel superior con su propio proxy.
• userId: ID completo de usuario de Matrix, por ejemplo @bot:example.org.
• accessToken: token de acceso para autenticación basada en token. Se admiten valores en texto plano y valores SecretRef para channels.matrix.accessToken y channels.matrix.accounts.<id>.accessToken en proveedores env/file/exec. Consulta Gestión de secretos.
• password: contraseña para inicio de sesión basado en contraseña. Se admiten valores en texto plano y valores SecretRef.
• deviceId: ID explícito de dispositivo de Matrix.
• deviceName: nombre visible del dispositivo para inicio de sesión con contraseña.
• avatarUrl: URL del avatar propio almacenada para sincronización del perfil y actualizaciones de profile set.
• initialSyncLimit: número máximo de eventos recuperados durante la sincronización de inicio.
• encryption: habilita E2EE.
• allowlistOnly: cuando es true, actualiza la política de sala open a allowlist y fuerza todas las políticas activas de mensajes directos excepto disabled (incluidas pairing y open) a allowlist. No afecta a las políticas disabled.
• allowBots: permite mensajes de otras cuentas configuradas de Matrix de OpenClaw (true o "mentions").
• groupPolicy: open, allowlist o disabled.
• contextVisibility: modo de visibilidad del contexto adicional de sala (all, allowlist, allowlist_quote).
• groupAllowFrom: lista de permitidos de IDs de usuario para tráfico de sala. Los IDs completos de usuario de Matrix son los más seguros; las coincidencias exactas del directorio se resuelven al inicio y cuando cambia la lista de permitidos mientras el monitor está en ejecución. Los nombres no resueltos se ignoran.
• historyLimit: máximo de mensajes de sala que se incluirán como contexto de historial de grupo. Recurre a messages.groupChat.historyLimit; si ambos no están definidos, el valor efectivo predeterminado es 0. Configura 0 para desactivar.
• replyToMode: off, first, all o batched.
• markdown: configuración opcional de renderizado Markdown para texto saliente de Matrix.
• streaming: off (predeterminado), "partial", "quiet", true o false. "partial" y true habilitan actualizaciones de borrador con vista previa primero usando mensajes de texto normales de Matrix. "quiet" usa avisos de vista previa sin notificación para configuraciones autohospedadas con reglas push. false equivale a "off".
• blockStreaming: true habilita mensajes de progreso separados para bloques completados del asistente mientras el streaming de borrador de vista previa está activo.
• threadReplies: off, inbound o always.
• threadBindings: sobrescrituras por canal para el enrutamiento y ciclo de vida de sesiones enlazadas a hilos.
• startupVerification: modo automático de solicitud de autoverificación al inicio (if-unverified, off).
• startupVerificationCooldownHours: período de espera antes de volver a intentar solicitudes automáticas de verificación al inicio.
• textChunkLimit: tamaño del fragmento de mensaje saliente en caracteres (se aplica cuando chunkMode es length).
• chunkMode: length divide los mensajes por número de caracteres; newline los divide por saltos de línea.
• responsePrefix: cadena opcional añadida al principio de todas las respuestas salientes para este canal.
• ackReaction: sobrescritura opcional de reacción de confirmación para este canal/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 multimedia en MB para envíos salientes y procesamiento multimedia entrante.
• autoJoin: política de unión automática por invitación (always, allowlist, off). Predeterminado: off. Se aplica a todas las invitaciones de Matrix, incluidas las de tipo mensaje directo.
• autoJoinAllowlist: salas/alias permitidos cuando autoJoin es allowlist. Las entradas de alias se resuelven a IDs de sala durante el manejo de la invitación; OpenClaw no confía en el estado de alias declarado por la sala invitada.
• dm: bloque de política de mensajes directos (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: controla el acceso a mensajes directos después de que OpenClaw se haya unido a la sala y la haya clasificado como mensaje directo. No cambia si una invitación se une automáticamente.
• dm.allowFrom: lista de permitidos de IDs de usuario para tráfico de mensajes directos. Los IDs completos de usuario de Matrix son los más seguros; las coincidencias exactas del directorio se resuelven al inicio y cuando cambia la lista de permitidos mientras el monitor está en ejecución. Los nombres no resueltos se ignoran.
• dm.sessionScope: per-user (predeterminado) o per-room. Usa per-room cuando quieras que cada sala de mensaje directo de Matrix mantenga contexto separado aunque el par sea el mismo.
• dm.threadReplies: sobrescritura de política de hilos solo para mensajes directos (off, inbound, always). Sobrescribe la configuración de nivel superior threadReplies tanto para la ubicación de respuestas como para el aislamiento de sesión en mensajes directos.
• execApprovals: entrega nativa de aprobaciones de ejecución de Matrix (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: IDs de usuario de Matrix autorizados para aprobar solicitudes de ejecución. Opcional cuando dm.allowFrom ya identifica a los aprobadores.
• execApprovals.target: dm | channel | both (predeterminado: dm).
• accounts: sobrescrituras nombradas por cuenta. Los valores de nivel superior de channels.matrix actúan como valores predeterminados para estas entradas.
• groups: mapa de políticas por sala. Se prefieren IDs o alias de sala; los nombres de sala no resueltos se ignoran en tiempo de ejecución. La identidad de sesión/grupo usa el ID de sala estable después de la resolución.
• groups.<room>.account: restringe una entrada de sala heredada a una cuenta específica de Matrix en configuraciones de varias cuentas.
• groups.<room>.allowBots: sobrescritura a nivel de sala para remitentes configurados como bots (true o "mentions").
• groups.<room>.users: lista de permitidos de remitentes por sala.
• groups.<room>.tools: sobrescrituras de permitir/denegar herramientas por sala.
• groups.<room>.autoReply: sobrescritura a nivel de sala para el filtrado por mención. true desactiva los requisitos de mención para esa sala; false los vuelve a forzar.
• groups.<room>.skills: filtro opcional de Skills a nivel de sala.
• groups.<room>.systemPrompt: fragmento opcional de prompt de sistema a nivel de sala.
• rooms: alias heredado de groups.
• actions: control de herramientas por acción (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

Relacionado

• Resumen de canales — todos los canales compatibles
• Pairing — autenticación de mensajes directos y flujo de emparejamiento
• Groups — comportamiento del chat grupal y filtrado por mención
• Enrutamiento de canales — enrutamiento de sesiones para mensajes
• Seguridad — modelo de acceso y refuerzo de seguridad