Instalando OpenClaw no Windows: o guia passo a passo definitivo (com armadilhas)

Instalei o OpenClaw no Windows umas 20 vezes nas últimas semanas. Não estou exagerando. O processo não é trivial — o software foi originalmente desenhado para macOS, e tanto Windows quanto Linux são adaptações que carregam armadilhas que ninguém documenta direito.

Este artigo é o guia que eu queria ter encontrado antes de começar. Cobre as duas formas de instalar no Windows, qual recomendo e por quê, todos os pré-requisitos, os erros comuns e — talvez o mais importante — como isolar a instalação para não comprometer sua máquina principal.

Material complementar: o documento Word completo com todos os comandos copy-paste está disponível no meu Notion. Acesse pela bio do meu Instagram (@gvelozo_tech) → link tree → "OpenClaw Install Document".

Decisão #1: WSL2 ou instalação nativa Windows?

Existem duas abordagens. Recomendo fortemente a primeira.

Abordagem	Complexidade	Estabilidade	Quando usar
WSL2 (Linux dentro do Windows)	Baixa	Alta	Padrão recomendado
Nativa Windows	Alta	Média	Apenas se você tem restrição corporativa contra WSL2

A documentação oficial do OpenClaw lista os ambientes suportados como macOS, Linux ou WSL2. O Windows nativo não é oficialmente suportado — você está em terreno menos testado. WSL2 é Linux real rodando dentro do Windows, então você herda toda a estabilidade do Linux sem abandonar a sua máquina Windows.

Antes de começar: arquitetura segura de instalação

Aqui está algo que nenhum tutorial que vi na internet menciona, e que como profissional de cybersegurança eu insisto: não instale o OpenClaw na sua máquina principal.

Por quê? Veja o disclaimer que o próprio onboarding mostra:

By default, OpenClaw is a personal trustworthy operator. It can read files, execute actions, and (if enabled) access your inbox, calendar, and more.

Tradução: você está dando a um agente autônomo acesso amplo ao seu sistema. Se algo der errado — bug, comprometimento de dependência, prompt injection através de um conteúdo lido — o estrago pode ser grande.

A configuração que eu recomendo

Sua máquina física principal
    │
    └─→ VM dedicada (Hyper-V / VirtualBox)
        │
        ├─ Conta Windows separada (Outlook account NOVA)
        ├─ WSL2 dentro da VM
        ├─ OpenClaw instalado no WSL2
        └─ Pasta compartilhada (única ponte com host)

Pontos críticos de isolamento:

1. VM dedicada — Hyper-V no Windows Pro, VirtualBox em qualquer edição
2. Conta Microsoft separada — crie um novo Hotmail/Outlook account específico para essa VM. NÃO use sua conta pessoal
3. No Mac equivalente: crie um Apple ID novo, não vincule à conta principal
4. Compartilhamento mínimo — apenas uma pasta específica de troca entre host e VM, nada mais

Se um atacante comprometer a VM, ele pega só o que está nela — não tem caminho para sua conta principal, seus arquivos, seu iPhone, etc.

Caminho A: instalação via WSL2 (recomendado)

Passo 1 — Instalar o WSL2

Em PowerShell como administrador:

wsl --install

Reinicie o computador.

Passo 2 — Após reiniciar, criar o usuário Linux

Quando a janela do Ubuntu abrir automaticamente, defina:

• Username: openclaw (ou outro nome dedicado)
• Password: uma senha forte específica para este ambiente

Passo 3 — Atualizar o sistema

sudo apt update && sudo apt upgrade -y

(Se cair em problema de DNS na VM, ajuste o /etc/resolv.conf ou troque o DNS para 8.8.8.8)

Passo 4 — Instalar o Git

sudo apt install git -y

