--- title: "Como Atualizar o OpenClaw sem Perder Configuração ou Sessões" url: "https://openclaw.ia.br/blog/como-atualizar-openclaw-sem-perder-configuracao/" markdown_url: "https://openclaw.ia.br/blog/como-atualizar-openclaw-sem-perder-configuracao.MD" description: "Aprenda a atualizar o OpenClaw com backup, verificação de versão, reinício do gateway, testes de WhatsApp e Telegram, rollback e solução de erros." date: "2026-07-26" author: "OpenClaw Brasil" --- # Como Atualizar o OpenClaw sem Perder Configuração ou Sessões Aprenda a atualizar o OpenClaw com backup, verificação de versão, reinício do gateway, testes de WhatsApp e Telegram, rollback e solução de erros. 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 | Etapa | Comando ou ação | Resultado esperado | |---|---|---| | 1. Diagnóstico | `openclaw gateway status` e `openclaw doctor` | Ambiente atual conhecido | | 2. Registrar versão | `openclaw --version` | Número salvo para eventual rollback | | 3. Fazer backup | Copiar workspace, configuração e estado dos canais | Ponto de recuperação fora da pasta original | | 4. Atualizar | `npm install -g openclaw@latest` | Pacote global atualizado | | 5. Reiniciar | `openclaw gateway restart` | Gateway usando a versão nova | | 6. Validar | `openclaw --version`, `openclaw doctor` e teste pelo canal | Atualização funcional, não apenas instalada | | 7. Observar | Revisar logs e tarefas agendadas | Problemas detectados antes de afetar a rotina | Se o OpenClaw está em um servidor de produção, faça isso em uma janela de manutenção. Se está em [Proxmox](/blog/instalar-openclaw-proxmox-lxc-vm/), 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: ```bash npm install -g openclaw@latest openclaw onboard --install-daemon ``` Confirme de onde vem o executável: ```bash 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](/tutoriais/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: ```bash 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](/guias/backup/) 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: ```bash 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: ```bash 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](/blog/agendamento-tarefas-openclaw-cron-guia/) 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: ```bash npm install -g openclaw@latest ``` Depois confira imediatamente: ```bash 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 ```bash 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 ```bash 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](/tutoriais/configurar-memoria/) ajuda a distinguir falha do modelo de falha no armazenamento. Para ações externas, mantenha o padrão de [human-in-the-loop](/blog/human-in-the-loop-ia-aprovacao-agentes-openclaw/): 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: ```bash wsl --list --verbose ``` Depois, no Ubuntu ou Debian usado pelo OpenClaw: ```bash 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](/instalacao/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](/instalacao/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](/blog/deploy-openclaw-vps-servidor-guia/) ou o guia de [OpenClaw no Proxmox](/blog/instalar-openclaw-proxmox-lxc-vm/). ## 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: ```bash 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`: ```bash 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: ```bash 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](/blog/openclaw-nao-responde-guia-diagnostico/) 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](/tutoriais/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 é: ```bash npm install -g openclaw@X.Y.Z 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.