Matrix

Ejecuta ZeroClaw en salas de Matrix, incluidas las salas con cifrado de extremo a extremo (E2EE).

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para matrix establece channel en matrix, lista los remitentes permitidos en external_peers (para matrix, el ID de usuario completo de Matrix, @user:server.tld; ["*"] acepta a cualquiera), opcionalmente nombra agents pares para el despacho entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulte Peer Groups para la referencia de campos.

Dónde configurar esto:

Modo de fallo común que este guía aborda:

Matrix está configurado correctamente, las verificaciones pasan, pero el bot no responde.

Preguntas frecuentes rápidas

Si Matrix aparece conectado pero no hay respuesta, valida primero lo siguiente:

1. El remitente está en el conjunto de pares del agente (para pruebas: external_peers = ["*"]).
2. La cuenta del bot se ha unido a la sala objetivo exacta.
3. Las credenciales pertenecen a la cuenta del bot (verificación whoami en la ruta del token, ver §5C).
4. La sala cifrada puede descifrarse: recovery_key configurada (recomendado) o claves compartidas con el dispositivo del bot.
5. El demonio se reinició después de los cambios en la configuración.

1. Requisitos

Antes de probar el flujo de mensajes:

1. La cuenta del bot está unida a la sala objetivo.
2. Las credenciales autentican la cuenta del bot: ya sea user_id + password (recomendado, consulte §2) o un access_token (vía token, §3).
3. allowed_rooms incluye la sala de destino (o está vacío para permitir todas las salas a las que el bot se ha unido). Las entradas se comparan literalmente con el ID canónico de la sala (!room:server) de cada mensaje entrante, por lo que debe listar aquí los IDs canónicos de las salas: ZeroClaw no resuelve una entrada #alias:server para esta lista de permitidos. (Los alias se resuelven solo para destinos de entrega salientes, como delivery.to de cron.) Encuentre el ID canónico de una sala en su cliente (en Element: Configuración de la sala → Avanzado → ID interno de la sala).
4. Un grupo de pares autoriza al remitente (external_peers = ["*"] para pruebas abiertas, consulte §6).
5. Para salas E2EE, el bot puede descifrar: una recovery_key (recomendado) restaura las claves automáticamente, o las claves se comparten manualmente con el dispositivo del bot.

2. Configuración

zeroclaw config set channels.matrix.<alias>.access_token    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__matrix__<alias>__access_token=

zeroclaw config set channels.matrix.<alias>.ack_reactions <value>

export ZEROCLAW_channels__matrix__<alias>__ack_reactions=

zeroclaw config set channels.matrix.<alias>.allowed_rooms <value>

export ZEROCLAW_channels__matrix__<alias>__allowed_rooms=

zeroclaw config set channels.matrix.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__matrix__<alias>__approval_timeout_secs=

zeroclaw config set channels.matrix.<alias>.device_id <value>

export ZEROCLAW_channels__matrix__<alias>__device_id=

zeroclaw config set channels.matrix.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__matrix__<alias>__draft_update_interval_ms=

zeroclaw config set channels.matrix.<alias>.excluded_tools <value>

export ZEROCLAW_channels__matrix__<alias>__excluded_tools=

zeroclaw config set channels.matrix.<alias>.homeserver <value>

export ZEROCLAW_channels__matrix__<alias>__homeserver=

zeroclaw config set channels.matrix.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__matrix__<alias>__interrupt_on_new_message=

zeroclaw config set channels.matrix.<alias>.mention_only <value>

export ZEROCLAW_channels__matrix__<alias>__mention_only=

zeroclaw config set channels.matrix.<alias>.message_max_bytes <value>

export ZEROCLAW_channels__matrix__<alias>__message_max_bytes=

zeroclaw config set channels.matrix.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__matrix__<alias>__multi_message_delay_ms=

zeroclaw config set channels.matrix.<alias>.password    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__matrix__<alias>__password=

zeroclaw config set channels.matrix.<alias>.recovery_key    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__matrix__<alias>__recovery_key=

zeroclaw config set channels.matrix.<alias>.reply_in_thread <value>

export ZEROCLAW_channels__matrix__<alias>__reply_in_thread=

zeroclaw config set channels.matrix.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__matrix__<alias>__reply_min_interval_secs=

zeroclaw config set channels.matrix.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__matrix__<alias>__reply_queue_depth_max=

zeroclaw config set channels.matrix.<alias>.stream_draft_delete <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_delete=

