Migración de Matrix

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• el plugin sigue siendo @openclaw/matrix
• el canal sigue siendo matrix
• tu configuración sigue en channels.matrix
• las credenciales en caché siguen en ~/.openclaw/credentials/matrix/
• el estado en tiempo de ejecución sigue en ~/.openclaw/matrix/

​

Qué hace la migración automáticamente

• las instalaciones desde código fuente ejecutan openclaw doctor --fix durante el flujo de actualización y luego reinician el Gateway de forma predeterminada
• las instalaciones mediante gestor de paquetes actualizan el paquete, ejecutan una pasada de doctor no interactiva y luego dependen del reinicio predeterminado del Gateway para que el arranque pueda completar la migración de Matrix
• si usas openclaw update --no-restart, la migración de Matrix respaldada por el arranque se aplaza hasta que más tarde ejecutes openclaw doctor --fix y reinicies el Gateway

• crear o reutilizar una instantánea previa a la migración en ~/Backups/openclaw-migrations/
• reutilizar tus credenciales de Matrix en caché
• mantener la misma selección de cuenta y la configuración channels.matrix
• mover el almacén de sincronización plano más antiguo de Matrix a la ubicación actual con ámbito de cuenta
• mover el almacén criptográfico plano más antiguo de Matrix a la ubicación actual con ámbito de cuenta cuando la cuenta de destino pueda resolverse de forma segura
• extraer una clave de descifrado de copia de seguridad de claves de sala de Matrix guardada previamente desde el almacén criptográfico rust antiguo, cuando esa clave exista localmente
• reutilizar la raíz de almacenamiento de hash de token existente más completa para la misma cuenta, homeserver y usuario de Matrix cuando el token de acceso cambie más tarde
• escanear raíces de almacenamiento de hash de token hermanas en busca de metadatos pendientes de restauración de estado cifrado cuando el token de acceso de Matrix cambió pero la identidad de la cuenta/dispositivo se mantuvo igual
• restaurar claves de sala respaldadas en el nuevo almacén criptográfico en el siguiente arranque de Matrix

• OpenClaw escribe un archivo marcador en ~/.openclaw/matrix/migration-snapshot.json después de una instantánea correcta para que pasadas posteriores de arranque y reparación puedan reutilizar el mismo archivo.
• Estas instantáneas automáticas de migración de Matrix respaldan solo configuración + estado (includeWorkspace: false).
• Si Matrix solo tiene estado de migración de advertencia, por ejemplo porque userId o accessToken aún faltan, OpenClaw todavía no crea la instantánea porque no hay ninguna mutación de Matrix accionable.
• Si el paso de instantánea falla, OpenClaw omite la migración de Matrix para esa ejecución en lugar de modificar el estado sin un punto de recuperación.

• el almacén plano más antiguo de Matrix (~/.openclaw/matrix/bot-storage.json y ~/.openclaw/matrix/crypto/) provenía de un diseño de almacén único, por lo que OpenClaw solo puede migrarlo a un objetivo resuelto de cuenta de Matrix
• los almacenes heredados de Matrix que ya tienen ámbito de cuenta se detectan y preparan por cada cuenta de Matrix configurada

​

Qué no puede hacer automáticamente la migración

• claves de sala solo locales que nunca se respaldaron
• estado cifrado cuando la cuenta de Matrix de destino aún no puede resolverse porque homeserver, userId o accessToken todavía no están disponibles
• migración automática de un almacén plano compartido de Matrix cuando hay varias cuentas de Matrix configuradas pero channels.matrix.defaultAccount no está establecido
• instalaciones con ruta de plugin personalizada que están fijadas a una ruta de repositorio en lugar del paquete estándar de Matrix
• una clave de recuperación faltante cuando el almacén antiguo tenía claves respaldadas pero no conservó localmente la clave de descifrado

• las instalaciones con ruta de plugin personalizada de Matrix se muestran tanto durante el arranque del Gateway como en openclaw doctor

​

Flujo de actualización recomendado

1. Actualiza OpenClaw y el plugin de Matrix normalmente. Prefiere openclaw update sin --no-restart para que el arranque pueda completar la migración de Matrix inmediatamente.
2. Ejecuta:
   openclaw doctor --fix
   
   Si Matrix tiene trabajo de migración accionable, doctor creará o reutilizará primero la instantánea previa a la migración e imprimirá la ruta del archivo.
