Guia completo de instalação do OpenClaw: do preparo do ambiente à primeira execução

Atualização de 08/06/2026: revisei a versão do Node.js, o script de instalação e o fluxo do onboard com base na documentação oficial do OpenClaw. A versão recomendada é a v24 e a mínima é a v22.14+. Também acrescentei leituras relacionadas desta série. Para comandos e portas, vale o que consta na documentação oficial.

O processo de instalação do OpenClaw foi mais simples do que eu esperava. Seja no Mac, no Linux ou no Windows, basta acompanhar o guia para evitar a maioria dos problemas. Reuni aqui minha experiência de instalação para quem ainda não tem muita familiaridade com a linha de comando, mas quer experimentar a ferramenta.

Guia para “criar sua lagosta” gastando pouco: o ArkClaw torna os Agents de IA realmente acessíveis

O OpenClaw, também conhecido como “lagosta”, está em alta e funciona muito bem, mas a configuração pode desanimar. O ArkClaw, da Volcano Engine, da ByteDance, reduz bastante essa barreira. Sem precisar lidar com servidor ou configuração de Token, você pode ter com um clique um “faz-tudo de IA” disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O principal é o preço baixo: a mensalidade custa apenas 9,9 yuans e, usando meu código de convite ZLKUK54M ao se cadastrar por este link, sai por apenas 8,9 yuans. Se você é programador, também pode assinar diretamente o Coding Plan Pro e usá-lo sem custo adicional.

O que é o OpenClaw?

Antes de começar a instalação, vale entender o que é o OpenClaw. Em poucas palavras, ele é uma plataforma de assistente de inteligência artificial (IA) de código aberto que conecta grandes modelos de linguagem, como ChatGPT e Claude, aos aplicativos de conversa que você já usa, como Telegram e WhatsApp.

Talvez você se pergunte por que instalar isso localmente em vez de usar uma IA diretamente pela web.

Cada opção tem suas vantagens. Com uma instalação local, você pode:

• Manter o controle dos seus dados e da sua privacidade
• Personalizar funções e Skills
• Integrar a IA ao seu próprio fluxo de trabalho
• Usar até mesmo modelos locais, sem depender de serviços de nuvem, caso queira fazer uma configuração mais avançada

Para mim, o mais interessante é poder conectar a IA ao Telegram. Assim, consigo acioná-la diretamente durante uma conversa, sem ficar alternando entre aplicativos.

Preparação: verifique o sistema

Sendo sincero, os requisitos de sistema do OpenClaw são bem acessíveis. Mesmo assim, antes de começar, é preciso confirmar alguns pontos.

Compatibilidade com sistemas operacionais

O OpenClaw oferece suporte nativo a macOS e Linux. No Windows, a documentação oficial de instalação apresenta tanto o Windows nativo quanto o WSL2. Se você pretende copiar diretamente os comandos de Linux mostrados abaixo, o WSL2 costuma ser o caminho mais simples.

O WSL2 permite executar um ambiente Linux leve dentro do Windows. Para instalá-lo, abra o PowerShell e execute um único comando:

wsl --install

Quando a instalação terminar, reinicie o computador. Depois, abra novamente o PowerShell e digite wsl para entrar no ambiente Linux.

Requisitos de hardware

Em termos de hardware, o OpenClaw não exige muito. A recomendação oficial é:

• Memória: 8 GB são suficientes; 16 GB oferecem uma experiência melhor
• Armazenamento: reserve pelo menos 20 GB, de preferência em um SSD para obter desempenho melhor

Em geral, se o seu computador executa um navegador sem dificuldades, também deve rodar o OpenClaw. Eu uso um MacBook antigo com 8 GB de memória e ele funciona sem problemas.

Ambiente Node.js

Esta é a etapa mais importante. O OpenClaw é baseado em Node.js, então você precisa instalar o Node primeiro. De acordo com a documentação oficial de instalação, o Node 24 é recomendado e a versão mínima é a 22.14+. Se a versão não for suficiente, o script de instalação poderá avisar ou ajudar a resolver o problema.

Se você gerencia as versões com o nvm, recomendo instalar diretamente a versão 24 para o uso cotidiano e o desenvolvimento.

Como instalar o Node.js no macOS

Para usuários de Mac, a maneira mais simples é usar o Homebrew:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

# Se você ainda não instalou o Homebrew, instale-o primeiro
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Depois, instale o Node.js
brew install node

Como instalar o Node.js no Linux

No Linux, recomendo usar o nvm, o Node Version Manager. Com ele, você consegue alternar facilmente entre versões diferentes do Node.js:

# Instale o nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Depois de reiniciar o terminal, instale o Node.js (versão 24 recomendada)
nvm install 24
nvm use 24

Como instalar o Node.js no Windows com WSL2

No WSL2, o processo é igual ao do Linux: basta usar o nvm.

Depois da instalação, verifique a versão:

node --version

Se o comando mostrar v22.14+ ou v24.x, a versão recomendada, o requisito oficial atual está atendido.

