OpenAI Codex: um guia passo a passo com 3 exemplos práticos

Resumo

• O OpenAI Codex é um agente de engenharia de software em nuvem disponível dentro do ChatGPT (planos Plus, Pro, Team e Enterprise)

• Conecte o Codex a um repositório no GitHub e atribua tarefas: corrigir bugs, aplicar patches, gerar testes ou explicar código

• Cada tarefa roda em um sandbox isolado; o Codex abre um pull request para você revisar antes de fazer o merge

• Use um arquivo AGENTS.md para definir convenções de codificação que o Codex vai seguir em todas as tarefas

• O Codex também roda no terminal via Codex CLI e como uma extensão do VS Code

O que é o Codex da OpenAI?

O OpenAI Codex é um agente de engenharia de software em nuvem que escreve e edita código, executa testes, corrige bugs e até propõe pull requests. Cada tarefa é executada em um ambiente isolado (sandbox).

O Codex é alimentado pelos modelos de fronteira mais recentes da OpenAI e foi projetado para segurança, testabilidade e produtividade para desenvolvedores. Você pode orientar o Codex usando arquivos AGENTS.md ou interagir com ele diretamente na barra lateral do ChatGPT.

Com o Codex CLI, você também leva esses recursos direto para o seu terminal.

Visão geral das formas de acesso ao Codex:

Configurando o Codex da OpenAI

Configurar o Codex leva só alguns minutos. Aqui vai um passo a passo para você começar.

Passo 1: localizando a ferramenta Codex

Comece fazendo login no ChatGPT. Na barra lateral esquerda, procure por Codex. No lançamento, o Codex foi liberado para usuários Pro, Business e Enterprise. Hoje, ele está incluído em todos os planos (embora o acesso nos planos Free e Go seja bem limitado).

Passo 2: começando com o Codex

Clique em Codex e você será levado a outra aba para a configuração inicial. Clique em “Get Started” e siga o procedimento de autenticação mostrado no próximo passo.

Passo 3: autenticação em duas etapas

Clique em “Set up MFA to continue” e escaneie o QR code usando seu app de autenticação preferido (como Google Authenticator ou Authy). Digite o código para verificar e pronto!

Passo 4: conecte ao GitHub

Depois de ativar a autenticação em duas etapas, conectamos o Codex ao GitHub.

Passo 4.1: autorize o conector do GitHub

“Connect to GitHub” abrirá um pop-up para autorizar o conector do GitHub. Leia o pop-up e autorize.

Passo 4.2: adicionando sua conta do GitHub

Com o GitHub conectado, precisamos adicionar nossa conta. Na aba da organização do GitHub, selecione “Add a GitHub account”. 

Isso abrirá outro pop-up para “Install and Authorize”. Clique para autorizar e todos os seus repositórios aparecerão na interface do ChatGPT. Você também pode autorizar apenas repositórios selecionados.

Passo 4.3: criando um ambiente

Escolha o repositório em que você quer trabalhar e clique em “Create environment”.

Você será levado aos “Data Controls”. O Codex ainda está em desenvolvimento ativo e pode aparecer um prompt opcional para permitir o uso dos seus dados para melhorar o modelo. Você pode desativar isso e continuar.

Agora seu ambiente está pronto para ser explorado. O Codex permite iniciar tarefas em paralelo com tarefas pré-selecionadas.

Basta clicar em “Start tasks” ou escolher tarefas conforme sua necessidade. Isso abrirá uma interface para você fazer perguntas ou pedir para o agente programar um recurso para você.

Quando tudo estiver pronto, selecione a tarefa em que você quer trabalhar — ou toque várias tarefas em paralelo.

Passo 5: arquivo AGENTS.md (opcional)

O arquivo AGENTS.md é um arquivo especial de configuração introduzido pela OpenAI para uso com a plataforma Codex, criado para orientar os agentes de IA enquanto trabalham na sua base de código. Pense nele como um manual do desenvolvedor para colegas de time com IA, similar a um README.md, mas focado em instruções para agentes autônomos. Veja um exemplo de arquivo AGENTS.md:

# AGENTS.md

## Code Style
- Use Black for Python formatting.
- Avoid abbreviations in variable names.

## Testing
- Run pytest tests/ before finalizing a PR.
- All commits must pass lint checks via flake8.

## PR Instructions
- Title format: [Fix] Short description
- Include a one-line summary and a "Testing Done" section

Quando o Codex executa uma tarefa na sua base de código, ele:

• Procura arquivos AGENTS.md cujo escopo inclua o(s) arquivo(s) que ele está modificando.
• Aplica as instruções desses arquivos para formatar, testar e documentar as mudanças.
• Prioriza instruções mais profundas na hierarquia quando vários arquivos se aplicam (como uma configuração em cascata).

