Migración de Matrix en OpenClaw: Guía de actualización

Qué hace la migración automáticamente

Cuando el Gateway arranca, y cuando ejecutas openclaw doctor --fix, OpenClaw intenta reparar el estado antiguo de Matrix automáticamente. Antes de que cualquier paso de migración de Matrix modifique el estado en el disco, OpenClaw crea o reutiliza un snapshot de recuperación específico.

Cuando usas openclaw update, el activador exacto depende de cómo esté instalado OpenClaw:

Las instalaciones desde el código fuente ejecutan openclaw doctor --fix durante el flujo de actualización y luego reinician el Gateway por defecto.
Las instalaciones mediante gestor de paquetes actualizan el paquete, ejecutan un paso de doctor no interactivo y luego dependen del reinicio por defecto del Gateway para que el arranque termine la migración de Matrix.
Si usas openclaw update --no-restart, la migración de Matrix vinculada al arranque se pospone hasta que ejecutes openclaw doctor --fix y reinicies el Gateway.

La migración automática cubre:

Crear o reutilizar un snapshot previo a la migración en ~/Backups/openclaw-migrations/.
Reutilizar tus credenciales de Matrix en caché.
Mantener la misma selección de cuenta y configuración de channels.matrix.
Mover el almacén de sincronización plano (flat) más antiguo de Matrix a la ubicación actual con alcance de cuenta.
Mover el almacén criptográfico plano más antiguo de Matrix a la ubicación actual con alcance de cuenta cuando la cuenta de destino se pueda resolver de forma segura.
Extraer una clave de descifrado de respaldo de claves de sala de Matrix guardada previamente del antiguo almacén criptográfico de Rust, cuando esa clave exista localmente.
Reutilizar la raíz de almacenamiento de hash de token existente más completa para la misma cuenta de Matrix, homeserver y usuario cuando el Access Token cambie más adelante.
Escanear raíces de almacenamiento de hash de token hermanas en busca de metadatos de restauración de estado cifrado pendientes cuando el Access Token de Matrix cambió pero la identidad de la cuenta/dispositivo se mantuvo igual.
Restaurar las claves de sala respaldadas en el nuevo almacén criptográfico en el siguiente arranque de Matrix.

Detalles del snapshot:

OpenClaw escribe un archivo marcador en ~/.openclaw/matrix/migration-snapshot.json después de un snapshot exitoso para que los arranques y pasos de reparación posteriores puedan reutilizar el mismo archivo.
Estos snapshots automáticos de migración de Matrix respaldan solo la configuración y el estado (includeWorkspace: false).
Si Matrix solo tiene un estado de migración de advertencia, por ejemplo porque todavía falta userId o accessToken, OpenClaw no crea el snapshot todavía porque no se puede realizar ninguna modificación en Matrix.
Si el paso del snapshot falla, OpenClaw omite la migración de Matrix en esa ejecución en lugar de modificar el estado sin un punto de recuperación.

Sobre las actualizaciones de múltiples cuentas:

