Como Atualizar o OpenClaw sem Perder Configuração ou Sessões

Para atualizar o OpenClaw, primeiro faça backup do workspace, da configuração e do estado dos canais; depois registre a versão atual, execute npm install -g openclaw@latest, reinicie o gateway e rode openclaw doctor. A atualização só está concluída quando você envia uma mensagem real pelo WhatsApp, Telegram ou Discord e confirma que memória, ferramentas e tarefas agendadas continuam funcionando.

A regra mais importante é simples: não transforme npm install no começo e no fim do processo. Uma atualização segura tem quatro fases — backup, instalação, validação e possibilidade de rollback. Isso reduz o risco de perder uma sessão de WhatsApp, descobrir tarde demais que o serviço não reiniciou ou manter uma configuração antiga incompatível com a versão nova.

Resposta rápida: sequência segura de atualização

Se o OpenClaw está em um servidor de produção, faça isso em uma janela de manutenção. Se está em Proxmox, VPS ou máquina virtual, crie também um snapshot ou backup do ambiente antes de trocar a versão. Snapshot ajuda na reversão rápida, mas não substitui uma cópia separada dos dados importantes.

Antes de atualizar: descubra como o OpenClaw foi instalado

O comando de atualização depende da forma de instalação. Este guia cobre principalmente a instalação global pelo npm, usada no fluxo:

npm install -g openclaw@latest
openclaw onboard --install-daemon

Confirme de onde vem o executável:

which openclaw
which node
which npm
npm config get prefix
openclaw --version

No Windows com WSL, rode esses comandos dentro da distribuição Linux em que o OpenClaw foi instalado. No macOS ou Linux, use a mesma conta de usuário que normalmente executa o gateway. Se você instalou com NVM, abrir um terminal como outro usuário ou executar sudo npm install pode atualizar uma cópia diferente daquela usada pelo serviço.

Para Docker, o princípio é o mesmo, mas a operação muda: preserve os volumes, atualize a imagem definida no seu Compose e recrie o container. Consulte o guia do OpenClaw com Docker em vez de misturar comandos npm dentro de um container que deveria ser descartável.

O que precisa entrar no backup

O backup deve preservar o que não pode ser reconstruído apenas instalando o pacote novamente. Isso normalmente inclui:

• workspace e arquivos de contexto;
• configuração do gateway e dos provedores;
• memória persistente;
• skills próprias;
• tarefas agendadas;
• estado de autenticação dos canais;
• arquivos locais usados por automações;
• lista das integrações habilitadas.

Os caminhos exatos podem variar conforme a versão, o sistema e a configuração escolhida. Por isso, não copie cegamente um diretório de um tutorial antigo. Identifique o workspace usado pela sua instalação e confira os arquivos que foram criados durante o onboarding.

Uma forma simples de criar uma cópia preservando permissões é usar rsync para outro diretório ou disco:

mkdir -p ~/backups/openclaw-antes-update
rsync -a --delete ~/SEU-WORKSPACE/ ~/backups/openclaw-antes-update/workspace/

Substitua ~/SEU-WORKSPACE/ pelo caminho real. Não publique o backup no Git e não envie o arquivo para um serviço sem criptografia se ele contiver tokens, sessões ou dados pessoais. O guia de backup do OpenClaw explica como separar dados essenciais de caches regeneráveis e, principalmente, como testar a restauração.

Também registre informações operacionais em um arquivo de texto sem segredos:

openclaw --version > ~/backups/openclaw-antes-update/versao.txt
node --version >> ~/backups/openclaw-antes-update/versao.txt
npm --version >> ~/backups/openclaw-antes-update/versao.txt
openclaw gateway status >> ~/backups/openclaw-antes-update/status.txt

Esse recibo evita o clássico “funcionava antes, mas não lembro qual versão estava instalada”.

Passo a passo para atualizar pelo npm

1. Verifique se o ambiente já está saudável

Antes de trocar a versão, execute:

openclaw gateway status
openclaw doctor

Se o WhatsApp já está desconectado, uma skill já falha ou o gateway já reinicia sozinho, resolva ou registre o problema antes da atualização. Caso contrário, você pode atribuir à versão nova uma falha que já existia.

Faça ainda um teste simples pelo canal principal. Peça ao agente para responder uma frase curta, consultar uma informação segura da memória e executar uma ferramenta de leitura de baixo risco. Guarde esse roteiro; ele será repetido depois.

2. Pare automações sensíveis

Uma atualização rápida pode coincidir com uma tarefa de cron, envio de mensagem ou alteração em sistema externo. Se você tem automações que publicam, apagam, cobram, criam tickets ou enviam e-mail, pause-as durante a manutenção.

Rotinas apenas de leitura oferecem risco menor, mas ainda podem falhar no meio da reinicialização. Consulte o guia de agendamento com cron para revisar quais tarefas existem e quais precisam ser testadas depois.

3. Instale a versão mais recente

Na mesma conta que executa o OpenClaw:

npm install -g openclaw@latest

Depois confira imediatamente:

