Mainstream messaging

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 @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 que a migração faz automaticamente

Quando o gateway inicia, e quando você executa openclaw doctor --fix, o OpenClaw 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 OpenClaw cria ou reutiliza um snapshot de recuperação focado.

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

instalações a partir do código-fonte executam openclaw 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 openclaw update --no-restart, a migração do Matrix apoiada pela inicialização será adiada até que você execute openclaw doctor --fix mais tarde e reinicie o gateway

A migração automática cobre:

criar ou reutilizar um snapshot pré-migração em ~/Backups/openclaw-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 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 de 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 o estado sem um ponto de recuperação.

Sobre atualizações com várias contas:

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 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 OpenClaw 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 openclaw 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

Atualize o OpenClaw e o plugin do Matrix normalmente. Prefira openclaw update simples, sem --no-restart, para que a inicialização possa concluir a migração do Matrix imediatamente.
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.
Inicie ou reinicie o gateway.

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

openclaw matrix verify status
openclaw matrix verify backup status

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.

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

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 estiver utilizável, 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 somente quando eles coincidirem. O comando sai com sucesso somente depois que Cross-signing verified se torna yes.
Se você estiver abandonando intencionalmente histórico antigo irrecuperável e quiser uma nova linha de base de backup para mensagens futuras, execute:
```
openclaw matrix verify backup reset --yes
```
Se ainda não existir nenhum backup de chaves no lado do servidor, crie um para recuperações futuras:
```
openclaw matrix verify bootstrap
```

Como a migração criptografada funciona

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

A inicialização ou openclaw doctor --fix cria ou reutiliza o snapshot pré-migração se a migração criptografada for acionável.
A inicialização ou openclaw doctor --fix inspeciona o armazenamento criptográfico antigo do Matrix por meio da instalação ativa do plugin do Matrix.
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.
Na próxima inicialização do Matrix, o OpenClaw 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 OpenClaw 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 OpenClaw 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 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: 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 OpenClaw 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 openclaw 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 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 funcional do Matrix ou execute novamente openclaw 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 OpenClaw 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 openclaw 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 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.

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

Significado: o OpenClaw 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 openclaw doctor --fix.

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

Significado: o OpenClaw 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 openclaw 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 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 funcional do Matrix ou execute novamente openclaw 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 OpenClaw 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 openclaw 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 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 então execute novamente openclaw doctor --fix ou reinicie o gateway.

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

Significado: o OpenClaw 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 (openclaw plugins install @openclaw/matrix, ou openclaw plugins install ./path/to/local/matrix-plugin para um checkout de repositório) e então execute novamente openclaw doctor --fix ou reinicie o gateway.

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

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 e, em seguida, execute novamente openclaw 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 "openclaw doctor --fix".

Significado: o OpenClaw 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 openclaw 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 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.

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 openclaw plugins install @openclaw/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 "openclaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.

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

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

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 o diretório de estado antigo intacto e recupere usando outro cliente Matrix verificado mais printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw 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 OpenClaw 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 openclaw matrix verify backup status e, se necessário, tente novamente com printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

Mensagens de recuperação manual

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

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.

Store a recovery key with 'openclaw matrix verify device --recovery-key-stdin', then run 'openclaw 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" | openclaw matrix verify device --recovery-key-stdin e, em seguida, restaure o backup.

Backup key mismatch on this device. Re-run 'openclaw 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" | openclaw 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 openclaw 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 'openclaw 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" | openclaw 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" | openclaw 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 OpenClaw 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 openclaw 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" | openclaw 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 openclaw matrix verify backup status.

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw 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" | openclaw 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 openclaw plugins install @openclaw/matrix ou, se estiver executando a partir de um checkout do repo, openclaw plugins install ./path/to/local/matrix-plugin.

Se o histórico criptografado ainda não voltar

Execute estas verificações em ordem:

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

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw 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.

# O que a migração faz automaticamente

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

# Fluxo de atualização recomendado

# Como a migração criptografada funciona

# Mensagens comuns e o que elas significam

# Mensagens de atualização e detecção

# Mensagens de recuperação de estado criptografado

# Mensagens de recuperação manual

# Mensagens de instalação de Plugin personalizado

# Se o histórico criptografado ainda não voltar

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

# Relacionado