Migración de Matrix

Actualice desde el Plugin público anterior matrix a la implementación actual.

Para la mayoría de los usuarios, la actualización ya está preparada:

• el Plugin sigue siendo @openclaw/matrix
• el canal sigue siendo matrix
• la configuración permanece en channels.matrix
• las credenciales almacenadas en caché permanecen en ~/.openclaw/credentials/matrix/
• el estado de ejecución permanece en ~/.openclaw/matrix/

No es necesario cambiar el nombre de las claves de configuración ni reinstalar el Plugin con un nombre nuevo. El paquete raíz openclaw ya no incluye el código de ejecución de Matrix ni las dependencias del SDK de Matrix. Si openclaw channels status muestra que Matrix está configurado pero el Plugin no está instalado, ejecute openclaw doctor --fix o openclaw plugins install @openclaw/matrix; no instale paquetes del SDK de Matrix en el paquete raíz de OpenClaw.

Qué hace automáticamente la migración

La migración de Matrix se ejecuta al ejecutar openclaw doctor --fix y, como mecanismo alternativo, cuando el cliente de Matrix se inicia y todavía encuentra estado auxiliar basado en archivos junto a su almacén SQLite.

La migración automática abarca:

• reutilizar las credenciales de Matrix almacenadas en caché
• conservar la misma selección de cuenta y la configuración de channels.matrix
• importar el estado auxiliar basado en archivos (caché de sincronización bot-storage.json, recovery-key.json, legacy-crypto-migration.json e instantáneas de IndexedDB) al estado SQLite de Matrix; los archivos migrados se archivan con el sufijo .migrated
• reutilizar la raíz de almacenamiento de hashes de tokens existente más completa para la misma cuenta, servidor doméstico, usuario y dispositivo de Matrix cuando el token de acceso cambie posteriormente

Actualización desde versiones de OpenClaw anteriores a 2026.4

Las versiones hasta la serie 2026.6 también migraban el diseño plano original de almacén único de Matrix (~/.openclaw/matrix/bot-storage.json junto con ~/.openclaw/matrix/crypto/) y preparaban la recuperación del estado cifrado desde el antiguo almacén criptográfico de Rust. Las versiones actuales ya no incluyen esa migración.

Si está actualizando una instalación que todavía utiliza el diseño plano, primero actualice a una versión 2026.6, ejecute openclaw doctor --fix e inicie el Gateway una vez para migrar el almacén plano y cualquier clave de sala recuperable. Después, actualice a la versión más reciente.

El Plugin público anterior de Matrix no creaba automáticamente copias de seguridad de las claves de sala de Matrix. Si la instalación anterior tenía un historial cifrado exclusivamente local del que nunca se hizo una copia de seguridad, algunos mensajes cifrados antiguos podrían seguir siendo ilegibles después de la actualización, independientemente de la ruta de migración.

Flujo de actualización recomendado

1. Actualice OpenClaw y el Plugin de Matrix de la forma habitual.

2. Ejecute:

   openclaw doctor --fix

3. Inicie o reinicie el Gateway.

4. Compruebe el estado actual de verificación y de la copia de seguridad:

   openclaw matrix verify statusopenclaw matrix verify backup status

5. Coloque la clave de recuperación de la cuenta de Matrix que está reparando en una variable de entorno específica de la cuenta. Para una única cuenta predeterminada, MATRIX_RECOVERY_KEY es adecuado. Para varias cuentas, utilice una variable por cuenta, por ejemplo MATRIX_RECOVERY_KEY_ASSISTANT, y añada --account assistant al comando.

6. Si OpenClaw indica que se necesita una clave de recuperación, ejecute el comando correspondiente a la cuenta:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant

7. Si este dispositivo todavía no está verificado, ejecute el comando correspondiente a la cuenta:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdinprintf '%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 se puede utilizar, pero Cross-signing verified sigue siendo no, complete la autoverificación desde otro cliente de Matrix:

   openclaw matrix verify self

   Acepte la solicitud en otro cliente de Matrix, compare los emojis o los números decimales y escriba yes únicamente cuando coincidan. El comando espera a que exista confianza plena en la identidad de Matrix antes de indicar que se ha completado correctamente.

