openclaw update

Atualize o OpenClaw e alterne entre os canais stable/extended-stable/beta/dev.

Se a instalação foi feita via npm/pnpm/bun (instalação global, sem metadados do git), as atualizações seguem o fluxo do gerenciador de pacotes descrito em Atualização.

Uso

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update é reescrito como openclaw update (útil para shells e scripts de inicialização).

Opções

Não há uma opção --verbose. Use --dry-run para visualizar as ações planejadas, --json para resultados legíveis por máquina e openclaw update status --json somente para canal/disponibilidade. O nível de detalhamento do console do Gateway (--verbose) e o nível de log em arquivo (logging.level: "debug"/"trace") são controles independentes; consulte Logs do Gateway.

update status

Mostra o canal de atualização ativo, a tag/branch/SHA do git (somente em checkouts do código-fonte) e a disponibilidade de atualizações.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Para instalações por pacote extended-stable, o status realiza a mesma seleção pública e verificação exata do pacote que a atualização em primeiro plano. Ele pode informar ahead of extended-stable quando a versão instalada é mais recente. As falhas em JSON incluem registry.reason (selector_missing, selector_query_failed, exact_package_mismatch ou unsupported_git_channel).

update repair

Executa novamente a finalização da atualização após o pacote principal já ter sido alterado, mas o trabalho de reparo posterior não ter sido concluído corretamente. Esse é o caminho de recuperação compatível quando openclaw update instalou o novo pacote principal, mas a sincronização de plugins posterior à atualização do núcleo, os metadados de plugins npm gerenciados, a atualização do registro ou o reparo do Doctor não convergiram.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair executa openclaw doctor --fix, recarrega a configuração reparada e os registros de instalação, sincroniza os plugins rastreados para o canal de atualização ativo, atualiza as instalações de plugins npm gerenciados, repara os conteúdos ausentes de plugins configurados, atualiza o registro de plugins e grava metadados convergentes nos registros de instalação. Ele não instala um novo pacote principal nem reinicia o Gateway.

update wizard

Fluxo interativo para escolher um canal de atualização e confirmar se o Gateway deve ser reiniciado depois (o padrão é reiniciar). Selecionar dev sem um checkout do git oferece a opção de criar um.

O que ele faz

Alternar explicitamente os canais (--channel ...) também mantém o método de instalação alinhado:

• dev -> garante um checkout do git (o padrão é ~/openclaw, ou $OPENCLAW_HOME/openclaw quando OPENCLAW_HOME está definido; substitua com OPENCLAW_GIT_DIR), atualiza-o e instala a CLI global a partir desse checkout.
• stable -> instala a partir do npm usando latest.
• extended-stable -> resolve o seletor público extended-stable do npm, verifica o pacote exato selecionado e instala essa versão exata. Ele não recorre a outro seletor como fallback e é rejeitado para checkouts do Git.
• beta -> prioriza a dist-tag beta do npm, recorrendo a latest quando a versão beta está ausente ou é anterior à versão stable atual.

Transferência da reinicialização

O atualizador automático do núcleo do Gateway (quando habilitado pela configuração) inicia o caminho de atualização da CLI fora do manipulador de solicitações ativo do Gateway. As atualizações pelo gerenciador de pacotes do plano de controle update.run e as atualizações supervisionadas de checkouts do git usam a mesma transferência para o serviço gerenciado, em vez de substituir a árvore de pacotes ou recompilar dist/ dentro do processo ativo do Gateway: o Gateway inicia um auxiliar desanexado e encerra, e esse auxiliar executa openclaw update --yes --json fora da árvore de processos do Gateway. Se a transferência não estiver disponível, update.run retorna uma resposta estruturada com o comando seguro do shell que deve ser executado manualmente.

As seleções de estabilidade estendida armazenadas recebem dicas de inicialização somente leitura e de atualização a cada 24 horas quando update.checkOnStart está habilitado. Essas verificações nunca aplicam uma atualização, iniciam uma transferência, reiniciam o Gateway, usam atraso/jitter do canal estável nem usam a cadência de sondagem beta. Atualizações explícitas em primeiro plano, atualizações simples em primeiro plano com update.channel: "extended-stable" armazenado, status sob demanda e a transferência do Gateway gerenciado correspondente continuam sendo compatíveis.

Quando um serviço local de Gateway gerenciado está instalado e a reinicialização está habilitada, as atualizações pelo gerenciador de pacotes e por checkout do git interrompem o serviço em execução antes de substituir a árvore do pacote ou modificar a saída do checkout/build. Em seguida, o atualizador renova os metadados do serviço, reinicia o serviço e verifica o Gateway reiniciado antes de informar Gateway: restarted and verified.. As atualizações pelo gerenciador de pacotes também verificam se o Gateway reiniciado informa a versão esperada do pacote; as atualizações por checkout do git verificam a integridade do gateway e a prontidão do serviço após a recompilação.

As atualizações pelo gerenciador de pacotes normalmente continuam usando o binário do Node registrado no serviço gerenciado. Se esse Node não puder executar a versão de destino, mas o Node atual da CLI puder e for comprovado que o serviço pertence ao pacote que está sendo atualizado, uma atualização com reinicialização habilitada usa o Node atual para a finalização e reescreve os metadados do serviço para esse runtime. --no-restart não pode reparar os metadados do serviço, portanto a mesma incompatibilidade de runtime interrompe o processo antes da modificação do pacote.

