Recomendado: openclaw update
A maneira mais rápida de atualizar. Ele detecta seu tipo de instalação (npm ou git), busca a versão mais recente, executa openclaw doctor e reinicia o Gateway.
openclaw update não aceita --verbose. Para diagnósticos de atualização, use
--dry-run para pré-visualizar as ações planejadas, --json para resultados estruturados ou
openclaw update status --json para inspecionar o canal e o estado de disponibilidade. O
instalador tem seu próprio sinalizador --verbose, mas esse sinalizador não faz parte de
openclaw update.
--channel beta prefere beta, mas o runtime recorre para stable/latest quando
a tag beta está ausente ou é mais antiga que a versão stable mais recente. Use --tag beta
se quiser o dist-tag beta bruto do npm para uma atualização de pacote pontual.
--channel extended-stable é somente para pacote e somente 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 de registro ausentes ou inconsistentes falham
de forma fechada; ele nunca recorre para latest. Se a versão selecionada for mais antiga que
a versão instalada, a confirmação normal de downgrade ainda se aplica.
Use --channel dev para um checkout persistente e móvel do main do GitHub. Para atualizações
de pacote, --tag main mapeia para github:openclaw/openclaw#main por uma execução, e
especificações de origem GitHub/git são empacotadas em um tarball temporário antes da instalação
npm preparada.
Para plugins gerenciados, o fallback do canal beta é um aviso: a atualização do core ainda pode
ter sucesso enquanto um Plugin usa sua versão default/latest registrada porque nenhum
beta do Plugin está disponível.
Veja Canais de desenvolvimento para a semântica dos canais.
Alternar entre instalações npm e git
Use canais quando quiser 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 a CLI e o Gateway usam.
--dry-run primeiro para pré-visualizar a troca exata de modo de instalação:
dev garante um checkout git, o compila e instala a CLI global
a partir desse checkout. Os canais stable, extended-stable e beta usam
instalações de pacote. Extended-stable é rejeitado em um checkout Git sem
alterá-lo ou convertê-lo. Se o
Gateway já estiver instalado, openclaw update atualiza os metadados do serviço
e o reinicia, a menos que você passe --no-restart.
Para instalações de pacote com um serviço Gateway gerenciado, openclaw update mira
a raiz do pacote usada por esse serviço. Se o comando de shell openclaw vier
de uma instalação diferente, o atualizador imprime ambas as raízes e o caminho do Node
do serviço gerenciado. A atualização do pacote usa o gerenciador de pacotes que possui a raiz
do serviço e verifica o Node do serviço gerenciado em relação ao engine da versão-alvo
antes de substituir o pacote.
Alternativa: executar o instalador novamente
--no-onboard para pular o onboarding. Para forçar um tipo de instalação específico pelo
instalador, passe --install-method git --no-onboard ou
--install-method npm --no-onboard.
Se openclaw update falhar após a fase de instalação do pacote npm, execute o
instalador novamente. O instalador não chama o atualizador antigo; ele executa a instalação
do pacote global diretamente e pode recuperar uma instalação npm parcialmente atualizada.
--version:
Alternativa: npm, pnpm ou bun manual
openclaw update para instalações supervisionadas, porque ele pode coordenar a
troca de pacote com o serviço Gateway em execução. Se você atualizar manualmente em uma
instalação supervisionada, pare o Gateway gerenciado antes que o gerenciador de pacotes comece.
Gerenciadores de pacotes substituem arquivos no local, e um Gateway em execução pode, caso contrário,
tentar carregar arquivos do core ou de plugins enquanto a árvore de pacotes está temporariamente semitrocada.
Reinicie o Gateway depois que o gerenciador de pacotes terminar para que o serviço use
a nova instalação.
Para uma instalação global de sistema Linux pertencente ao root, se openclaw update falhar com
EACCES e você recuperar com o npm do sistema, mantenha o Gateway parado durante a
substituição manual do pacote. Use os mesmos sinalizadores de perfil openclaw ou ambiente
que você normalmente usa para esse Gateway. Substitua /usr/bin/npm pelo npm do sistema
que possui o prefixo global pertencente ao root no seu host:
openclaw update gerencia uma instalação npm global, ele primeiro instala o alvo em
um prefixo npm temporário, verifica o inventário dist empacotado e então troca
a árvore de pacotes limpa para o prefixo global real. Isso evita que o npm sobreponha um
novo pacote a arquivos obsoletos do pacote antigo. Se o comando de instalação falhar,
o OpenClaw tenta novamente uma vez com --omit=optional. Essa nova tentativa ajuda hosts em que dependências
opcionais nativas não conseguem compilar, mantendo a falha original visível
se o fallback também falhar.
Comandos de atualização npm e atualização de Plugin gerenciados pelo OpenClaw também limpam a quarentena
min-release-age do npm para o processo npm filho. O npm pode relatar essa
política como um corte derivado before; ambos são úteis para políticas gerais de quarentena
de cadeia de suprimentos, mas uma atualização explícita do OpenClaw significa “instalar a versão
selecionada do OpenClaw agora.”
Tópicos avançados de instalação npm
Árvore de pacotes somente leitura
Árvore de pacotes somente leitura
O OpenClaw trata instalações globais empacotadas como somente leitura em runtime, mesmo quando o diretório global de pacotes pode ser escrito pelo usuário atual. Instalações de pacotes de Plugin ficam em raízes npm/git pertencentes ao OpenClaw sob o diretório de configuração do usuário, e a inicialização do Gateway não altera a árvore de pacotes do OpenClaw.Algumas configurações npm no Linux instalam pacotes globais em diretórios pertencentes ao root, como
/usr/lib/node_modules/openclaw. O OpenClaw oferece suporte a esse layout porque comandos de instalação/atualização de Plugin escrevem fora desse diretório global de pacotes.Unidades systemd endurecidas
Unidades systemd endurecidas
Dê ao OpenClaw acesso de escrita às suas raízes de configuração/estado para que instalações explícitas de Plugin, atualizações de Plugin e limpeza do doctor possam persistir suas alterações:
Pré-verificação de espaço em disco
Pré-verificação de espaço em disco
Antes de atualizações de pacote e instalações explícitas de Plugin, o OpenClaw tenta uma verificação de espaço em disco de melhor esforço para o volume-alvo. Pouco espaço produz um aviso com o caminho verificado, mas não bloqueia a atualização porque cotas de sistema de arquivos, snapshots e volumes de rede podem mudar após a verificação. A instalação real pelo gerenciador de pacotes e a verificação pós-instalação continuam sendo autoritativas.
Atualizador automático
O atualizador automático fica desativado por padrão. Ative-o em~/.openclaw/openclaw.json:
| Canal | Comportamento |
|---|---|
stable | Aguarda stableDelayHours e então aplica com jitter determinístico ao longo de stableJitterHours (lançamento distribuído). |
extended-stable | Sem verificação na inicialização ou aplicação automática. Use openclaw update ou openclaw update status manualmente. |
beta | Verifica a cada betaCheckIntervalHours (padrão: a cada hora) e aplica imediatamente. |
dev | Sem aplicação automática. Use openclaw update manualmente. |
update.checkOnStart: false).
Seleções extended-stable armazenadas pulam completamente a resolução na inicialização e em segundo plano.
Para downgrade ou recuperação de incidente, defina OPENCLAW_NO_AUTO_UPDATE=1 no ambiente do Gateway para bloquear aplicações automáticas mesmo quando update.auto.enabled estiver configurado. Dicas de atualização na inicialização ainda podem ser executadas, a menos que update.checkOnStart também esteja desativado.
Atualizações de gerenciador de pacotes solicitadas pelo manipulador do plano de controle do Gateway em execução
não substituem a árvore de pacotes dentro do processo Gateway em execução. Em instalações de serviço
gerenciado, o Gateway inicia uma transferência destacada, sai e deixa o
caminho normal da CLI openclaw update --yes --json parar o serviço, substituir o
pacote, atualizar os metadados do serviço, reiniciar, verificar a versão e
alcançabilidade do Gateway, e recuperar um LaunchAgent do macOS instalado mas não carregado quando
possível. Se o Gateway não puder fazer essa transferência com segurança, update.run relata um
comando de shell seguro em vez de executar o gerenciador de pacotes dentro do processo.
Depois de atualizar
Migra a configuração, audita políticas de DM e verifica a saúde do Gateway. Detalhes: Doctor
Rollback
Fixar uma versão (npm)
Fixar um commit (código-fonte)
git checkout main && git pull.
Se você estiver travado
- Execute
openclaw doctornovamente e leia a saída com atenção. - Para
openclaw update --channel devem checkouts de código-fonte, o atualizador inicializa automaticamente opnpmquando necessário. Se você vir um erro de bootstrap do pnpm/corepack, instale opnpmmanualmente (ou reative ocorepack) e execute a atualização novamente. - Confira: Solução de problemas
- Pergunte no Discord: https://discord.gg/clawd
Relacionados
- Visão geral de instalação: todos os métodos de instalação.
- Doctor: verificações de saúde após atualizações.
- Migração: guias de migração de versões principais.