8. Si está abandonando intencionadamente un historial antiguo irrecuperable y desea una base de referencia nueva para las copias de seguridad de los mensajes futuros, ejecute:

   openclaw matrix verify backup reset --yes

   Añada --rotate-recovery-key únicamente cuando la clave de recuperación antigua deba dejar de permitir el acceso a la copia de seguridad nueva.

9. Si todavía no existe una copia de seguridad de claves en el servidor, cree una para recuperaciones futuras:

   openclaw matrix verify bootstrap

Mensajes habituales y su significado

Failed migrating legacy Matrix client storage: ...

• Significado: el mecanismo alternativo del lado del cliente de Matrix encontró estado auxiliar basado en archivos, pero la importación a SQLite falló. OpenClaw revierte los movimientos completados y cancela ese mecanismo alternativo, en lugar de iniciarse silenciosamente con un almacén nuevo.
• Qué hacer: revise los permisos o conflictos del sistema de archivos, conserve intacto el estado antiguo y vuelva a intentarlo después de corregir el error.

Matrix is installed from a custom path: ...

• Significado: Matrix está fijado a una instalación desde una ruta, por lo que las actualizaciones de la línea principal no lo sustituyen automáticamente por el paquete predeterminado de Matrix.
• Qué hacer: vuelva a instalarlo con openclaw plugins install @openclaw/matrix cuando desee regresar al Plugin predeterminado de Matrix.

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

• Significado: el registro de instalación del Plugin apunta a una ruta local que ya no existe.
• Qué hacer: vuelva a instalarlo con openclaw plugins install @openclaw/matrix o, si está ejecutando desde una copia de trabajo del repositorio, con openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix también puede eliminar las referencias obsoletas al Plugin de Matrix.

Mensajes de recuperación manual

openclaw matrix verify status y openclaw matrix verify backup status muestran una línea Backup issue: junto con indicaciones en Next steps: cuando la copia de seguridad de claves de sala no está en buen estado en este dispositivo:

Otros errores de recuperación:

Matrix recovery key is required

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

Invalid Matrix recovery key: ...

• Significado: no se pudo analizar la clave proporcionada o esta no coincidía con el formato esperado.
• Qué hacer: vuelva a intentarlo con la clave de recuperación exacta de su cliente de Matrix o de la exportación de la clave de recuperación.

Matrix recovery key was applied, but this device still lacks full Matrix identity trust.

• Significado: la clave de recuperación desbloqueó material utilizable de la copia de seguridad, pero Matrix no ha establecido una confianza plena en la identidad mediante firmas cruzadas para este dispositivo. Compruebe si la salida del comando contiene Recovery key accepted, Backup usable, Cross-signing verified y Device verified by owner.
• Qué hacer: ejecute openclaw matrix verify self, acepte la solicitud en otro cliente de Matrix, compare el SAS y escriba yes únicamente cuando coincida. Utilice printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing únicamente cuando desee sustituir intencionadamente la identidad actual de firmas cruzadas.

Si acepta perder el historial cifrado antiguo irrecuperable, puede restablecer en su lugar la base de referencia actual de la copia de seguridad con openclaw matrix verify backup reset --yes. Cuando el secreto almacenado de la copia de seguridad está dañado, este restablecimiento también repara el almacén de secretos para que la nueva clave de la copia de seguridad pueda cargarse correctamente después del reinicio.

Si el historial cifrado todavía no se recupera

Ejecute estas comprobaciones en orden:

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

Si la copia de seguridad se restaura correctamente, pero todavía falta el historial de algunas salas antiguas, es probable que el Plugin anterior nunca haya creado una copia de seguridad de esas claves ausentes.

Si desea empezar de cero para los mensajes futuros

Si acepta perder el historial cifrado antiguo irrecuperable y solo desea una base de referencia limpia para las copias de seguridad futuras, ejecute estos comandos en orden:

openclaw matrix verify backup reset --yesopenclaw matrix verify backup status --verboseopenclaw matrix verify status

Si el dispositivo todavía no está verificado después de eso, finalice la verificación desde su cliente de Matrix comparando los emojis o códigos decimales del SAS y confirmando que coinciden.

Temas relacionados

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