Atualizacao

O OpenClaw esta evoluindo rapido (antes da “1.0”). Trate atualizacoes como deploy de infraestrutura: atualizar → executar verificacoes → reiniciar (ou use openclaw update, que reinicia automaticamente) → verificar.

Recomendado: re-execute o instalador do site (atualizacao in-place)

O caminho de atualizacao preferido e re-executar o instalador do site. Ele detecta instalacoes existentes, atualiza in-place e executa openclaw doctor quando necessario.

curl -fsSL https://openclaw.ai/install.sh | bash

Observacoes:

• Adicione --no-onboard se nao quer que o assistente de onboarding rode novamente.

• Para instalacoes a partir do codigo-fonte, use:

  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

  O instalador executara git pull --rebase apenas se o repositorio estiver limpo.

• Para instalacoes globais, o script usa npm install -g openclaw@latest internamente.

• Nota legada: clawdbot continua disponivel como shim de compatibilidade.

Antes de atualizar

• Saiba como voce instalou: global (npm/pnpm) vs a partir do codigo-fonte (git clone).
• Saiba como seu Gateway esta rodando: terminal em foreground vs servico supervisionado (launchd/systemd).
• Faca backup das suas personalizacoes:
  • Config: ~/.openclaw/openclaw.json
  • Credenciais: ~/.openclaw/credentials/
  • Workspace: ~/.openclaw/workspace

Atualizacao (instalacao global)

Instalacao global (escolha uma):

npm i -g openclaw@latest

pnpm add -g openclaw@latest

Nao recomendamos o Bun para o runtime do Gateway (bugs com WhatsApp/Telegram).

Para trocar canais de atualizacao (instalacoes git + npm):

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

Use --tag <dist-tag|version> para uma tag/versao pontual de instalacao.

Consulte Canais de desenvolvimento para semantica dos canais e notas de release.

Observacao: em instalacoes npm, o gateway registra uma dica de atualizacao na inicializacao (verifica a tag do canal atual). Desative via update.checkOnStart: false.

Auto-updater core (opcional)

O auto-updater esta desabilitado por padrao e e um recurso core do Gateway (nao um plugin).

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

Comportamento:

• stable: quando uma nova versao e detectada, o OpenClaw espera stableDelayHours e depois aplica um jitter deterministico por instalacao em stableJitterHours (rollout gradual).
• beta: verifica no intervalo betaCheckIntervalHours (padrao: a cada hora) e aplica quando uma atualizacao esta disponivel.
• dev: sem aplicacao automatica; use manualmente openclaw update.

Use openclaw update --dry-run para pre-visualizar acoes de atualizacao antes de habilitar a automacao.

Depois:

openclaw doctor
openclaw gateway restart
openclaw health

Observacoes:

• Se seu Gateway roda como servico, openclaw gateway restart e preferivel a matar PIDs.
• Se voce esta fixado em uma versao especifica, veja “Rollback / fixacao” abaixo.

Atualizacao (openclaw update)

Para instalacoes a partir do codigo-fonte (checkout git), prefira:

openclaw update

Ele executa um fluxo de atualizacao seguro:

• Requer um worktree limpo.
• Muda para o canal selecionado (tag ou branch).
• Fetch + rebase contra o upstream configurado (canal dev).
• Instala deps, compila, compila a interface de controle e executa openclaw doctor.
• Reinicia o gateway por padrao (use --no-restart para pular).

Se voce instalou via npm/pnpm (sem metadados git), openclaw update tentara atualizar via seu gerenciador de pacotes. Se nao conseguir detectar a instalacao, use “Atualizacao (instalacao global)” em vez disso.

Atualizacao (Interface de Controle / RPC)

A Interface de Controle tem Atualizar e Reiniciar (RPC: update.run). Ela:

1. Executa o mesmo fluxo de atualizacao de codigo-fonte que openclaw update (apenas checkout git).
2. Escreve um sentinel de reinicio com um relatorio estruturado (cauda de stdout/stderr).
3. Reinicia o gateway e faz ping na ultima sessao ativa com o relatorio.

Se o rebase falhar, o gateway aborta e reinicia sem aplicar a atualizacao.

Atualizacao (a partir do codigo-fonte)

A partir do checkout do repositorio:

Preferido:

openclaw update

Manual (equivalente aproximado):

git pull
pnpm install
pnpm build
pnpm ui:build # instala automaticamente deps da UI na primeira execucao
openclaw doctor
openclaw health

Observacoes:

• pnpm build e importante quando voce executa o binario empacotado openclaw (openclaw.mjs) ou usa Node para executar dist/.
• Se voce executa a partir de um checkout do repositorio sem instalacao global, use pnpm openclaw ... para comandos CLI.
• Se voce executa diretamente de TypeScript (pnpm openclaw ...), uma recompilacao geralmente nao e necessaria, mas migracoes de configuracao ainda se aplicam → execute o doctor.
• Trocar entre instalacoes globais e git e facil: instale a outra variante, depois execute openclaw doctor para que o ponto de entrada do servico do gateway seja reescrito para a instalacao atual.

Sempre execute: openclaw doctor

O Doctor e o comando de “atualizacao segura”. E intencionalmente chato: reparar + migrar + avisar.

Observacao: se voce esta em uma instalacao a partir do codigo-fonte (checkout git), openclaw doctor vai oferecer executar openclaw update primeiro.

O que ele tipicamente faz:

• Migrar chaves de configuracao obsoletas / localizacoes de arquivo de configuracao legadas.
• Auditar politicas de DM e avisar sobre configuracoes “abertas” arriscadas.
• Verificar a saude do Gateway e pode oferecer reinicio.
• Detectar e migrar servicos de gateway antigos (launchd/systemd; schtasks legado) para servicos OpenClaw atuais.
• No Linux, garantir lingering de usuario systemd (para que o Gateway sobreviva ao logout).

Detalhes: Doctor

Iniciar / parar / reiniciar o Gateway

CLI (funciona independente do SO):

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

Se voce esta supervisionado:

• macOS launchd (LaunchAgent empacotado no app): launchctl kickstart -k gui/$UID/ai.openclaw.gateway (use ai.openclaw.<profile>; legado com.openclaw.* ainda funciona)
• Servico de usuario systemd Linux: systemctl --user restart openclaw-gateway[-<profile>].service
• Windows (WSL2): systemctl --user restart openclaw-gateway[-<profile>].service
  • launchctl/systemctl so funcionam se o servico estiver instalado; caso contrario, execute openclaw gateway install.

Runbook + labels de servico exatos: Runbook do gateway

Rollback / fixacao (quando algo quebra)

Fixar (instalacao global)

Instale uma versao conhecida como funcional (substitua <version> pela ultima que funcionou):

npm i -g openclaw@<version>

pnpm add -g openclaw@<version>

Dica: para ver a versao publicada atual, execute npm view openclaw version.

Depois reinicie + re-execute o doctor:

openclaw doctor
openclaw gateway restart

Fixar (codigo-fonte) por data

Escolha um commit de uma data (exemplo: “estado de main em 01 de janeiro de 2026”):

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

Depois reinstale deps + reinicie:

pnpm install
pnpm build
openclaw gateway restart

Para voltar ao mais recente depois:

git checkout main
git pull

Se voce ficou travado

• Execute openclaw doctor novamente e leia a saida com atencao (frequentemente indica a correcao).
• Consulte: Solucao de problemas
• Pergunte no Discord: https://discord.gg/clawd