Principais pontos de uso no Windows: nativo ou WSL, como rodar sem complicação

📚 Navegação da série: Anterior 〔32 Migrando do Claude Code 〕fala sobre "como transitar suavemente para o Codex após se familiarizar com o Claude Code". Esta parte é dedicada especialmente aos usuários de Windows — os trinta capítulos anteriores presumem que você digita comandos no Mac ou Linux, mas a maioria das pessoas usa Windows, onde caminhos, quebras de linha e sandboxes seguem regras totalmente diferentes. Próxima 〔34 Prática Geral 〕junta tudo o que aprendemos na parte do Codex e executa como um projeto completo.

Deixe-me contar uma burrice que eu mesmo fiz.

Em março de 2026, instalei o Codex pela primeira vez no meu notebook corporativo com Windows 11. Para poupar trabalho, não instalei o WSL e rodei diretamente no PowerShell nativo. Ele foi instalado, mas assim que pedi para alterar um arquivo, deu erro — olhei os logs por um bom tempo até perceber que o projeto que eu tinha feito git clone no Mac tinha scripts com quebra de linha LF, e o Git no Windows, por padrão, converteu todos para CRLF. Quando o Codex salvou a alteração, o diff do arquivo inteiro ficou cheio de ^M, o que significava que cada linha havia sido "alterada". Achei que fosse um bug do Codex, passei um tempão rascunhando uma issue, e no fim descobri que eu simplesmente não entendia as regras de quebra de linha do Windows.

Sendo sincero, hoje o Codex realmente roda de forma nativa no Windows, e a experiência não é ruim, mas não é a mesma coisa que no Mac/Linux. O mecanismo de sandbox tem duas versões exclusivas para Windows, os caminhos usam barra invertida e as quebras de linha são um fardo histórico. Se você não conhecer essas armadilhas de antemão, vai acabar caindo nelas mais cedo ou mais tarde.

Neste artigo, vamos esclarecer todos os detalhes no Windows: como instalar, como escolher entre nativo ou WSL, como evitar as três armadilhas específicas do Windows, quais as diferenças do sandbox em relação ao Mac/Linux e, por fim, rodar um exemplo mínimo no PowerShell passo a passo.

Ao ler este artigo, você obterá:

• Uma conclusão direta: qual é a forma de rodar no Windows que dá menos dor de cabeça, para você não ficar na dúvida
• O passo a passo completo para instalar o Codex usando o script oficial do PowerShell, além de algumas dependências prévias essenciais para Windows
• Uma lista de prós e contras para decidir entre "PowerShell Nativo vs WSL2": que tipo de usuário você é e qual caminho escolher
• Como evitar antecipadamente as três armadilhas exclusivas do Windows: barras invertidas em caminhos, quebras de linha CRLF e alertas de permissão Everyone
• A diferença das duas modalidades de sandbox do Windows (elevated / unelevated) em relação ao Mac/Linux, e o que fazer em caso de erro 1385
• Um fluxo prático para seguir passo a passo, rodando a sua primeira tarefa do Codex do zero no Windows

⚠️ Os comandos, configurações e comportamentos padrão são todos baseados na documentação oficial do Codex; nomes de modelos, limites de planos e números de versão podem mudar com atualizações, então guie-se pelo codex --help local e pela interface real. Indiquei em todos os comandos deste artigo se devem ser rodados no PowerShell ou no shell do WSL, certifique-se de não rodar no lugar errado.

---

01 一句话结论：Windows 上最省心的跑法

Deixe-me apresentar a conclusão de cara, para você não ficar hesitando:

Por padrão, use "Windows Nativo + sandbox elevated", que é a forma recomendada oficialmente, oferecendo a maior velocidade sem abrir mão da segurança. Só volte a usar o WSL2 se o seu fluxo de trabalho já for nativo do Linux ou se nenhum dos dois modos de sandbox nativos funcionar no computador da sua empresa.