openclaw --version

Se a versão não mudou, verifique se existem instalações duplicadas do Node.js ou do pacote global. O resultado de which openclaw e npm config get prefix costuma mostrar quando o terminal usa um caminho e o serviço usa outro.

4. Reinicie o gateway

openclaw gateway restart
openclaw gateway status

Aguarde o processo estabilizar. Um status “ativo” significa apenas que o processo iniciou; ainda não prova que o modelo, os canais e as ferramentas estão funcionando.

5. Rode o diagnóstico pós-atualização

openclaw doctor

Leia os avisos, em vez de apenas procurar uma linha verde no final. Uma versão nova pode exigir ajuste de configuração, dependência mais recente ou nova autenticação de uma integração. Não apague arquivos para “limpar” o erro antes de entender o que será perdido.

Checklist de validação depois da atualização

Faça testes em camadas. Comece pelo componente mais básico e avance até as automações reais.

Camada 1: processo e modelo

• openclaw --version mostra a versão esperada;
• o gateway permanece ativo por alguns minutos;
• uma pergunta simples recebe resposta;
• o provedor de IA não retorna erro de autenticação ou limite;
• os logs não repetem a mesma exceção continuamente.

Camada 2: canais

Envie uma mensagem por cada canal usado de verdade:

• WhatsApp responde e mantém a sessão após reiniciar;
• Telegram aceita mensagem apenas dos usuários ou grupos permitidos;
• Discord continua nos canais autorizados e com os intents corretos;
• anexos, áudio ou imagens funcionam, se fazem parte da rotina.

Se o WhatsApp perdeu autenticação, não pareie novamente de imediato. Primeiro confirme se o serviço está usando a mesma conta e o mesmo diretório de estado de antes. Criar uma sessão nova pode esconder um problema de caminho ou permissão.

Camada 3: memória e ferramentas

Peça ao agente para recuperar uma informação de teste que já existia antes da atualização. Depois execute ferramentas somente de leitura, como consultar agenda ou listar um diretório permitido. Só então teste uma ação de escrita com baixo impacto e aprovação humana.

A página de configuração de memória ajuda a distinguir falha do modelo de falha no armazenamento. Para ações externas, mantenha o padrão de human-in-the-loop: o agente prepara, uma pessoa aprova e o sistema registra o resultado.

Camada 4: tarefas agendadas

Não espere até o dia seguinte para descobrir que o briefing das 7h não roda mais. Quando possível, crie uma execução temporária para alguns minutos à frente ou execute manualmente o mesmo fluxo. Confirme horário, fuso, destino e permissões.

Como atualizar em Windows, macOS, Linux e servidor

Windows com WSL2

Abra a distribuição Linux correta e atualize dentro dela:

wsl --list --verbose

Depois, no Ubuntu ou Debian usado pelo OpenClaw:

node --version
npm install -g openclaw@latest
openclaw gateway restart
openclaw doctor

Se o serviço não iniciar após reiniciar o Windows, revise o mecanismo usado para subir o WSL e o gateway. O guia de instalação no Windows cobre a configuração completa.

macOS

Se Node.js veio do NVM, atualize na conta habitual. Se veio do Homebrew, confirme que o node encontrado pelo terminal é o mesmo usado no momento da instalação. Depois rode a sequência npm, restart e doctor. Veja também a instalação no macOS.

Linux, VPS, LXC ou VM

Use a conta sem privilégios responsável pelo serviço. Em servidor, mantenha uma segunda sessão SSH aberta durante a manutenção e evite atualizar simultaneamente sistema operacional, Node.js e OpenClaw. Mudar uma camada por vez facilita descobrir a causa de qualquer falha.

Para uma instalação sempre ligada, consulte o guia de deploy em VPS ou o guia de OpenClaw no Proxmox.

Erros comuns ao atualizar o OpenClaw

EACCES: permission denied

Esse erro indica que a conta atual não pode escrever no diretório global do npm. Não resolva automaticamente com sudo, pois isso pode criar uma segunda instalação ou arquivos pertencentes ao root.

Verifique:

npm config get prefix
ls -ld "$(npm config get prefix)"
which node
which npm

Se você usava NVM, carregue o ambiente correto ou abra uma nova sessão do mesmo usuário. Corrija a instalação do Node/npm antes de repetir o update.

A versão continua antiga

Provavelmente há mais de um executável no PATH:

which -a openclaw
npm list -g --depth=0 | grep openclaw

Compare o caminho retornado com o ambiente do serviço. Reiniciar o terminal também pode ser necessário quando o gerenciador de versões alterou links ou variáveis.

Gateway não volta depois do restart

Rode o diagnóstico e revise os logs sem expor tokens:

openclaw gateway status
openclaw doctor

Confira versão do Node.js, permissões do workspace, sintaxe da configuração e disponibilidade da porta. O guia de OpenClaw que não responde organiza a investigação por camadas.

WhatsApp desconectou

