Guia de Instalacao

Instalar o OpenClaw do zero e bem simples! Siga os passos abaixo, leva uns 5-10 minutos. Relaxa, vamos explicar cada etapa.

📋 Requisitos do Sistema

Antes de comecar a instalacao, confirme que seu computador atende a estes requisitos basicos:

Node.js 22 ou superior — E o ambiente base para rodar o OpenClaw (relaxa, o script de instalacao verifica isso pra voce)
Sistema operacional — macOS, Linux ou Windows (precisa do WSL2)
Memoria — Pelo menos 2GB de memoria disponivel
Espaco em disco — Pelo menos 500MB de espaco livre
Rede — Precisa de internet pra baixar e acessar as APIs dos modelos de IA

ℹ️ O que e Node.js? De forma simples, o Node.js e como um "tradutor" que permite que seu computador execute programas escritos em JavaScript. O OpenClaw e feito em JavaScript, entao precisa do Node.js pra funcionar. Voce nao precisa aprender JavaScript, basta instalar o Node.js.

ℹ️ O que e WSL2? Usuarios de Windows, prestem atencao: o OpenClaw nao roda diretamente no Windows, ele precisa do WSL2 (Windows Subsystem for Linux 2), que e basicamente um mini sistema Linux dentro do Windows. Se voce usa Windows, o script de instalacao cuida disso automaticamente.

🌟 Metodo 1: Script de instalacao com um comando (Recomendado para iniciantes!)

Esse e o jeito mais simples de instalar. Basta copiar e colar um comando no terminal e o script faz tudo automaticamente. E super facil, e so seguir os passos!

💡 O que e o "terminal"? O terminal e uma janela onde voce digita comandos de texto. No macOS se chama "Terminal", no Windows se chama "PowerShell" ou "Prompt de Comando". Voce pode buscar "Terminal" no seu computador pra encontrar.

Abra o Terminal

Pressione Command + Espaco, digite "Terminal" e aperte Enter. Uma janela de linha de comando (preta ou branca) vai aparecer.

Copie e cole o comando de instalacao

Copie o comando abaixo, cole na janela do terminal e aperte Enter:

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

Esse comando faz o seguinte:

Verifica se o Node.js esta instalado no seu computador; se nao estiver, instala automaticamente
Baixa e instala a versao mais recente do OpenClaw
Executa o assistente de configuracao inicial (onboarding) pra te guiar na configuracao basica

Aguarde a instalacao terminar

A instalacao leva de 2 a 5 minutos, dependendo da sua internet. Voce vai ver um monte de texto rolando no terminal - isso e normal, nao se preocupe! Quando terminar, o assistente de configuracao vai abrir automaticamente.

Abra o Terminal

No Linux, voce pode pressionar Ctrl + Alt + T pra abrir o terminal, ou buscar "Terminal" no menu de aplicativos.

Copie e cole o comando de instalacao

Igualzinho no macOS, copie o comando abaixo, cole no terminal e aperte Enter:

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

O script vai verificar o Node.js automaticamente, baixar e instalar o OpenClaw e rodar o assistente de configuracao.

Aguarde a instalacao terminar

Espere alguns minutinhos. Quando aparecer o assistente de configuracao, a instalacao foi um sucesso!

Abra o PowerShell (como Administrador)

Busque "PowerShell" no menu Iniciar, clique com o botao direito e selecione "Executar como administrador". Esse passo e importante porque a instalacao precisa de permissoes de administrador.

Copie e cole o comando de instalacao

Usuarios de Windows usam este comando especifico:

iwr -useb https://openclaw.ai/install.ps1 | iex

Esse script vai automaticamente:

Verificar e configurar o WSL2 (se ainda nao estiver instalado)
Instalar o Node.js
Baixar e instalar o OpenClaw
Executar o assistente de configuracao inicial

Aguarde a instalacao terminar

No Windows a instalacao pode demorar um pouquinho mais (por causa do WSL2), cerca de 5-10 minutos. Quando terminar, o assistente de configuracao vai abrir automaticamente.

⚠️ Atencao, usuarios Windows: Depois de instalar o WSL2, pode ser necessario reiniciar o computador. Se o script pedir pra reiniciar, reinicie e depois execute o comando de instalacao novamente.

📦 Metodo 2: Instalacao via npm

Se voce ja conhece Node.js e npm (o gerenciador de pacotes do Node.js), pode usar esse metodo. Ele te da mais controle sobre a instalacao.

Confirme que o Node.js esta instalado

Abra o terminal e digite o seguinte comando pra verificar a versao do Node.js:

node --version

Se aparecer v22.x.x ou uma versao mais recente, voce esta pronto. Se nao estiver instalado ou a versao for antiga, va ate nodejs.org pra baixar e instalar a versao mais recente.

Instale o OpenClaw globalmente com npm

No terminal, execute:

npm install -g openclaw@latest

Explicando esse comando:

