Migração do 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.

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

​

O que a migração faz automaticamente

• instalações a partir do código-fonte executam openclaw doctor --fix durante o fluxo de atualização e depois reiniciam o Gateway por padrão
• instalações por gerenciador de pacotes atualizam o pacote, executam uma passagem não interativa do doctor e então dependem do reinício padrão do Gateway para que a inicialização conclua a migração do Matrix
• se você usar openclaw update --no-restart, a migração do Matrix apoiada pela inicialização é adiada até que você execute openclaw doctor --fix mais tarde e reinicie o Gateway

• criação ou reutilização de um snapshot pré-migração em ~/Backups/openclaw-migrations/
• reutilização das suas credenciais do Matrix em cache
• manutenção da mesma seleção de conta e configuração channels.matrix
• movimentação do armazenamento plano mais antigo de sincronização do Matrix para o local atual com escopo de conta
• movimentação do armazenamento plano mais antigo de criptografia do Matrix para o local atual com escopo de conta quando a conta de destino puder ser resolvida com segurança
• extração de uma chave de descriptografia de backup de chaves de sala do Matrix salva anteriormente a partir do armazenamento de criptografia rust antigo, quando essa chave existir localmente
• reutilização da raiz de armazenamento de hash de token existente mais completa para a mesma conta, homeserver e usuário do Matrix quando o token de acesso mudar posteriormente
• varredura de raízes irmãs de armazenamento de hash de token em busca de metadados pendentes de restauração de estado criptografado quando o token de acesso do Matrix mudou, mas a identidade da conta/dispositivo permaneceu a mesma
• restauração de chaves de sala com backup no novo armazenamento de criptografia na próxima inicialização do Matrix

• O OpenClaw grava um arquivo marcador em ~/.openclaw/matrix/migration-snapshot.json após um snapshot bem-sucedido para que passagens posteriores de inicialização e reparo possam reutilizar o mesmo arquivo.
• Esses snapshots automáticos de migração do Matrix fazem backup apenas de configuração + estado (includeWorkspace: false).
• Se o Matrix tiver apenas estado de migração somente com aviso, por exemplo porque userId ou accessToken ainda está ausente, o OpenClaw ainda não cria o snapshot porque nenhuma mutação do Matrix é acionável.
• Se a etapa de snapshot falhar, o OpenClaw ignora a migração do Matrix nessa execução em vez de alterar estado sem um ponto de recuperação.

• o armazenamento plano mais antigo do Matrix (~/.openclaw/matrix/bot-storage.json e ~/.openclaw/matrix/crypto/) veio de um layout de armazenamento único, então o OpenClaw só pode migrá-lo para um destino resolvido de uma conta Matrix
• armazenamentos legados do Matrix já com escopo de conta são detectados e preparados por conta Matrix configurada

​

O que a migração não consegue fazer automaticamente

• chaves de sala somente locais que nunca tiveram backup
• estado criptografado quando a conta Matrix de destino ainda não puder ser resolvida porque homeserver, userId ou accessToken ainda estão indisponíveis
• migração automática de um armazenamento plano compartilhado do Matrix quando várias contas Matrix estão configuradas, mas channels.matrix.defaultAccount não está definido
• instalações com caminho de plugin personalizado que estão fixadas em um caminho de repositório em vez do pacote padrão do Matrix
• uma chave de recuperação ausente quando o armazenamento antigo tinha chaves com backup, mas não manteve a chave de descriptografia localmente

• instalações com caminho de plugin Matrix personalizado são exibidas tanto pela inicialização do Gateway quanto pelo openclaw doctor

​

Fluxo de atualização recomendado

1. Atualize o OpenClaw e o plugin Matrix normalmente. Prefira openclaw update simples, sem --no-restart, para que a inicialização possa concluir a migração do Matrix imediatamente.
2. Execute:
   openclaw doctor --fix
   
   Se o Matrix tiver trabalho de migração acionável, o doctor criará ou reutilizará primeiro o snapshot pré-migração e imprimirá o caminho do arquivo.
3. Inicie ou reinicie o Gateway.
4. Verifique o estado atual de verificação e backup:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Coloque a chave de recuperação da conta 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-stdin
   printf '%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-stdin
   printf '%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 a partir de outro cliente Matrix:
   openclaw matrix verify self
   
   Aceite a solicitação em outro cliente Matrix, compare os emojis ou decimais, e digite yes apenas quando corresponderem. O comando só termina com sucesso depois que Cross-signing verified se tornar yes.
8. Se você está abandonando intencionalmente o histórico antigo irrecuperável e quer uma nova linha de base de backup para mensagens futuras, execute:
   openclaw matrix verify backup reset --yes
   
9. Se ainda não existir backup de chaves no servidor, crie um para recuperações futuras:
   openclaw matrix verify bootstrap
   

​

Como a migração criptografada funciona