Passo 5 — Instalar o NVM (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

Passo 6 — Instalar o Node.js versão 22 (NÃO a versão mais recente)

nvm install 22
nvm use 22
node --version  # deve mostrar v22.x.x

⚠️ Importante: o Node.js já está em versão 24/25, mas o OpenClaw foi testado contra v22. Versões mais recentes podem causar erros silenciosos. Especifique a versão.

Passo 7 — Instalar o OpenClaw

npm install -g @openclaw/cli

Output esperado: algo como added 682 packages in 2 minutes. Esse número varia entre 600-800 dependendo da versão.

Passo 8 — Onboarding

openclaw onboard

A maioria dos tutoriais começa daqui. Pulam a parte difícil (todos os pré-requisitos acima) porque dá muito trabalho documentar — e você fica preso quando seu setup quebra.

Caminho B: instalação nativa no Windows (não recomendado, mas se precisar)

Se sua organização proíbe WSL2, você precisa de:

# Como administrador
winget install --id Git.Git -e
winget install --id CoreyButler.NVMforWindows -e

# Em uma NOVA janela PowerShell (após instalar NVM)
nvm install 22.0.0
nvm use 22.0.0

E depois adicionar variáveis de ambiente ao perfil do Windows. Em máquinas mais antigas sem suporte a GPU, sem isso a instalação trava ao tentar carregar o LLaMA local:

[System.Environment]::SetEnvironmentVariable('OPENCLAW_NO_GPU', '1', 'User')
[System.Environment]::SetEnvironmentVariable('LLAMA_CPP_USE_CPU', '1', 'User')
[System.Environment]::SetEnvironmentVariable('OPENCLAW_OFFLINE_MODELS', 'false', 'User')

Crítico: após definir variáveis, feche e reabra o terminal — caso contrário o ambiente novo não é carregado e a instalação falha.

Aí sim:

npm install -g @openclaw/cli
openclaw onboard

Configurando a chave de API

Durante o onboarding, o OpenClaw pede uma chave de API de algum provedor LLM. Suas opções:

• OpenAI
• Anthropic
• Google Gemini
• OpenRouter ← minha recomendação

Por que OpenRouter

OpenRouter é um roteador inteligente — uma única chave dá acesso a vários modelos, e ele escolhe o melhor para o tipo de tarefa em cada caso. Vantagens:

• Você não fica preso a um único provedor
• Não precisa trocar configuração se quiser experimentar modelos diferentes
• Cobrança consolidada
• Fallback automático se um provedor estiver fora

Como obter:

1. Acesse openrouter.ai
2. Crie uma conta
3. Vá em "Keys" → "Create Key" → nomeie como openclaw-bot
4. Copie o número longo gerado
5. Cole no onboarding do OpenClaw quando ele pedir

Configuração de skills (mantenha simples no início)

Durante o onboarding, ele oferece skills para conectar:

• WhatsApp ✅ (funciona em todas as plataformas)
• Google Workspace
• Slack
• Notion
• Outros

Dica de teclado (apanhei para descobrir): use barra de espaço para selecionar/deselecionar cada skill, e Enter para confirmar a seleção.

Recomendação: comece só com WhatsApp, ou nada. Configure skills adicionais depois que o sistema estiver estável. Alguns skills (como o que usa brew) só funcionam em macOS — se você selecionar no Windows, a instalação falha com mensagem confusa.

Boas práticas pós-instalação

1. Use um número de WhatsApp dedicado se for ativar o skill — não vincule seu pessoal
2. Re-execute openclaw onboard sempre que quiser mudar configuração — não tem efeito destrutivo
3. Atualize com cuidado — quebras entre versões beta ainda são frequentes; mantenha o documento de instalação versionado para reproduzir o setup atual

Erros comuns e mitigações

Erro	Causa	Solução
LLaMA load failed	Máquina sem GPU + flag não setada	Variáveis de ambiente do passo Windows
EACCES: permission denied	Falta de privilégio admin	Re-rode o terminal como administrador
Cannot find module ...	Versão errada do Node	nvm use 22 antes de instalar
brew: command not found	Skill macOS-only no Windows	Re-rode onboard e desmarque o skill
Instalação trava em DNS	DNS da VM mal configurado	Ajustar /etc/resolv.conf para 8.8.8.8
npm não encontrado após NVM	Terminal não recarregou	Feche e reabra o terminal

Conclusão

OpenClaw é uma ferramenta poderosa, mas a instalação ainda está longe de ser plug-and-play em Windows. Os 20 minutos que você gasta preparando ambiente isolado economizam horas de debug e protegem sua máquina principal.

A recompensa vale: depois de instalado, você tem um agente autônomo open-source com acesso a 150k+ estrelas no GitHub, integração nativa com WhatsApp e os principais LLMs do mercado.

Próximo vídeo no canal: como configurar o OpenClaw para automatizar tarefas reais — vou cobrir o caso de uso de criação de um agente que monitora seu inbox e responde mensagens com base em regras de negócio.

---

Este artigo foi gerado a partir do meu vídeo no YouTube. Assista a versão completa para o passo a passo na minha tela e o documento Notion completo com todos os comandos copy-paste.