Tutorial do OpenAI Codex CLI

Há um boom de IDEs com agentes, como Cursor AI e Windsurf, que entendem seu código-fonte, sugerem mudanças e até executam comandos por você. Tudo o que você precisa fazer é conversar com o agente de IA e seguir o fluxo — daí o termo "vibe coding".

A OpenAI, talvez se sentindo de fora desse movimento de vibe coding, lançou recentemente uma ferramenta open source que usa um modelo de raciocínio para entender o código-fonte e ajudar você a depurar ou até criar um projeto inteiro com um único comando.

Neste tutorial, vamos conhecer o Codex CLI da OpenAI e como configurá-lo localmente. Depois, vamos usar o comando Codex para montar um site a partir de uma captura de tela. Também vamos encarar um projeto mais complexo: treinar um modelo de machine learning e desenvolver a inferência com uma interface personalizada.

Mantemos nossos leitores por dentro do que há de novo em IA com o The Median, nossa newsletter gratuita de sexta-feira que explica as principais notícias da semana. Assine e fique afiado em poucos minutos por semana:

Você pode saber mais sobre Cursor AI e Windsurf em guias separados, e colocar a mão na massa com nossa trilha de aprendizado OpenAI Fundamentals.  

Imagem do autor

O que é o Codex CLI da OpenAI?

OpenAI Codex CLI é uma ferramenta de linha de comando open source que leva o poder dos mais novos modelos de raciocínio da OpenAI (o4) direto para o seu terminal. Essa CLI leve permite ler, modificar e executar código diretamente na sua máquina local. 

Ela foi pensada para ajudar desenvolvedores a criar funcionalidades mais rápido, corrigir bugs e entender melhor códigos desconhecidos. O mais importante: como a CLI roda localmente, seu código-fonte permanece seguro no seu ambiente, a menos que você o compartilhe.

Aqui estão os principais recursos do Codex CLI:

1. Instalação sem configuração: você começa com um simples comando do NPM.
2. Entradas multimodais:  a CLI aceita texto, capturas de tela ou diagramas, permitindo que o agente de IA gere ou edite código conforme necessário.
3. Fluxo de aprovações robusto: você escolhe seu nível de envolvimento entre três modos: Suggest, Auto Edit e Full Auto.
4. Roda totalmente no terminal: seu terminal vira editor de código, assistente de IA e um depurador poderoso. 

Mais detalhes sobre os modos de aprovação:

• Suggest (padrão): o agente lê arquivos e propõe edições ou comandos de shell, pedindo sua aprovação antes de aplicar mudanças. 
• Auto Edit: o agente pode ler e escrever arquivos automaticamente, mas ainda pede permissão antes de executar comandos de shell. 
• Full Auto: nesse modo, o agente lê, escreve e executa comandos de forma autônoma em um ambiente isolado, sem rede, limitado ao diretório atual. 

Se você está começando em IA e quer aprender o básico, recomendamos concluir a trilha AI Fundamentals.

Configurando o Codex CLI 

Siga estes passos para configurar o OpenAI Codex CLI no seu sistema.

Requisitos do sistema

Antes de instalar o Codex CLI, verifique se seu sistema atende aos seguintes requisitos:

• Sistemas operacionais:
• macOS 12+
• Ubuntu 20.04+/Debian 10+
• Windows 11 (WSL2 opcional)
• Node.js: versão 22 ou superior (recomendado LTS)
• Git: versão 2.23+ (opcional, mas recomendado para os helpers de PR).
• RAM: mínimo de 4 GB (8 GB recomendados para melhor desempenho).

Passos de instalação

1. Instale o Node.js: garanta que você tem a versão 22 ou superior. Baixe no site oficial do Node.js.
2. Instale o Git: se ainda não tiver, baixe e instale em git-scm.com. 
3. Configure o PowerShell: se você usa Windows, ajuste seu terminal PowerShell assim:
• Abra seu perfil do PowerShell executando:

$PROFILE

• Adicione esta linha ao perfil para definir o Git Bash como shell padrão:

Set-Alias sh.exe "C:\Program Files\Git\bin\bash.exe"

4. Instale o Codex CLI: rode o comando abaixo para instalar globalmente:

npm install -g @openai/codex

5. Defina sua OpenAI API Key: para usar o Codex CLI, você precisa de uma chave da OpenAI. Exporte-a como variável de ambiente:

export OPENAI_API_KEY="your-api-key-here"

Usando o Codex CLI

1. Digite o comando abaixo no terminal para abrir o modo interativo:

codex

2. Se você não estiver em um repositório Git, verá um aviso dizendo que é perigoso criar um projeto fora de um repositório Git. Quando for perguntado, pressione “N” para continuar.

3. Navegue até o diretório do seu projeto usando o comando cd:

