--- read_when: - Atualizando o OpenClaw - Algo para de funcionar após uma atualização summary: Atualização segura do OpenClaw (instalação global ou código-fonte), além da estratégia de reversão title: Atualização x-i18n: generated_at: "2026-07-12T00:03:32Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 06b475fcd715afa5f4b9fa3fc7d546ba8dc53805c6a29e12fd4706dceb04cb60 source_path: install/updating.md workflow: 16 --- Mantenha o OpenClaw atualizado. Para substituições de imagens do Docker, Podman e Kubernetes, consulte [Atualização de imagens de contêiner](/pt-BR/install/docker#upgrading-container-images). O Gateway executa tarefas de atualização seguras para a inicialização antes de ficar pronto e encerra se o estado montado precisar de reparo manual. ## Recomendado: `openclaw update` Detecta o tipo de instalação (npm ou git), obtém a versão mais recente, executa `openclaw doctor` e reinicia o Gateway. ```bash openclaw update ``` Alterne entre canais ou selecione uma versão específica: ```bash openclaw update --channel beta openclaw update --channel extended-stable openclaw update --channel dev openclaw update --dry-run # preview without applying ``` `openclaw update` não tem a opção `--verbose` (o instalador tem). Para diagnóstico, use `--dry-run` para visualizar as ações planejadas, `--json` para obter resultados estruturados ou `openclaw update status --json` para inspecionar o canal e o estado de disponibilidade. `--channel beta` prioriza a dist-tag beta do npm, mas recorre a stable/latest quando a tag beta está ausente ou sua versão é anterior à versão estável mais recente. Em vez disso, use `--tag beta` para uma atualização pontual do pacote fixada na dist-tag beta bruta do npm. `--channel extended-stable` funciona somente com pacotes, e a instalação permanece exclusivamente em primeiro plano. O OpenClaw lê o seletor público `extended-stable` do npm, verifica o pacote exato selecionado e instala essa versão exata. Dados ausentes ou inconsistentes do registro provocam uma falha segura; nunca há fallback para `latest`. Se a versão selecionada for anterior à versão instalada, a confirmação normal de downgrade ainda será aplicada. A CLI mantém o canal após uma atualização bem-sucedida do núcleo; uma execução direta de `npm install -g openclaw@extended-stable` não atualiza `update.channel`. Após a substituição do núcleo, os plugins npm oficiais elegíveis com intenção vazia/padrão ou `latest` convergem para essa versão exata do núcleo. Fixações exatas e tags explícitas diferentes de `latest`, plugins de terceiros e fontes que não sejam npm permanecem inalterados. As instalações pelo catálogo criadas pelas versões atuais do OpenClaw mantêm essa intenção padrão. Registros antigos que contêm apenas uma versão exata permanecem fixados porque o OpenClaw não consegue distinguir com segurança uma fixação automática antiga de uma fixação feita pelo usuário; execute `openclaw plugins update @openclaw/name` uma vez no canal extended-stable para reativar o acompanhamento da versão exata do núcleo para esse plugin. `--channel dev` fornece um checkout persistente e móvel do `main` no GitHub. Para uma atualização pontual de pacote, `--tag main` é mapeado para a especificação de pacote `github:openclaw/openclaw#main` e o instala diretamente por meio do gerenciador de pacotes de destino (npm/pnpm/bun). Para plugins gerenciados, a ausência de uma versão beta gera um aviso, não uma falha: a atualização do núcleo ainda pode ser concluída enquanto um plugin recorre à sua versão padrão/latest registrada. Consulte [Canais de lançamento](/pt-BR/install/development-channels) para conhecer a semântica dos canais. ## Alternar entre instalações npm e git Use canais para alterar o tipo de instalação. O atualizador mantém seu estado, configuração, credenciais e workspace em `~/.openclaw`; ele altera apenas qual instalação do código do OpenClaw é usada pela CLI e pelo Gateway. ```bash # npm package install -> editable git checkout openclaw update --channel dev # git checkout -> npm package install openclaw update --channel stable ``` Primeiro, visualize a alteração do modo de instalação: ```bash openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` `dev` garante um checkout git, faz sua compilação e instala a CLI global a partir desse checkout. Os canais `stable`, `extended-stable` e `beta` usam instalações de pacotes. O extended-stable é rejeitado em um checkout git sem modificá-lo nem convertê-lo. Se o Gateway já estiver instalado, `openclaw update` atualiza os metadados do serviço e o reinicia, a menos que você use `--no-restart`. Para instalações de pacote com um serviço Gateway gerenciado, `openclaw update` utiliza a raiz do pacote usada por esse serviço. Se o comando `openclaw` do shell vier de outra instalação, o atualizador exibirá as duas raízes e o caminho do Node do serviço gerenciado e verificará essa versão do Node em relação ao requisito `engines.node` da versão de destino antes de substituir o pacote. ## Alternativa: executar novamente o instalador ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` Adicione `--no-onboard` para ignorar a integração inicial. Para forçar um tipo de instalação específico, use `--install-method git --no-onboard` ou `--install-method npm --no-onboard`. Se `openclaw update` falhar após a etapa de instalação do pacote npm, execute novamente o instalador. Ele não chama o atualizador; executa diretamente a instalação global do pacote e pode recuperar uma instalação npm parcialmente atualizada. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm ``` Fixe a recuperação em uma versão ou dist-tag específica com `--version`: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version ``` ## Alternativa: npm, pnpm ou bun manualmente ```bash npm i -g openclaw@latest ``` Prefira `openclaw update` para instalações supervisionadas: ele pode coordenar a substituição do pacote com o serviço Gateway em execução. Se você atualizar manualmente uma instalação supervisionada, interrompa primeiro o Gateway gerenciado. Os gerenciadores de pacotes substituem os arquivos no próprio local, e um Gateway em execução poderia tentar carregar arquivos do núcleo ou de plugins durante a substituição. Reinicie o Gateway após a conclusão do gerenciador de pacotes para que ele use a nova instalação. Para uma instalação global de sistema no Linux pertencente ao usuário root, se `openclaw update` falhar com `EACCES`, faça a recuperação com o npm do sistema, mantendo o Gateway parado durante a substituição manual. Use as mesmas opções de perfil e variáveis de ambiente que você normalmente usa para esse Gateway. Substitua `/usr/bin/npm` pelo npm do sistema que controla o prefixo global pertencente ao usuário root em seu host: ```bash openclaw gateway stop sudo /usr/bin/npm i -g openclaw@latest openclaw gateway install --force openclaw gateway restart ``` Em seguida, verifique: ```bash openclaw --version curl -fsS http://127.0.0.1:18789/readyz openclaw plugins list --json openclaw gateway status --deep --json openclaw doctor --lint --json ``` Quando `openclaw update` gerencia uma instalação npm global, ele primeiro instala o destino em um prefixo npm temporário, verifica o inventário `dist` do pacote e depois substitui a árvore limpa do pacote no prefixo global real — evitando que o npm sobreponha um pacote novo a arquivos obsoletos do pacote anterior. Se o comando de instalação falhar, o OpenClaw tentará novamente uma vez com `--omit=optional`, o que ajuda em hosts nos quais dependências opcionais nativas não podem ser compiladas. Os comandos de atualização do npm e de atualização de plugins gerenciados pelo OpenClaw também removem a quarentena de cadeia de suprimentos `min-release-age` do npm (ou a chave de configuração mais antiga `before`) para o processo npm filho. Essa política existe para proteção geral, mas uma atualização explícita do OpenClaw significa “instalar agora a versão selecionada”. ```bash pnpm add -g openclaw@latest ``` ```bash bun add -g openclaw@latest ``` ### Tópicos avançados de instalação com npm O OpenClaw trata instalações globais empacotadas como somente leitura durante a execução, mesmo quando o diretório global de pacotes permite gravação pelo usuário atual. As instalações de pacotes de plugins ficam em raízes npm/git pertencentes ao OpenClaw no diretório de configuração do usuário, e a inicialização do Gateway não modifica a árvore de pacotes do OpenClaw. Algumas configurações npm no Linux instalam pacotes globais em diretórios pertencentes ao usuário root, como `/usr/lib/node_modules/openclaw`. O OpenClaw oferece suporte a esse layout porque os comandos de instalação e atualização de plugins gravam fora desse diretório global de pacotes. Conceda ao OpenClaw acesso de gravação às raízes de configuração/estado para que instalações explícitas de plugins, atualizações de plugins e limpezas realizadas pelo doctor possam manter suas alterações: ```ini ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp ``` Antes de atualizações de pacotes e instalações explícitas de plugins, o OpenClaw tenta realizar uma verificação de melhor esforço do espaço em disco no volume de destino. Pouco espaço gera um aviso com o caminho verificado, mas não bloqueia a atualização, pois cotas do sistema de arquivos, snapshots e volumes de rede podem mudar após a verificação. A instalação efetiva pelo gerenciador de pacotes e a verificação pós-instalação continuam sendo a referência definitiva. ## Atualizador automático Desativado por padrão. Ative-o em `~/.openclaw/openclaw.json`: ```json5 { update: { channel: "stable", auto: { enabled: true, stableDelayHours: 6, stableJitterHours: 12, betaCheckIntervalHours: 1, }, }, } ``` | Canal | Comportamento | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stable` | Aguarda `stableDelayHours` (padrão: 6) e depois aplica com variação determinística ao longo de `stableJitterHours` (padrão: 12) para uma implantação distribuída. | | `extended-stable` | Verifica uma indicação de atualização somente leitura na inicialização e a cada 24 horas quando `checkOnStart` está ativado. Nunca aplica a atualização automaticamente. | | `beta` | Verifica a cada `betaCheckIntervalHours` (padrão: 1) e aplica imediatamente. | | `dev` | Não aplica automaticamente. Use `openclaw update` manualmente. | O Gateway também registra uma indicação de atualização na inicialização (desative com `update.checkOnStart: false`). As seleções extended-stable armazenadas usam esse caminho de indicação somente leitura e o intervalo de indicação existente de 24 horas, mas nunca iniciam instalação automática, transferência de controle, reinicialização, atraso/variação do stable nem sondagem do beta. Para downgrade ou recuperação de incidentes, defina `OPENCLAW_NO_AUTO_UPDATE=1` no ambiente do Gateway para bloquear aplicações automáticas, mesmo quando `update.auto.enabled` estiver configurado. As indicações de atualização na inicialização ainda podem ser executadas, a menos que `update.checkOnStart` também esteja desativado. As atualizações do gerenciador de pacotes solicitadas pelo plano de controle ativo do Gateway (`update.run`) não substituem a árvore de pacotes dentro do processo do Gateway em execução. Em instalações com serviço gerenciado, o Gateway inicia uma transferência de controle desacoplada, encerra e permite que o fluxo normal da CLI `openclaw update --yes --json` interrompa o serviço, substitua o pacote, atualize os metadados do serviço, reinicie, verifique a versão e a acessibilidade do Gateway e recupere, quando possível, um LaunchAgent do macOS instalado, mas não carregado. Se o Gateway não puder realizar essa transferência de controle com segurança, `update.run` informará um comando de shell seguro em vez de executar o gerenciador de pacotes dentro do processo. O cartão de atualização na barra lateral da interface de controle inicia esse mesmo fluxo `update.run`. No aplicativo assinado para macOS, o cartão primeiro atualiza o aplicativo pelo Sparkle; após a reabertura, o aplicativo ajusta seu Gateway local gerenciado para a versão correspondente. ## Após a atualização ### Executar o doctor ```bash openclaw doctor ``` Migra a configuração, audita políticas de mensagens diretas e verifica a integridade do Gateway. Detalhes: [Doctor](/pt-BR/gateway/doctor) ### Reiniciar o Gateway ```bash openclaw gateway restart ``` ### Verificar ```bash openclaw health ``` ## Reversão ### Fixar uma versão (npm) ```bash npm i -g openclaw@ openclaw doctor openclaw gateway restart ``` `npm view openclaw version` mostra a versão publicada atualmente. ### Fixar um commit (código-fonte) ```bash git fetch origin git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)" pnpm install && pnpm build openclaw gateway restart ``` Para retornar à versão mais recente: `git checkout main && git pull`. ## Se você estiver com dificuldades - Execute `openclaw doctor` novamente e leia a saída com atenção. - Para `openclaw update --channel dev` em checkouts do código-fonte, o atualizador inicializa automaticamente o `pnpm` quando necessário. Se você encontrar um erro de inicialização do pnpm/corepack, instale o `pnpm` manualmente (ou reative o `corepack`) e execute novamente a atualização. - Consulte: [Solução de problemas](/pt-BR/gateway/troubleshooting) - Peça ajuda no Discord: [https://discord.gg/clawd](https://discord.gg/clawd) ## Relacionados - [Visão geral da instalação](/pt-BR/install): todos os métodos de instalação. - [Doctor](/pt-BR/gateway/doctor): verificações de integridade após atualizações. - [Migração](/pt-BR/install/migrating): guias de migração entre versões principais.