1. A inicialização ou openclaw doctor --fix cria ou reutiliza o snapshot pré-migração se a migração criptografada for acionável.
2. A inicialização ou openclaw doctor --fix inspeciona o armazenamento antigo de criptografia do Matrix por meio da instalação ativa do plugin Matrix.
3. Se uma chave de descriptografia de backup for encontrada, o OpenClaw a grava no novo fluxo de chave de recuperação e marca a restauração de chaves de sala como pendente.
4. Na próxima inicialização do Matrix, o OpenClaw restaura automaticamente as chaves de sala com backup no novo armazenamento de criptografia.

​

Mensagens comuns e o que elas significam

​

Mensagens de atualização e detecção

• Significado: o estado antigo do Matrix em disco foi detectado e migrado para o layout atual.
• O que fazer: nada, a menos que a mesma saída também inclua avisos.

• Significado: o OpenClaw criou um arquivo de recuperação antes de alterar o estado do Matrix.
• O que fazer: mantenha o caminho do arquivo impresso até confirmar que a migração foi concluída com sucesso.

• Significado: o OpenClaw encontrou um marcador de snapshot de migração do Matrix existente e reutilizou esse arquivo em vez de criar um backup duplicado.
• O que fazer: mantenha o caminho do arquivo impresso até confirmar que a migração foi concluída com sucesso.

• Significado: existe estado antigo do Matrix, mas o OpenClaw não consegue mapeá-lo para uma conta Matrix atual porque o Matrix não está configurado.
• O que fazer: configure channels.matrix e depois execute novamente openclaw doctor --fix ou reinicie o Gateway.

• Significado: o OpenClaw encontrou estado antigo, mas ainda não consegue determinar a raiz exata da conta/dispositivo atual.
• O que fazer: inicie o Gateway uma vez com um login Matrix funcional, ou execute novamente openclaw doctor --fix depois que credenciais em cache existirem.

• Significado: o OpenClaw encontrou um armazenamento plano compartilhado do Matrix, mas se recusa a adivinhar qual conta Matrix nomeada deve recebê-lo.
• O que fazer: defina channels.matrix.defaultAccount para a conta pretendida e depois execute novamente openclaw doctor --fix ou reinicie o Gateway.

• Significado: o novo local com escopo de conta já tem um armazenamento de sincronização ou criptografia, então o OpenClaw não o sobrescreveu automaticamente.
• O que fazer: verifique se a conta atual é a correta antes de remover ou mover manualmente o destino conflitante.

• Significado: o OpenClaw tentou mover o estado antigo do Matrix, mas a operação no sistema de arquivos falhou.
• O que fazer: inspecione as permissões do sistema de arquivos e o estado do disco, depois execute novamente openclaw doctor --fix.

• Significado: o OpenClaw encontrou um armazenamento antigo criptografado do Matrix, mas não há configuração atual do Matrix à qual anexá-lo.
• O que fazer: configure channels.matrix e depois execute novamente openclaw doctor --fix ou reinicie o Gateway.

• Significado: o armazenamento criptografado existe, mas o OpenClaw não consegue decidir com segurança a qual conta/dispositivo atual ele pertence.
• O que fazer: inicie o Gateway uma vez com um login Matrix funcional, ou execute novamente openclaw doctor --fix depois que credenciais em cache estiverem disponíveis.

• Significado: o OpenClaw encontrou um armazenamento legado plano compartilhado de criptografia, mas se recusa a adivinhar qual conta Matrix nomeada deve recebê-lo.
• O que fazer: defina channels.matrix.defaultAccount para a conta pretendida e depois execute novamente openclaw doctor --fix ou reinicie o Gateway.

• Significado: o OpenClaw detectou estado antigo do Matrix, mas a migração ainda está bloqueada por dados de identidade ou credenciais ausentes.
• O que fazer: conclua o login ou a configuração do Matrix e depois execute novamente openclaw doctor --fix ou reinicie o Gateway.

• Significado: o OpenClaw encontrou um estado Matrix criptografado antigo, mas não conseguiu carregar o ponto de entrada auxiliar do plugin Matrix que normalmente inspeciona esse armazenamento.
• O que fazer: reinstale ou repare o plugin Matrix (openclaw plugins install @openclaw/matrix, ou openclaw plugins install ./path/to/local/matrix-plugin para um checkout do repositório), depois execute novamente openclaw doctor --fix ou reinicie o gateway.
• Se o npm relatar o pacote Matrix pertencente ao OpenClaw como obsoleto, use o plugin incluído em uma build empacotada atual do OpenClaw ou o caminho do checkout local até que um pacote npm mais novo seja publicado.

• Significado: o OpenClaw encontrou um caminho de arquivo auxiliar que escapa da raiz do plugin ou falha nas verificações de limite do plugin, então recusou importá-lo.
• O que fazer: reinstale o plugin Matrix a partir de um caminho confiável, depois execute novamente openclaw doctor --fix ou reinicie o gateway.