3. Inicia o reinicia el Gateway.
4. Comprueba el estado actual de verificación y copia de seguridad:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Coloca la clave de recuperación de la cuenta de Matrix que estás reparando en una variable de entorno específica de cuenta. Para una sola cuenta predeterminada, MATRIX_RECOVERY_KEY está bien. Para varias cuentas, usa una variable por cuenta, por ejemplo MATRIX_RECOVERY_KEY_ASSISTANT, y añade --account assistant al comando.
6. Si OpenClaw te indica que se necesita una clave de recuperación, ejecuta el comando para la cuenta correspondiente:
   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant
   
7. Si este dispositivo sigue sin verificarse, ejecuta el comando para la cuenta correspondiente:
   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant
   
   Si se acepta la clave de recuperación y la copia de seguridad es utilizable, pero Cross-signing verified sigue siendo no, completa la autoverificación desde otro cliente de Matrix:
   openclaw matrix verify self
   
   Acepta la solicitud en otro cliente de Matrix, compara los emojis o decimales, y escribe yes solo cuando coincidan. El comando sale correctamente solo después de que Cross-signing verified pase a ser yes.
8. Si estás abandonando intencionalmente el historial antiguo irrecuperable y quieres una referencia de copia de seguridad nueva para mensajes futuros, ejecuta:
   openclaw matrix verify backup reset --yes
   
9. Si todavía no existe una copia de seguridad de claves del lado del servidor, crea una para futuras recuperaciones:
   openclaw matrix verify bootstrap
   

​

Cómo funciona la migración cifrada

1. El arranque o openclaw doctor --fix crea o reutiliza la instantánea previa a la migración si la migración cifrada es accionable.
2. El arranque o openclaw doctor --fix inspecciona el almacén criptográfico antiguo de Matrix mediante la instalación activa del plugin de Matrix.
3. Si se encuentra una clave de descifrado de copia de seguridad, OpenClaw la escribe en el nuevo flujo de clave de recuperación y marca la restauración de claves de sala como pendiente.
4. En el siguiente arranque de Matrix, OpenClaw restaura automáticamente las claves de sala respaldadas en el nuevo almacén criptográfico.

​

Mensajes comunes y qué significan

​

Mensajes de actualización y detección

• Significado: se detectó el estado de Matrix antiguo en disco y se migró al diseño actual.
• Qué hacer: nada, a menos que la misma salida también incluya advertencias.

• Significado: OpenClaw creó un archivo de recuperación antes de modificar el estado de Matrix.
• Qué hacer: conserva la ruta del archivo impresa hasta que confirmes que la migración se completó correctamente.

• Significado: OpenClaw encontró un marcador de instantánea de migración de Matrix existente y reutilizó ese archivo en lugar de crear una copia de seguridad duplicada.
• Qué hacer: conserva la ruta del archivo impresa hasta que confirmes que la migración se completó correctamente.

• Significado: existe estado antiguo de Matrix, pero OpenClaw no puede asignarlo a una cuenta de Matrix actual porque Matrix no está configurado.
• Qué hacer: configura channels.matrix y luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

• Significado: OpenClaw encontró estado antiguo, pero aún no puede determinar la raíz exacta de la cuenta/dispositivo actual.
• Qué hacer: inicia el Gateway una vez con un inicio de sesión funcional de Matrix, o vuelve a ejecutar openclaw doctor --fix después de que existan credenciales en caché.

• Significado: OpenClaw encontró un almacén plano compartido de Matrix, pero se niega a adivinar qué cuenta nombrada de Matrix debe recibirlo.
• Qué hacer: establece channels.matrix.defaultAccount en la cuenta prevista y luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

• Significado: la nueva ubicación con ámbito de cuenta ya tiene un almacén de sincronización o criptográfico, por lo que OpenClaw no lo sobrescribió automáticamente.
• Qué hacer: verifica que la cuenta actual sea la correcta antes de eliminar o mover manualmente el objetivo en conflicto.

