​

Migração do Matrix

• 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 via gerenciador de pacotes atualizam o pacote, executam uma passagem não interativa do doctor e depois dependem da reinicialização padrão do gateway para que a inicialização possa concluir a migração do Matrix
• se você usar openclaw update --no-restart, a migração do Matrix baseada na inicialização será adiada até que você execute openclaw doctor --fix e reinicie o gateway depois

• criar ou reutilizar um snapshot pré-migração em ~/Backups/openclaw-migrations/
• reutilizar suas credenciais Matrix em cache
• manter a mesma seleção de conta e a configuração channels.matrix
• mover o armazenamento de sincronização Matrix plano mais antigo para o local atual delimitado por conta
• mover o armazenamento de criptografia Matrix plano mais antigo para o local atual delimitado por conta quando a conta de destino puder ser resolvida com segurança
• extrair uma chave de descriptografia de backup de chave de sala Matrix salva anteriormente do antigo armazenamento rust crypto, quando essa chave existir localmente
• reutilizar a raiz de armazenamento com hash de token mais completa existente para a mesma conta Matrix, homeserver e usuário quando o token de acesso mudar depois
• examinar raízes irmãs de armazenamento com 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
• restaurar chaves de sala em 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 futuras passagens 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 com aviso, por exemplo porque userId ou accessToken ainda estão ausentes, o OpenClaw ainda não cria o snapshot porque nenhuma mutação Matrix é acionável.
• Se a etapa de snapshot falhar, o OpenClaw pula a migração do Matrix nessa execução em vez de alterar o estado sem um ponto de recuperação.

• o armazenamento Matrix plano mais antigo (~/.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 de conta Matrix resolvido
• armazenamentos Matrix legados já delimitados por conta são detectados e preparados por conta Matrix configurada

​

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

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

• instalações do plugin Matrix em caminho personalizado são exibidas tanto pela inicialização do gateway quanto por openclaw doctor

​

Fluxo de atualização recomendado

1. Atualize o OpenClaw e o plugin Matrix normalmente. Prefira openclaw update 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. Se o OpenClaw informar que uma chave de recuperação é necessária, execute:
   openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
   
6. Se este dispositivo ainda não estiver verificado, execute:
   openclaw matrix verify device "<your-recovery-key>"
   
7. Se você estiver intencionalmente abandonando histórico antigo irrecuperável e quiser uma nova linha de base de backup para mensagens futuras, execute:
   openclaw matrix verify backup reset --yes
   
8. Se ainda não existir backup de chave 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 Matrix pela 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 da chave de sala como pendente.
4. Na próxima inicialização do Matrix, o OpenClaw restaura automaticamente as chaves de sala em backup para o novo armazenamento de criptografia.

​

Mensagens comuns e o que significam

​

Mensagens de atualização e detecção

• Significado: o estado Matrix antigo 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 Matrix.
• O que fazer: mantenha o caminho do arquivo impresso até confirmar que a migração foi bem-sucedida.

• Significado: o OpenClaw encontrou um marcador de snapshot de migração 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 bem-sucedida.

• Significado: existe estado Matrix antigo, 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, 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 existirem credenciais em cache.

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

• Significado: o local delimitado por 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 em conflito.

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

• Significado: o OpenClaw encontrou um armazenamento Matrix criptografado antigo, mas não há configuração Matrix atual à qual anexá-lo.
• O que fazer: configure channels.matrix, 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 de criptografia compartilhado plano, mas se recusa a adivinhar qual conta Matrix nomeada deve recebê-lo.
• O que fazer: defina channels.matrix.defaultAccount como a conta pretendida e depois execute novamente openclaw doctor --fix ou reinicie o gateway.

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

• Significado: o OpenClaw encontrou 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 de repositório), depois execute novamente openclaw doctor --fix ou reinicie o gateway.

• 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 se recusou a 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 se recusou a alterar o estado Matrix porque não conseguiu criar primeiro o snapshot de recuperação.
• O que fazer: resolva o erro de backup e 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 interrompe esse fallback em vez de iniciar silenciosamente com um armazenamento novo.
• O que fazer: inspecione permissões ou conflitos do sistema de arquivos, mantenha o estado antigo intacto e tente novamente após corrigir o erro.

• Significado: o Matrix está fixado em 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.

​

Mensagens de recuperação de estado criptografado

• Significado: chaves de sala em backup foram restauradas com sucesso para o novo armazenamento de criptografia.
• O que fazer: normalmente nada.

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

• Significado: o backup existe, mas o OpenClaw não conseguiu recuperar a chave de recuperação automaticamente.
• O que fazer: execute openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".

• 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 se repetir, mantenha o diretório de estado antigo intacto e recupere usando outro cliente Matrix verificado mais openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".

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

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

• Significado: o novo plugin tentou restaurar, mas o Matrix retornou um erro.
• O que fazer: execute openclaw matrix verify backup status e depois tente novamente com openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" 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 passe --recovery-key se necessário.

• Significado: este dispositivo atualmente não tem a chave de recuperação armazenada.
• O que fazer: verifique o dispositivo com sua chave de recuperação primeiro e depois restaure o backup.

• Significado: a chave armazenada não corresponde ao backup Matrix ativo.
• O que fazer: execute novamente openclaw matrix verify device "<your-recovery-key>" com a chave correta.

• Significado: o backup existe, mas este dispositivo ainda não confia com força suficiente na cadeia de assinatura cruzada.
• O que fazer: execute novamente openclaw matrix verify device "<your-recovery-key>".

• Significado: você tentou uma etapa de recuperação sem fornecer uma chave de recuperação quando ela era necessária.
• O que fazer: execute o comando novamente com sua chave de recuperação.

• 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: a chave foi aplicada, mas o dispositivo ainda não conseguiu concluir a verificação.
• O que fazer: confirme se você usou a chave correta e se a assinatura cruzada está disponível na conta, depois tente novamente.

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

• Significado: este dispositivo não consegue restaurar a partir do armazenamento de segredo até que a verificação do dispositivo seja concluída.
• O que fazer: execute primeiro openclaw matrix verify device "<your-recovery-key>".

​

Mensagens de instalação de plugin personalizado

• Significado: seu 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 você estiver executando a partir de um checkout de repositório, openclaw plugins install ./path/to/local/matrix-plugin.

​

Se o histórico criptografado ainda não voltar

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --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

​

Páginas relacionadas

• Matrix
• Doctor
• Migração
• Plugins