WSL 2 para Agentes de IA — Configuração Otimizada no Windows em 2026

Sumário

• Por que WSL 2 é essencial para agentes de IA no Windows
• Configuração inicial otimizada do WSL 2
• Instalação de Node.js, Python e ferramentas no WSL para agentes
• Integração WSL + Windows: acesso a arquivos, PATH compartilhado, Docker
• Performance tuning: .wslconfig, CPU affinity, limites de RAM
• Troubleshooting comum: permissões, rede, sistema de arquivos
• FAQ

Por que WSL 2 é essencial para agentes de IA no Windows

Agentes de IA como Claude Code e Codex foram projetados para rodar em ambientes Unix. O PowerShell e o CMD do Windows até funcionam, mas a experiência é cheia de atritos: permissões inconsistentes, diferenças de PATH, incompatibilidade de scripts e chamadas de sistema que simplesmente não existem no Windows. É aqui que o WSL 2 entra como camada de compatibilidade nativa.

O WSL 2 não é uma máquina virtual tradicional. Ele usa um kernel Linux real, mas integrado ao Windows de forma que os processos Linux consomem memória gerenciada pelo próprio Windows. Isso significa que Claude Code rodando no WSL 2 enxerga um sistema de arquivos Linux, usa syscalls nativas e executa scripts bash sem adaptação — tudo isso sem abrir mão do acesso a arquivos e ferramentas do Windows.

Para quem orquestra múltiplos agentes, o ganho é ainda maior. Codex, que depende de chamadas de API concorrentes e processamento de streams, se beneficia da pilha de rede nativa do Linux. Claude Code, por sua vez, usa ptrace e inotify para monitorar mudanças no sistema de arquivos — chamadas que só existem no kernel Linux. Sem o WSL 2, esses agentes operam com funcionalidade reduzida ou exigem workarounds frágeis.

O resultado prático: agentes rodando no WSL 2 são visivelmente mais rápidos, estáveis e confiáveis do que no PowerShell nativo. A diferença é particularmente perceptível em tarefas que envolvem manipulação intensa de arquivos, instalação de dependências e execução de testes.

Configuração inicial otimizada do WSL 2

A instalação padrão do WSL 2 é suficiente para testes, mas para rodar agentes de IA profissionalmente, você precisa de uma configuração sob medida. Comece verificando se seu Windows 11 atende aos requisitos: builds 22000 ou superiores, com virtualização habilitada na BIOS (Intel VT-x ou AMD SVM).

Instalação limpa

Abra o PowerShell como administrador e execute:

Esse comando instala o WSL 2, a distribuição Ubuntu 24.04 LTS e configura tudo com as recomendações padrão. Após a instalação, reinicie e defina seu usuário e senha Linux.

Configuração de memória e swap

Agentes de IA são sedentos por RAM. Claude Code pode consumir entre 300 MB e 1,5 GB de RAM dependendo do tamanho do contexto. Codex, operando com múltiplos workers, adiciona mais 200-500 MB. Para evitar que o WSL 2 engasgue, configure limites explícitos.

No PowerShell, crie ou edite o arquivo de configuração:

Cole estas configurações:

Esses valores funcionam bem para máquinas com 16 GB de RAM. Se você tem 32 GB, suba memory para 12-14 GB e processors para 6. O swap de 4 GB garante que o sistema não trave quando a memória encher durante tarefas pesadas.

Escolha da distribuição

Ubuntu 24.04 LTS é a escolha mais equilibrada para agentes de IA. O suporte a pacotes é maduro, o kernel 6.8 tem melhor gerenciamento de memória, e todas as ferramentas necessárias (Node.js, Python, Git) estão disponíveis nos repositórios oficiais. Evite distribuições muito leves como Alpine — elas usam musl em vez de glibc, o que quebra a compatibilidade com várias ferramentas de IA.

Instalação de Node.js, Python e ferramentas no WSL para agentes

Com o WSL 2 instalado, o próximo passo é preparar o ambiente para os agentes. Claude Code e Codex dependem de Node.js e Python, respectivamente. A instalação direta pelos repositórios do Ubuntu entrega versões desatualizadas — você precisa das versões mais recentes.

Node.js via nvm

O gerenciador de versões nvm é essencial para alternar entre versões do Node sem conflitos:

Com o Node.js instalado, instale o Claude Code globalmente:

A CLI do Claude Code agora está disponível em qualquer diretório do seu WSL.

Python com pyenv

Assim como o nvm para Node, o pyenv gerencia versões do Python sem poluir o sistema:

