Skip to main content
O OpenClaw inclui três scripts de instalação, disponibilizados em openclaw.ai. Todos os três são compatíveis com o Node 22.22.3+, 24.15+ ou 25.9+; o Node 24 é o destino padrão para novas instalações.

​
Comandos rápidos

Se a instalação for bem-sucedida, mas openclaw não for encontrado em um novo terminal, consulte solução de problemas do Node.js.

​
install.sh

Recomendado para a maioria das instalações interativas no macOS/Linux/WSL.

​
Fluxo (install.sh)

1

Detectar o sistema operacional

Compatível com macOS e Linux (incluindo WSL).
2

Garantir o Node.js 24 por padrão

Verifica a versão do Node e instala o Node 24, se necessário (Homebrew no macOS, scripts de configuração do NodeSource no Linux com apt/dnf/yum). No macOS, o Homebrew é instalado somente quando o instalador precisa dele para o Node ou o Git. Node 22.22.3+, Node 24.15+ e Node 25.9+ são compatíveis; o Node 23 não é compatível. No Alpine/Linux com musl, o instalador usa pacotes apk em vez do NodeSource e verifica a versão real vinculada do SQLite. Os fluxos de pacotes estáveis atuais do Alpine podem fornecer um Node suficientemente recente com um SQLite vulnerável do sistema; quando isso ocorrer, use um contêiner oficial node:24-alpine ou um host baseado em glibc.
3

Garantir o Git

Instala o Git, caso não esteja presente, usando o gerenciador de pacotes detectado, incluindo o Homebrew no macOS e o apk no Alpine.
4

Instalar o OpenClaw

  • Método npm (padrão): instalação global via npm
  • Método git: clona/atualiza o repositório, instala as dependências com pnpm, compila e, em seguida, instala o wrapper em ~/.local/bin/openclaw
5

Tarefas pós-instalação

  • Resolve o binário openclaw recém-instalado para comandos subsequentes
  • Para uma instalação não configurada, inicia a configuração inicial antes das verificações do doctor ou do gateway. Com --no-onboard ou sem TTY, exibe o comando para concluir a configuração posteriormente.
  • Para uma instalação configurada, atualiza e reinicia, na medida do possível, um serviço do gateway carregado e executa o doctor. As atualizações atualizam os plugins quando possível ou exibem o comando manual em uma execução sem interface gráfica com prompts habilitados.
  • Quando --verify é executado, verifica a versão instalada e a integridade do gateway somente após a configuração existir.

​
Detecção do checkout do código-fonte

Se executado dentro de um checkout do OpenClaw (package.json + pnpm-workspace.yaml), o script oferece as opções:
  • usar o checkout (git) ou
  • usar a instalação global (npm)
Se nenhum TTY estiver disponível e nenhum método de instalação estiver definido, o padrão será npm e um aviso será exibido. O script é encerrado com o código 2 quando a seleção do método ou os valores de --install-method são inválidos.

​
Exemplos (install.sh)

​
install-cli.sh

Projetado para ambientes nos quais se deseja manter tudo em um prefixo local (padrão ~/.openclaw) e sem dependência do Node do sistema. Por padrão, é compatível com instalações via npm, além de instalações a partir de um checkout do git no mesmo fluxo de prefixo.

​
Fluxo (install-cli.sh)

1

Instalar o runtime local do Node

Baixa um tarball fixado de uma versão LTS compatível do Node (a versão está incorporada ao script e é atualizada de forma independente; o padrão é 24.15.0) em <prefix>/tools/node-v<version> e verifica o SHA-256. O Linux ARMv7 usa o Node 22.22.3 porque os binários oficiais do Node 24+ para ARMv7 não estão disponíveis. No Alpine/Linux com musl, onde o Node não publica tarballs compatíveis para o runtime fixado, instala nodejs e npm com apk e, em seguida, verifica tanto o Node quanto a biblioteca SQLite realmente vinculada. Os fluxos de pacotes estáveis atuais do Alpine ainda podem vincular um SQLite vulnerável, mesmo com um Node suficientemente recente; use um contêiner oficial node:24-alpine ou um host baseado em glibc quando a verificação de segurança rejeitar o pacote.
2

