Migração do Matrix

Faça upgrade do Plugin público matrix anterior para a implementação atual.

Para a maioria dos usuários, o upgrade já está implementado:

• o Plugin continua sendo @openclaw/matrix
• o canal continua sendo matrix
• sua configuração continua em channels.matrix
• as credenciais em cache continuam em ~/.openclaw/credentials/matrix/
• o estado de runtime continua em ~/.openclaw/matrix/

Você não precisa renomear chaves de configuração nem reinstalar o Plugin com um novo nome. O pacote raiz openclaw não inclui mais o código de runtime do Matrix nem as dependências do SDK do Matrix. Se openclaw channels status mostrar que o Matrix está configurado, mas o Plugin não está instalado, execute openclaw doctor --fix ou openclaw plugins install @openclaw/matrix; não instale pacotes do SDK do Matrix no pacote raiz do OpenClaw.

O que a migração faz automaticamente

A migração do Matrix é executada quando você executa openclaw doctor --fix e, como alternativa, quando o cliente Matrix é iniciado e ainda encontra um estado auxiliar baseado em arquivos ao lado de seu armazenamento SQLite.

A migração automática abrange:

• reutilizar suas credenciais do Matrix em cache
• manter a mesma seleção de conta e configuração de channels.matrix
• importar o estado auxiliar baseado em arquivos (cache de sincronização bot-storage.json, recovery-key.json, legacy-crypto-migration.json, snapshots do IndexedDB) para o estado SQLite do Matrix; os arquivos migrados são arquivados com um sufixo .migrated
• reutilizar a raiz de armazenamento de hash de token existente mais completa para a mesma conta, homeserver, usuário e dispositivo do Matrix quando o token de acesso for alterado posteriormente

Upgrade de versões do OpenClaw anteriores a 2026.4

As versões até a série 2026.6 também migravam o layout plano original de armazenamento único do Matrix (~/.openclaw/matrix/bot-storage.json mais ~/.openclaw/matrix/crypto/) e preparavam a recuperação do estado criptografado do armazenamento criptográfico antigo em Rust. As versões atuais não incluem mais essa migração.

Se você estiver fazendo upgrade de uma instalação que ainda usa o layout plano, primeiro faça upgrade para uma versão 2026.6, execute openclaw doctor --fix e inicie o Gateway uma vez para que o armazenamento plano e quaisquer chaves de sala recuperáveis sejam migrados. Depois, atualize para a versão mais recente.

O Plugin público anterior do Matrix não criava automaticamente backups de chaves de sala do Matrix. Se a instalação antiga tinha um histórico criptografado somente local que nunca foi incluído em backup, algumas mensagens criptografadas mais antigas podem continuar ilegíveis após o upgrade, independentemente do caminho de migração.

Fluxo de upgrade recomendado

1. Atualize o OpenClaw e o Plugin do Matrix normalmente.

2. Execute:

   openclaw doctor --fix

3. Inicie ou reinicie o Gateway.

4. Verifique o estado atual de verificação e backup:

   openclaw matrix verify statusopenclaw matrix verify backup status

5. Coloque a chave de recuperação da conta do Matrix que você está reparando em uma variável de ambiente específica da conta. Para uma única conta padrão, MATRIX_RECOVERY_KEY é suficiente. Para várias contas, use uma variável por conta, por exemplo, MATRIX_RECOVERY_KEY_ASSISTANT, e adicione --account assistant ao comando.

6. Se o OpenClaw informar que uma chave de recuperação é necessária, execute o comando para a conta correspondente:

   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. Se este dispositivo ainda não estiver verificado, execute o comando para a conta correspondente:

   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

   Se a chave de recuperação for aceita e o backup puder ser usado, mas Cross-signing verified ainda for no, conclua a autoverificação em outro cliente Matrix:

   openclaw matrix verify self

   Aceite a solicitação em outro cliente Matrix, compare os emojis ou números decimais e digite yes somente se forem iguais. O comando aguarda a confiança total na identidade do Matrix antes de informar êxito.