• Significado: o OpenClaw recusou modificar o estado Matrix porque não conseguiu criar primeiro o snapshot de recuperação.
• O que fazer: resolva o erro de backup, depois execute novamente openclaw doctor --fix ou reinicie o gateway.

• Significado: o fallback do lado do cliente Matrix encontrou armazenamento plano antigo, mas a movimentação falhou. O OpenClaw agora aborta esse fallback em vez de iniciar silenciosamente com um armazenamento novo.
• O que fazer: inspecione permissões ou conflitos no sistema de arquivos, mantenha o estado antigo intacto e tente novamente depois de corrigir o erro.

• Significado: o Matrix está fixado a uma instalação por caminho, então atualizações da linha principal não o substituem automaticamente pelo pacote Matrix padrão do repositório.
• O que fazer: reinstale com openclaw plugins install @openclaw/matrix quando quiser voltar ao plugin Matrix padrão.
• Se o npm relatar o pacote Matrix pertencente ao OpenClaw como obsoleto, use o plugin incluído em uma build empacotada atual do OpenClaw até que um pacote npm mais novo seja publicado.

​

Mensagens de recuperação de estado criptografado

• Significado: chaves de sala salvas em backup foram restauradas com sucesso no novo armazenamento criptográfico.
• O que fazer: geralmente nada.

• Significado: algumas chaves de sala antigas existiam apenas no armazenamento local antigo e nunca tinham sido enviadas ao backup do Matrix.
• O que fazer: espere que parte do histórico criptografado antigo permaneça indisponível, a menos que você consiga recuperar essas chaves manualmente de outro cliente verificado.

• Significado: existe backup, mas o OpenClaw não conseguiu recuperar automaticamente a chave de recuperação.
• O que fazer: execute printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Significado: o OpenClaw encontrou o armazenamento criptografado antigo, mas não conseguiu inspecioná-lo com segurança suficiente para preparar a recuperação.
• O que fazer: execute novamente openclaw doctor --fix. Se o problema se repetir, mantenha intacto o diretório de estado antigo e recupere usando outro cliente Matrix verificado mais printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Significado: o OpenClaw detectou um conflito de chave de backup e recusou sobrescrever automaticamente o arquivo recovery-key atual.
• O que fazer: verifique qual chave de recuperação está correta antes de tentar novamente qualquer comando de restauração.

• Significado: este é o limite rígido do formato de armazenamento antigo.
• O que fazer: as chaves em backup ainda podem ser restauradas, mas o histórico criptografado somente local pode permanecer indisponível.

• Significado: o novo plugin tentou restaurar, mas o Matrix retornou um erro.
• O que fazer: execute openclaw matrix verify backup status, depois tente novamente com printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin se necessário.

​

Mensagens de recuperação manual

• Significado: o OpenClaw sabe que você deveria ter uma chave de backup, mas ela não está ativa neste dispositivo.
• O que fazer: execute openclaw matrix verify backup restore, ou defina MATRIX_RECOVERY_KEY e execute printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin se necessário.

• Significado: este dispositivo atualmente não tem a chave de recuperação armazenada.
• O que fazer: defina MATRIX_RECOVERY_KEY, execute printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin, depois restaure o backup.

• Significado: a chave armazenada não corresponde ao backup Matrix ativo.
• O que fazer: defina MATRIX_RECOVERY_KEY como a chave correta e execute printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Significado: o backup existe, mas este dispositivo ainda não confia na cadeia de assinatura cruzada de forma suficientemente forte.
• O que fazer: defina MATRIX_RECOVERY_KEY e execute printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Significado: você tentou uma etapa de recuperação sem fornecer uma chave de recuperação quando uma 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.

• Significado: a chave fornecida não pôde ser analisada ou não correspondia ao formato esperado.
• O que fazer: tente novamente com a chave de recuperação exata do seu cliente Matrix ou do arquivo recovery-key.

• Significado: o OpenClaw conseguiu aplicar a chave de recuperação, mas o Matrix ainda não estabeleceu confiança completa de identidade por assinatura cruzada para este dispositivo. Verifique a saída do comando para 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 quando corresponder. O comando aguarda a confiança completa de identidade Matrix antes de informar sucesso. Use printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing somente quando você intencionalmente quiser substituir a identidade de assinatura cruzada atual.

• Significado: o armazenamento secreto não produziu uma sessão de backup ativa neste dispositivo.
• O que fazer: verifique o dispositivo primeiro, depois confira novamente com openclaw matrix verify backup status.

• Significado: este dispositivo não consegue restaurar a partir do armazenamento secreto até que a verificação do dispositivo seja concluída.
• O que fazer: execute primeiro printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

​

Mensagens de instalação de plugin personalizado

• Significado: o registro de instalação do seu 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.
• Se o npm relatar o pacote Matrix pertencente ao OpenClaw como obsoleto, use o plugin incluído em uma build empacotada atual do OpenClaw ou o caminho do checkout local até que um pacote npm mais novo seja publicado.

​

Se o histórico criptografado ainda não voltar

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

​

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

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

​

Relacionado

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