Sei que muitos tutoriais antigos na internet dizem "recomenda-se unelevated no Windows" ou "recomenda-se instalar o WSL primeiro" — essas afirmações estão desatualizadas. A documentação oficial agora diz claramente: o sandbox nativo do Windows tem a melhor performance, é o mais rápido e oferece o mesmo nível de segurança que as outras plataformas; o elevated é a primeira escolha, enquanto o unelevated é apenas uma alternativa de contingência.

Analogia: Instalação de internet. O técnico vai até sua casa e instala primeiro a fibra óptica (elevated), que é a opção mais rápida e estável; apenas se o seu prédio não tiver fibra óptica ou a fiação for bloqueada pelo condomínio, você aceita como segunda opção um cabo de rede via LAN (unelevated); se nada disso funcionar, você cogita trabalhar na sala do vizinho que tem internet (WSL2). A maioria das pessoas instala a fibra direta e pronto, sem necessidade de se preocupar com as outras duas opções.

Na prática, essa escolha divide-se em três perfis de usuários:

• Você quer programar normalmente no Windows, usando as ferramentas do Windows — rode de forma nativa, com elevated, sem hesitar.
• Você usa um "computador corporativo controlado", e a TI bloqueou as permissões de administrador — se não conseguir instalar no modo nativo elevated, use o unelevated provisoriamente e notifique a TI.
• Seus projetos já estão no WSL e você está acostumado com ferramentas do Linux — rode direto dentro do WSL2, evite ficar alternando constantemente entre o Windows e o Linux.

💡 Resumo em uma frase: O padrão é "Windows Nativo + elevated"; o WSL2 é destinado a quem "já vive no ambiente Linux", e não como ponto de partida padrão.

---

02 安装与前置依赖

Para instalar a CLI do Codex no Windows, o caminho mais direto fornecido oficialmente é usar o script de instalação próprio para o PowerShell, que instala tudo com uma única linha.

Execute no PowerShell ou no Windows Terminal:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Se você já tem o Node.js instalado em sua máquina, também pode optar por este caminho alternativo oficial via npm:

npm install -g @openai/codex

Após a instalação, feche o terminal e abra um novo para atualizar o PATH, depois verifique a instalação:

codex --version

O retorno esperado é uma linha com a versão (o número específico dependerá da versão que você instalou), no formato aproximado codex 0.x.x. Se conseguir exibir essa informação, a instalação foi bem-sucedida.

Prefere uma interface gráfica ao invés da linha de comando? Há uma versão oficial do app desktop do Codex para Windows disponível para download diretamente na Microsoft Store; se não quiser abrir a interface da Store, você também pode instalar via winget install Codex -s msstore. Este artigo foca na CLI, então os comandos abaixo serão baseados na linha de comando codex.

Algumas dependências prévias para evitar problemas futuros:

Dependência	Por que é necessária	Como resolver
Windows 11 (Recomendado)	Linha de base preferencial oficial, mais estável	Atualize para o Windows 11; o Windows 10 também funciona, mas requer a versão 1809 ou mais recente
winget disponível	Necessário para instalar ferramentas de compilação C++ e o app desktop	Se estiver faltando, atualize o Windows ou instale o App Installer
Permissão de aprovação de administrador	Necessária para a inicialização do sandbox elevated	No computador pessoal, basta clicar em "Permitir"; em computadores corporativos, pode estar bloqueado
Ferramentas de compilação C++ (ao usar a extensão de IDE)	Algumas dependências nativas exigem compilação	winget install --id Microsoft.VisualStudio.2022.BuildTools -e

Quando instalei pela primeira vez no Windows 10, a extensão de IDE foi instalada com sucesso, mas ficava apenas carregando sem responder. Levei quase vinte minutos pesquisando até achar na seção de solução de problemas da documentação oficial: faltava a carga de trabalho de C++ do Visual Studio Build Tools. Adicionei o comando winget install indicado, reiniciei o VS Code e funcionou na hora. Portanto, se você também usa a extensão do Codex no VS Code, recomendo providenciar as ferramentas de compilação C++ logo no início.

💡 Resumo em uma frase: Um único script de instalação do PowerShell resolve a instalação da CLI do Codex. Quanto aos pré-requisitos, atente-se à versão do Windows, disponibilidade do winget e privilégios de administrador.