Gerenciador de pacotes: npm ou pnpm?

Ao instalar o Node.js, você também recebe o npm, o Node Package Manager. O OpenClaw funciona normalmente com ele.

Se você já conhece o pnpm, também pode usá-lo. Em comparação com o npm, o pnpm oferece algumas vantagens:

• Instalações mais rápidas
• Menor uso de espaço em disco
• Gerenciamento mais rigoroso de dependências

Para a maioria das pessoas, qualquer uma das opções funciona. Eu costumo usar o pnpm, mas isso depende totalmente da sua preferência.

Para instalar o pnpm:

npm install -g pnpm

Como instalar o OpenClaw

Com o ambiente preparado, podemos começar a instalação. O OpenClaw oferece vários métodos, que apresento abaixo em ordem de recomendação.

Método 1: script oficial de instalação (mais recomendado)

Esta é a forma mais simples: um único comando resolve tudo.

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

O script faz automaticamente o seguinte:

• Verifica o ambiente do sistema
• Instala as dependências necessárias
• Baixa e instala a CLI do OpenClaw
• Orienta você a executar a configuração inicial

O processo inteiro leva cerca de um a dois minutos, dependendo da velocidade da sua internet. Na minha primeira instalação, ver as linhas de log passando rapidamente pelo terminal deu uma boa sensação de progresso.

Método 2: instalação global com npm

Se você prefere usar um gerenciador de pacotes, pode instalar diretamente com o npm:

npm install -g openclaw@latest

O @latest garante a instalação da versão mais recente. Depois disso, o comando openclaw poderá ser usado diretamente no terminal.

Método 3: instalação global com pnpm

Se você usa o pnpm, execute:

pnpm add -g openclaw@latest

O resultado é o mesmo da instalação com npm; muda apenas a ferramenta utilizada.

Método 4: instalação a partir do código-fonte (avançado)

Se você gosta de explorar o código ou pretende contribuir com o OpenClaw, pode clonar o repositório do GitHub:

# Clone o repositório
git clone https://github.com/openclaw/openclaw.git

# Entre no diretório
cd openclaw

# Instale as dependências
pnpm install

# Faça o build
pnpm ui:build

Esse método é voltado a desenvolvedores e não é recomendado para usuários comuns.

Configuração inicial: coloque o OpenClaw para funcionar

Depois da instalação, o OpenClaw ainda precisa passar pelo assistente de configuração. Esta etapa é importante, mas também é simples.

Execute o assistente onboard

No terminal, digite:

openclaw onboard --install-daemon

Esse comando inicia um assistente de configuração interativo. O parâmetro --install-daemon instala o OpenClaw como um serviço do sistema, permitindo que ele seja iniciado automaticamente com o computador, sem que você precise executá-lo manualmente todas as vezes.

Em seguida, o assistente fará algumas perguntas, uma de cada vez:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

1. Escolha o modo de execução

Em geral, basta selecionar o modo local (Local gateway), a menos que você queira fazer a implantação em um servidor remoto.

2. Configure o modelo de IA

Aqui, você precisa escolher o provedor de IA. Atualmente, há suporte para:

• OpenAI, incluindo GPT-5 e outros modelos
• Anthropic, com a família Claude
• Modelos locais, que exigem configuração adicional

Se você já tem uma API Key da OpenAI ou da Anthropic, informe-a nesta etapa. Caso contrário, pode pular e configurá-la depois.

Para obter uma API Key:

• OpenAI: crie uma conta em platform.openai.com e gere uma chave na página de API Keys
• Anthropic: crie uma conta em console.anthropic.com e gere a chave nas configurações da API

3. Defina o diretório de trabalho

O assistente perguntará onde armazenar a configuração e os dados do OpenClaw. O padrão é ~/.openclaw/; na maioria dos casos, basta pressionar Enter e manter esse local.

4. Conecte um canal de mensagens

Nesta etapa, você escolhe a plataforma de conversa que usará para falar com a IA. Atualmente, há suporte para:

• Telegram: primeiro, procure @BotFather no Telegram, crie um bot e obtenha o token
• WhatsApp: um QR code será gerado para que você faça a vinculação pelo aplicativo no celular
• Pular: se quiser usar apenas a interface web, você pode ignorar esta etapa por enquanto

Eu escolhi o Telegram, e a configuração foi bem simples:

1. Procure @BotFather no Telegram
2. Envie o comando /newbot
3. Siga as instruções para dar um nome ao bot
4. Copie o token gerado
5. Cole-o na configuração do OpenClaw

5. Instale o daemon

Por fim, o assistente perguntará se você quer instalar o daemon. Ao escolher “sim”, o OpenClaw continuará em execução em segundo plano mesmo depois de você fechar o terminal.

Todo o processo de configuração leva cerca de cinco a dez minutos. A maior parte do tempo é gasta na obtenção da API Key e na configuração do canal de conversa.

Configuração manual (opcional)

