Migração do Matrix

Atualize do matrix plugin público anterior para a implementação atual.

Para a maioria dos usuários, a atualização é feita no local:

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

Você não precisa renomear chaves de configuração nem reinstalar o plugin com um novo nome.

O que a migração faz automaticamente

Quando o gateway inicia, e quando você executa OmeniaClaw doctor --fix, o OmeniaClaw tenta reparar automaticamente o estado antigo do Matrix. Antes que qualquer etapa acionável de migração do Matrix altere o estado no disco, o OmeniaClaw cria ou reutiliza um snapshot de recuperação focado.

Quando você usa OmeniaClaw update, o gatilho exato depende de como o OmeniaClaw está instalado:

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

A migração automática cobre:

• criar ou reutilizar um snapshot pré-migração em ~/Backups/OmeniaClaw-migrations/
• reutilizar suas credenciais do Matrix em cache
• manter a mesma seleção de conta e a configuração channels.matrix
• mover o armazenamento de sincronização plano mais antigo do Matrix para o local atual com escopo de conta
• mover o armazenamento criptográfico plano mais antigo do Matrix para o local atual com escopo de conta quando a conta de destino puder ser resolvida com segurança
• extrair uma chave de descriptografia de backup de chaves de sala do Matrix salva anteriormente a partir do armazenamento criptográfico rust antigo, quando essa chave existir localmente
• reutilizar a raiz de armazenamento de hash de token mais completa existente para a mesma conta, homeserver e usuário do Matrix quando o token de acesso mudar depois
• verificar 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
• restaurar chaves de sala em backup no novo armazenamento criptográfico na próxima inicialização do Matrix

Detalhes do snapshot:

• O OmeniaClaw grava um arquivo marcador em ~/.OmeniaClaw/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 de aviso, por exemplo porque userId ou accessToken ainda está ausente, o OmeniaClaw ainda não cria o snapshot porque nenhuma mutação do Matrix é acionável.
• Se a etapa de snapshot falhar, o OmeniaClaw ignora a migração do Matrix nessa execução em vez de alterar o estado sem um ponto de recuperação.

Sobre atualizações com várias contas:

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

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

O plugin público anterior do Matrix não criava backups de chaves de sala do Matrix automaticamente. Ele persistia o estado criptográfico local e solicitava verificação de dispositivo, mas não garantia que suas chaves de sala fossem copiadas para o homeserver.

Isso significa que algumas instalações criptografadas só podem ser migradas parcialmente.

O OmeniaClaw não consegue recuperar automaticamente:

• chaves de sala apenas locais que nunca foram copiadas
• estado criptografado quando a conta de destino do Matrix 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 plano compartilhado do Matrix quando várias contas do Matrix estão configuradas, mas channels.matrix.defaultAccount não está definido
• instalações com caminho personalizado de plugin 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 em backup, mas não manteve a chave de descriptografia localmente

Escopo atual de avisos:

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

Se sua instalação antiga tinha histórico criptografado apenas local que nunca foi copiado, algumas mensagens criptografadas mais antigas podem permanecer ilegíveis após a atualização.

Fluxo de atualização recomendado

1. Atualize o OmeniaClaw e o plugin do Matrix normalmente. Prefira OmeniaClaw update simples, sem --no-restart, para que a inicialização possa concluir a migração do Matrix imediatamente.

2. Execute:

   OmeniaClaw 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:

   OmeniaClaw matrix verify statusOmeniaClaw 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 OmeniaClaw informar que uma chave de recuperação é necessária, execute o comando para a conta correspondente:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | OmeniaClaw 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" | OmeniaClaw matrix verify device --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | OmeniaClaw matrix verify device --recovery-key-stdin --account assistant

   Se a chave de recuperação for aceita e o backup estiver utilizável, mas Cross-signing verified ainda for no, conclua a autoverificação a partir de outro cliente Matrix:

   OmeniaClaw matrix verify self

   Aceite a solicitação em outro cliente Matrix, compare os emojis ou decimais e digite yes somente quando eles coincidirem. O comando sai com sucesso somente depois que Cross-signing verified se torna yes.

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

   OmeniaClaw matrix verify backup reset --yes

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

   OmeniaClaw matrix verify bootstrap

Como a migração criptografada funciona

A migração criptografada é um processo em duas etapas:

1. A inicialização ou OmeniaClaw doctor --fix cria ou reutiliza o snapshot pré-migração se a migração criptografada for acionável.
2. A inicialização ou OmeniaClaw doctor --fix inspeciona o armazenamento criptográfico antigo do Matrix por meio da instalação ativa do plugin do Matrix.
3. Se uma chave de descriptografia de backup for encontrada, o OmeniaClaw 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 OmeniaClaw restaura automaticamente as chaves de sala em backup no novo armazenamento criptográfico.

Se o armazenamento antigo relatar chaves de sala que nunca foram copiadas, o OmeniaClaw avisa em vez de fingir que a recuperação teve sucesso.

Mensagens comuns e o que elas significam

Mensagens de atualização e detecção

Matrix plugin upgraded in place.

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

Matrix migration snapshot created before applying Matrix upgrades.

• Significado: o OmeniaClaw criou um arquivo de recuperação antes de alterar o estado do Matrix.
• O que fazer: guarde o caminho do arquivo impresso até confirmar que a migração teve sucesso.

Matrix migration snapshot reused before applying Matrix upgrades.

• Significado: o OmeniaClaw 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: guarde o caminho do arquivo impresso até confirmar que a migração teve sucesso.

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