No macOS, a verificação pós-atualização também confirma se o LaunchAgent está carregado/em execução para o perfil ativo e se a porta de loopback configurada está íntegra. Se o plist estiver instalado, mas o launchd não o estiver supervisionando, o OpenClaw reinicializa o bootstrap do LaunchAgent automaticamente e executa novamente as verificações de integridade/versão/ prontidão do canal (um novo bootstrap carrega diretamente o trabalho RunAtLoad, portanto a recuperação não kickstart -k imediatamente o Gateway recém-iniciado). Se o Gateway ainda não ficar íntegro, o comando será encerrado com código diferente de zero e exibirá o caminho do log de reinicialização, além de instruções de reinicialização, reinstalação e reversão do pacote.

Se não for possível executar a reinicialização, o comando exibirá Gateway: restart skipped (...) ou Gateway: restart failed: ... com uma dica manual de openclaw gateway restart. Com --no-restart, a substituição do pacote ou a recompilação do git ainda é executada, mas o serviço gerenciado não é interrompido nem reiniciado; portanto, o Gateway em execução mantém o código antigo até ser reiniciado manualmente.

Formato da resposta do plano de controle

Quando update.run é executado pelo plano de controle do Gateway em uma instalação por gerenciador de pacotes ou um checkout do git supervisionado, o manipulador informa o início da transferência separadamente da atualização da CLI que continua após o encerramento do Gateway:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" e handoff.status: "started": o Gateway criou a transferência do serviço gerenciado e agendou a própria reinicialização para que o auxiliar desanexado possa executar openclaw update --yes --json fora do processo ativo do serviço.
• ok: false, result.reason: "managed-service-handoff-unavailable" e handoff.status: "unavailable": o OpenClaw não conseguiu encontrar um limite de serviço supervisor e uma identidade durável de serviço para uma transferência segura (por exemplo, a transferência do systemd exige a identidade da unidade OPENCLAW_SYSTEMD_UNIT, não apenas marcadores de processo do systemd presentes no ambiente). A resposta inclui handoff.command, o comando de shell a ser executado fora do Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": o Gateway tentou criar a transferência, mas não conseguiu iniciar o auxiliar desanexado.

O payload sentinel é gravado antes do encerramento do Gateway, e a transferência da CLI atualiza esse mesmo sentinela de reinicialização depois que as verificações de integridade da reinicialização do serviço gerenciado são concluídas. Durante a transferência, o sentinela pode conter stats.reason: "restart-health-pending" sem continuação de sucesso; o Gateway reiniciado o consulta periodicamente e aciona a continuação somente depois que a CLI verifica a integridade do serviço e reescreve o sentinela com o resultado final ok. openclaw status e openclaw status --all mostram uma linha Update restart enquanto esse sentinela está pendente ou apresenta falha, e update.status atualiza e retorna o sentinela mais recente.

Fluxo de checkout do Git

Seleção de canal

• stable: faz checkout da tag não beta mais recente e, em seguida, executa o build e o doctor.
• beta: dá preferência à tag -beta mais recente, recorrendo à tag estável mais recente quando a beta estiver ausente ou for mais antiga.
• dev: faz checkout de main e, em seguida, busca e executa o rebase.
• extended-stable: incompatível com checkouts do Git; nenhuma modificação do checkout ocorre.

Etapas da atualização

Detalhes da sincronização de plugins

No canal beta, as instalações rastreadas de plugins do npm e do ClawHub que seguem a linha padrão/mais recente tentam primeiro uma versão @beta do plugin. Se o plugin não tiver uma versão beta, o OpenClaw recorrerá à especificação padrão/mais recente registrada e informará um aviso. Para plugins do npm, o OpenClaw também recorrerá à alternativa quando o pacote beta existir, mas falhar na validação da instalação. Esses avisos de alternativa não causam falha na atualização do núcleo. Versões exatas e tags explícitas nunca são reescritas.

Após uma atualização bem-sucedida do núcleo de estabilidade estendida, a integridade e a convergência pós-núcleo dos plugins têm como alvo os plugins npm oficiais qualificados na versão exata instalada do núcleo. Para a intenção padrão/latest, o OpenClaw não consulta o @extended-stable do plugin nem recorre ao latest do npm; ele deriva a versão do pacote a partir do núcleo instalado. Fixações de versão explícitas, tags explícitas diferentes de latest, pacotes de terceiros e fontes que não sejam npm mantêm a intenção existente.

Para instalações por gerenciador de pacotes, openclaw update resolve a versão de destino do pacote antes de invocar o gerenciador de pacotes. As instalações globais do npm usam uma instalação em estágio: o OpenClaw instala o novo pacote em um prefixo temporário do npm, permite que o pacote candidato valide a versão do Node do host durante preinstall e verifica ali o inventário empacotado dist. Uma proteção de conclusão empacotada permanece fora desse inventário até preinstall ser concluído com sucesso; assim, os gerenciadores de pacotes que ignoram scripts de ciclo de vida também são interrompidos antes da ativação. No npm 12 e posteriores, o atualizador aprova somente o ciclo de vida do OpenClaw candidato; os scripts de dependências transitivas permanecem bloqueados. Em seguida, o OpenClaw troca a árvore de pacotes limpa pelo prefixo global real. Se a verificação falhar, o doctor pós-atualização, a sincronização de plugins e o trabalho de reinicialização não serão executados a partir da árvore suspeita. Mesmo quando a versão instalada já corresponde à versão de destino, o comando renova a instalação global do pacote e depois executa a sincronização de plugins, uma renovação da conclusão dos comandos do núcleo e o trabalho de reinicialização. Isso mantém os componentes auxiliares empacotados e os registros de plugins pertencentes ao canal alinhados ao build instalado do OpenClaw, enquanto deixa as recompilações completas da conclusão dos comandos de plugins para execuções explícitas de openclaw completion --write-state.

Relacionado

• openclaw doctor (oferece executar a atualização primeiro em checkouts do git)
• Canais de desenvolvimento
• Atualização
• Referência da CLI