Para fazer ajustes mais detalhados, edite o arquivo de configuração:

nano ~/.openclaw/openclaw.json

Esse arquivo usa o formato JSON e contém todas as opções de configuração. Para a maioria das pessoas, o assistente é suficiente e não há necessidade de editar o arquivo manualmente.

Primeira execução: verifique se tudo funciona

Depois da configuração, você pode iniciar o OpenClaw.

Inicie o Gateway

Se você não instalou o daemon, inicie-o manualmente:

openclaw gateway --port 18789

18789 é a porta padrão, mas você pode escolher outra. Se a inicialização for bem-sucedida, verá uma mensagem parecida com esta:

✓ OpenClaw Gateway started on http://localhost:18789

Acesse a interface web

Abra o navegador e acesse:

http://localhost:18789

Você deverá ver a interface de controle do OpenClaw. Ela é bem simples e se divide principalmente nestas áreas:

• Chat: área para testar conversas
• Agents: gerenciamento dos seus Agents de IA
• Skills: configuração de Skills e plugins
• Settings: configurações do sistema

Teste uma conversa

Na página Chat, envie uma mensagem como “Olá” ou “Fale um pouco sobre você”.

Se tudo estiver configurado corretamente, a IA deverá responder. Ver a primeira resposta é empolgante: afinal, esse é o assistente de IA que você acabou de instalar.

Solução de problemas comuns

Ao instalar um software, é normal encontrar alguns contratempos. Reuni abaixo os problemas mais frequentes para facilitar o diagnóstico.

Versão incorreta do Node.js

Sintoma: o comando openclaw apresenta um erro de incompatibilidade com a versão do Node

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Solução: verifique a versão do Node.js e confirme se ela é pelo menos a v22.14; a v24 é recomendada.

node --version

Se a versão for muito antiga, reinstale ou atualize o Node.js.

Problemas de configuração do WSL2 para usuários do Windows

Sintoma: vários erros aparecem durante a instalação no Windows

Solução: confirme se o WSL2 está instalado corretamente e atualizado para a versão mais recente.

wsl --update

API Key inválida

Sintoma: você configurou uma API Key, mas a IA não responde ou apresenta um erro

Solução:

• Confirme se a chave foi copiada corretamente, sem espaços extras antes ou depois
• Verifique se a conta da API tem saldo; tanto a OpenAI quanto a Anthropic exigem créditos
• Tente gerar uma nova chave

Porta em uso

Sintoma: ao iniciar o Gateway, uma mensagem informa que a porta 18789 já está em uso

Solução: escolha outra porta ou identifique e encerre o processo que está usando a porta atual.

# Veja qual processo está usando a porta 18789
lsof -i :18789

# Inicie em outra porta
openclaw gateway --port 18790

Problemas de permissão

Sintoma: a instalação informa que não há permissão suficiente

Solução: no Linux ou Mac, talvez seja necessário usar sudo ou conferir as permissões do diretório.

# Garanta a permissão de escrita
chmod -R 755 ~/.openclaw

Recomendações de segurança

Depois de instalar o OpenClaw, preste atenção a alguns pontos de segurança:

1. Não exponha a porta: por padrão, a porta 18789 escuta apenas em localhost. Nunca a exponha à internet pública, pois qualquer pessoa poderia acessar sua IA
2. Proteja as API Keys: as chaves armazenadas no arquivo de configuração são confidenciais. Não as compartilhe nem envie o arquivo para um repositório Git
3. Use um túnel SSH para acesso remoto: se quiser acessar de outro dispositivo, use um túnel SSH em vez de abrir a porta diretamente

# Acesse de outro computador por SSH
ssh -L 18789:localhost:18789 user@your-server

Leituras relacionadas

• Configuração do OpenClaw: guia completo do openclaw.json
• Arquitetura do OpenClaw em detalhes: design em três camadas e práticas de extensão
• OpenClaw vs ChatGPT: comparação de arquitetura técnica, custo e privacidade

Para concluir

Pronto: a esta altura, você já deve ter instalado o OpenClaw com sucesso. Recapitulando todo o processo:

Como próximos passos, você pode:

• Explorar as Skills e adicionar novas capacidades à IA
• Conectar o Telegram ou o WhatsApp para usar a IA diretamente no aplicativo de mensagens
• Aprender a desenvolver Skills personalizadas, se tiver interesse
• Consultar a documentação oficial para conhecer funções mais avançadas

Sendo sincero, apesar de ser um projeto de código aberto, o OpenClaw já oferece uma experiência muito boa. Se você encontrar algum problema durante a instalação, vale consultar a página de Issues no GitHub; a comunidade é bastante ativa.

Um último lembrete: ao ter contato com esse tipo de ferramenta pela primeira vez, tudo pode parecer um pouco complicado. Depois de fazer a instalação uma vez, porém, você perceberá que o processo é bem mais simples do que parece. Vá com calma e pesquise quando surgir alguma dúvida; quase sempre há uma solução.

Divirta-se!