El almacén plano de Matrix más antiguo (~/.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 destino de cuenta de Matrix resuelto.
Los almacenes heredados de Matrix que ya tienen alcance de cuenta se detectan y preparan por cada cuenta de Matrix configurada.

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

El plugin de Matrix anterior no creaba automáticamente respaldos de las claves de sala de Matrix. Persistía el estado criptográfico local y solicitaba la verificación del dispositivo, pero no garantizaba que tus claves de sala estuvieran respaldadas en el homeserver.

Eso significa que algunas instalaciones cifradas solo pueden migrarse parcialmente.

OpenClaw no puede recuperar automáticamente:

Claves de sala solo locales que nunca se respaldaron.
Estado cifrado cuando la cuenta de Matrix de destino aún no se puede resolver porque homeserver, userId o accessToken siguen sin estar disponibles.
Migración automática de un almacén plano de Matrix compartido cuando hay varias cuentas de Matrix configuradas pero channels.matrix.defaultAccount no está establecido.
Instalaciones con rutas de plugin personalizadas que están vinculadas 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 guardó la clave de descifrado localmente.

Alcance actual de las advertencias:

Las instalaciones con rutas de plugin de Matrix personalizadas son detectadas tanto por el arranque del Gateway como por openclaw doctor.

Si tu antigua instalación tenía historial cifrado solo local que nunca se respaldó, es posible que algunos mensajes cifrados antiguos sigan sin poder leerse después de la actualización.

Flujo de actualización recomendado

Actualiza OpenClaw y el plugin de Matrix de forma normal. Te recomiendo usar openclaw update a secas, sin el flag --no-restart, para que el proceso de inicio finalice la migración de Matrix de inmediato.
Ejecuta:
Ventana de terminal
```
openclaw doctor --fix
```
Si Matrix tiene tareas de migración pendientes, doctor creará o reutilizará primero el snapshot previo a la migración y mostrará la ruta del archivo.
Inicia o reinicia el Gateway.

Revisa el estado actual de verificación y backup:

openclaw matrix verify status
openclaw matrix verify backup status

Si OpenClaw te indica que necesitas una recovery key, ejecuta:
Ventana de terminal
```
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
```
Si este dispositivo todavía no está verificado, ejecuta:
Ventana de terminal
```
openclaw matrix verify device "<your-recovery-key>"
```
Si decides abandonar el historial antiguo que no se puede recuperar y quieres un punto de partida limpio para futuros mensajes, ejecuta:
Ventana de terminal
```
openclaw matrix verify backup reset --yes
```
Si todavía no existe un backup de llaves en el servidor, crea uno para futuras recuperaciones:
Ventana de terminal
```
openclaw matrix verify bootstrap
```

Cómo funciona la migración cifrada

La migración cifrada es un proceso de dos etapas:

El inicio o openclaw doctor --fix crea o reutiliza el snapshot previo a la migración si la migración cifrada es necesaria.
El inicio o openclaw doctor --fix inspecciona el antiguo crypto store de Matrix a través de la instalación activa del plugin de Matrix.
Si encuentra una llave de descifrado del backup, OpenClaw la escribe en el nuevo flujo de recovery-key y marca la restauración de llaves de sala como pendiente.
En el siguiente inicio de Matrix, OpenClaw restaura automáticamente las llaves de sala respaldadas en el nuevo crypto store.

Si el almacén antiguo detecta llaves de sala que nunca se respaldaron, OpenClaw mostrará una advertencia en lugar de fingir que la recuperación fue exitosa.

Mensajes comunes y qué significan

Mensajes de actualización y detección

Matrix plugin upgraded in place.

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

Matrix migration snapshot created before applying Matrix upgrades.

Significado: OpenClaw creó un archivo de recuperación antes de modificar el estado de Matrix.
Qué hacer: guarda la ruta del archivo que aparece en pantalla hasta que confirmes que la migración se realizó con éxito.

Matrix migration snapshot reused before applying Matrix upgrades.

Significado: OpenClaw encontró un marcador de snapshot de migración de Matrix existente y reutilizó ese archivo en lugar de crear un respaldo duplicado.
Qué hacer: guarda la ruta del archivo impreso hasta que confirmes que la migración terminó bien.

Legacy Matrix state detected at ... but channels.matrix is not configured yet.

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

Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

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

Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

Significado: OpenClaw encontró un almacén de Matrix compartido, pero no puede decidir a qué cuenta de Matrix configurada debe asignarlo.
Qué hacer: define channels.matrix.defaultAccount con la cuenta deseada, luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

Matrix legacy sync store not migrated because the target already exists (...)

Significado: la nueva ubicación específica de la cuenta ya tiene un almacén de sincronización o de criptografía, 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 destino que causa el conflicto.

Failed migrating Matrix legacy sync store (...) o Failed migrating Matrix legacy crypto store (...)

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

Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.

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

Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

Significado: el almacén cifrado existe, pero OpenClaw no puede decidir con seguridad a qué cuenta o dispositivo actual pertenece.
Qué hacer: inicia el Gateway una vez con un login de Matrix válido, o vuelve a ejecutar openclaw doctor --fix cuando las credenciales en caché estén disponibles.

Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

Significado: OpenClaw encontró un almacén de criptografía antiguo compartido, pero no puede adivinar qué cuenta de Matrix debería recibirlo.
Qué hacer: configura channels.matrix.defaultAccount con la cuenta correspondiente, luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.

Significado: OpenClaw detectó un estado antiguo de Matrix, pero la migración sigue bloqueada por falta de datos de identidad o credenciales.
Qué hacer: termina de configurar el login o la configuración de Matrix, luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw/matrix so OpenClaw can inspect the old rust crypto store before upgrading.

Significado: OpenClaw encontró un estado cifrado antiguo de Matrix, pero no pudo cargar el helper 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 si usas un checkout local), luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.

