Projeto 4: Agentic com Codex CLI

O que é

O OpenAI Codex CLI é um agente de terminal lançado pela OpenAI em abril de 2025. Trata-se de uma ferramenta open-source escrita em TypeScript (com partes em Rust) que roda diretamente no seu terminal e permite interagir com modelos da OpenAI — como o o4-mini, gpt-4o e o3 — para executar tarefas de desenvolvimento de software de forma autônoma.

Ao contrário de ferramentas como Copilot (que apenas completa código) ou ChatGPT (que responde em uma interface web), o Codex CLI age diretamente no seu sistema de arquivos: lê arquivos, escreve código, executa comandos shell, cria branches git e navega pelo projeto como um desenvolvedor real sentado ao seu lado.

Por que usar

▸ Integração nativa com OpenAI: acesso direto aos modelos de raciocínio como o3 e o4-mini, especialmente bons em programação e lógica complexa.
▸ Open-source: código disponível no GitHub, auditável, contribuível e hospedável em infraestrutura própria.
▸ Modos de aprovação granulares: você controla exatamente o nível de autonomia do agente — de apenas sugestões até execução totalmente autônoma.
▸ Ideal para CI/CD: modo --headless permite integrar o Codex em pipelines automatizados sem intervenção humana.
▸ Sandbox configurável: o agente pode ser restrito a apenas ler arquivos, ou liberado para executar qualquer comando shell conforme necessário.

Codex CLI vs Claude Code — quando usar cada um

Ambas são ferramentas de agentes de terminal, mas cada uma tem pontos fortes distintos. A escolha depende do seu ecossistema, modelo preferido e nível de autonomia desejado.

◆ Use Codex CLI quando:

· Já usa OpenAI API e quer consistência
· Precisa do o3/o4-mini para raciocínio profundo
· Quer controlar o código-fonte da ferramenta
· Automatiza tarefas em CI/CD com --headless
· Prefere configuração via TOML

◆ Use Claude Code quando:

· Quer a melhor experiência de UX integrada
· Precisa de contexto de janela muito longo
· Usa o ecossistema Anthropic (Claude Opus 4)
· Prefere CLAUDE.md para contexto persistente
· Trabalha muito com análise de arquivos grandes

O que é o processo de setup

A instalação do Codex CLI é feita via npm e requer apenas uma chave de API da OpenAI. O processo completo leva menos de 5 minutos: instalar o pacote globalmente, exportar a variável de ambiente com a chave e iniciar a primeira sessão dentro do diretório do projeto.

Por que o setup é simples

Por ser distribuído como pacote npm, o Codex CLI não requer dependências adicionais além do Node.js 18+. A autenticação é feita por variável de ambiente padrão da OpenAI (OPENAI_API_KEY), o que significa que qualquer projeto que já usa a API da OpenAI já tem a autenticação configurada.

Como instalar e configurar

1. Instalar globalmente via npm:

terminal

$ npm install -g @openai/codex

# Verificar instalação
$ codex --version
1.0.0

2. Configurar autenticação:

~/.bashrc ou ~/.zshrc

# Adicionar ao seu arquivo de perfil do shell
export OPENAI_API_KEY="sk-proj-..."

# Recarregar o perfil
$ source ~/.bashrc

3. Primeira execução (modo interativo):

terminal

# Entrar no diretório do projeto
$ cd meu-projeto

# Iniciar sessão interativa (modo padrão: suggest)
$ codex

# Ou passar uma tarefa diretamente
$ codex "adicione validação de email no endpoint POST /users"

# Com modo de aprovação específico
$ codex --approval-mode auto-edit "corrija os testes quebrados"

4. Estrutura mínima de um projeto com Codex:

estrutura de arquivos

meu-projeto/
├── AGENTS.md          # Contexto persistente para o Codex
├── .codex/
│   └── config.toml   # Configuração do Codex CLI
├── src/
├── package.json
└── README.md

O que é o AGENTS.md

O AGENTS.md é o arquivo de contexto persistente do Codex CLI — injetado automaticamente no início de toda sessão. É o equivalente direto do CLAUDE.md do Claude Code, mas com algumas diferenças importantes na semântica e estrutura recomendada.

O arquivo serve como "briefing" permanente: descreve o projeto, as convenções de código, os comandos disponíveis, as regras de comportamento e qualquer contexto que o agente precisa para trabalhar de forma eficaz sem precisar reler o projeto inteiro a cada sessão.