Ferramentas auxiliares

Algumas ferramentas fazem diferença no fluxo com agentes:

O htop permite monitorar o consumo de recursos dos agentes em tempo real. O ripgrep e fd-find aceleram buscas em projetos grandes — úteis quando Claude Code precisa escanear milhares de arquivos.

Integração WSL + Windows: acesso a arquivos, PATH compartilhado, Docker

Um dos maiores equívocos ao usar WSL 2 com agentes de IA é manter os projetos no sistema de arquivos do Windows e acessá-los via /mnt/c/. Isso introduz latência porque o WSL 2 precisa traduzir chamadas de sistema entre ext4 e NTFS — uma operação chamada DrvFs que custa performance.

Regra de ouro: projetos no ext4 do WSL

Mantenha seus projetos dentro do sistema de arquivos Linux ( /home/seuuser/projetos/). O acesso a arquivos no ext4 é 3 a 5 vezes mais rápido do que via /mnt/c/. Para abrir esses arquivos no editor do Windows, use \\wsl.localhost\Ubuntu-24.04\home\seuuser\projetos no explorador de arquivos.

PATH compartilhado entre Windows e WSL

Por padrão, o WSL 2 adiciona o PATH do Windows ao seu ambiente Linux. Isso é útil, mas pode causar conflitos — versões diferentes de Node.js ou Python podem competir. Configure para priorizar o PATH do WSL:

Para usar ferramentas do Windows dentro do WSL (como VS Code), o comando code . funciona magicamente graças à integração nativa da Microsoft.

Docker com WSL 2

Se seus agentes precisam rodar contêineres (por exemplo, para testar código em ambientes isolados), instale o Docker Desktop com backend WSL 2. A configuração é simples: instale o Docker Desktop, vá em Settings > Resources > WSL Integration e ative a integração com Ubuntu-24.04. Agora docker ps funciona direto do terminal WSL, sem precisar alternar contextos.

Performance tuning: .wslconfig, CPU affinity, limites de RAM

A configuração padrão do WSL 2 reserva 50% da RAM total e todos os núcleos da CPU disponíveis. Para agentes de IA, isso não é ideal — você precisa de controle granular para evitar que um agente monopolize recursos.

Ajustes finos no .wslconfig

Além das configurações básicas, você pode refinar o comportamento:

A flag kernelCommandLine=intel_iommu=off mitigations=off desativa correções de segurança de CPU que reduzem performance em até 15% em operações de E/S — aceitável para ambientes de desenvolvimento locais onde segurança de hypervisor não é preocupação primária.

CPU affinity e prioridade de processos

Para máquinas com múltiplos núcleos (6+), você pode isolar núcleos específicos para o WSL 2 usando o PowerShell:

Isso garante que o Windows e outros aplicativos não disputem os mesmos núcleos que seus agentes de IA.

Limpando cache de memória

Com o tempo, o WSL 2 acumula cache de disco e memória que não é liberado automaticamente. Crie um script para limpeza periódica:

Execute com cron a cada 4 horas ou manualmente quando notar lentidão.

Troubleshooting comum: permissões, rede, sistema de arquivos

Mesmo com a configuração correta, alguns problemas podem surgir ao usar WSL 2 com agentes de IA. Aqui estão os mais comuns e como resolvê-los.

Permissões de arquivos entre Windows e WSL

Arquivos criados no Windows e acessados pelo WSL podem herdar permissões 777 (todos podem executar), o que confunde agentes como Claude Code. A solução é configurar a máscara de permissão:

Depois, reinicie o WSL com wsl --shutdown no PowerShell e abra o terminal novamente.

Problemas de rede: DNS e proxy

O WSL 2 usa uma rede NAT, o que pode causar problemas de resolução de DNS ou conectividade com APIs de agentes de IA. Se Claude Code ou Codex não conseguirem se conectar, edite /etc/resolv.conf:

Para evitar que o WSL sobrescreva essa configuração, use sudo chattr +i /etc/resolv.conf.

Sistema de arquivos lento com projetos grandes

Se você insiste em manter projetos no NTFS, pelo menos evite que o WSL indexe arquivos desnecessários:

Isso impede que o WSL 2 monitore mudanças em diretórios que não interessam aos agentes.

WSL 2 não inicia ou trava

Se o WSL 2 parar de responder, reinicie o serviço LxssManager:

Depois, execute wsl novamente. Isso resolve 90% dos problemas de travamento.

FAQ — Perguntas frequentes sobre WSL 2 para agentes de IA