---

03 WSL vs 原生 PowerShell：你是哪种人

Esta é a primeira pergunta que os usuários do Windows precisam responder. Apesar de haver muita discussão na internet, o critério é simples: veja onde residem seu código e seu fluxo de trabalho diário.

Analogia: Onde estabelecer residência. O PowerShell nativo é como "morar na cidade do Windows", resolvendo os assuntos pelos processos nativos do Windows, o que é mais rápido e prático; o WSL2 é como "alugar uma casa Linux na cidade", onde você entra para trabalhar se quiser usar ferramentas e rodar scripts Linux. Ambos os ambientes são viáveis, mas você não deve ficar indo e voltando diariamente da sala do Windows para a sala do Linux — escolher um local de trabalho fixo evita transtornos.

Veja a tabela comparativa direta:

Dimensão	PowerShell Nativo	WSL2
Dificuldade de instalação	✅ Resolvido com um único script de instalação	❌ Exige instalar uma distribuição com wsl --install primeiro
Velocidade	✅ Mais rápido por ser nativo	I/O de arquivos um pouco mais lento, ainda mais lento entre diferentes letras de unidade
Implementação do sandbox	Exclusivo para Windows (elevated/unelevated)	Utiliza o sandbox bubblewrap do Linux
Compatibilidade de ferramentas	✅ Ferramentas nativas do Windows, .exe	✅ Ferramentas nativas do Linux, scripts bash
Indicado para quem	A maioria dos usuários de Windows	Quem já tem projetos hospedados no Linux

Quando escolher o PowerShell nativo? Se você é um usuário comum de Windows, costuma usar o VS Code para programar e o Git para Windows — use o modo nativo diretamente, sem se sobrecarregar instalando o WSL.

Quando escolher o WSL2? Em três situações: você precisa de uma cadeia de ferramentas nativa do Linux; seus repositórios e fluxos de trabalho já residem no WSL2; ou nenhum dos modos de sandbox nativos roda em sua máquina.

Se for usar o WSL2, comece instalando no "PowerShell executado como Administrador":

wsl --install
wsl

Ao acessar o shell do WSL, o Codex precisará ser instalado novamente dentro do Linux (a instalação feita no Windows não é compartilhada):

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Aqui está uma armadilha em que caí em abril de 2026: por conveniência, coloquei meus repositórios em /mnt/c/Users/... (ou seja, no disco C do Windows, montado no WSL). O Codex ficou lento demais, levando segundos apenas para rodar um git status. Descobri depois que a comunicação de I/O de arquivos do WSL acessando a partição montada do Windows (/mnt/c/...) é extremamente lenta. O correto é mover seus repositórios para o diretório base nativo do Linux:

mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo

Após a mudança, a velocidade normalizou de imediato. Quando precisar acessar esses arquivos a partir do Windows, basta digitar \\wsl$\Ubuntu\home\<user> no Explorador de Arquivos (substitua <user> pelo seu usuário do Linux). Aliás, vale mencionar que o WSL1 deixou de ser suportado a partir do Codex 0.115 (quando o sandbox passou a usar o bubblewrap), e como a instalação padrão do WSL hoje em dia já é o WSL2, você não precisa se preocupar com isso.

💡 Resumo em uma frase: Se seu código está no Windows, use o PowerShell nativo; se estiver no Linux, use o WSL2 e armazene o repositório em ~/, não sob /mnt/c.

---

04 Windows 特有的三个坑：路径、换行、权限

Armadilha 1: Barras invertidas nos caminhos

Os caminhos no Windows utilizam barras invertidas (C:\Users\You\project), enquanto os sistemas Unix usam barras normais (/home/you/project). O Codex lida automaticamente com essa diferença na maior parte do tempo, mas existem dois pontos em que você precisa ter atenção:

• Caminhos adicionados ao arquivo ~/.codex/config.toml: recomenda-se definir caminhos absolutos de forma estrita, como C:\absolute\directory\path.
• Ao adicionar diretórios de leitura permitida ao sandbox do Codex: o caminho precisa ser de um "diretório absoluto já existente". Use o comando abaixo (digitado na interface interativa do Codex):