Significado: OpenClaw encontró una ruta de archivo del helper que escapa de la raíz del plugin o falla las comprobaciones de seguridad, por lo que rechazó importarlo.
Qué hacer: reinstala el plugin de Matrix desde una ruta confiable, luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

- Failed creating a Matrix migration snapshot before repair: ...

- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".

Significado: OpenClaw se negó a modificar el estado de Matrix porque no pudo crear el snapshot de recuperación primero.
Qué hacer: soluciona el error del respaldo, luego vuelve a ejecutar openclaw doctor --fix o reinicia el Gateway.

Failed migrating legacy Matrix client storage: ...

Significado: el sistema de respaldo del cliente de Matrix encontró un almacenamiento antiguo, pero el movimiento falló. OpenClaw cancela ese proceso en lugar de iniciar con un almacén vacío sin avisar.
Qué hacer: revisa los permisos del sistema de archivos o posibles conflictos, mantén intacto el estado antiguo e inténtalo de nuevo tras corregir el error.

Matrix is installed from a custom path: ...

Significado: Matrix está vinculado a una instalación por ruta, por lo que las actualizaciones generales no lo reemplazarán automáticamente con el paquete estándar del repositorio.
Qué hacer: reinstala con openclaw plugins install @openclaw/matrix cuando quieras volver al plugin de Matrix por defecto.

Mensajes de recuperación de estado cifrado

matrix: restored X/Y room key(s) from legacy encrypted-state backup

Significado: las llaves de sala respaldadas se restauraron correctamente en el nuevo almacén de criptografía.
Qué hacer: normalmente nada.

matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically

Significado: algunas llaves de sala antiguas solo existían en el almacén local anterior y nunca se subieron al backup de Matrix.
Qué hacer: es probable que parte del historial cifrado antiguo no esté disponible a menos que recuperes esas llaves manualmente desde otro cliente verificado.

Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "openclaw matrix verify backup restore --recovery-key <key>" after upgrade if they have the recovery key.

Significado: el backup existe, pero OpenClaw no pudo recuperar la llave de recuperación automáticamente.
Qué hacer: ejecuta openclaw matrix verify backup restore --recovery-key "<tu-llave-de-recuperación>".

Failed inspecting legacy Matrix encrypted state for account "..." (...): ...

Significado: OpenClaw encontró el almacén cifrado antiguo, pero no pudo inspeccionarlo de forma segura para preparar la recuperación.
Qué hacer: vuelve a ejecutar openclaw doctor --fix. Si el problema persiste, mantén intacto el directorio del estado antiguo y recupera usando otro cliente de Matrix verificado junto con openclaw matrix verify backup restore --recovery-key "<tu-llave-de-recuperación>".

Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.

Significado: OpenClaw detectó un conflicto de llaves de backup y rechazó sobrescribir el archivo recovery-key actual automáticamente.
Qué hacer: verifica cuál es la llave de recuperación correcta antes de intentar cualquier comando de restauración.

Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.