• Significado: existe estado antigo do Matrix, mas o OmeniaClaw não consegue mapeá-lo para uma conta atual do Matrix porque o Matrix não está configurado.
• O que fazer: configure channels.matrix e então execute novamente OmeniaClaw doctor --fix ou reinicie o 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: o OmeniaClaw 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 funcional do Matrix ou execute novamente OmeniaClaw doctor --fix depois que existirem credenciais em cache.

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

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

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

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

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

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

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

• Significado: o OmeniaClaw encontrou um armazenamento antigo criptografado do Matrix, mas não há configuração atual do Matrix para associá-lo.
• O que fazer: configure channels.matrix e então execute novamente OmeniaClaw doctor --fix ou reinicie o 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: o armazenamento criptografado existe, mas o OmeniaClaw 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 funcional do Matrix ou execute novamente OmeniaClaw doctor --fix depois que as credenciais em cache estiverem disponíveis.

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

• Significado: o OmeniaClaw encontrou um armazenamento criptográfico legado plano compartilhado, mas se recusa a adivinhar qual conta nomeada do Matrix deve recebê-lo.
• O que fazer: defina channels.matrix.defaultAccount para a conta pretendida e então execute novamente OmeniaClaw doctor --fix ou reinicie o gateway.

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

• Significado: o OmeniaClaw 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 então execute novamente OmeniaClaw doctor --fix ou reinicie o gateway.

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

• Significado: o OmeniaClaw encontrou estado antigo criptografado do Matrix, mas não conseguiu carregar o ponto de entrada auxiliar do plugin do Matrix que normalmente inspeciona esse armazenamento.
• O que fazer: reinstale ou repare o plugin do Matrix (OmeniaClaw plugins install @OmeniaClaw/matrix, ou OmeniaClaw plugins install ./path/to/local/matrix-plugin para um checkout de repositório) e então execute novamente OmeniaClaw doctor --fix ou reinicie o gateway.

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

• Significado: o OmeniaClaw 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 e, em seguida, execute novamente OmeniaClaw doctor --fix ou reinicie o Gateway.

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

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

• Significado: o OmeniaClaw recusou alterar o estado do Matrix porque não conseguiu criar primeiro o snapshot de recuperação.
• O que fazer: resolva o erro de backup e, em seguida, execute novamente OmeniaClaw doctor --fix ou reinicie o Gateway.

Failed migrating legacy Matrix client storage: ...

• Significado: o fallback do lado do cliente Matrix encontrou armazenamento plano antigo, mas a movimentação falhou. O OmeniaClaw 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.

Matrix is installed from a custom path: ...

• Significado: o Matrix está fixado em uma instalação por caminho, então as atualizações principais não o substituem automaticamente pelo pacote Matrix padrão do repo.
• O que fazer: reinstale com OmeniaClaw plugins install @OmeniaClaw/matrix quando quiser voltar ao Plugin Matrix padrão.

Mensagens de recuperação de estado criptografado

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

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

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

• Significado: algumas chaves de sala antigas existiam apenas no armazenamento local antigo e nunca tinham sido enviadas para o 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.

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

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

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

• Significado: o OmeniaClaw 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 OmeniaClaw doctor --fix. Se o problema se repetir, mantenha o diretório de estado antigo intacto e recupere usando outro cliente Matrix verificado mais printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify backup restore --recovery-key-stdin.

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

• Significado: o OmeniaClaw detectou um conflito de chave de backup e recusou 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.

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 é 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 apenas local pode permanecer indisponível.

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

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

Mensagens de recuperação manual

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

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

Store a recovery key with 'OmeniaClaw matrix verify device --recovery-key-stdin', then run 'OmeniaClaw matrix verify backup restore'.

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

Backup key mismatch on this device. Re-run 'OmeniaClaw matrix verify device --recovery-key-stdin' with the matching recovery key.

• 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" | OmeniaClaw matrix verify device --recovery-key-stdin.

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

Backup trust chain is not verified on this device. Re-run 'OmeniaClaw matrix verify device --recovery-key-stdin'.

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

Matrix recovery key is required

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

Invalid Matrix recovery key: ...

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

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

• Significado: o OmeniaClaw conseguiu aplicar a chave de recuperação, mas o Matrix ainda não estabeleceu confiança total 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 OmeniaClaw matrix verify self, aceite a solicitação em outro cliente Matrix, compare o SAS e digite yes somente quando ele corresponder. O comando aguarda a confiança total de identidade do Matrix antes de relatar sucesso. Use printf '%s\n' "$MATRIX_RECOVERY_KEY" | OmeniaClaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing somente quando você quiser intencionalmente substituir a identidade de assinatura cruzada atual.

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

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

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'OmeniaClaw matrix verify device --recovery-key-stdin' first.

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

Mensagens de instalação de Plugin personalizado

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

• Significado: o registro de instalação do seu Plugin aponta para um caminho local que não existe mais.
• O que fazer: reinstale com OmeniaClaw plugins install @OmeniaClaw/matrix ou, se estiver executando a partir de um checkout do repo, OmeniaClaw plugins install ./path/to/local/matrix-plugin.

Se o histórico criptografado ainda não voltar

Execute estas verificações em ordem:

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

Se o backup for restaurado com sucesso, mas algumas salas antigas ainda estiverem sem histórico, essas chaves ausentes provavelmente 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 em ordem:

OmeniaClaw matrix verify backup reset --yesOmeniaClaw matrix verify backup status --verboseOmeniaClaw matrix verify status

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

Relacionado

• Matrix: configuração e config do canal.
• Regras de 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.