Para uma visão mais ampla sobre como construir sistemas que agem em diversas ferramentas e APIs, veja nosso tutorial do OpenAI Agents SDK.

OpenAI Codex: três exemplos práticos

Vamos ver como o Codex pode te ajudar no desenvolvimento do dia a dia com três exemplos que rodei em um repositório.

Exemplo 1: correções básicas e typos

Às vezes, o Codex divide um pedido em subtarefas, como corrigir typos, melhorar o README ou escrever testes — tudo no mesmo workspace.

Você pode iniciar uma nova tarefa dentro de uma tarefa existente com base na revisão inicial, solicitar mudanças na base de código ou fazer perguntas pela caixa de texto. Para estender a tarefa ou corrigir algo novo, clique em “Code” e inicie um novo subtask diretamente.

Quando estiver satisfeito com as alterações, clique em “Push”, o que criará um novo pull request. Após alguns segundos, clique em “View Pull Request” para acessar o PR e fazer o merge na main.

Exemplo 2: explicação da codebase

Em seguida, usei o Codex para uma tarefa sem edição: explorar a base de código e perguntar o que eu poderia fazer a seguir. Isso é especialmente útil se você é novo em um projeto, quer se ambientar rápido ou está empacado tentando entender como uma função funciona.

O Codex navegou pelo projeto e trouxe uma visão clara e amigável para iniciantes da estrutura da base de código. Em vez de só listar arquivos, agrupou por finalidade:

• Destacou que qwen3_demo.py é o script principal, lançando duas interfaces baseadas em Gradio — uma para alternar modos de raciocínio e outra para tradução multilíngue.
• Identificou qwen3_demo.ipynb como um notebook interativo alternativo.
• Apontou test_qwen3_demo.py para testes de unidade e README.md para documentação e tutoriais em vídeo.

Além disso, o Codex listou “Pontos-chave”, como dependências (Ollama CLI), o papel da função _run_ollama e dicas para estender a interface. Ele ainda sugeriu próximos passos, como explorar versionamento de modelos, melhorar a UI e adicionar tratamento de erros.

Exemplo 3: encontrar e corrigir um bug

O Codex consegue vasculhar toda a codebase, identificar um bug, propor uma correção e mostrar um preview das mudanças. O processo lembra as revisões de mudança de código no GitHub.

Você pode revisar os logs para entender o que aconteceu em segundo plano clicando em “Logs”.

O Codex retorna um resumo das mudanças realizadas, além dos arquivos criados ou afetados. Você também pode tirar dúvidas sobre as alterações ou pedir para o Codex escrever novo código para aprimorar a implementação atual.

Quando estiver tudo ok com as correções, clique em “Push” e “Create New PR” para abrir um novo pull request.

Depois de alguns segundos, clique em “View Pull Request” para acessar o PR e fazer o merge na main.

O Codex permite fazer o merge das mudanças com poucos cliques.

As mudanças aparecem na branch principal em segundos.

Por que o Codex é importante?

O Codex é um agente colaborativo, não um gerador de código passivo. Você pode pedir para escrever, refatorar, testar, depurar ou explicar — e ele te mostra os logs de terminal, referências e saídas de cada etapa.

Aqui estão alguns benefícios práticos que observei:

• As tarefas são rastreáveis e verificáveis.
• O Codex trabalha em paralelo, então você pode enfileirar várias mudanças.
• Ele respeita sua configuração de desenvolvimento, principalmente se você definiu convenções em um arquivo AGENTS.md.
• Se alinha aos padrões humanos de PR e consegue passar nos testes de CI.

Para mim, a sensação é de que a OpenAI acabou de lançar um estagiário de engenharia de software.

Considerações finais

Vimos como o Codex consegue corrigir bugs, aplicar patches de recursos e explicar a lógica do código — tudo enquanto gera pull requests, executa testes e registra suas ações em logs de terminal e diffs.

Este passo a passo prático mostra como o Codex pode turbinar seu fluxo de trabalho diário, seja depurando código legado, entrando em um repositório novo ou triando tarefas de manutenção.

À medida que o Codex evolui, espero integrações mais profundas com IDEs, pipelines de CI e planejadores de tarefas, tornando-o um reforço prático para qualquer workflow de engenharia. Para saber mais sobre o Codex, leia o post oficial de lançamento, e você também encontra casos de uso no canal da OpenAI no YouTube.

Para se aprofundar nos modelos e ferramentas da OpenAI voltados para engenharia, recomendo estes blogs:

• Tutorial do OpenAI Codex CLI
• Guia do GPT-5.1 Codex: construindo um agente analisador de issues do GitHub
• Codex CLI para automação de workflows de dados: guia completo
• Tutorial Codex CLI MCP: construindo um agente de dashboard de portfólio