Significado: este es el límite técnico del formato de almacenamiento antiguo.
Qué hacer: las llaves respaldadas aún pueden restaurarse, pero el historial cifrado que solo era local podría no estar disponible.

matrix: failed restoring room keys from legacy encrypted-state backup: ...

Significado: el nuevo plugin intentó la restauración pero Matrix devolvió un error.
Qué hacer: ejecuta openclaw matrix verify backup status, luego reintenta con openclaw matrix verify backup restore --recovery-key "<tu-llave-de-recuperación>" si es necesario.

Mensajes de recuperación manual

Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.

Significado: OpenClaw sabe que deberías tener una llave de backup, pero no está activa en este dispositivo.
Qué hacer: ejecuta openclaw matrix verify backup restore, o pasa el parámetro --recovery-key si es necesario.

Store a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.

Significado: este dispositivo no tiene almacenada la llave de recuperación actualmente.
Qué hacer: verifica primero el dispositivo con tu llave de recuperación y luego restaura el backup.

Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.

Significado: la llave almacenada no coincide con el backup activo de Matrix.
Qué hacer: vuelve a ejecutar openclaw matrix verify device "<tu-llave-de-recuperación>" con la llave correcta.

Si aceptas perder el historial cifrado antiguo que no se puede recuperar, puedes reiniciar la base del backup actual con openclaw matrix verify backup reset --yes.

Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.

Significado: el backup existe, pero este dispositivo aún no confía lo suficiente en la cadena de firma cruzada (cross-signing).
Qué hacer: vuelve a ejecutar openclaw matrix verify device "<tu-llave-de-recuperación>".

Matrix recovery key is required

Significado: intentaste un paso de recuperación sin proporcionar la llave de recuperación cuando era obligatoria.
Qué hacer: vuelve a ejecutar el comando incluyendo tu llave de recuperación.

Invalid Matrix recovery key: ...

Significado: la llave proporcionada no se pudo procesar o no coincide con el formato esperado.
Qué hacer: reintenta usando la llave de recuperación exacta de tu cliente de Matrix o de tu archivo de llaves.

Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.

Significado: se aplicó la llave, pero el dispositivo no pudo completar la verificación.
Qué hacer: confirma que usaste la llave correcta y que el cross-signing está activo en la cuenta, luego reintenta.

Matrix key backup is not active on this device after loading from secret storage.

Significado: el almacenamiento secreto no generó una sesión de backup activa en este dispositivo.
Qué hacer: verifica primero el dispositivo y luego revisa de nuevo con openclaw matrix verify backup status.

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device <key>' first.

Significado: este dispositivo no puede restaurar desde el almacenamiento secreto hasta que se complete la verificación del dispositivo.
Qué hacer: ejecuta primero openclaw matrix verify device "<tu-llave-de-recuperación>".

Mensajes de instalación de plugins personalizados

Matrix is installed from a custom path that no longer exists: ...

Significado: el registro de instalación de tu plugin apunta a una ruta local que ya no existe.
Qué hacer: reinstala con openclaw plugins install @openclaw/matrix, o si estás usando un checkout del repositorio, usa openclaw plugins install ./path/to/local/matrix-plugin.

Si el historial cifrado sigue sin aparecer

Ejecuta estas comprobaciones en orden:

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

Si el backup se restaura con éxito pero en algunas salas antiguas sigue faltando el historial, es probable que el plugin anterior nunca haya respaldado esas llaves.

Si quieres empezar de cero para futuros mensajes

Si aceptas perder el historial cifrado antiguo que no se puede recuperar y solo quieres un backup limpio de ahora en adelante, ejecuta estos comandos en orden:

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

Si el dispositivo sigue sin estar verificado después de eso, termina la verificación desde tu Matrix client comparando los emojis SAS o los códigos decimales y confirmando que coinciden.

Páginas relacionadas

Aquí tienes otros recursos que te resultarán útiles para complementar lo que has aprendido:

OpenClaw Expert

Sigues atascado?

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