Como instalar o OpenClaw em 2026: npm, Docker e script

Resumo rápido: escolha primeiro a opção de instalação

Para a maioria das pessoas, o caminho é simples:
no computador pessoal, prefira o npm; para manter o serviço rodando em um servidor, use Docker; se quiser apenas testar rapidamente, escolha o script automatizado.
Confirmar antes a versão do Node e o ambiente de rede evita boa parte do tempo perdido com instalações que falham e tentativas repetidas.

Às duas da manhã, eu encarava a 17ª mensagem de erro na tela.

“Cannot find module ‘@anthropic-ai/sdk’” — aquela linha vermelha já me acompanhava havia três dias. Como desenvolvedor que já testou inúmeros projetos de código aberto, achei que estivesse acostumado a todo tipo de falha de instalação. Mas implantar o OpenClaw realmente me levou da confiança absoluta à dúvida completa.

Para ser sincero, quando finalmente consegui executar a primeira conversa no Mac Mini, a sensação foi comparável à de escrever “Hello World” pela primeira vez. Depois de instalado, o OpenClaw vale a pena: você pode acessar Claude, GPT-4 e outros modelos de IA pelo WhatsApp, Telegram, Discord e até iMessage, mantendo seus dados privados e reduzindo preocupações com vazamento de informações.

O problema é que o processo de instalação ainda não é muito amigável para iniciantes.

Este guia não promete milagres nem repete o que você já leu dez vezes na documentação oficial. Vou mostrar os problemas que encontrei, os caminhos que testei e o método que finalmente funcionou. Seja você usuário de Windows ou Mac, ou alguém preparando uma implantação em servidor, há uma opção adequada aqui. No Windows, as instruções oficiais de instalação cobrem tanto o Windows nativo quanto o WSL2. Se sua prioridade for seguir os comandos Linux apresentados abaixo, o WSL2 costuma facilitar o processo.

Um jeito barato de criar seu “claw”: ArkClaw torna os agentes de IA mais acessíveis

O popular OpenClaw, também chamado de “lagosta”, é útil, mas sua configuração afasta muita gente. O ArkClaw, da Volcengine, da ByteDance, reduz drasticamente essa barreira. Sem precisar configurar servidor ou Token, você obtém com um clique um agente de IA disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

E o preço é baixo: a mensalidade custa apenas 9,9 yuans. Com meu código de convite ZLKUK54M, o valor cai para 8,9 yuans ao se cadastrar aqui. Se você programa, também pode usar o Coding Plan Pro gratuitamente.

Antes da instalação: não tenha pressa

Muita gente vê as palavras “script de instalação automatizado” e já copia e cola o comando. Espere um pouco.

O OpenClaw impõe requisitos de sistema. Se você ignorá-los, os problemas aparecerão nas etapas seguintes. De acordo com a documentação oficial e os relatos da comunidade, estes são os pontos que precisam ser confirmados:

Versão do Node.js, de acordo com a documentação oficial

A documentação oficial de instalação informa que o Node 24 é recomendado e que a versão mínima é o Node 22.14+. O script automatizado também avisa quando o requisito não é atendido. Nos meus testes, o Node 20 causou problemas de dependência; depois da atualização para o 24, o processo ficou bem mais tranquilo.

node --version

Se a versão for anterior à v22.14, atualize pelo menos para a v22.14 ou instale diretamente a v24, que é a opção recomendada. Para usuários do Windows, a versão 24.x também é a primeira escolha.

Compatibilidade do sistema operacional

• macOS: versão 12.0 Monterey ou posterior, com suporte a Intel e Apple Silicon
• Windows: tanto o Windows nativo quanto o WSL2 têm suporte oficial; para uma experiência mais completa, a documentação oficial recomenda o WSL2
• Linux: há mais testes em distribuições comuns, como Ubuntu 20.04+, Debian 11+ e CentOS 8+

Preparação da API Key

O OpenClaw é apenas um “gateway”: para usá-lo, você precisa conectá-lo a um serviço de IA. Atualmente há suporte a Claude da Anthropic, OpenAI, Google Gemini e outros. Recomendo ter pelo menos uma API Key da Claude, que oferece a melhor experiência.

Aviso específico para usuários na China

O registry oficial do npm é muito lento na China. Recomenda-se trocar antes para o espelho do Taobao:

npm config set registry https://registry.npmmirror.com

Também é preciso considerar o acesso de rede às APIs: as interfaces da Anthropic e da OpenAI exigem um ambiente de rede internacional. Caso você não tenha uma conexão internacional estável, procure uma opção intermediária que esteja em conformidade com as regras aplicáveis.

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

Ganhar 15% off →Anúncio

Opção 1: instalação por script automatizado, a mais rápida

Escolha esta opção se você atender às condições abaixo:

• usa macOS, Linux ou WSL2
• quer apenas testar rapidamente, sem lidar com muitos detalhes
• aceita que o script faça alterações no sistema

Comando de instalação

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

O script realiza automaticamente as seguintes operações:

1. verifica a versão do Node.js e pede a atualização, se necessário
2. instala globalmente o pacote npm do openclaw
3. cria os diretórios de configuração necessários em ~/.openclaw/
4. configura o serviço do sistema, opcionalmente

Inicialização após a instalação

openclaw onboard --install-daemon

Nesta etapa, você informa a API Key e configura o canal de conversa padrão. Basta seguir as instruções; não há nenhum cuidado especial.

Verificar a instalação

openclaw --version

Se o número da versão aparecer, a instalação foi concluída. Quando tudo funciona sem problemas, o processo realmente leva apenas 5 minutos.

Mas preciso ser honesto: esse script “automatizado” falhou duas vezes em um dos meus servidores Ubuntu, ambas por problemas de permissão. Se isso também acontecer com você, não se preocupe; use a opção de instalação manual via npm abaixo.

Opção 2: instalação global via npm, a mais flexível

É o método que mais uso e também o que recomendo para usuários avançados. Há algumas etapas a mais, mas os problemas são mais fáceis de diagnosticar e a interferência no sistema é menor.

Etapa 1: confirmar o ambiente do Node.js

# Verificar a versão
node --version

# Se a versão for insuficiente, recomenda-se gerenciar o Node com o nvm
# Instalar o nvm no macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Em seguida, instalar o Node 24
nvm install 24
nvm use 24

Etapa 2: instalar o OpenClaw

npm install -g openclaw@latest

O sufixo @latest garante a instalação da versão mais recente. O OpenClaw é atualizado com frequência; em fevereiro de 2026, a versão já havia chegado à v2026.2.24.

Se ocorrer um erro de permissão EACCES durante a instalação, algo comum no macOS, as permissões do diretório global do npm não estão configuradas corretamente. Faça o seguinte:

# Criar um diretório dedicado
mkdir ~/.npm-global

# Configurar o npm para usar o novo diretório
npm config set prefix '~/.npm-global'

# Adicionar ao PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Instalar novamente
npm install -g openclaw@latest

Etapa 3: inicializar a configuração

openclaw onboard --install-daemon

O assistente interativo orienta você nestas etapas:

1. escolher o provedor de IA, como Claude, OpenAI ou Gemini
2. informar a API Key correspondente
3. configurar os canais de mensagem, como Telegram Bot e Discord
4. configurar o serviço do sistema, uma opção recomendada, mas não obrigatória

Etapa 4: iniciar e verificar o Gateway

Se você executou openclaw onboard --install-daemon na etapa anterior, o serviço local do Gateway normalmente já está registrado. Confira primeiro:

openclaw gateway status

Para depurar em primeiro plano, mantenha o terminal aberto e execute:

openclaw gateway

Para iniciar ou interromper explicitamente o serviço instalado no sistema, de acordo com a CLI oficial:

openclaw gateway start
openclaw gateway stop

Opção 3: instalação com Docker, a mais segura para servidores

Se você pretende executar o OpenClaw em um VPS, NAS ou outro ambiente que precise ficar estável por longos períodos, o Docker é a escolha mais sensata. O isolamento do contêiner ajuda a impedir que uma operação indevida do agente de IA afete o sistema host. Pode parecer exagero, mas já houve casos em que uma instância do OpenClaw excluiu arquivos por engano.

Etapa 1: confirmar o ambiente do Docker

docker --version
docker-compose --version

Não há um requisito rígido de versão, mas recomenda-se Docker 20.10+.

Etapa 2: criar os diretórios de configuração

mkdir -p ~/openclaw-data/config
mkdir -p ~/openclaw-data/data

Etapa 3: preparar o arquivo Docker Compose

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ~/openclaw-data/config:/app/config
      - ~/openclaw-data/data:/app/data
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${{ANTHROPIC_API_KEY}}
      - OPENAI_API_KEY=${{OPENAI_API_KEY}}

Etapa 4: configurar as variáveis de ambiente

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

# Criar o arquivo .env
cat > ~/openclaw-data/.env << EOF
ANTHROPIC_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
EOF

Etapa 5: iniciar o contêiner

cd ~/openclaw-data
docker-compose up -d

Etapa 6: acompanhar os logs e confirmar o estado

docker logs -f openclaw

Quando aparecer “OpenClaw Gateway started on port 3000”, o serviço estará funcionando.

Outra vantagem do Docker é poder implantar o OpenClaw em um Mac Mini, Raspberry Pi ou qualquer dispositivo compatível e acessá-lo a qualquer momento pelo Telegram ou WhatsApp no celular. Esse é, na verdade, um dos principais usos do OpenClaw.

Windows: passos detalhados para WSL2, uma opção disponível

Se você escolher o WSL2, veja os problemas mais comuns ao seguir os comandos Linux deste artigo. O Windows nativo também tem suporte oficial; consulte as instruções de instalação quando necessário.

Problema 1: versão incorreta do WSL

# Verificar a versão do WSL
wsl --list --verbose

Se aparecer Version 1, faça a atualização:

# Executar no PowerShell como administrador
wsl --set-version Ubuntu 2

Problema 2: memória insuficiente no WSL2

O OpenClaw usa uma quantidade considerável de memória, e a configuração padrão do WSL2 pode ser insuficiente. Recomenda-se criar um arquivo .wslconfig no diretório do usuário do Windows:

[wsl2]
memory=4GB
processors=2

Em seguida, reinicie o WSL:

wsl --shutdown

Problema 3: bloqueio do Firewall do Windows

Para acessar no navegador do Windows a interface web do OpenClaw que está sendo executada no WSL2, talvez seja necessário liberar a porta correspondente no Firewall do Windows.

Como executar o OpenClaw em um Mac Mini

O Mac Mini é uma ótima opção para executar o OpenClaw: consome pouca energia, é silencioso e tem desempenho suficiente. Meu Mac Mini M1 está funcionando de forma estável há três meses.

Cuidados com chips da série M

A imagem Docker precisa oferecer suporte a ARM64. A imagem oficial mais recente do OpenClaw já é compatível nativamente com Apple Silicon e não exige tradução pelo Rosetta.

# Especifique a plataforma no docker-compose.yml; normalmente não é necessário, mas tente se o download falhar
services:
  openclaw:
    platform: linux/arm64
    image: openclaw/openclaw:latest

Execução permanente em segundo plano

No macOS, recomenda-se gerenciar o serviço com o launchd. O parâmetro --install-daemon cria automaticamente o arquivo plist durante a instalação. Em uma instalação manual, talvez seja preciso configurá-lo por conta própria:

# Verificar o estado do serviço
launchctl list | grep openclaw

# Carregar manualmente
launchctl load ~/Library/LaunchAgents/ai.openclaw.daemon.plist

Solução de erros comuns do OpenClaw

Mesmo seguindo todos os passos, alguns problemas ainda podem ocorrer. Veja os erros mais frequentes e como resolvê-los:

Erro 1: mensagens “Cannot find module”

Causa: instalação incompleta do npm ou versão incompatível

Solução:

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

Erro 2: “EACCES: permission denied”

Causa: problema de permissão no diretório global do npm

Solução: siga as etapas de correção de permissões na seção sobre instalação via npm

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

Ver preços →Anúncio

Erro 3: chamadas de API retornam 401/403

Causa: API Key inválida ou cota esgotada

Diagnóstico:

# Verificar a configuração
openclaw config get

# Configurar novamente
openclaw config set anthropic.apiKey=your_new_key

Erro 4: contêiner Docker reiniciando continuamente

Causa: variáveis de ambiente incorretas ou conflito de porta

Diagnóstico:

# Consultar os logs detalhados
docker logs openclaw

# Verificar o uso da porta
lsof -i :3000

Erro 5: o canal de mensagens não recebe respostas

Causa: Webhook configurado incorretamente ou falha de rede

Diagnóstico:

• Telegram: confirme que o Bot Token está correto e que a URL do Webhook pode ser acessada
• Discord: confirme que as permissões do Bot estão corretas e que os Intents estão habilitados
• Servidores na China: verifique se conseguem acessar os servidores do Telegram e do Discord

Recomendações de configuração após a instalação

Depois de instalar o OpenClaw, algumas configurações podem melhorar a experiência:

1. Configurar vários provedores de IA

Recomenda-se configurar Claude e GPT-4 ao mesmo tempo, permitindo a troca automática quando um dos serviços estiver instável.

2. Configurar um atalho global

No macOS, use Alfred + Workflow; no Windows, use PowerToys Run para acessar o OpenClaw por um atalho global.

3. Fazer backup periódico da configuração

# Todos os arquivos de configuração ficam em ~/.openclaw/
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)

4. Monitorar o estado de execução

Em implantações com Docker, recomenda-se adicionar uma verificação de integridade:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Conclusão

Se você ainda não decidiu como instalar, minha recomendação é:

• para testar o mais rápido possível → script automatizado
• para uso diário como opção principal → instalação global via npm
• para execução contínua em servidor → Docker

Instalar o OpenClaw não é tão difícil quanto parece. Muitos dos problemas surgem porque a documentação não é amigável o suficiente ou porque as mensagens de erro não são claras. Espero que este guia ajude você a evitar alguns desses obstáculos.

Para terminar, implantar o OpenClaw não significa apenas instalar um programa. É também uma postura em relação ao uso da IA: manter os dados privados, preservar o controle e não ficar preso a uma única plataforma. À medida que a IA se torna mais poderosa, essa ideia de soberania pode ser mais importante do que parece.

Agora é sua vez de testar. Se você encontrar um problema não abordado aqui, compartilhe nos comentários. Já passei por mais dificuldades do que você imagina.

Próximas leituras

• Solução de problemas do OpenClaw: Node, Docker, WSL2 e erros de API
• Configuração do OpenClaw: guia completo do openclaw.json
• Configuração segura do OpenClaw: defesa em cinco camadas