zeroclaw config set channels.matrix.<alias>.stream_draft_lines <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_lines=

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

export ZEROCLAW_channels__matrix__<alias>__stream_mode=

zeroclaw config set channels.matrix.<alias>.stream_reasoning <value>

export ZEROCLAW_channels__matrix__<alias>__stream_reasoning=

zeroclaw config set channels.matrix.<alias>.stream_tool_arguments <value>

export ZEROCLAW_channels__matrix__<alias>__stream_tool_arguments=

zeroclaw config set channels.matrix.<alias>.user_id <value>

export ZEROCLAW_channels__matrix__<alias>__user_id=

Matrix se configura como un bloque [channels.matrix.<alias>]. Configúralo a través de cualquiera de estas superficies:

Configuración recomendada: contraseña + clave de recuperación

La forma oficial y de menor fricción de ejecutar Matrix es dejar que ZeroClaw inicie sesión desde cero y gestione su propia identidad de dispositivo:

• Omita device_id. Deje que el homeserver asigne uno al iniciar sesión. ZeroClaw guarda el id asignado en session.json y lo reutiliza en cada reinicio, por lo que no hay ningún valor que usted deba buscar, copiar ni mantener sincronizado. Fijar un device_id manualmente es la fuente más común de fallos en el intercambio de claves.
• Omite access_token. Cuando no está configurado, ZeroClaw recurre al inicio de sesión con contraseña. Un inicio de sesión nuevo es también lo que utiliza la ruta de recuperación automática (§8), por lo que el bot se autorrepara ante un estado local dañado sin intervención del operador.
• Establece password. Con access_token ausente, user_id + password realizan el inicio de sesión.
• Configura recovery_key. Esto restaura las claves de sala desde la copia de seguridad del lado del servidor y firma de forma cruzada el dispositivo recién registrado automáticamente en cada inicio: sin verificación con emojis, sin compartir claves manualmente, sin bootstrap. Consulta §5I para saber cómo obtenerla desde Element.

Así que un bloque completo recomendado establece homeserver, user_id, password y recovery_key, y deja access_token y device_id sin establecer.

La ruta access_token + device_id (§3) sigue funcionando y está documentada en su totalidad para operadores que necesiten reutilizar un token preexistente, pero requiere que usted mantenga un device_id estable por su cuenta, así que prefiera contraseña + clave de recuperación a menos que tenga una razón específica para no hacerlo.

channels.matrix.<alias>.password es un secreto. Se almacena cifrado, nunca en config.toml en texto plano. Configúralo a través de uno de estos métodos, que cifran al escribir:

zeroclaw config set channels.matrix.<alias>.password    # solicita entrada enmascarada, almacena cifrado

channels.matrix.<alias>.access_token es un secreto. Se almacena cifrado, nunca en config.toml en texto plano. Configúrelo a través de una de estas opciones, que cifran al escribir:

zeroclaw config set channels.matrix.<alias>.access_token    # solicita entrada enmascarada, almacena cifrado

homeserver es obligatorio. Para la configuración recomendada, establece también user_id, password y recovery_key. access_token y device_id solo son necesarios para la ruta basada en tokens en §3; allowed_rooms opcionalmente restringe en qué salas responde el bot. Autoriza a los remitentes con un grupo de pares. Índice completo de campos: referencia de configuración.

¿Aún no tienes una recovery_key? Consulta §5I: explica paso a paso cómo generar una en Element. ¿Prefieres la ruta del token? Consulta §3 para la llamada a la API de inicio de sesión con contraseña que genera un access_token junto con un device_id estable de una sola vez. Para buscar el device_id de un token que ya tienes, consulta §5H.

Acerca de user_id y device_id

• Para la configuración recomendada de contraseña + clave de recuperación, establece user_id y deja device_id sin definir: el homeserver lo asigna y ZeroClaw lo persiste.
• ZeroClaw lee la identidad desde Matrix /_matrix/client/v3/account/whoami.
• Solo en la ruta de access_token se establece device_id manualmente: un inicio de sesión con token lleva un dispositivo que el servidor ya generó, y ZeroClaw necesita ese id exacto para restaurar la sesión E2EE (consulta §5H para encontrarlo).

Hilos y contexto