/sandbox-add-read-dir C:\absolute\directory\path

Após a execução com sucesso, os comandos rodados no sandbox durante a sessão atual conseguirão ler esse diretório. Tenha em mente que isso se aplica apenas à sessão ativa; ao iniciar uma nova, será preciso adicioná-lo de novo.

Armadilha 2: Quebras de linha CRLF (a que me pegou no início)

Para deixar claro: esse é um comportamento comum de quebras de linha ao usar o Git no Windows, não um problema do Codex em si. Porém, como o Codex modifica arquivos, é muito provável que você se depare com isso ao utilizá-lo.

Analogia: Tomadas de diferentes padrões. O LF (quebra de linha Unix) e o CRLF (quebra de linha Windows) funcionam como tomadas com padrões incompatíveis: visualmente ambos representam uma "quebra de linha", mas tecnicamente um deles inclui um caractere de retorno \r. O projeto que você clonou de um colega no Mac/Linux usa LF, mas ao baixar no Windows o Git pode convertê-lo silenciosamente para CRLF. Quando o Codex faz modificações e salva, o arquivo inteiro é marcado como alterado no diff.

Foi exatamente aí que eu errei. A solução é padronizar a política de quebras de linha. O jeito mais fácil é colocar um arquivo .gitattributes na raiz do seu projeto para instruir o Git a não fazer conversões indesejadas:

* text=auto eol=lf

Ou desativar globalmente a conversão automática do Git (execute no PowerShell):

git config --global core.autocrlf false

A escolha de qual usar depende da convenção da sua equipe, mas a ideia principal é: impeça que as quebras de linha sejam alteradas silenciosamente entre plataformas, ou suas alterações e as do Codex acabarão poluídas por ruídos de formatação.

Armadilha 3: Alertas de permissão de escrita para Everyone

Ao rodar de forma nativa, o Codex pode emitir um aviso informando que "determinadas pastas possuem permissão de escrita para Everyone". Isso não é um bug — é um alerta de segurança indicando que as permissões dessas pastas no Windows são permissivas demais para que o sandbox possa protegê-las. A solução é revogar as permissões de gravação de Everyone nessas pastas e, em seguida, reiniciar o Codex ou executar novamente a inicialização do sandbox. Se não tiver certeza de como gerenciar as permissões, fale com a equipe de TI em vez de forçar.

Armadilha	Sintoma	Como evitar
Barras invertidas nos caminhos	Configurações ou caminhos de leitura não surtem efeito	Escreva caminhos absolutos; use caminhos absolutos já existentes ao rodar /sandbox-add-read-dir
Quebras de linha CRLF	Cada linha é sinalizada como modificada no diff, com tela cheia de ^M	Use .gitattributes para padronizar com eol=lf ou desative o core.autocrlf
Escrita para Everyone	O Codex emite alerta de que a permissão da pasta é ampla demais	Remova a permissão de gravação para Everyone e reinicie o Codex

💡 Resumo em uma frase: Escreva caminhos absolutos, configure as quebras de linha com o .gitattributes e dê atenção aos alertas de permissão. Evitando essas três armadilhas, o uso no Windows será tão fluido quanto no Mac.

---

05 Sandbox e permissões: Diferenças entre Windows e Mac/Linux

O sandbox do Codex (a barreira de segurança que o impede de realizar escritas não autorizadas ou estabelecer conexões indevidas com a rede) é implementado de formas diferentes em cada plataforma. O Mac utiliza o sandbox-exec do sistema, o Linux adota o bubblewrap, enquanto o Windows conta com uma estrutura própria e isolada em duas modalidades distintas.

No Windows nativo, sob o modo agent, o sandbox impedirá "gravações em arquivos fora do diretório de trabalho (working folder)" e bloqueará "acessos de rede não autorizados". Você pode configurá-lo no arquivo ~/.codex/config.toml (escreva no arquivo de configuração):

[windows]
sandbox = "elevated" # 或 "unelevated"

Veja a tabela comparativa das duas modalidades:

Modo	Nível de proteção	Como é implementado	Quando utilizar
elevated (Preferencial)	Mais forte	Usuário de sandbox dedicado de baixo privilégio + limites de permissão do sistema de arquivos + regras de firewall + ajustes nas políticas locais	Use como padrão, pois apresenta a melhor performance e segurança
unelevated (Alternativa)	Mais fraco	Token restrito herdado do seu usuário atual + limites no sistema de arquivos via ACL + controle offline em nível de ambiente	Utilizado temporariamente se o modo elevated não puder ser configurado

Atenção: Isso é exatamente o oposto do que alguns tutoriais antigos dizem ao "recomendar unelevated". A documentação oficial estabelece de forma clara que o elevated é a escolha padrão, e o unelevated funciona apenas como contingência quando o elevated falha devido a restrições de permissão. Por padrão, ambas as opções utilizam uma "área de trabalho privada" para isolamento de interface gráfica. Não desative windows.sandbox_private_desktop a menos que necessite de compatibilidade com comportamentos herdados de sessões do Windows Station Winsta0\Default.

Por que a instalação do modo elevated pode falhar? Esse modo requer a criação de um usuário dedicado para o sandbox, modificações nas regras de firewall e alterações de políticas locais. Em ambientes corporativos gerenciados, essas operações são frequentemente bloqueadas pelas diretivas de segurança da TI. O erro mais característico é o 1385 — o que significa que o Windows rejeitou os privilégios de logon requeridos pelo usuário do sandbox para rodar os comandos. Se encontrar o erro 1385, siga estas recomendações oficiais:

1. Solicite à equipe de TI a confirmação de que as diretivas do dispositivo concedem os privilégios de logon exigidos ao "usuário do sandbox criado pelo Codex".
2. Se apenas algumas máquinas apresentarem o problema, compare as diferenças de Diretivas de Grupo (GPO) ou Unidades Organizacionais (OU).
3. Se precisar trabalhar imediatamente, alterne para o modo unelevated como alternativa provisória.
4. Envie o log CODEX_HOME/.sandbox/sandbox.log junto com a sua versão do Windows para a equipe responsável analisar.

🔒 Existe um diretório que nunca deve ser exposto: a pasta CODEX_HOME/.sandbox-secrets/ contém chaves criptográficas. Ao coletar dados para resolução de problemas, envie exclusivamente o arquivo sandbox.log e desconsidere essa pasta.

Se determinado comando falhar sob a alegação de que "o sandbox não consegue ler determinada pasta", utilize o comando /sandbox-add-read-dir abordado no tópico 04 para adicionar o caminho correspondente.

💡 Resumo em uma frase: O sandbox do Windows oferece dois modos isolados. O padrão é elevated; use unelevated caso não consiga instalar. O erro 1385 geralmente indica que o logon foi barrado pelas políticas de TI do computador da empresa.

---

06 Prática: Executando sua primeira tarefa do Codex no Windows

Após abordar a teoria, vamos à prática. Siga os passos indicados a seguir no PowerShell nativo para criar um projeto e permitir que o Codex realize modificações nos arquivos.

Passo 1: Crie um projeto de testes simples (no PowerShell):

mkdir codex-win-test
cd codex-win-test
git init
"console.log('hi')" | Out-File -Encoding utf8 app.js

Dica rápida: Nas versões antigas do PowerShell (5.1), o comando Out-File -Encoding utf8 insere uma marca de ordem de byte (BOM) no arquivo, o que pode gerar ruídos de codificação no próximo git diff. No PowerShell 7+, você pode adotar Set-Content -Encoding utf8NoBOM para salvar arquivos sem o cabeçalho BOM, o que facilita o monitoramento das quebras de linha.

Passo 2: Defina as regras de quebras de linha para evitar o problema que citei no início. Crie um arquivo .gitattributes no diretório raiz do projeto:

* text=auto eol=lf

Passo 3: Inicialize o Codex:

codex

