OpenClaw no Windows: como preparar o ambiente e escolher entre instalação nativa e WSL2

Fala aí, beleza? Instalar o OpenClaw no Windows quase nunca trava na instalação em si, trava na ESCOLHA do caminho

O projeto é um assistente pessoal de IA open source, desenhado pra um único operador, conectando modelos, ferramentas, canais de mensagem e apps companheiros através de um Gateway

O código vive no repositório openclaw/openclaw, que traz a licença MIT com copyright da OpenClaw Foundation

Aí você chega na parte do Windows e a documentação oficial não te dá um botão, te dá TRÊS caminhos: Windows Hub, instalador PowerShell nativo e WSL2

Ou seja: a primeira decisão não é instalar, é decidir onde a coisa vai rodar

Bora preparar o terreno?

O que precisa estar pronto antes de instalar o OpenClaw

Antes de sair colando comando, se liga no checklist do ambiente

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

• Versão do Windows: o Windows Hub requer Windows 10 20H2+ ou Windows 11
• Node.js em versão suportada: Node 22.22.3+, 24.15+ ou 25.9+
• Chave de API de um provedor de modelo: Anthropic, OpenAI, Google, entre outros

Essa última é a que mais pega gente desprevenida

O OpenClaw depende de uma chave de provedor, e o assistente de onboarding conduz a escolha do provedor, a definição da chave e a configuração do Gateway

Melhor ainda: ele testa os candidatos ao vivo, em ordem, e só salva modelo e credencial depois de uma completion bem-sucedida

E o Node, preciso instalar na mão?

Não necessariamente

O script oficial de instalação detecta o sistema, instala o Node se for preciso, baixa a CLI, instala globalmente via npm e já abre o onboarding

Então se você não faz questão de controlar a versão do Node, dá pra deixar essa parte com ele

Se você JÁ tem Node na máquina, vale conferir se ele bate com as versões mínimas antes de começar, porque versão velha é o tipo de coisa que só aparece lá na frente 🙂

Windows Hub, PowerShell nativo ou WSL2: comparação dos três caminhos

A documentação oficial de Windows lista os três e deixa a escolha com você, conforme o uso

E se a sua dúvida for mais ampla, tipo onde hospedar seus agentes de IA fora da máquina de trabalho, isso é outra conversa que já rolou por aqui

Repara que o Hub e o WSL2 não são exatamente rivais

A opção Set up locally do Hub provisiona uma distro WSL própria do app pra rodar o Gateway, então dá pra ter os dois mundos sem montar nada na mão

Como instalar o OpenClaw pelo Windows Hub (app de desktop)

Esse é o caminho de quem quer ver a coisa acontecendo, com ícone na bandeja e tudo mais

1. Confira o requisito de sistema: Windows 10 20H2+ ou Windows 11
2. Baixe o instalador assinado da sua arquitetura (x64 ou ARM64) na página de releases do openclaw-windows-node
3. Rode o instalador normalmente

O erro comum deste passo: procurar o famoso "executar como administrador"

O Windows Hub instala SEM privilégio de administrador, então se você está caçando elevação, provavelmente está resolvendo um problema que não existe

4. No app, escolha a opção Set up locally

O que acontece aqui: o Hub provisiona uma distro WSL de propriedade do app chamada OpenClawGateway, instala o Gateway dentro dela e pareia o app

5. Deixe o pareamento concluir e acompanhe o status pela bandeja

Cuidado: a distro OpenClawGateway não é um Ubuntu de uso geral

Esse é O erro clássico do caminho do Hub

A distro criada pelo app é restrita de propósito:

• o Gateway roda como o usuário Linux openclaw
• a interoperabilidade com o Windows fica desabilitada dentro do WSL
• o automount dos drives do Windows fica desabilitado
• não existe fluxo de sudo por senha

Ou seja: não adianta abrir ela esperando montar seu C: e sair fazendo os rm -rf da vida lá dentro haha

A boa notícia é que ela também não exporta nem altera a sua distro Ubuntu existente

Se você já tem um Ubuntu configurado no WSL, ele continua intacto

Como instalar o OpenClaw pelo terminal no Windows nativo

Se o seu ambiente já é PowerShell aberto o dia inteiro, esse caminho é mais direto

1. Abra o PowerShell e rode o script oficial

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

2. Deixe o script fazer o trabalho dele

Ele detecta o SO, instala o Node se preciso, baixa a CLI, instala globalmente via npm e inicia o assistente de onboarding

3. Se você NÃO quer que o onboarding dispare na hora, a documentação traz uma variante do mesmo script que só instala, usando o parâmetro -NoOnboard

4. Prefere instalar pelo gerenciador de pacotes? Também rola, com o daemon em passo separado

npm install -g openclaw@latest
openclaw onboard --install-daemon

Esse fluxo funciona com npm, pnpm ou bun

O erro comum deste passo: instalar o pacote global, ver o comando respondendo e achar que o Gateway já está de pé

Não está

O daemon é outra coisa, e é ele que mantém o Gateway vivo, por isso o --install-daemon (ou o comando de serviço da próxima seção) existe

5. Tenha a chave de API do provedor em mãos quando o onboarding pedir

Como o assistente testa os candidatos ao vivo antes de salvar, chave errada aparece na hora, e não três dias depois

Como deixar o Gateway subindo sozinho no Windows

Aqui é onde muita instalação "funciona hoje e some amanhã"