Cuando una conversación de Matrix ocurre en un hilo, ese hilo es su propia conversación. ZeroClaw deriva una clave de sesión distinta por hilo, de modo que cada hilo lleva una ventana de contexto y un historial independientes: los mensajes de un hilo nunca se filtran a otro, y el agente no ve los turnos anteriores de un hilo hermano. Para Matrix esto se controla con reply_in_thread: cuando está activado, los mensajes de nivel superior abren un hilo y cada hilo es una conversación separada; cuando está desactivado, las respuestas se publican en la raíz del canal y el historial se indexa por remitente y destino en lugar de por hilo.

• El aislamiento es el objetivo. El contexto de cada hilo es autónomo: no se filtra fuera del hilo, y nada de fuera del hilo se filtra hacia dentro. Los hilos paralelos mantienen estados conversacionales separados, por lo que las tareas no relacionadas nunca se contaminan entre sí.
• Los hilos largos hacen crecer el contexto. Un hilo acumula historial mientras permanece activo, por lo que un hilo muy largo eventualmente llena la ventana de contexto del modelo como cualquier otra conversación larga. Inicia un nuevo hilo para restablecer.
• El trabajo en curso está delimitado por hilo. Un mensaje nuevo en un hilo no cancela una respuesta en curso en otro; la tarea de cada hilo es independiente.

Establece el comportamiento del hilo en cualquier superficie:

zeroclaw config set channels.matrix.<alias>.reply_in_thread true     # respuestas de hilo activadas
zeroclaw config set channels.matrix.<alias>.reply_in_thread false    # de respuestas en la raíz del canal

3. Ruta de token (alternativa): obtención de access_token y device_id

[!IMPORTANT] Esta sección es solo para la ruta de access_token. Si seguiste la configuración recomendada de contraseña + clave de recuperación en §2, puedes omitirla: no necesitas un token de acceso ni un device_id gestionado manualmente.

Use esta ruta cuando deba reutilizar un token preexistente (por ejemplo, uno copiado de otro despliegue). Element no expone el token directamente, por lo que la forma canónica de generar uno es una llamada única a la API de inicio de sesión con contraseña que devuelve juntos el token de acceso y un ID de dispositivo estable. El inicio de sesión con token lleva asociado un dispositivo, por lo que en esta ruta device_id es obligatorio y debe permanecer estable.

Si su cuenta de operador ya tiene un token, pase a la §4. Si solo necesita consultar el device_id de un token existente, consulte la §5H, Opción 1 (whoami) u Opción 2 (Element).

Paso 1: Genere un token mediante inicio de sesión con contraseña

Ejecuta esto una vez. Reemplaza your.homeserver, el nombre de usuario del bot, la contraseña, y elige cualquier cadena corta de device_id (alfanumérica, sin espacios; esta es la etiqueta de dispositivo del lado del servidor que ZeroClaw reutilizará en cada reinicio):

curl -sS -X POST https://your.homeserver/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'

Respuesta:

{`user_id`: "@bot:example.com", "access_token": "syt_...", `device_id`: "NUEVODISPOSITIVO"}

Paso 2: Aplica ambos valores a ZeroClaw

Coloca access_token, device_id y user_id de la respuesta en tu bloque [channels.matrix.<alias>] (consulta §2 para saber dónde configurarlos) y luego reinicia: zeroclaw service restart.

Notas

• Conserva una copia del token cuando lo pegues por primera vez. Los secretos se cifran en reposo y zeroclaw config get imprimirá [masked] para el campo del token; no podrás recuperarlo más tarde. Guárdalo en una nota temporal si lo necesitarás para los fragmentos de validación con curl en §5C.
• Reutilice el mismo device_id en cada reinicio: cambiarlo fuerza un nuevo registro del dispositivo en el servidor, lo que rompe el intercambio de claves y la verificación en salas cifradas. La ruta de recuperación automática en §8 gestiona los casos raros en los que borrar los datos es realmente la opción correcta.
• Rotar el token de acceso más adelante sin volver a ejecutar el asistente: actualice el campo access_token en su configuración (consulte §2) y luego ejecute zeroclaw service restart.
• El token aparece como expirado o no válido al iniciar: genera uno nuevo con el mismo curl, repite el Paso 2.

4. Validación rápida

Aplica el conjunto de campos de la §2 si aún no lo has hecho, luego reinicia con zeroclaw service restart (segundo plano) o zeroclaw daemon (primer plano). Envía un mensaje de texto sin formato en la sala de Matrix configurada. Confirma:

• Los registros de ZeroClaw muestran que el oyente de Matrix se inicia sin errores repetidos de sincronización o autenticación.
• En una sala cifrada, el bot puede leer y responder a mensajes cifrados de usuarios permitidos.

5. Solución de problemas de “no response”