Ao rodar o sandbox nativo pela primeira vez, o Windows exibirá uma notificação do Controle de Conta de Usuário (UAC) solicitando acesso de administrador (esta é a fase de inicialização do modo elevated). No computador de uso pessoal, selecione "Sim"; se estiver em uma máquina corporativa com restrições, o Codex alternará automaticamente para o modo unelevated. Nesse caso, você visualizará uma mensagem informando sobre a alteração do modo — este é o comportamento alternativo padrão para continuar trabalhando.

Passo 4: Defina uma tarefa simples para o Codex, digitando o seguinte comando na interface interativa:

把 app.js 里的 'hi' 改成 'hello, codex on windows'

Resultado esperado: O Codex lerá o arquivo app.js, exibirá uma prévia das alterações (diff) e solicitará sua aprovação antes de aplicar (conforme as políticas padrão de permissão). Após a confirmação, ele gravará os dados em disco. Feito isso, visualize o conteúdo do arquivo:

Get-Content app.js

Você deverá ver:

console.log('hello, codex on windows')

Passo 5: Verifique se as quebras de linha continuam íntegras — este é o hábito mais importante a ser adotado no Windows:

git diff

Se você configurou o .gitattributes corretamente na etapa anterior, a alteração no diff constará apenas para aquela linha específica, sem a presença de ^M por todo o texto ou a notificação de que o arquivo inteiro foi reformatado. Se o diff apresentar divergências nas outras linhas, retorne ao tópico 04 (Armadilha 2) para corrigir a formatação.

Toda vez que configuro o Codex em um novo computador Windows, executo esse fluxo mínimo, prestando atenção especial à validação com git diff no final — essa virou uma regra que adotei após gastar uma tarde inteira lidando com as issues causadas por isso.

💡 Resumo em uma frase: Crie o projeto → crie o .gitattributes → inicialize → delegue uma tarefa simples → valide a quebra de linha com git diff. Seguindo estes cinco passos, o Codex estará pronto no Windows.

---

Resumo

Relembrando os pontos centrais abordados neste artigo:

• Forma padrão: Windows nativo + sandbox elevated. Esta é a escolha prioritária recomendada oficialmente, fornecendo o melhor desempenho e segurança total. O WSL2 é indicado apenas para desenvolvedores cujo fluxo de trabalho já se baseia no Linux.
• Instalacão: Utilize o script de instalação oficial do PowerShell para obter a CLI. Lembre-se de validar a versão do Windows, verificar se o winget está ativo e conferir as permissões administrativas. Se usar a extensão de IDE, certifique-se de configurar as ferramentas de compilação C++.
• Três armadilhas comuns: Use sempre caminhos absolutos, trave as quebras de linha como LF por meio do .gitattributes e não ignore avisos relacionados a permissões.
• Diferenças no sandbox: O Windows emprega duas soluções exclusivas (elevated e unelevated), distanciando-se do sandbox-exec do Mac e do bubblewrap do Linux. Se deparar com o erro 1385, o logon provavelmente foi barrado por diretrizes corporativas de TI.

A partir daqui, você está pronto para configurar o Codex em uma nova máquina Windows, decidir pelo uso nativo ou pelo WSL, precaver-se contra erros de caminho e quebras de linha e rodar com êxito seu primeiro teste, com validação do diff.

No fim das contas, utilizar o Codex no Windows é tão simples quanto no Mac, bastando se habituar aos detalhes de quebras de linha e aos modos de sandbox característicos do sistema; uma vez entendidos, não haverá novas dores de cabeça.

---

O próximo artigo 〔34 Prática Geral 〕marcará o encerramento do módulo sobre o Codex. Nele, consolidaremos todos os tópicos das partes anteriores (configuração, modelos, permissões, subagentes, automação, migração, adaptação para Windows...) em um projeto prático do início ao fim.

Fica uma reflexão: se você fosse iniciar um projeto hoje, do git clone até instruir o Codex a implementar a primeira funcionalidade, quais seriam as três principais configurações e regras que definiria de início? Nos vemos no próximo capítulo.

---

Leituras recomendadas

• Integrando modelos como o DeepSeek
• Quatro tipos de fluxos de trabalho diários: exploração, correção de bugs, refatoração e testes
• Extensões de IDE (VS Code, etc.)