• Significado: OpenClaw intentó mover el estado antiguo de Matrix, pero la operación del sistema de archivos falló.
• Qué hacer: inspecciona los permisos del sistema de archivos y el estado del disco, y luego vuelve a ejecutar openclaw doctor --fix.

• Significado: OpenClaw encontró un almacén cifrado antiguo de Matrix, pero no hay una configuración actual de Matrix a la que adjuntarlo.
• Qué hacer: configura channels.matrix y luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

• Significado: el almacén cifrado existe, pero OpenClaw no puede decidir de forma segura a qué cuenta/dispositivo actual pertenece.
• Qué hacer: inicia el Gateway una vez con un inicio de sesión funcional de Matrix, o vuelve a ejecutar openclaw doctor --fix después de que las credenciales en caché estén disponibles.

• Significado: OpenClaw encontró un almacén criptográfico heredado plano compartido, pero se niega a adivinar qué cuenta nombrada de Matrix debe recibirlo.
• Qué hacer: establece channels.matrix.defaultAccount en la cuenta prevista y luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

• Significado: OpenClaw detectó estado antiguo de Matrix, pero la migración sigue bloqueada por datos de identidad o credenciales faltantes.
• Qué hacer: finaliza el inicio de sesión o la configuración de Matrix, y luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

• Significado: OpenClaw encontró estado antiguo cifrado de Matrix, pero no pudo cargar el punto de entrada auxiliar del plugin de Matrix que normalmente inspecciona ese almacén.
• Qué hacer: reinstala o repara el plugin de Matrix (openclaw plugins install @openclaw/matrix, o openclaw plugins install ./path/to/local/matrix-plugin para un checkout del repositorio), luego vuelve a ejecutar openclaw doctor --fix o reinicia el gateway.
• Si npm informa que el paquete Matrix propiedad de OpenClaw está obsoleto, usa el plugin incluido desde una compilación empaquetada actual de OpenClaw o la ruta del checkout local hasta que se publique un paquete de npm más nuevo.

• Significado: OpenClaw encontró una ruta de archivo auxiliar que sale de la raíz del plugin o no supera las comprobaciones de límite del plugin, por lo que rechazó importarlo.
• Qué hacer: reinstala el plugin de Matrix desde una ruta de confianza, luego vuelve a ejecutar openclaw doctor --fix o reinicia el gateway.

• Significado: OpenClaw se negó a modificar el estado de Matrix porque no pudo crear primero la instantánea de recuperación.
• Qué hacer: resuelve el error de copia de seguridad, luego vuelve a ejecutar openclaw doctor --fix o reinicia el gateway.

• Significado: la alternativa del lado cliente de Matrix encontró almacenamiento plano antiguo, pero el traslado falló. OpenClaw ahora interrumpe esa alternativa en lugar de iniciar silenciosamente con un almacén nuevo.
• Qué hacer: revisa los permisos del sistema de archivos o los conflictos, conserva intacto el estado antiguo y vuelve a intentarlo después de corregir el error.

• Significado: Matrix está fijado a una instalación por ruta, por lo que las actualizaciones principales no lo sustituyen automáticamente por el paquete Matrix estándar del repositorio.
• Qué hacer: reinstala con openclaw plugins install @openclaw/matrix cuando quieras volver al plugin de Matrix predeterminado.
• Si npm informa que el paquete Matrix propiedad de OpenClaw está obsoleto, usa el plugin incluido desde una compilación empaquetada actual de OpenClaw hasta que se publique un paquete de npm más nuevo.

​

Mensajes de recuperación de estado cifrado

• Significado: las claves de sala incluidas en la copia de seguridad se restauraron correctamente en el nuevo almacén criptográfico.
• Qué hacer: normalmente, nada.

• Significado: algunas claves de sala antiguas solo existían en el almacén local antiguo y nunca se habían subido a la copia de seguridad de Matrix.
• Qué hacer: espera que parte del historial cifrado antiguo siga no disponible, a menos que puedas recuperar esas claves manualmente desde otro cliente verificado.