Proceda en orden.

A. Sala y membresía

• Confirma que la cuenta del bot se haya unido a la sala.
• Si agregas una sala en allowed_rooms, debe ser el ID canónico de la sala (!room:server), no un #alias:server. Los alias no se resuelven para la lista de permitidos, por lo que una entrada de alias silenciosamente no coincide con nada. Encuentra el ID canónico en Element a través de Configuración de la sala → Avanzado → Internal room ID.

B. Lista de remitentes permitidos (grupos de pares)

El remitente debe estar en el conjunto de pares del agente, consulte Quién puede comunicarse con el agente en la parte superior de esta página. Para diagnosticar, establezca temporalmente external_peers = ["*"] y reinicie el daemon.

C. Token e identidad

Los secretos se cifran en reposo y no son recuperables: zeroclaw config get imprime [masked] para cualquier campo secreto. Para ejecutar las comprobaciones a continuación, usa el token de acceso que generaste en §3 (o genera uno nuevo) y la URL de tu propio homeserver.

Valida el token del lado del servidor:

curl -sS -H "Authorization: Bearer <access_token>" \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

• El user_id devuelto debe coincidir con la cuenta del bot.
• Si device_id falta en la respuesta, configúrelo manualmente (consulte §5H).
• Rota el token de acceso: actualiza el campo access_token en tu configuración (consulta la §2) y luego ejecuta zeroclaw service restart.

D. Verificaciones específicas de E2EE

• El dispositivo del bot debe haber recibido las claves de sala desde dispositivos de confianza.
• Si las claves no se han compartido con este dispositivo, los eventos cifrados no se pueden descifrar.
• Verifica la confianza del dispositivo y el intercambio de claves desde una sesión de Matrix de confianza.
• matrix_sdk_crypto::backups: Trying to backup room keys but no backup key was found: la recuperación de copia de seguridad de claves aún no está habilitada en este dispositivo. No es fatal para el flujo de mensajes; aun así vale la pena completarla (ver §5I).
• Si los destinatarios ven los mensajes del bot como “no verificados”, verifica/firma el dispositivo del bot desde una sesión de Matrix confiable y mantén el device_id estable entre reinicios.

E. Niveles de registro

ZeroClaw suprime matrix_sdk, matrix_sdk_base y matrix_sdk_crypto a warn de forma predeterminada; generan demasiado ruido en info. Restaura la salida del SDK para depuración:

RUST_LOG=info,matrix_sdk=info,matrix_sdk_base=info,matrix_sdk_crypto=info zeroclaw daemon

F. Formato de mensajes (Markdown)

• ZeroClaw envía respuestas de Matrix como contenido de texto m.room.message con capacidad de markdown.
• Los clientes de Matrix que admiten formatted_body renderizan énfasis, listas y bloques de código.
• Si el formato aparece como texto sin formato: verifica primero la capacidad del cliente y luego confirma que ZeroClaw esté ejecutando una versión con salida de Matrix habilitada para markdown.

G. Prueba de reinicio

Después de realizar cambios en la configuración, reinicia el daemon y envía un nuevo mensaje. El historial de la línea de tiempo anterior no se volverá a reproducir.

H. Buscar device_id para un token existente

Solo necesitas esto en la ruta de access_token (§3). La configuración recomendada de contraseña + clave de recuperación omite device_id por completo: el homeserver asigna uno y ZeroClaw lo persiste, por lo que no hay nada que buscar. Si ya has cambiado a la configuración recomendada, omite esta sección.

Si realmente debes fijar un device_id (porque estás reutilizando un token de acceso existente en lugar de iniciar sesión con una contraseña), usa esto para encontrar el que está vinculado a ese token. Para bots completamente nuevos en la ruta del token, consulta §3: el flujo de inicio de sesión con contraseña descrito allí devuelve ambos valores juntos.

ZeroClaw necesita un device_id estable para la restauración de sesiones E2EE en la ruta del token. Sin él, se registra un dispositivo nuevo en cada reinicio, lo que rompe el intercambio de claves y la verificación de dispositivos.

Opción 1: whoami (la más fácil)

curl -sS -H "Authorization: Bearer <access_token>" \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

La respuesta incluye device_id si el token está vinculado a una sesión de dispositivo:

{`user_id`: "@bot:example.com", `device_id`: "ABCDEF1234"}

Si falta device_id, el token se creó sin un inicio de sesión de dispositivo (p. ej., a través de la API de administración). Genera un nuevo token + device_id juntos a través de §3.