Por que o AGENTS.md é essencial

Sem um AGENTS.md bem escrito, o agente precisa inferir o contexto do projeto a cada sessão, o que aumenta o custo de tokens, reduz a precisão das respostas e pode levar a comportamentos inconsistentes. Com um AGENTS.md completo:

▸ O agente sabe imediatamente as convenções sem precisar analisar o código existente
▸ Comandos de teste e build ficam disponíveis imediatamente — o agente pode rodar testes corretamente
▸ Regras de segurança (nunca modificar X, sempre criar branch Y) são respeitadas desde o início
▸ A arquitetura explicada evita que o agente coloque código no lugar errado

Seções obrigatórias e como escrever

Seções obrigatórias

Contexto do projeto (o que é, stack)
Comandos de desenvolvimento
Comandos de teste
Convenções de código
Regras de comportamento
Arquitetura / estrutura de pastas

Diferenças: AGENTS.md vs CLAUDE.md

· Nome: AGENTS.md (Codex) vs CLAUDE.md (Claude Code)
· Config: AGENTS.md referenciado no config.toml
· Escopo: AGENTS.md permite múltiplos arquivos de contexto via extra_context
· Formato: ambos usam Markdown padrão

AGENTS.md — estrutura recomendada

# AGENTS.md — Guia de Contexto para o Codex CLI

## 1. Contexto do Projeto
**Nome:** Nome do Projeto
**Stack:** Node.js 20, Express, PostgreSQL, Redis
**Descrição:** O que o projeto faz e para quem

## 2. Comandos de Desenvolvimento
```bash
npm run dev    # Servidor em modo desenvolvimento
npm test       # Testes unitários
npm run lint   # Verificar estilo de código
```

## 3. Convenções de Código
- camelCase para variáveis e funções
- PascalCase para classes
- Sempre usar async/await (nunca callbacks)

## 4. Regras de Comportamento
### NUNCA faça:
- Modificar arquivos .env
- Alterar package.json sem aprovação

## 5. Arquitetura
src/modules/{modulo}/{modulo}.controller.js
src/modules/{modulo}/{modulo}.service.js

O que é o config.toml

O arquivo .codex/config.toml é a configuração central do Codex CLI para o projeto. Define qual modelo usar, como o agente deve pedir aprovação antes de agir, quais comandos shell são permitidos e quais arquivos nunca devem ser modificados automaticamente.

Os três modos de aprovação

suggest

O agente apenas sugere mudanças. Você vê o diff e decide se aplica. Ideal para exploração e aprendizado. Mais lento, mais seguro.

auto-edit

O agente edita arquivos automaticamente, mas pede aprovação antes de executar comandos shell. Equilíbrio entre velocidade e controle. Recomendado para desenvolvimento diário.

full-auto

O agente age sem pedir aprovação para nada. Ideal para CI/CD e automação headless. Use apenas com sandbox restrito e comandos bloqueados configurados.

Como configurar — config.toml completo

Modos de sandbox de rede:

read-only

Apenas lê arquivos. Não escreve, não executa nada.

workspace-write

Escreve apenas no workspace atual. Bloqueia acesso ao sistema.

danger-full-access

Acesso total ao sistema. Use apenas em containers isolados.

.codex/config.toml

# Codex CLI — Configuração do Projeto

[model]
provider = "openai"
name = "o4-mini"       # Alternativas: "gpt-4o", "o3"
temperature = 0.2

[approval]
mode = "auto-edit"     # suggest | auto-edit | full-auto
require_approval = [
  "*.env", ".env.*",
  "package.json",
  "Dockerfile"
]

[sandbox]
network = "workspace-write"
allow_shell = ["npm test", "npm run lint", "git status"]
deny_shell = ["npm publish", "git push --force", "sudo"]

[context]
agents_file = "AGENTS.md"
extra_context = ["README.md"]
max_context_files = 10

[telemetry]
enabled = false

O que é o modo headless

O modo headless do Codex CLI permite executar o agente sem interface interativa, recebendo a tarefa como argumento e retornando o resultado via stdout. É ativado com a flag --headless (ou -H) e combinado com --approval-mode full-auto para execução totalmente autônoma.

