Atualização

Mantenha o OpenClaw atualizado.

# Recomendado: openclaw update

A forma 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

Para trocar de canal ou mirar uma versão específica:

openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
openclaw update --dry-run   # preview without applying

openclaw update não aceita --verbose. Para diagnósticos de atualização, use --dry-run para visualizar as ações planejadas, --json para resultados estruturados ou openclaw update status --json para inspecionar o estado do canal e da disponibilidade. O instalador tem sua própria flag --verbose, mas essa flag não faz parte de openclaw update.

--channel beta dá preferência à beta, mas o runtime volta para stable/latest quando a tag beta está ausente ou é mais antiga que a versão estável mais recente. Use --tag beta se você quiser a dist-tag beta bruta do npm para uma atualização pontual de pacote.

Consulte Canais de desenvolvimento para ver 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 de código do OpenClaw a CLI e o gateway usam.

# npm package install -> editable git checkout
openclaw update --channel dev

# git checkout -> npm package install
openclaw update --channel stable

Execute com --dry-run primeiro para visualizar a troca exata de modo de instalação:

openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run

O canal dev garante um checkout git, compila-o e instala a CLI global a partir desse checkout. Os canais stable e beta usam instalações por pacote. Se o gateway já estiver instalado, openclaw update atualiza os metadados do serviço e o reinicia, a menos que você passe --no-restart.

# Alternativa: executar novamente o instalador

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

Adicione --no-onboard para pular o onboarding. Para forçar um tipo de instalação específico por meio do 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 novamente o instalador. 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.

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

Para fixar a recuperação em uma versão ou dist-tag específica, adicione --version:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

# Alternativa: npm, pnpm ou bun manual

npm i -g openclaw@latest

Prefira 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 enquanto um Gateway gerenciado estiver em execução, reinicie o Gateway imediatamente depois que o gerenciador de pacotes terminar, para que o processo antigo não continue servindo a partir de arquivos de pacote substituídos.

Quando openclaw update gerencia uma instalação npm global, ele instala primeiro o destino em um prefixo npm temporário, verifica o inventário dist empacotado e então troca a árvore de pacote 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.

pnpm add -g openclaw@latest

bun add -g openclaw@latest

# Tópicos avançados de instalação npm

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

# Atualizador automático

O atualizador automático fica desativado por padrão. Ative-o em ~/.openclaw/openclaw.json:

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

O gateway também registra uma dica de atualização na inicialização (desative com update.checkOnStart: false). 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. As dicas de atualização na inicialização ainda podem ser executadas, a menos que update.checkOnStart também esteja desativado.

Atualizações do gerenciador de pacotes solicitadas por meio do handler do plano de controle do Gateway ao vivo forçam uma reinicialização de atualização sem adiamento e sem cooldown após a troca de pacote. Isso evita deixar um processo antigo em memória por tempo suficiente para carregar chunks sob demanda a partir de uma árvore de pacotes que já foi substituída. O openclaw update pelo shell continua sendo o caminho preferido para instalações supervisionadas porque ele pode parar e reiniciar o serviço durante a atualização.

# Após atualizar

openclaw doctor

openclaw gateway restart

openclaw health

# Reversão

# Fixar uma versão (npm)

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

# Fixar um commit (código-fonte)

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart

Para voltar para a mais recente: git checkout main && git pull.

# Se você estiver travado

• Execute openclaw doctor novamente e leia a saída com atenção.
• Para openclaw update --channel dev em checkouts de código-fonte, o atualizador inicializa automaticamente o pnpm quando necessário. Se você vir um erro de bootstrap do pnpm/corepack, instale o pnpm manualmente (ou reative o corepack) e execute a atualização novamente.
• Consulte: Solução de problemas
• Pergunte no Discord: https://discord.gg/clawd

# Relacionados

• Visão geral da 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ão principal.