Opción 2: Desde Element u otro cliente de Matrix

1. Iniciar sesión como la cuenta del bot en Element.
2. Configuración → Sesiones.
3. Copia el ID del dispositivo para la sesión activa.
4. Establece device_id en tu configuración (ver §2), luego ejecuta zeroclaw service restart. Mantén device_id estable: cambiarlo fuerza un nuevo registro de dispositivo, lo que rompe el intercambio de claves y la verificación existentes.

H (continuación). Recuperación de la eliminación de la tienda de criptografía

Síntoma: Se ha detectado un conflicto en la carga de la clave de un solo uso de Matrix; se detiene la sincronización para evitar un bucle infinito de reintento y el canal queda no disponible.

Causa: El almacén de criptografía local se eliminó mientras el dispositivo antiguo aún tenía claves de un solo uso registradas en el servidor. El SDK no puede cargar nuevas claves porque las claves antiguas aún existen en el servidor, lo que provoca un bucle infinito de conflicto de claves de un solo uso (OTK).

Corrección: inicio de sesión nuevo

Un inicio de sesión nuevo crea un nuevo dispositivo con un device_id nuevo, evitando por completo el conflicto de OTK (no se requiere eliminación de dispositivos con UIA).

1. Detener ZeroClaw.

   sh

   zeroclaw service stop
   

2. Obtén un nuevo token de acceso y device_id:

   sh

   curl -sS -X POST "https://matrix.org/_matrix/client/v3/login" \
     -H "Content-Type: application/json" \
     -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'
   

   Guarde el access_token y el device_id devueltos.

3. Eliminar la tienda de criptografía local:

   sh

   rm -rf ~/.zeroclaw/state/matrix/
   

4. Aplica las nuevas credenciales: configura access_token (secreto, consulta la §2) y device_id en tu configuración.

5. Reiniciar:

   sh

   zeroclaw service start
   

Qué esperar en el primer reinicio

• Our own device might have been deleted: inofensivo; el dispositivo antiguo ya no existe.
• Failed to decrypt a room event: mensajes antiguos anteriores al restablecimiento; irrecuperables.
• Matrix E2EE recovery successful: claves de sala restauradas desde la copia de seguridad del servidor (solo si recovery_key está configurada; consulte §5I).
• Los nuevos mensajes se descifran y funcionan normalmente.

Prevención: No elimine el directorio de estado local sin planificar un nuevo inicio de sesión. Si necesita un reinicio completo, obtenga nuevas credenciales primero, luego elimine el almacén y, por último, actualice la configuración.

I. Clave de recuperación (recomendada para E2EE)

Una clave de recuperación permite que ZeroClaw restaure automáticamente las claves de sala y los secretos de firma cruzada desde la copia de seguridad del lado del servidor. Los restablecimientos de dispositivos, las eliminaciones del almacén criptográfico y las instalaciones nuevas se recuperan todas automáticamente: sin verificación por emojis, sin compartir claves manualmente.

Paso 1: Obtén tu clave de recuperación de Element

1. Inicia sesión en la cuenta del bot en Element (web o escritorio).
2. Configuración → Seguridad y privacidad → Cifrado → Copia de seguridad segura.
3. Si la copia de seguridad ya está configurada, tu clave de recuperación se mostró cuando la habilitaste por primera vez. Si la guardaste, úsala.
4. Si la copia de seguridad no está configurada, haz clic en “Set up Secure Backup” → “Generate a Security Key”. Element muestra la clave (tiene un aspecto como EsTj 3yST y93F SLpB ...); cópiala en un lugar seguro.
5. Continúe después de la pantalla de la clave: Element luego le pide volver a introducir la clave en un cuadro de confirmación para demostrar que la guardó. Péguela y continúe para finalizar la configuración. Este es el mismo valor que puso en recovery_key.
6. (Opcional) Cierra la sesión del bot en Element una vez guardada la clave: haz clic en el menú de cuenta → All settings → Account, luego Remove this device. Dejar la sesión iniciada está bien; eliminarla solo mantiene ordenada la lista de dispositivos.

Paso 2: Agrega la clave de recuperación a ZeroClaw

Aplica la clave de recuperación a ZeroClaw:

channels.matrix.<alias>.recovery_key es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.matrix.<alias>.recovery_key    # solicita entrada enmascarada, almacena cifrado

Luego zeroclaw service restart. La clave de recuperación se cifra en reposo inmediatamente.

Paso 3: Reiniciar