Isso abre um leque enorme de possibilidades: o Codex pode ser invocado em pipelines de CI/CD para revisar código automaticamente, gerar changelogs, corrigir code style, criar documentação ou até abrir pull requests com base em issues do GitHub.

Por que usar automação com Codex

▸ Code review automático: o Codex analisa cada PR e comenta problemas de qualidade, segurança e convenções antes de um humano revisar.
▸ Auto-fix de linting: em vez de apenas reportar erros, o agente pode corrigi-los automaticamente em um commit separado.
▸ Geração de testes: toda vez que um novo arquivo de feature é criado, um job de CI pode pedir ao Codex para gerar os testes correspondentes.
▸ Changelog automático: ao mergear uma branch, o Codex analisa os commits e gera uma entrada de changelog semântico.

Como integrar com GitHub Actions

.github/workflows/codex-review.yml

name: Codex Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Instalar Codex CLI
        run: npm install -g @openai/codex

      - name: Revisar PR com Codex
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --headless \
            --approval-mode full-auto \
            "Revise as mudanças neste PR. Verifique: \
             1) Convenções de código do AGENTS.md \
             2) Possíveis bugs ou problemas de segurança \
             3) Cobertura de testes adequada \
             Crie o arquivo .codex-review.md com seu feedback."

      - name: Comentar review no PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('.codex-review.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review
            });

uso headless via linha de comando

# Modo headless básico
$ codex --headless "liste todos os endpoints sem testes"

# Com full-auto (sem aprovação)
$ codex -H --approval-mode full-auto \
  "corrija todos os erros de ESLint e faça commit"

# Com output para arquivo
$ codex -H "gere changelog dos últimos 10 commits" \
  > CHANGELOG_DRAFT.md

# Em script de pre-commit
$ codex -H --approval-mode suggest \
  "verifique se este commit segue as convenções do AGENTS.md"

O que são cada ferramenta

Ambas são ferramentas de agentic coding que rodam no terminal, leem e escrevem arquivos, executam comandos e interagem com o seu repositório de forma autônoma. A diferença fundamental está no ecossistema de modelos: Claude Code usa os modelos Anthropic (Claude Sonnet, Claude Opus), enquanto o Codex CLI usa os modelos OpenAI (GPT-4o, o3, o4-mini). Cada ecossistema tem suas forças.

Por que comparar importa

A maioria dos projetos pode usar ambas as ferramentas de forma complementar. Conhecer os pontos fortes de cada uma permite escolher a ferramenta certa para cada tipo de tarefa. Por exemplo: usar Codex CLI com o4-mini para refatorações complexas que precisam de raciocínio profundo, e Claude Code para análise rápida de código com janela de contexto longa.

Tabela de decisão

Critério	Claude Code	Codex CLI
Arquivo de contexto	`CLAUDE.md`	`AGENTS.md`
Configuração	CLAUDE.md + flags	.codex/config.toml
Modelos disponíveis	Claude Sonnet, Opus	GPT-4o, o3, o4-mini
Janela de contexto	200k tokens	128k tokens
Raciocínio profundo	Claude Opus (forte)	o3/o4-mini (excelente)
Modo headless / CI	Parcial	Nativo e robusto
Open-source	Não	Sim (GitHub)
Modos de aprovação	Básico	3 modos granulares
UX interativa	Excelente	Boa
Custo por tarefa	Anthropic pricing	OpenAI pricing

Recomendação: Use Codex CLI quando precisar de raciocínio profundo em código, automação em CI/CD ou controle granular de aprovações. Use Claude Code para análise de bases de código grandes (maior janela de contexto) e para uma experiência de desenvolvimento mais fluída no dia a dia.

Exemplo: AGENTS.md para projeto Node.js

exemplo real

Este é o AGENTS.md incluído neste projeto. Serve como referência para projetos Node.js/Express com PostgreSQL.

AGENTS.md

# AGENTS.md — Guia de Contexto para o Codex CLI

## 1. Contexto do Projeto
**Nome:** API de Gerenciamento de Tarefas (Task Manager API)
**Stack:** Node.js 20, Express 4.18, PostgreSQL 15 (Prisma 5), Redis 7
**Auth:** JWT + Refresh Tokens

## 2. Comandos de Desenvolvimento
```bash
npm install          # Instalar dependências
npm run dev          # Servidor com hot reload (porta 3000)
npm run db:migrate   # Aplicar migrations pendentes
npm run db:seed      # Popular banco com dados de dev
```