1. Instale o serviço do Gateway

openclaw gateway install

2. Se já existe uma instalação anterior e você quer reinstalar ou sobrescrever, use o --force

openclaw gateway install --force

3. Se preferir resolver isso durante o onboarding, é a mesma história com outra porta de entrada

openclaw onboard --install-daemon

4. Confira o resultado com o comando de status

Ele mostra o estado de instalação do serviço (launchd, systemd ou schtasks) e ainda sonda a saúde do Gateway

O erro comum deste passo: pular a conferência

Contar com um Gateway que "deve estar rodando" é o caminho mais rápido pra descobrir que não estava

E como isso funciona por baixo no Windows nativo?

A inicialização automática usa uma Scheduled Task chamada OpenClaw Gateway (ou OpenClaw Gateway (<profile>) quando você usa perfis nomeados)

A tarefa dispara um wrapper gateway.vbs, e o motivo é bem prático: assim o Gateway em segundo plano não abre janela de console visível

E se a criação da tarefa for negada no seu ambiente? Tem plano B documentado

O instalador cai pra um launcher na pasta Startup do usuário, apontando pro gateway.cmd dentro do diretório de estado

Saber disso ajuda muito na hora de investigar, porque o lugar onde você procura muda conforme o mecanismo que ficou ativo

Pontos de atrito clássicos do OpenClaw no Windows (e como sair deles)

Agora a parte que ninguém coloca no README bonitinho 😀

O navegador não responde com o Gateway no WSL2 e o Chrome no Windows

Sintoma: o Gateway está no WSL2, o Chrome está no Windows, e o controle do navegador simplesmente não acontece

Causa: é o bind da porta de debug do Chromium

O Chromium tenta ligar o remote debugging em 127.0.0.1 primeiro e só cai pra [::1] se o bind IPv4 falhar

Aí entra o detalhe traiçoeiro: uma regra persistente v4tov4 escutando em 127.0.0.1:9222 pode ocupar o endpoint antes do Chrome subir

Solução: se o chrome.exe está respondendo só em [::1], o listener alcançável pelo WSL2 precisa apontar pra ::1 com v4tov6, e o OpenClaw é apontado pro endereço alcançável pelo parâmetro cdpUrl no perfil de navegador

Como prevenir: nunca exponha a porta CDP em 0.0.0.0, em endereço de LAN ou em endereço de tailnet

O alerta é explícito na documentação, e a razão é séria: o CDP dá controle da sessão do navegador

Erros parecidos que vêm de camadas diferentes

Sintoma: mensagens de falha que se parecem, mas somem e voltam sem padrão

Causa: no setup dividido (Gateway no WSL2, Chrome no Windows) existem camadas independentes, e cada uma pode falhar sozinha produzindo erro parecido

Solução: percorra na ordem que a documentação orienta, transporte CDP, depois origem da Control UI, depois token e pareamento

Como prevenir: resista à tentação de mexer em três coisas ao mesmo tempo

É justamente por causa desse arranjo que existe uma página de troubleshooting só pra ele

O comando do node não roda e ninguém explica por quê

Sintoma: você chama um comando de node e nada acontece

Causa: comandos sensíveis à privacidade, como screen.record, camera.snap e camera.clip, exigem opt-in explícito

Solução: libere em gateway.nodes.commands.allow

E lembre da regra dupla: um comando precisa ser DECLARADO pelo node E permitido pela política do Gateway antes de rodar

Como prevenir: trate a política como parte do setup, não como troubleshooting

Se você já sabe que vai usar captura de tela ou câmera, deixa isso resolvido junto da instalação

A própria documentação te manda pra dois lugares

Sintoma: você lê uma página e entende que o caminho é o PowerShell, lê outra e entende que é WSL2

Causa: não é impressão sua

Existe registro público no repositório oficial sobre isso, a issue #15027, intitulada "Conflicting installation guidance for Windows: Getting Started recommends PowerShell IRM, Install page recommends WSL2"

Solução: decida pelo USO, não pela página que você abriu primeiro

Quer app de desktop com bandeja e Command Center? Hub

Quer CLI no terminal? Instalador nativo

Quer o runtime de Gateway mais compatível com Linux? WSL2

Como prevenir: escolha um caminho e vá até o fim nele antes de misturar tutorial de um com passo do outro

Vídeo: como manter a IA sob controle enquanto você monta o ambiente

Pra começar do zero com IA sem virar refém dela, este vídeo do canal mostra a evolução do vibe coding pro que ele chama de Loop Engineering, o jeito de trabalhar que faz a IA não quebrar nada

Preparou o terreno? O próximo passo

Recapitulando: o OpenClaw no Windows tem caminho documentado, o que ele não tem é clique único

Existem três rotas oficiais, cada uma entrega uma coisa diferente, e a maior parte da dor de cabeça nasce de escolher uma rota e seguir instrução de outra

Então o próximo passo é bem concreto:

1. confira a versão do Node na sua máquina (22.22.3+, 24.15+ ou 25.9+)
2. tenha a chave de API do provedor em mãos antes de abrir o onboarding
3. escolha o caminho pelo uso pretendido, app, terminal nativo ou WSL2
4. rode o comando de status e confirme o serviço instalado e a saúde do Gateway antes de contar com ele rodando sozinho

Esse último item parece burocracia, mas é ele que separa "instalei" de "está funcionando"

Até o próximo post!