cd <project-directory>

4. Se seu projeto ainda não for um repositório Git, inicialize-o com:

git init

5. Dentro do diretório do projeto, digite o comando abaixo para usar o Codex CLI em modo interativo:

codex

Nesse modo, você conversa com o agente de IA de forma semelhante ao ChatGPT. Basta digitar suas dúvidas de programação e a IA vai ajudar gerando, depurando ou modificando o código conforme necessário.

Construindo o site com o Codex CLI

Neste projeto, vamos usar o Codex CLI para criar um site inspirado no CodeCut usando uma captura de tela do design. Por que o CodeCut? Sou fã do trabalho da Khuyen Tran e quis reproduzir o estilo do site dela, adicionando meu próprio tempero.

1. Primeiro, acesse o site do CodeCut e faça uma captura da landing page.

Fonte: CodeCut

2. Informe ao Codex CLI o local da captura com o comando:

 codex --image "C:\Users\abida\Pictures\Screenshots\Screenshot 2025-04-19 213702.png"

3. O agente do Codex CLI vai analisar a imagem e pedir para você enviar uma pergunta de acompanhamento. 

Por padrão, ele usa o novo modelo O4-Mini. Você pode conhecer os fundamentos do O4 lendo o guia O4-Mini: testes, recursos, comparação com O3, benchmarks e mais.

4. Peça para o agente criar um site semelhante com o logo “🙌” e o nome da empresa handsup.

5. O agente pode fazer perguntas adicionais para executar comandos de criação de arquivos e inclusão de código.

6. No fim do processo, o agente fornece um resumo das mudanças realizadas. 

7. Para atualizar a imagem hero, navegue até a pasta assets e substitua a imagem atual pela ilustração escolhida. Lembre-se de renomear o novo arquivo com o mesmo nome da imagem original. A imagem original era bem simples; eu queria uma ilustração mostrando todo mundo levantando as mãos em um escritório.
8. Clique duas vezes no arquivo index.html para ver seu site. 

O resultado ficou melhor do que eu imaginava. O logo, o título, a paleta de cores, os links e o design geral ficaram totalmente alinhados com o que eu queria. 

Construindo a aplicação de inferência de ML 

No segundo projeto, vamos encarar algo mais complexo: construir uma aplicação completa de machine learning. Vamos cobrir tudo, do carregamento de dados até a criação de um pipeline de inferência com uma interface personalizada. 

Além disso, vamos dar autonomia total ao agente, permitindo que ele execute comandos sem intervenção do usuário. 

1. Usando o comando abaixo, pedimos ao Codex para construir a aplicação:

codex --approval-mode full-auto "Build a proper FastAPI ML application with user interface."

Como resultado, o agente criou um projeto com todos os arquivos e configurações necessários. Tudo o que você precisa fazer é seguir o comando final para rodar a aplicação.

2. Para instalar os pacotes Python, execute:

pip install -r requirements.txt

3. Em seguida, rode o script de treino:

$ python train.py

Model saved to C:\Repository\GitHub\ML App with Codex\model\model.pkl

4. Depois, rode o app com:

uvicorn app.main:app -reload

5. Abra o navegador e cole a URL http://127.0.0.1:8000 para acessar o app.

A aplicação está totalmente funcional e entrega alta acurácia. 

Fiquei especialmente impressionado com a interface e com a velocidade com que o Codex CLI gerou todos os arquivos sem bugs. 

Embora este projeto seja um exemplo — já implementado por muitos desenvolvedores — vale notar que, mesmo em algo direto assim, a maioria dos LLMs não consegue entregar tudo funcionando de primeira. Com o Codex, digitei um único comando e ele entregou um resultado excelente. Fiquei realmente impressionado.

Não detalhamos o funcionamento interno da CLI. Se você quer aprender e usar a OpenAI API nos seus projetos, faça o curso Developing AI Systems with the OpenAI API.

Considerações finais

Embora o OpenAI Codex CLI não seja uma ideia totalmente inédita, o grande diferencial é ser open source e permitir conectar sua conta da OpenAI para aproveitar modelos ainda mais avançados.

Pessoalmente, acho o Codex CLI uma alternativa melhor em muitos casos. Exige menos passos para chegar ao objetivo, é muito rápido e simplifica o desenvolvimento. Mas a única forma de saber se ele funciona para o seu caso é testando. Ele brilha em fluxos simples, mas pode não ser a melhor escolha para projetos complexos, com muitas partes móveis.

Como vimos, a OpenAI lançou recentemente um novo modelo, GPT-4.1, ao lado dos já existentes o4-mini e o3. Para saber mais sobre o GPT-4.1 — recursos, comparações com o GPT-4o e como acessar — leia o post GPT 4.1: recursos, acesso, comparação com GPT-4o e mais.