zeroclaw service restart

Al iniciar, deberías ver:

Matrix E2EE recovery successful — room keys and cross-signing secrets restored from server backup.

A partir de ahora, incluso si se elimina la tienda de criptografía local, ZeroClaw se recupera automáticamente en el próximo inicio.

6. Registro de depuración

Diagnósticos específicos del canal de Matrix:

RUST_LOG=zeroclaw::channels::matrix=debug zeroclaw daemon

Superficies:

• Confirmación de restauración de sesión
• Cada ciclo de sincronización completado
• Estado de la bandera de conflicto OTK
• Resultados de la verificación de salud
• Clasificación de errores de sincronización transitorios frente a errores fatales

Para detalles a nivel de SDK:

RUST_LOG=zeroclaw::channels::matrix=debug,matrix_sdk_crypto=debug zeroclaw daemon

7. Notas operativas

• Mantén los tokens de Matrix fuera de los registros y capturas de pantalla.
• Comienza con external_peers = ["*"] permisivo, restríngelo a IDs de usuario explícitos una vez verificado.
• Usa siempre IDs canónicos de sala en allowed_rooms: los alias no se resuelven para la lista de permitidos de entrada (solo se resuelven para delivery.to de salida).
• Hilos: cuando channels.matrix.reply_in_thread es true (predeterminado), cada respuesta del bot vive en un hilo cuya raíz es el mensaje del usuario. Los mensajes de usuario de nivel superior abren un hilo nuevo; los hilos existentes se continúan. La línea de tiempo principal de la sala solo contiene los mensajes iniciados por el usuario.
• Contexto de la raíz del hilo: el primer mensaje entrante que ZeroClaw ve en cualquier hilo dado lleva el prefijo [Thread root from @sender]: <root body> para que el agente tenga la conversación que originó la respuesta. Los hilos que el propio bot inició omiten el preámbulo. El seguimiento es solo en memoria; después de un reinicio del daemon, el siguiente mensaje en cada hilo activo vuelve a inyectar el preámbulo exactamente una vez.
• Medios en respuestas inline: channels.matrix.mention_only = true hace que el bot ignore las subidas de medios sin texto (no hay cuerpo de texto contra el cual hacer la mención). Cuando el usuario responde inline a un evento descartado de este tipo con una pregunta (@bot can you see this?), ZeroClaw recorre el m.relates_to.m.in_reply_to.event_id de la respuesta, obtiene el evento padre e incorpora sus medios al mensaje actual: el pipeline de visión del agente ve la imagen aunque la subida original haya sido filtrada.
• Los archivos adjuntos se encadenan junto al texto: las llamadas a room.send_attachment incluyen un AttachmentConfig::reply(...) con EnforceThread::Threaded cuando hay un ancla de hilo presente, de modo que los PDF, las imágenes y las notas de voz aterrizan dentro del hilo del bot en lugar de en la línea de tiempo principal.
• Marcadores de medios salientes: el agente emite [image:url|path], [file:url|path], [voice:url|path], [video:...], [audio:...] (y alias en mayúsculas / [document:...]) dentro del texto de su respuesta; ZeroClaw obtiene los bytes (HTTP para http(s)://, lectura local en caso contrario) y los sube como el evento de mensaje de Matrix correspondiente. Los destinos ausentes o ilegibles no son fatales: el canal registra una advertencia, descarta únicamente ese marcador y añade una línea (note: I couldn't deliver the file at <path>.) para que el operador vea lo que se intentó en lugar de una respuesta descartada silenciosamente.
• Mensajes de voz (MSC3245): los eventos m.audio entrantes que contienen el campo org.matrix.msc3245.voice se guardan en {workspace_dir}/matrix_files/ y se procesan a través del proveedor de transcripción configurado del agente, de modo que el agente obtiene tanto el texto de la transcripción como la ruta de origen. Las notas de voz salientes usan el marcador [voice:<url|path>]; ZeroClaw las sube como m.audio con el indicador de voz + forma de onda cero establecidos para que Element muestre la burbuja como una nota de voz. Consulta Model Providers para la configuración del proveedor de transcripción.
• Reacciones de confirmación: controladas por channels.matrix.ack_reactions (por defecto true). Cuando está activado, el bot reacciona con 👀 mientras procesa y con ✅ al terminar. Establézcalo en false para mantener las salas sin reacciones.
• Sesiones persistentes: en el primer inicio de sesión exitoso, ZeroClaw escribe ~/.zeroclaw/state/matrix/session.json (user_id + device_id + access_token + refresh_token opcional). Los reinicios posteriores llaman a restore_session() desde ese blob: no hay nuevo inicio de sesión. El almacén criptográfico SQLite de matrix-rust-sdk reside junto a él en ~/.zeroclaw/state/matrix/store/. Una vez que session.json existe, rotar access_token en la configuración no tiene efecto hasta que el archivo sea eliminado: el token guardado prevalece. Elimina session.json para forzar un nuevo inicio de sesión a partir de los valores de configuración.
• Firma cruzada: cuando recovery_key coincide con lo que está sellado en el almacenamiento secreto del lado del servidor de tu cuenta, ZeroClaw ejecuta recovery().recover(key) en cada inicio, el SDK importa tus claves existentes maestra / de autofirma / de firma de usuario, y el dispositivo recién registrado se firma automáticamente. Sin bootstrap, sin UIA, sin rotación de claves. Si tu cuenta aún no tiene configurada la firma cruzada, genera la clave de recuperación en Element (Settings → Security & Privacy → Secure Backup) antes de configurar recovery_key.
• Entrega de cron: delivery.to debe ser un id de sala simple (!abc:server) o un alias (#room:server). Las configuraciones antiguas que escribían <sender>||<room> se toleran: ZeroClaw extrae el último segmento con prefijo !/# y advierte sobre el valor malformado.

Transmisión

Matrix transmite respuestas en streaming mediante la configuración stream_mode:

• off (predeterminado): toda la respuesta se publica como un solo mensaje una vez que el agente termina. Es lo más simple, y nunca muestra una respuesta a medio escribir.
• partial: el bot publica un borrador inmediatamente y lo edita en el lugar a medida que la respuesta se transmite. draft_update_interval_ms regula el ritmo de las ediciones; auméntalo si Matrix les aplica límites de velocidad.
• multi_message: cada párrafo se publica como un mensaje independiente, separados por multi_message_delay_ms. Útil para respuestas largas que de otro modo serían un solo bloque de texto.

Colócalo sobre cualquier superficie:

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

Detalles específicos de Matrix: en el modo partial, el estado de ejecución de las herramientas se muestra mediante el mismo flujo de edición que el texto de la respuesta. En el modo single_message, las actualizaciones del estado de las herramientas y del progreso se incorporan mediante ediciones a un único borrador deslizante, mientras que la respuesta final se envía como un mensaje de Matrix separado. stream_draft_lines controla las líneas de progreso visibles: 0 elimina únicamente el límite de cantidad de líneas; nunca crea un segundo mensaje de progreso. message_max_bytes limita el contenido de los eventos de borrador y final, contando el Markdown renderizado (incluido el HTML generado) y los metadatos de relación de respuesta y edición de Matrix, en lugar de contar solo el código fuente Markdown. Cuando el progreso excede el tamaño, se descartan líneas o entradas completas, empezando por las más antiguas, para que la ventana conserve la actividad más reciente; un elemento individual que exceda el tamaño se sustituye por una alerta visible. La respuesta final separada conserva un prefijo seguro para UTF-8. El contenido del progreso se escapa antes de renderizar Markdown, por lo que el razonamiento sigue siendo legible en varias líneas, mientras que el contenido del usuario, del modelo y de las herramientas no puede introducir formato Markdown ni HTML. Los valores inferiores a 512 usan este mínimo efectivo para que pueda caber un evento de Matrix serializado que no esté vacío. El presupuesto no se aplica a las solicitudes de aprobación, los avisos del sistema, la entrega programada ni otros envíos ordinarios. Elija un presupuesto inferior al límite de eventos de Matrix. stream_reasoning controla la visibilidad del razonamiento del proveedor en ese borrador de progreso: off suprime las actualizaciones del borrador derivadas del razonamiento, status emite indicaciones de actividad sin texto de razonamiento sin procesar y full emite texto de razonamiento sin procesar del proveedor en el borrador de progreso. stream_draft_delete controla si las transcripciones persistentes del progreso se eliminan antes de publicar la respuesta final; los errores de eliminación se registran y la entrega de la respuesta final continúa. Los borradores que solo contienen marcadores de posición se eliminan antes de la respuesta final, incluso cuando la conservación de transcripciones está habilitada. En el modo multi_message, cada párrafo se publica como su propio mensaje en el hilo, y la división tiene en cuenta los delimitadores de bloques de código, por lo que las líneas en blanco dentro de bloques delimitados no dividen un bloque de código entre mensajes.

stream_tool_arguments controla qué argumentos de herramienta aparecen en las líneas de progreso de single_message. La configuración ausente o vacía usa valores predeterminados conservadores por herramienta; los wrappers de skills, plugins, herramientas MCP y nombres no resueltos muestran solo sus nombres. Una única entrada de default_base selecciona none, safe o all, mientras que las reglas de herramientas con nombre exacto pueden reemplazar esa base o agregar y quitar campos:

stream_tool_arguments = [
    { default_base = "safe", argument_chars = 60 },
    { tool = "delegate", base = "none", include = ["agent", "background", "prompt"], argument_chars = 0 },
    { tool = "mock_tool", base = "all", exclude = ["token"] },
]

El orden de las reglas no es relevante, se rechazan las entradas de herramienta/predeterminadas duplicadas y una regla base omitida hereda default_base. include añade campos después de seleccionar la base; exclude los elimina. Los campos exclusivos del tiempo de ejecución nunca se muestran, los campos cuyos nombres son credenciales se redactan recursivamente dentro de cada valor seleccionado y cada valor renderizado pasa por la detección de filtraciones de credenciales y la normalización a una sola línea antes de llegar a Matrix. Incluir un valor compuesto sigue siendo una decisión explícita de divulgación por parte del operador, pero no omite la redacción de credenciales. En el modo safe, solo se renderizan los argumentos escalares de nivel superior recomendados; se omiten los valores nulos, las matrices y los objetos. Seleccionar all o nombrar un argumento en include es una aceptación explícita del operador para el renderizado de un valor compuesto como JSON compacto. argument_chars en la entrada predeterminada cambia el límite heredado por valor de 60; el mismo campo en una regla de herramienta lo anula para esa herramienta. 0 conserva los valores completos, mientras message_max_bytes sigue limitando el borrador renderizado. all explícito se aplica a herramientas desconocidas; usa una regla con el nombre exacto al habilitar argumentos solo para una herramienta de extensión.

8. Recuperación automática desde un estado local dañado

El almacén SQLite predeterminado de matrix-rust-sdk es de un solo dispositivo y asume que la vista local se mantiene sincronizada con el homeserver. Dos modos de fallo rompen esa suposición de forma irrecuperable; ZeroClaw detecta cada uno al inicio y (cuando password y user_id están ambos configurados) borra automáticamente ~/.zeroclaw/state/matrix/ y vuelve a autenticarse para que se cree un dispositivo nuevo en el lado del servidor.

• Estado de cifrado huérfano. Existe un directorio store/ pero session.json no (limpieza manual, instalación previa interrumpida, etc.). Iniciar sesión desde cero sobre un estado de cifrado huérfano reproduce conflictos Duplicate one-time keys / SigningKeyChanged que no se reparan automáticamente.
• Indicador StateStoreDataKey::OneTimeKeyAlreadyUploaded activado. El SDK persiste esta clave en el almacén de estado la primera vez que detecta una carga de OTK duplicada (según el propio comentario del SDK: “we forgot about some of our one-time keys. This will lead to UTDs.”). Sobrevive a los reinicios; la única solución es borrar y volver a registrar.

Se detecta la desviación de device_id, pero se tolera, no se borra. Si channels.matrix.device_id difiere del id de dispositivo almacenado en session.json, el canal registra una advertencia y respeta el id guardado (que es el valor que el homeserver realmente asignó al iniciar sesión). Borrar ante una desviación crearía un bucle de recuperación porque la auto-recuperación en sí misma genera un nuevo id, dejando la configuración y la sesión permanentemente desincronizadas.

Cuando recover() falla en sí mismo (típicamente MAC check for the secret storage key failed), el canal registra el id de la clave de almacenamiento secreto predeterminada del homeserver, si el evento de la clave tiene información de frase de contraseña, la longitud de la entrada sin espacios en blanco, y la cadena completa de errores: estos indican qué capa rechazó la clave de recuperación sin filtrar el valor. Los fallos de recuperación son no fatales (no activan el borrado automático); el bot continúa, simplemente el nuevo dispositivo no tendrá firma cruzada.

Si password + user_id no están configurados, la recuperación automática no puede ejecutarse: el canal aborta con un error accionable que señala las dos opciones: configurarlos, o ejecutar rm -rf ~/.zeroclaw/state/matrix/ manualmente.

Ver también

• Despliegue de red
• Referencia de configuración: generada a partir del esquema activo
• Visión general de los canales