Primeiro confirme que o diretório de estado ainda existe, pertence ao usuário correto e está sendo lido pela instalação nova. Só refaça o pareamento quando tiver certeza de que a sessão anterior não pode ser recuperada. Em Docker, confirme a montagem do volume; em VM ou LXC, confirme que o disco persistente não foi trocado.

Uma skill parou de funcionar

Atualização do núcleo e atualização de skills são mudanças diferentes. Verifique se a skill usa API, pacote ou formato de configuração alterado. Teste-a isoladamente e não atualize todas as dependências ao mesmo tempo. Para extensões próprias, mantenha controle de versão e um caso de teste mínimo. Veja o guia para criar skills.

Como fazer rollback para a versão anterior

Rollback é a volta controlada para a versão que você registrou antes. Se a versão antiga era, por exemplo, X.Y.Z, o padrão de instalação é:

npm install -g [email protected]
openclaw gateway restart
openclaw --version
openclaw doctor

Substitua X.Y.Z pelo número real anotado. Não copie uma versão fictícia de um tutorial. Depois restaure configuração ou dados somente se eles tiverem sido alterados e se a restauração for compatível com a versão anterior.

Em VM ou Proxmox, reverter snapshot pode ser mais rápido, mas cuidado: tudo que mudou depois do snapshot também volta no tempo. Mensagens, memória e arquivos novos podem desaparecer. Por isso, o melhor plano combina snapshot do ambiente com backup separado dos dados.

Faça rollback quando houver falha operacional clara que você não consegue corrigir dentro da janela de manutenção. Não faça rollback apenas porque um aviso novo apareceu; primeiro entenda se ele representa risco real ou uma checagem mais rigorosa da versão atual.

Política recomendada para manter o OpenClaw atualizado

Para uso pessoal, uma revisão semanal ou quinzenal costuma ser mais segura do que instalar toda versão no minuto em que aparece. Para uma empresa, use três etapas:

1. leia as notas da versão e identifique mudanças em canais, configuração e ferramentas;
2. teste em ambiente separado ou em uma cópia da VM quando o agente executa tarefas importantes;
3. promova para produção com backup, janela curta e checklist de validação.

Evite adiar indefinidamente. Versões novas podem corrigir segurança, compatibilidade e estabilidade. O objetivo não é “nunca mudar”; é tornar a mudança observável e reversível.

Perguntas frequentes

Qual é o comando para atualizar o OpenClaw?

Em uma instalação global pelo npm, o comando é npm install -g openclaw@latest. Depois, reinicie com openclaw gateway restart, confira openclaw --version e execute openclaw doctor. Instalações Docker devem atualizar a imagem e preservar os volumes, não instalar o pacote manualmente dentro do container.

Atualizar o OpenClaw apaga minha configuração?

A atualização do pacote não deveria apagar o workspace ou a configuração persistente, mas erros de usuário, caminho, volume ou migração podem fazer a instalação parecer vazia. Faça backup antes e confirme que a versão nova usa os mesmos diretórios e a mesma conta de serviço.

Preciso desconectar WhatsApp e Telegram antes de atualizar?

Normalmente não. Você deve, porém, preservar o estado dos canais e evitar apagar diretórios de sessão. Depois do restart, teste os dois canais. Se uma sessão desaparecer, investigue caminho e permissão antes de autenticar novamente.

Posso atualizar sem parar o gateway?

O pacote pode ser instalado enquanto o processo antigo ainda está ativo, mas o gateway precisa ser reiniciado para carregar a versão nova. Em produção, pause tarefas sensíveis e trate o restart como uma pequena janela de manutenção.

Como saber qual versão estava instalada antes?

Execute openclaw --version antes da atualização e salve o resultado com data. Registre também versões de Node.js e npm. Sem esse número, um rollback preciso fica mais difícil.

O que fazer se o OpenClaw não funcionar depois do update?

Confirme a versão, rode openclaw doctor, verifique o status e compare usuário, PATH, configuração e diretórios com o ambiente anterior. Se a correção não couber na janela de manutenção, reinstale a versão registrada e valide os canais. Restaure dados apenas quando necessário.

É melhor atualizar automaticamente?

Atualização automática sem teste pode ser aceitável em um laboratório descartável, mas não é recomendada quando o agente envia mensagens, acessa dados ou executa ações externas. Para produção, prefira notificação de nova versão, backup automático e atualização deliberada com validação.

Checklist final

Antes de encerrar a manutenção, confirme:

• backup criado em destino separado;
• versão anterior registrada;
• versão nova confirmada pelo executável correto;
• gateway reiniciado e estável;
• openclaw doctor revisado;
• WhatsApp, Telegram ou Discord testados;
• memória e uma ferramenta de leitura testadas;
• tarefa agendada validada;
• logs sem erro repetitivo;
• caminho de rollback conhecido.

Atualizar o OpenClaw com segurança não exige uma operação complexa. Exige disciplina: saber o que estava funcionando, preservar os dados, mudar uma camada por vez e provar que o agente continua útil depois do restart. Com esse processo, você pode receber correções e recursos novos sem transformar cada openclaw update em uma aposta sobre suas sessões e automações.