openclaw update

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

Se você instalou 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á um sinalizador --verbose. Use --dry-run para visualizar as ações planejadas, --json para obter 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 do 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 de pacotes extended-stable, o status executa o mesmo seletor público e a mesma verificação exata de pacote que a atualização em primeiro plano. Ele pode informar ahead of extended-stable quando a versão instalada é mais recente. Falhas no 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 depois que o pacote principal já foi alterado, mas o trabalho de reparo posterior não foi 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, 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 payloads ausentes de plugins configurados, atualiza o registro de plugins e grava metadados convergentes dos registros de instalação. Ele não instala um novo pacote principal nem reinicializa o Gateway.

update wizard

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

O que ele faz

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

• dev -> garante um checkout do git (padrão: ~/openclaw, ou $OPENCLAW_HOME/openclaw quando OPENCLAW_HOME estiver 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. Não usa outro seletor como fallback e é rejeitado para checkouts do Git.
• beta -> dá preferência à dist-tag beta do npm, usando latest como fallback quando beta está ausente ou é mais antigo que a versão estável 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 do gerenciador de pacotes update.run do plano de controle 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 desacoplado 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 de shell seguro que deve ser executado manualmente.

As seleções extended-stable 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 stable nem usam a cadência de sondagem do canal 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 do 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 de pacotes ou modificar a saída do checkout/build. Em seguida, o atualizador atualiza os metadados do serviço, reinicia o serviço e verifica o Gateway reiniciado antes de informar Gateway: restarted and verified.. Além disso, as atualizações pelo gerenciador de pacotes 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.

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á funcionando corretamente. Se o plist estiver instalado, mas o launchd não estiver supervisionando-o, o OpenClaw reinicializa automaticamente o bootstrap do LaunchAgent e executa novamente as verificações de integridade/versão/ prontidão do canal (um bootstrap novo carrega diretamente o trabalho RunAtLoad, portanto a recuperação não executa imediatamente kickstart -k no 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 para reiniciar, reinstalar e reverter o pacote.

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

Formato da resposta do plano de controle

Quando update.run é executado pelo plano de controle do Gateway em uma instalação pelo gerenciador de pacotes ou em um checkout supervisionado do Git, 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 sua própria reinicialização para que o auxiliar desacoplado possa executar openclaw update --yes --json fora do processo do serviço ativo.
• 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 de serviço persistente para uma transferência segura (por exemplo, a transferência do systemd exige a identidade de unidade OPENCLAW_SYSTEMD_UNIT, não apenas marcadores de processo do systemd presentes no ambiente). A resposta inclui handoff.command, o comando de shell que deve 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 desacoplado.

O payload sentinel é gravado antes de o Gateway ser encerrado, e a transferência da CLI atualiza essa mesma 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, a sentinela pode conter stats.reason: "restart-health-pending" sem continuação de sucesso; o Gateway reiniciado consulta a sentinela e dispara a continuação somente depois que a CLI verifica a integridade do serviço e regrava a sentinela com o resultado ok final. openclaw status e openclaw status --all exibem uma linha Update restart enquanto essa sentinela está pendente ou apresenta falha, e update.status atualiza e retorna a sentinela mais recente.

Fluxo de checkout do Git

Seleção do 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 stable mais recente quando a beta não existe ou é mais antiga.
• dev: faz checkout de main e, em seguida, executa fetch e rebase.
• extended-stable: incompatível com checkouts do Git; nenhuma modificação no 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/latest 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/latest registrada e informará um aviso. Para plugins do npm, o OpenClaw também recorre à alternativa quando o pacote beta existe, mas falha na validação da instalação. Esses avisos de uso de alternativa não causam falha na atualização do núcleo. Versões exatas e tags explícitas nunca são regravadas.

Depois que uma atualização do núcleo extended-stable é concluída com sucesso, a integridade e a convergência de plugins pós-núcleo têm como destino os plugins npm oficiais elegíveis na versão exata instalada do núcleo. Para a intenção padrão/latest, o OpenClaw não consulta @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 explícitas de versão, tags explícitas diferentes de latest, pacotes de terceiros e fontes que não sejam npm mantêm sua intenção existente.

Para instalações pelo 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 preparada: o OpenClaw instala o novo pacote em um prefixo temporário do npm, verifica ali o inventário de dist empacotado e, em seguida, troca essa árvore de pacotes limpa para o prefixo global real. Se a verificação falhar, o doctor pós-atualização, a sincronização de plugins e a reinicialização não serão executados a partir da árvore suspeita. Mesmo quando a versão instalada já corresponde ao destino, o comando atualiza a instalação global do pacote e, em seguida, executa a sincronização de plugins, uma atualização das conclusões de comandos do núcleo e a reinicialização. Isso mantém os componentes auxiliares empacotados e os registros de plugins pertencentes ao canal alinhados com o build instalado do OpenClaw, enquanto deixa as recompilações completas das conclusões de comandos de plugins para execuções explícitas de openclaw completion --write-state.

Relacionados

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