8. Se você estiver abandonando intencionalmente o histórico antigo irrecuperável e quiser uma nova linha de base de backup para mensagens futuras, execute:

   openclaw matrix verify backup reset --yes

   Adicione --rotate-recovery-key somente quando a chave de recuperação antiga não deva mais desbloquear o novo backup.

9. Se ainda não existir um backup de chaves no servidor, crie um para recuperações futuras:

   openclaw matrix verify bootstrap

Mensagens comuns e seus significados

Failed migrating legacy Matrix client storage: ...

• Significado: a alternativa do lado do cliente Matrix encontrou um estado auxiliar baseado em arquivos, mas houve falha ao importá-lo para o SQLite. O OpenClaw desfaz as movimentações concluídas e interrompe essa alternativa, em vez de iniciar silenciosamente com um novo armazenamento.
• O que fazer: verifique as permissões ou os conflitos do sistema de arquivos, mantenha o estado antigo intacto e tente novamente após corrigir o erro.

Matrix is installed from a custom path: ...

• Significado: o Matrix está fixado a uma instalação por caminho, portanto, as atualizações da linha principal não o substituem automaticamente pelo pacote padrão do Matrix.
• O que fazer: reinstale com openclaw plugins install @openclaw/matrix quando quiser retornar ao Plugin padrão do Matrix.

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

• Significado: o registro de instalação do Plugin aponta para um caminho local que não existe mais.
• O que fazer: reinstale com openclaw plugins install @openclaw/matrix ou, se estiver executando a partir de um checkout do repositório, openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix também pode remover as referências obsoletas ao Plugin do Matrix para você.

Mensagens de recuperação manual

openclaw matrix verify status e openclaw matrix verify backup status exibem uma linha Backup issue: seguida de orientações em Next steps: quando o backup das chaves de sala não está íntegro neste dispositivo:

Outros erros de recuperação:

Matrix recovery key is required

• Significado: você tentou realizar uma etapa de recuperação sem fornecer uma chave de recuperação quando ela era necessária.
• O que fazer: execute novamente o comando com --recovery-key-stdin, por exemplo, printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

Invalid Matrix recovery key: ...

• Significado: não foi possível interpretar a chave fornecida ou ela não correspondia ao formato esperado.
• O que fazer: tente novamente com a chave de recuperação exata do seu cliente Matrix ou da exportação da chave de recuperação.

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

• Significado: a chave de recuperação desbloqueou material de backup utilizável, mas o Matrix não estabeleceu confiança total na identidade de assinatura cruzada para este dispositivo. Verifique na saída do comando os campos Recovery key accepted, Backup usable, Cross-signing verified e Device verified by owner.
• O que fazer: execute openclaw matrix verify self, aceite a solicitação em outro cliente Matrix, compare o SAS e digite yes somente se ele corresponder. Use printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing somente quando quiser intencionalmente substituir a identidade atual de assinatura cruzada.

Se você aceitar perder o histórico criptografado antigo irrecuperável, poderá redefinir a linha de base atual do backup com openclaw matrix verify backup reset --yes. Quando o segredo armazenado do backup estiver corrompido, essa redefinição também reparará o armazenamento de segredos para que a nova chave de backup seja carregada corretamente após a reinicialização.

Se o histórico criptografado ainda não reaparecer

Execute estas verificações na ordem indicada:

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

Se o backup for restaurado com êxito, mas o histórico ainda estiver ausente em algumas salas antigas, provavelmente essas chaves ausentes nunca foram incluídas em backup pelo Plugin anterior.

Se você quiser começar do zero para mensagens futuras

Se você aceitar perder o histórico criptografado antigo irrecuperável e quiser apenas uma linha de base de backup limpa daqui em diante, execute estes comandos na ordem indicada:

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

Se o dispositivo ainda não estiver verificado depois disso, conclua a verificação em seu cliente Matrix comparando os emojis ou códigos decimais do SAS e confirmando que são iguais.

Relacionado

• Matrix: configuração do canal.
• Regras de push do Matrix: roteamento de notificações.
• Doctor: verificação de integridade e acionamento da migração automática.
• Guia de migração: todos os caminhos de migração (mudanças de máquina, importações entre sistemas).
• Plugins: instalação e registro de Plugins.