• Significado: existe una copia de seguridad, pero OpenClaw no pudo recuperar automáticamente la clave de recuperación.
• Qué hacer: ejecuta printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Significado: OpenClaw encontró el almacén cifrado antiguo, pero no pudo inspeccionarlo de forma lo bastante segura para preparar la recuperación.
• Qué hacer: vuelve a ejecutar openclaw doctor --fix. Si se repite, conserva intacto el directorio de estado antiguo y recupera usando otro cliente Matrix verificado más printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Significado: OpenClaw detectó un conflicto de clave de copia de seguridad y se negó a sobrescribir automáticamente el archivo recovery-key actual.
• Qué hacer: verifica qué clave de recuperación es la correcta antes de reintentar cualquier comando de restauración.

• Significado: este es el límite estricto del formato de almacenamiento antiguo.
• Qué hacer: las claves incluidas en copia de seguridad aún se pueden restaurar, pero el historial cifrado solo local puede seguir no disponible.

• Significado: el nuevo plugin intentó restaurar, pero Matrix devolvió un error.
• Qué hacer: ejecuta openclaw matrix verify backup status, luego reintenta con printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin si es necesario.

​

Mensajes de recuperación manual

• Significado: OpenClaw sabe que deberías tener una clave de copia de seguridad, pero no está activa en este dispositivo.
• Qué hacer: ejecuta openclaw matrix verify backup restore, o define MATRIX_RECOVERY_KEY y ejecuta printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin si es necesario.

• Significado: este dispositivo actualmente no tiene almacenada la clave de recuperación.
• Qué hacer: define MATRIX_RECOVERY_KEY, ejecuta printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin, luego restaura la copia de seguridad.

• Significado: la clave almacenada no coincide con la copia de seguridad de Matrix activa.
• Qué hacer: define MATRIX_RECOVERY_KEY con la clave correcta y ejecuta printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Significado: la copia de seguridad existe, pero este dispositivo todavía no confía lo suficiente en la cadena de firma cruzada.
• Qué hacer: define MATRIX_RECOVERY_KEY y ejecuta printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Significado: intentaste un paso de recuperación sin proporcionar una clave de recuperación cuando era obligatoria.
• Qué hacer: vuelve a ejecutar el comando con --recovery-key-stdin, por ejemplo printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Significado: la clave proporcionada no se pudo analizar o no coincidía con el formato esperado.
• Qué hacer: reintenta con la clave de recuperación exacta de tu cliente Matrix o del archivo recovery-key.

• Significado: OpenClaw pudo aplicar la clave de recuperación, pero Matrix todavía no ha establecido plena confianza de identidad con firma cruzada para este dispositivo. Revisa la salida del comando para Recovery key accepted, Backup usable, Cross-signing verified y Device verified by owner.
• Qué hacer: ejecuta openclaw matrix verify self, acepta la solicitud en otro cliente Matrix, compara el SAS y escribe yes solo cuando coincida. El comando espera la confianza plena de identidad de Matrix antes de informar éxito. Usa printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing solo cuando quieras sustituir intencionadamente la identidad de firma cruzada actual.

• Significado: el almacenamiento secreto no produjo una sesión de copia de seguridad activa en este dispositivo.
• Qué hacer: verifica primero el dispositivo, luego vuelve a comprobar con openclaw matrix verify backup status.

• Significado: este dispositivo no puede restaurar desde el almacenamiento secreto hasta que se complete la verificación del dispositivo.
• Qué hacer: ejecuta primero printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

​

Mensajes de instalación de plugin personalizado

• Significado: tu registro de instalación del plugin apunta a una ruta local que ya no existe.
• Qué hacer: reinstala con openclaw plugins install @openclaw/matrix, o si estás ejecutando desde un checkout del repositorio, openclaw plugins install ./path/to/local/matrix-plugin.
• Si npm informa que el paquete Matrix propiedad de OpenClaw está obsoleto, usa el plugin incluido desde una compilación empaquetada actual de OpenClaw o la ruta del checkout local hasta que se publique un paquete de npm más nuevo.

​

Si el historial cifrado todavía no vuelve

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

​

Si quieres empezar de cero para mensajes futuros

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

​

Relacionado

• Matrix: configuración del canal.
• Reglas push de Matrix: enrutamiento de notificaciones.
• Doctor: comprobación de estado y activador de migración automática.
• Guía de migración: todas las rutas de migración (traslados de máquina, importaciones entre sistemas).
• Plugins: instalación y registro de plugins.