## 3. Comandos de Teste
```bash
npm test             # Testes unitários (Jest)
npm run test:watch   # Watch mode
npm run e2e          # Testes E2E (Supertest)
npm run test:coverage # Cobertura (meta: 80%)
```

## 4. Regras de Comportamento
### NUNCA faça sem aprovação:
- Modificar arquivos .env ou package.json
- Alterar migrations existentes (irreversível)
- Executar npm publish ou git push --force

### SEMPRE faça:
- Criar branches com prefixo feature/ ou fix/
- Rodar npm run lint antes de commits
- Adicionar testes para código novo

Exemplo: .codex/config.toml comentado

configuração completa

.codex/config.toml

# Codex CLI — Configuração do Projeto
# Documentação: https://github.com/openai/codex

[model]
provider = "openai"
name = "o4-mini"             # Modelo principal
# Alternativas: "gpt-4o", "o3", "o4-mini"
temperature = 0.2                # Baixo = mais determinístico

[approval]
# Modos: "suggest" | "auto-edit" | "full-auto"
mode = "auto-edit"
# Arquivos que sempre precisam de aprovação manual
require_approval = [
  "*.env", ".env.*",
  "package.json", "package-lock.json",
  "Dockerfile", "docker-compose*.yml"
]

[sandbox]
# Modos: "read-only" | "workspace-write" | "danger-full-access"
network = "workspace-write"
allow_shell = [             # Comandos permitidos sem aprovação
  "npm test", "npm run lint", "npm run build",
  "git status", "git diff", "git log --oneline -10"
]
deny_shell = [              # Comandos sempre bloqueados
  "npm publish", "git push --force",
  "rm -rf", "sudo"
]

[context]
agents_file = "AGENTS.md"     # Contexto lido em toda sessão
extra_context = [
  "README.md", "ARCHITECTURE.md"
]
max_context_files = 10

[telemetry]
enabled = false              # Desabilitar envio de dados

Tabela Comparativa Completa

Comparação detalhada entre Claude Code e Codex CLI para ajudar na escolha da ferramenta certa.

Feature	Claude Code Anthropic	Codex CLI OpenAI
Fonte / licença	Proprietário	Open-source (MIT)
Linguagem de implementação	TypeScript	TypeScript + Rust
Modelo padrão	claude-sonnet-4	o4-mini
Janela de contexto máxima	200k tokens	128k tokens
Raciocínio profundo	Claude Opus 4	o3 / o4-mini (nativo)
Arquivo de contexto persistente	`CLAUDE.md`	`AGENTS.md`
Arquivo de configuração	Flags CLI / CLAUDE.md	`.codex/config.toml`
Modos de aprovação	Básico	suggest / auto-edit / full-auto
Modo headless para CI/CD	Parcial	Nativo e completo
Sandbox configurável	Limitado	3 níveis + allow/deny lists
Análise de imagens/diagramas	Excelente (multimodal)	GPT-4o (bom)
Ecossistema de integrações	Anthropic SDK	OpenAI SDK (maior base)
Melhor para	Análise de grandes codebases, UX diária	CI/CD, automação, raciocínio complexo

Próximos Passos

Continue sua jornada de desenvolvimento agentic com estas ações práticas.

Instale e experimente

Instale o Codex CLI em um projeto real seu. Comece com modo suggest para se familiarizar antes de aumentar a autonomia.

Escreva seu AGENTS.md

Crie um AGENTS.md para um projeto existente. Use o exemplo deste projeto como base e adapte para sua stack e convenções.

Configure o config.toml

Copie o .codex/config.toml deste projeto e ajuste os allow_shell e deny_shell para o seu projeto.

Automatize com GitHub Actions

Implemente o workflow de code review automático do Tópico 5. Configure o secret OPENAI_API_KEY no repositório.

Compare Claude Code vs Codex CLI no seu workflow

Use as duas ferramentas para a mesma tarefa e compare os resultados. Identifique onde cada uma brilha no seu contexto específico de projeto e crie um workflow híbrido que usa o melhor de cada ecossistema.

Ver Codex CLI no GitHub

Projeto 4: Agentic com OpenAI Codex CLI

Baixar Configuração do Codex CLI

⚡ Execute em 3 passos

O que é o Codex CLI