OpenClaw com Ollama no Windows e WSL2: como diagnosticar erros de conexão
Um guia baseado em testes reais para integrar OpenClaw, Ollama e Qwen no Windows com WSL2, entender a rede entre os ambientes e corrigir bloqueios de firewall sem expor a API.
Instalar um modelo local é relativamente simples. Fazer um agente instalado em outro ambiente conversar com ele, de forma estável e segura, é uma história diferente.
Passei por isso ao montar uma estação com Windows 11, WSL2, OpenClaw, Ollama e Qwen. O modelo baixava normalmente, a API respondia no próprio Windows, mas o OpenClaw não conseguia acessá-la pelo Linux. Em outro momento, a instalação do OpenClaw falhou porque o Node.js era antigo. Houve até um manifesto de modelo que o Windows se recusava a atravessar por causa de um link simbólico.
O objetivo deste guia não é prometer que um comando resolve qualquer instalação. É ensinar a identificar qual camada falhou antes de mudar configurações ao acaso.
Entenda primeiro a arquitetura
No cenário deste artigo, existem dois ambientes distintos no mesmo computador:
Windows 11
├── Ollama (servidor HTTP, porta 11434)
├── modelo Qwen
├── firewall do Windows
└── WSL2
└── OpenClaw Gateway e agente
└── chamada HTTP → Ollama no Windows
O fato de tudo estar no mesmo PC não significa que compartilhe o mesmo endereço de loopback. Em determinadas configurações de rede do WSL2, 127.0.0.1 dentro do Linux não é o servidor que escuta em 127.0.0.1 no Windows. A configuração do modo de rede também pode alterar esse comportamento.
Por isso, a pergunta correta não é apenas “o Ollama está instalado?”, mas “de onde o OpenClaw está tentando acessá-lo?”
1. Confirme que o Ollama está saudável no Windows
No PowerShell:
ollama --version
ollama list
Invoke-RestMethod http://127.0.0.1:11434/api/tags
O comando ollama list mostra os modelos conhecidos pelo Ollama. O endpoint /api/tags verifica se o servidor HTTP responde. Se a lista estiver vazia, isso não prova uma falha de rede: talvez você ainda não tenha baixado um modelo.
No meu caso, utilizei:
ollama pull qwen3.5:4b-q4_K_M
ollama list
O nome da tag é importante: use a tag efetivamente disponível na sua instalação e referencie a mesma tag no OpenClaw. Não confunda modelo instalado, modelo carregado na memória e modelo configurado como padrão do agente. São estados diferentes.
Para testar uma resposta sem envolver o OpenClaw:
ollama run qwen3.5:4b-q4_K_M
Se isso falhar, resolva o Ollama antes de avançar para a integração.
2. Descubra onde o servidor está escutando
O Windows pode responder em loopback e continuar inacessível pelo WSL2.
Get-NetTCPConnection -LocalPort 11434 -State Listen |
Select-Object LocalAddress,LocalPort,OwningProcess
Interprete os endereços:
127.0.0.1: escuta apenas no loopback IPv4;0.0.0.0: escuta nas interfaces IPv4 disponíveis;::: endereço curinga IPv6; não assuma que isso garante, sozinho, conectividade IPv4 a partir do WSL.
O Ollama permite configurar o endereço de escuta por OLLAMA_HOST. No meu ambiente, precisei definir:
[Environment]::SetEnvironmentVariable(
"OLLAMA_HOST",
"0.0.0.0:11434",
"User"
)
Atenção: essa variável só afeta novos processos que a leem. Reinicie o processo do Ollama que está servindo a API e verifique novamente o endereço de escuta. Abrir outro terminal, por si só, não altera um servidor já iniciado.
Também existe uma implicação de segurança: escutar em todas as interfaces pode tornar a API alcançável fora do WSL. Não exponha a porta 11434 à internet; restrinja o firewall e, quando possível, prefira uma interface de rede mais limitada.
3. Descubra o endereço correto do host Windows visto pelo WSL2
No PowerShell, consulte o ambiente Linux que realmente executa o Gateway:
wsl -d OpenClawGateway -- sh -lc "ip route | grep default"
Em uma instalação WSL2 com NAT, o endereço do gateway da rota padrão costuma ser um candidato para alcançar o host Windows. Não copie o IP de outro tutorial: ele pode mudar quando a distribuição ou a rede reinicia.
Teste a API a partir do próprio Linux:
wsl -d OpenClawGateway -- sh -lc "curl -sS --max-time 5 http://SEU_IP_DO_HOST:11434/api/tags"
Substitua SEU_IP_DO_HOST pelo endereço observado no seu ambiente.
No meu diagnóstico, a chamada feita no Windows ao endereço do host respondia, mas a chamada feita pelo WSL2 expirava. Esse contraste foi mais útil do que reinstalar qualquer componente.
Se host.docker.internal resolver para um endereço, não conclua automaticamente que esse é o endereço correto para o seu Ollama. Resolução DNS não prova conectividade TCP. Faça o teste HTTP.
4. Quando o problema é o firewall do Windows
O padrão de falha era este:
Windows → API Ollama: responde
WSL2 → API Ollama: timeout
Com o servidor já escutando em uma interface acessível, investigamos o firewall. O PowerShell comum recusou a criação da regra com “Acesso negado”; o comando precisava de um terminal executado como Administrador.
O exemplo abaixo mostra a estrutura da regra, não uma sub-rede universal:
New-NetFirewallRule `
-DisplayName "Ollama from WSL" `
-Direction Inbound `
-Protocol TCP `
-LocalPort 11434 `
-RemoteAddress "SUA_SUB-REDE_WSL" `
-Action Allow
Descubra a sub-rede real do WSL2 antes de criar a regra. A máscara e o intervalo devem corresponder ao endereço da interface Linux, não a uma faixa copiada da internet.
Depois, teste novamente /api/tags a partir do WSL2. No meu ambiente, foi essa combinação — servidor escutando no endereço adequado e regra de entrada restrita à rede do WSL — que permitiu ao Linux listar o modelo.
Não use RemoteAddress Any apenas para fazer o erro desaparecer.
5. Se o modelo foi baixado, mas ollama list continua vazio
Passei por um erro específico do Windows:
O caminho não pode ser atravessado porque contém
um ponto de montagem não confiável.
A inspeção revelou que o manifesto da tag do modelo era um SymbolicLink apontando para um blob local. O blob existia, mas o Windows recusava atravessar aquele link. O download havia sido concluído; o problema era a leitura do manifesto.
O diagnóstico foi feito com:
Get-Item -LiteralPath "CAMINHO_DO_MANIFESTO" -Force |
Format-List FullName,LinkType,Target,Attributes
Não remova diretórios nem substitua manifestos às cegas. Verifique se o item é mesmo um link simbólico, confira o destino e faça backup antes de qualquer reparo. No caso observado, preservar o link original e colocar uma cópia do blob de manifesto no caminho esperado permitiu que ollama list reconhecesse o modelo.
Esse foi um reparo pontual para um estado comprovado. Não é uma etapa padrão da instalação e pode deixar de ser apropriado em versões futuras.
6. Node.js antigo pode quebrar a atualização do OpenClaw
Outro bloqueio foi a tentativa de instalar uma versão recente do OpenClaw com Node.js 22.14.0. O instalador mostrou EBADENGINE e interrompeu a atualização. Para a versão OpenClaw 2026.9.9 usada neste caso, o requisito informado era Node 24.16.0+ dentro da linha 24 ou Node 26.1.0+.
A sequência segura é:
node -v
npm -v
openclaw --version
Compare as versões com os requisitos da versão exata do OpenClaw que pretende instalar. Atualize o Node.js pelo canal oficial, abra um novo terminal e só então atualize o OpenClaw.
Um aviso EPERM durante uma atualização pode indicar arquivos em uso. Feche processos antigos e evite rodar várias instalações simultâneas; não conclua que a instalação terminou só porque parte dos pacotes foi copiada.
7. Valide a integração completa, não apenas a API
Uma instalação confiável passa por três provas diferentes:
| Prova | O que demonstra |
|---|---|
ollama list |
O runtime conhece o modelo |
curl .../api/tags a partir do WSL2 |
O Gateway alcança a API |
| Resposta do agente usando o provider Ollama | O OpenClaw realmente usou o modelo |
O último teste precisa mostrar o provider efetivo, não apenas uma resposta em linguagem natural. Um agente pode responder usando outro provider ou fallback. Consulte os metadados de execução e confirme provider: ollama e a tag do modelo.
Também diferencie “consegue conversar” de “consegue usar ferramentas”. Um modelo local pequeno pode responder bem a perguntas simples e ainda falhar em planejamento de ações, seleção de nós e interpretação de resultados estruturados.
Checklist de diagnóstico por sintomas
| Sintoma | Investigue primeiro |
|---|---|
ollama list vazio |
Modelo não instalado ou manifesto ilegível |
| API responde no Windows, mas expira no WSL | Bind, IP, modo de rede, firewall |
New-NetFirewallRule: Acesso negado |
Terminal sem elevação |
EBADENGINE |
Node.js incompatível |
| OpenClaw responde, mas não usa Qwen | Provider/modelo efetivo e fallback |
| Qwen responde, mas falha ao agir | Tool policy, capacidade, roteamento e limites do modelo |
O que eu faria diferente desde o início
Começaria com um roteiro de validação incremental. Primeiro Ollama no Windows, depois HTTP a partir do WSL, depois OpenClaw com uma pergunta curta e, finalmente, uma ferramenta somente de leitura.
Isso evita uma armadilha comum: mudar firewall, modelo, runtime, plugin e pareamento ao mesmo tempo. Quando tudo muda junto, até um sucesso fica difícil de explicar.
O ganho real de um modelo local não está apenas em economizar chamadas de API. Está em poder construir uma camada de execução controlável, observável e apropriada para tarefas específicas. Para chegar lá, porém, é preciso tratar o agente como um sistema distribuído — mesmo quando todos os componentes rodam no mesmo computador.
Próximo artigo: como habilitar o controle gráfico do Windows pelo OpenClaw, entender o cua-computer e diferenciar um nó pareado de um nó realmente apto a executar computer.act.
Leituras relacionadas
- O modelo não é o produto: arquitetura, validação e a nova engenharia da IA — por que contratos, validação e ferramentas determinísticas importam mais do que escolher apenas um modelo maior.
- Agentes em produção: migração, permissões e segurança em 2026 — princípios de governança, permissões e observabilidade para agentes que acessam sistemas reais.