Garantir o Git

Se o Git não estiver presente, tenta instalá-lo via apt/dnf/yum/apk no Linux ou Homebrew no macOS.
3

Instalar o OpenClaw no prefixo

  • Método npm (padrão): instala no prefixo com npm e grava o wrapper em <prefix>/bin/openclaw
  • Método git: clona/atualiza um checkout (padrão ~/openclaw) e também grava o wrapper em <prefix>/bin/openclaw
4

Atualizar o serviço do gateway carregado

Se um serviço do gateway já estiver carregado a partir desse mesmo prefixo, o script executará openclaw gateway install --force, que ativa o serviço substituto, e depois verificará a integridade do gateway na medida do possível.

​
Exemplos (install-cli.sh)

openclaw@main e outras especificações de origem do GitHub não são destinos --version válidos para instalações via npm. Use --install-method git --version main em vez disso.

​
install.ps1

​
Fluxo (install.ps1)

1

Garantir o ambiente PowerShell + Windows

Requer PowerShell 5+.
2

Garantir o Node.js 24 por padrão

Se estiver ausente, tenta instalá-lo pelo winget, depois pelo Chocolatey e, em seguida, pelo Scoop. Se nenhum gerenciador de pacotes estiver disponível, o script baixa o arquivo zip oficial do Node.js 24 para Windows em %LOCALAPPDATA%\OpenClaw\deps\portable-node e o adiciona ao PATH do processo atual e do usuário. Há suporte para Node 22.22.3+, Node 24.15+ e Node 25.9+; não há suporte para Node 23.
3

Instalar o OpenClaw

  • Método npm (padrão): instalação global via npm usando o -Tag selecionado, iniciada a partir de um diretório temporário do instalador com permissão de gravação, para que shells abertos em pastas protegidas, como C:\, continuem funcionando
  • Método git: clona/atualiza o repositório, instala/compila com pnpm e instala o wrapper em %USERPROFILE%\.local\bin\openclaw.cmd. Se o Git estiver ausente, o script inicializa o MinGit local do usuário em %LOCALAPPDATA%\OpenClaw\deps\portable-git e o adiciona ao PATH do processo atual e do usuário.
4

Tarefas pós-instalação

  • Adiciona o diretório de binários necessário ao PATH do usuário quando possível
  • Atualiza, em caráter de melhor esforço, um serviço Gateway carregado (openclaw gateway install --force e depois reinicialização)
  • Executa openclaw doctor --non-interactive em atualizações e instalações via git (melhor esforço)
5

Tratar falhas

Instalações com iwr ... | iex e blocos de script relatam um erro de encerramento sem fechar a sessão atual do PowerShell. Instalações diretas com powershell -File / pwsh -File ainda encerram com código diferente de zero para automação.

​
Exemplos (install.ps1)

Se -InstallMethod git for usado e o Git estiver ausente, o script tentará inicializar um MinGit local do usuário antes de exibir o link do Git for Windows.

​
CI e automação

Use sinalizadores/variáveis de ambiente não interativos para obter execuções previsíveis.

​
Solução de problemas

O Git é necessário para o método de instalação git. Para instalações npm, o Git ainda é verificado/instalado para evitar falhas de spawn git ENOENT quando as dependências usam URLs git.
Algumas configurações do Linux apontam o prefixo global do npm para caminhos pertencentes ao root. install.sh pode alterar o prefixo para ~/.npm-global e acrescentar exportações de PATH aos arquivos rc do shell (quando esses arquivos existirem).
Execute novamente o instalador para que ele possa inicializar o MinGit local do usuário ou instale o Git for Windows e reabra o PowerShell.
Execute npm config get prefix, adicione esse diretório ao PATH do usuário (nenhum sufixo \bin é necessário no Windows) e reabra o PowerShell.
install.ps1 não oferece um sinalizador -Verbose. Use o rastreamento do PowerShell para diagnósticos no nível do script:
Geralmente, é um problema de PATH. Consulte Solução de problemas do Node.js.

​
Relacionados