npm install — Usa o npm pra instalar um pacote
-g — Instalacao global, assim voce pode usar o comando openclaw de qualquer lugar
openclaw@latest — Instala a versao mais recente do OpenClaw

Execute a configuracao inicial e registre o servico em segundo plano

Depois de instalar, execute:

openclaw onboard --install-daemon

Esse comando faz duas coisas:

onboard — Inicia o assistente de configuracao, te guiando pela configuracao inicial (escolher modelo de IA, inserir chave de API, etc.)
--install-daemon — Registra o OpenClaw como servico em segundo plano (daemon), assim ele inicia automaticamente quando voce liga o computador, sem precisar abrir manualmente toda vez

💡 O que e um daemon (processo em segundo plano)? Basicamente, e um programa que roda em segundo plano sem voce ver a janela dele, mas ele continua trabalhando. Com o --install-daemon, o OpenClaw fica rodando silenciosamente em segundo plano, sempre pronto pra receber suas mensagens.

🐳 Metodo 3: Instalacao com Docker

Se voce gosta de usar Docker (uma tecnologia de containerizacao), ou quer rodar o OpenClaw em um ambiente completamente isolado, essa e a opcao ideal.

ℹ️ O que e Docker? O Docker e como uma "caixinha virtual" onde voce coloca o software pra rodar. Assim, mesmo se algo der errado, nao afeta seu computador. Se voce nao sabe o que e Docker, recomendamos usar o Metodo 1 ou Metodo 2 pra instalar.

Certifique-se de que o Docker esta instalado

Se voce ainda nao instalou o Docker, va ate docker.com pra baixar e instalar o Docker Desktop.

Execute o container Docker do OpenClaw

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/openclaw/openclaw:latest

Esse comando baixa a imagem Docker do OpenClaw e inicia o container. O parametro -v mapeia os arquivos de configuracao pro seu computador, assim seus dados nao se perdem.

✅ Verificacao pos-instalacao

Depois de instalar, vamos confirmar que tudo esta funcionando direitinho. Siga os passos abaixo:

Execute a verificacao de saude

openclaw doctor

Esse comando e como fazer um "check-up" no OpenClaw. Ele verifica se todos os componentes necessarios estao funcionando corretamente. Se tudo estiver certo, voce vai ver varios sinais verdes de confirmacao.

Verifique o status de execucao

openclaw status

Esse comando mostra se o OpenClaw esta rodando. Se aparecer "running", esta tudo certo!

Abra o painel de controle Web

openclaw dashboard

Esse comando abre automaticamente o navegador no painel de controle Web do OpenClaw. O endereco e:

http://127.0.0.1:18789/

Nesse painel voce pode ver todas as configuracoes e o status do OpenClaw, de forma bem intuitiva!

🎉 Se os tres comandos funcionaram sem erros, parabens! O OpenClaw foi instalado com sucesso! Agora va para a secao de Inicio Rapido pra aprender como comecar a usar.

🛠️ Problemas comuns na instalacao

Encontrou um problema? Calma! Aqui estao os problemas mais comuns durante a instalacao e como resolver:

Problema 1: Comando nao encontrado (command not found: openclaw)

Isso geralmente e um problema com a variavel de ambiente PATH. Basicamente, seu computador nao sabe onde o comando openclaw esta.

Solucao:

# Veja onde o openclaw esta instalado
which openclaw || npm list -g openclaw

# Se voce usa bash, adicione o caminho ao arquivo de configuracao
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Se voce usa zsh (padrao no macOS)
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Problema 2: Versao do Node.js muito antiga

Se voce vir um erro tipo "Node.js v18 is not supported", significa que voce precisa atualizar o Node.js.

Solucao:

# Use o nvm (Node Version Manager) pra gerenciar versoes do Node.js
# Primeiro instale o nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Instale o Node.js 22
nvm install 22

# Mude pra versao 22
nvm use 22

# Confirme a versao
node --version

Problema 3: Conflito de porta (EADDRINUSE)

Se voce vir "EADDRINUSE: address already in use :::18789", significa que a porta 18789 ja esta sendo usada por outro programa.

Solucao:

# Encontre o processo usando a porta 18789
lsof -i :18789

# Se for um processo antigo do OpenClaw, pare ele primeiro
openclaw stop

# Depois reinicie
openclaw start

Problema 4: Permissao insuficiente (EACCES)

Pode acontecer ao usar npm pra instalacao global no Linux/macOS.

Solucao:

# Metodo A: Mude o diretorio de instalacao global do npm
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Depois reinstale
npm install -g openclaw@latest

⚠️ Nunca use sudo npm install -g! Apesar de o sudo resolver o problema de permissao, isso pode causar outros problemas de seguranca. Use o metodo acima pra alterar o diretorio de instalacao global do npm.

Problema 5: Timeout de rede

Se o download estiver muito lento ou dando timeout, pode ser um problema de rede.

Solucao:

# Configure o npm pra usar um mirror alternativo
npm config set registry https://registry.npmmirror.com

# Depois reinstale
npm install -g openclaw@latest