Quem desenvolve no Windows e quer usar o Codex CLI já percebeu que a documentação oficial da OpenAI prioriza macOS e Linux. O Codex CLI Windows depende de configurações que não vêm prontas de fábrica — WSL 2, Node.js, variáveis de ambiente — e cada etapa mal feita vira bloqueio. Mas com o roteiro certo, a instalação leva menos de 10 minutos e o terminal passa a executar tarefas de programação com um comando. Este tutorial mostra como ter o Codex CLI Windows rodando sem atalhos e sem frustração.
Imagem sugerida: Banner do Codex CLI em execução dentro do Windows Terminal, com WSL 2 ativo e uma sessão de comandos sendo processada. Alt text: "Codex CLI rodando no Windows 11 com WSL 2 — terminal exibindo agente da OpenAI em ação."
Sumário
O problema: agentes no Windows ainda têm barreiras
O Codex CLI é o agente de terminal da OpenAI que transforma instruções em linguagem natural em código funcional. Ele entende o contexto do repositório, edita arquivos, executa comandos e interage com Git. No macOS e Linux, a instalação é simples. No Windows, o cenário é outro.
Os problemas mais comuns ao tentar instalar o Codex CLI no Windows incluem:
- WSL 2 ausente ou desatualizado: o Codex CLI foi construído para ambientes Unix e depende do subsistema Linux.
- Node.js instalado no lugar errado: o Node.js do Windows não é acessível de dentro do WSL.
- PATH mal configurado: o npm global pode não estar no caminho de execução dentro do WSL.
- Permissões de diretório: projetos em montagens do Windows (
/mnt/c/) geram erros de permissão.
Cada problema tem solução direta. Resolvidos em conjunto, o Codex CLI Windows funciona com a mesma eficiência que em qualquer outro sistema operacional.
Imagem sugerida: Print de tela com erro "command not found" ao tentar rodar Codex CLI sem a configuração correta de PATH no WSL. Alt text: "Erro de comando não encontrado ao tentar executar Codex CLI no Windows sem configurar o PATH do npm global."
Pré-requisitos
Windows 11 (build 22000 ou superior)
O Windows 11 oferece o melhor suporte ao WSL 2, com desempenho de I/O e gerenciamento de memória superiores. Versões antigas do Windows 10 podem funcionar, mas a experiência não é garantida.
WSL 2 com Ubuntu 22.04 LTS
O Codex CLI executa comandos usando chamadas POSIX. Sem o WSL 2, ele não funciona no Windows.
Para instalar, abra o PowerShell como administrador:
Reinicie o computador e conclua a configuração inicial do Ubuntu.
Node.js 18+ instalado dentro do WSL
O Codex CLI é distribuído via npm. A instalação deve ser feita dentro do WSL, usando nvm para evitar conflitos de permissão.
Git configurado
O Codex CLI usa Git para entender o contexto do repositório. Verifique com git --version dentro do WSL.
Chave de API da OpenAI
Você precisa de uma chave válida, obtida no portal da OpenAI.
Imagem sugerida: Windows Terminal com três abas — PowerShell (admin), WSL Ubuntu e diretório do projeto. Alt text: "Windows Terminal configurado com abas de PowerShell, WSL Ubuntu e diretório do projeto para Codex CLI."
Instalação passo a passo do Codex CLI Windows
Com os pré-requisitos atendidos, a instalação do Codex CLI Windows leva menos de 5 minutos.
1. Atualize o WSL e instale dependências
Abra o terminal do WSL:
2. Instale o Node.js via nvm
A saída deve exibir v20.x.x.
3. Instale o Codex CLI globalmente
4. Configure a chave de API
Adicione ao ~/.bashrc:
Confirme com echo $OPENAI_API_KEY.
5. Verifique a instalação
Se o README.md for gerado, a instalação está completa.
6. (Opcional) Configure o modelo
Imagem sugerida: Três capturas lado a lado: instalação npm, configuração da API key no .bashrc, primeiro comando executado. Alt text: "Passo a passo da instalação do Codex CLI no WSL: npm install, configuração da API key e primeiro comando."
Primeiros comandos
A sintaxe básica do Codex CLI é:
O agente analisa o diretório atual e executa a instrução — cria arquivos, edita código, instala pacotes, executa testes.
Comandos úteis para começar:
O Codex CLI também entende comandos com múltiplas etapas, como "Crie uma rota POST /usuarios, valide os campos e escreva um teste para cada erro."
Imagem sugerida: Terminal mostrando o Codex CLI processando um comando em linguagem natural e gerando múltiplos arquivos. Alt text: "Codex CLI processando comando em linguagem natural e gerando arquivos no diretório do projeto."
Exemplo prático: gerar uma API
Vamos usar o Codex CLI Windows para criar uma API REST completa em Node.js.
Peça ao Codex CLI para gerar a API:
O agente analisa o pedido e gera os arquivos. Durante o processo, ele pode pedir confirmação antes de modificar arquivos — é o comportamento padrão de segurança.
Depois do código gerado:
Acesse http://localhost:3000/tarefas. Se a resposta for [], a API está no ar e o Codex CLI Windows funcionou como esperado.
Imagem sugerida: Terminal dividido em duas janelas: à esquerda o Codex CLI gerando arquivos, à direita o servidor Express rodando e respondendo a curl. Alt text: "Codex CLI gerando API REST em Node.js no Windows — servidor Express rodando."
Dicas e troubleshooting
Codex CLI não encontrado
Solução: adicione ao ~/.bashrc:
Erro de permissão
Solução: mantenha o projeto em /home/usuario/..., não em /mnt/c/.... O ext4 do WSL não tem as restrições do NTFS.
API key inválida
Solução: verifique echo $OPENAI_API_KEY e confirme que a chave está ativa no portal da OpenAI.
Codex CLI lento
Solução: para tarefas simples, use codex config set model "gpt-4o-mini". O modelo é mais rápido e mais barato.
WSL consumindo muita RAM
Crie %USERPROFILE%\.wslconfig:
Reinicie com wsl --shutdown no PowerShell.
Imagem sugerida: Bloco de Notas exibindo o .wslconfig com limite de 4 GB de RAM. Alt text: "Arquivo .wslconfig configurado para limitar memória do WSL 2 a 4 GB."
Perguntas frequentes
Codex CLI funciona nativamente no Windows ou precisa de WSL?
Precisa do WSL 2. Foi desenvolvido para Unix e depende de chamadas de sistema inexistentes no kernel Windows.
Qual a diferença entre Codex CLI e Claude Code?
Codex CLI é o agente da OpenAI com modelos GPT. Claude Code é o agente da Anthropic com modelos Claude. Ambos operam no terminal, mas usam modelos e custos de API diferentes. Veja Claude Code e Codex no Windows para detalhes.
Codex CLI funciona com qualquer modelo da OpenAI?
Sim. Use codex config set model para alternar entre gpt-4o, gpt-4o-mini e outros.
Quanto custa?
O Codex CLI é gratuito. O custo está no consumo da API OpenAI, que varia conforme o modelo e os tokens processados.
Preciso de GPU?
Não. O processamento ocorre nos servidores da OpenAI. Qualquer notebook com Windows 11 e 8 GB de RAM roda sem dificuldade.
Codex CLI tem suporte a Git?
Sim. Ele integra-se com Git para entender o contexto do repositório e analisar alterações.
Comece a orquestrar seus agentes hoje
Agora que você tem o Codex CLI Windows funcionando, o próximo passo é integrá-lo ao seu ecossistema. O verdadeiro potencial aparece quando múltiplos agentes trabalham juntos — Codex CLI gerando back-end, Claude Code revisando arquitetura, OpenCode automatizando tarefas.
O Orquestra foi criado para isso: um canvas infinito nativo para Windows 11 onde você conecta Codex CLI, Claude Code e outras ferramentas em terminais lado a lado. Sem alternar abas, sem perder contexto, tudo em um único espaço.
Baixe o Orquestra gratuitamente por 7 dias e veja seus agentes trabalharem em sincronia.
*Artigo atualizado em 11 de julho de 2026. Leia também o guia de orquestração de Claude Code e Codex e confira os planos e preços do Orquestra.*
Pronto para orquestrar seus agentes?
Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.