Guia Definitivo: Codex (OpenAI)

O Codex CLI é o agente de codificação da OpenAI que vive no seu terminal. Você descreve o que quer em linguagem natural, e ele lê arquivos, edita código, executa comandos e verifica resultados — tudo sem sair da linha de comando. Open-source, escrito em Rust, com mais de 67 mil stars no GitHub e sandbox habilitado por padrão.

Overview

O Codex CLI nasceu em abril de 2025 como a resposta da OpenAI ao Claude Code da Anthropic. Enquanto o Claude Code aposta na colaboração em tempo real — mostrando raciocínio e pedindo input nos pontos de decisão — o Codex segue uma filosofia diferente: autonomia com isolamento. Você delega uma tarefa, o agente executa em sandbox, e você revisa o resultado.

Posicionamento no mercado

O Codex ocupa o espaço de agente de codificação CLI junto com Claude Code, Gemini CLI, OpenCode e Kiro CLI. Seu diferencial principal é a combinação de:

• Sandbox por padrão — único agente CLI major com isolamento habilitado automaticamente
• Ecossistema OpenAI — acesso direto aos modelos GPT-5.3-Codex, integração com ChatGPT, Codex Cloud e extensões IDE
• Open-source — código aberto em Rust, com comunidade ativa (400+ contribuidores)
• Eficiência de tokens — usa aproximadamente metade dos tokens que o Claude Code para tarefas equivalentes

Modelo de execução

O Codex opera como um agente autônomo no terminal. Ao receber uma instrução em linguagem natural, ele:

1. Analisa o contexto do projeto (arquivos, estrutura, AGENTS.md)
2. Planeja as mudanças necessárias
3. Executa edições e comandos dentro do sandbox
4. Verifica o resultado (roda testes, checa output)
5. Apresenta o diff para sua aprovação

Diferente de um autocomplete ou copilot passivo, o Codex toma decisões sobre quais ferramentas usar, quais arquivos modificar e como validar o trabalho.

Preço e planos

O Codex CLI está incluído em todos os planos pagos do ChatGPT:

Para uso via API key (sem assinatura ChatGPT), o billing é por token consumido — sem limites de rate, pagando exatamente o que usar. A OpenAI estima um custo médio de $100–$200 por desenvolvedor/mês para uso intensivo via API.

[IMAGEM: Tabela visual de planos e preços do Codex]

Tutorial

Instalação

Pré-requisitos:

• Node.js 22 ou superior
• macOS ou Linux (Windows via WSL)
• 4 GB RAM mínimo (8 GB recomendado)

Instalação via npm:

npm install -g @openai/codex

Para atualizar:

npm install -g @openai/codex@latest

No Windows (via WSL):

# Instalar WSL se necessário
wsl --install

# Dentro do WSL (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @openai/codex

Autenticação

Você tem duas opções:

Opção 1 — Conta ChatGPT (recomendado):

Simplesmente rode codex e siga o fluxo de autenticação via device code. Se você tem Plus, Pro ou Business, o Codex já está incluído.

Opção 2 — API Key (para CI/CD e automação):

export OPENAI_API_KEY="sk-sua-chave-aqui"

Para persistir, adicione ao ~/.codex/config.toml:

preferred_auth_method = "apikey"

Primeiro Uso

Navegue até o diretório do seu projeto e rode:

codex

Isso abre uma interface full-screen no terminal — um REPL interativo onde você conversa com o agente sobre seu código.

Para um uso rápido sem interface interativa:

codex "Explique a estrutura deste projeto"

Exemplo prático — seu primeiro comando útil:

cd ~/meu-projeto
codex "Adicione validação de email no endpoint POST /users"

O Codex vai:

1. Ler a estrutura do projeto
2. Encontrar o arquivo do endpoint
3. Implementar a validação
4. Mostrar o diff para aprovação

Você aprova com a (aceitar) ou rejeita com d (declinar).

[IMAGEM: Terminal mostrando o Codex executando uma tarefa com diff]

Uso Intermediário

Vamos a um cenário real mais complexo — adicionar testes a um módulo existente:

codex "Escreva testes unitários para src/utils/validation.ts. 
       Cubra edge cases de validação de email, força de senha e parsing de datas."

Ou investigar e corrigir um bug:

codex "Usuários reportam erro 500 ao fazer upload de arquivos maiores que 10MB. 
       Encontre o limite de tamanho, trace o path de erro e corrija."

Pipe de dados para o Codex:

Uma feature poderosa é aceitar stdin — você pode pipar output de outros comandos:

# Gerar release notes a partir dos commits
git log --oneline v1.0.0..HEAD | codex -p "Crie release notes detalhadas destes commits"

# Analisar diff entre branches
git diff main..feature/nova-api | codex -p "Resuma as mudanças e sinalize breaking changes"

Code review integrado:

codex
> /review main

O comando /review analisa o diff entre sua branch atual e main, sinalizando problemas potenciais com migrações, mudanças de API ou modificações breaking.

Configuração Avançada

Modos de aprovação

O Codex oferece três modos que controlam a autonomia do agente:

Troque durante a sessão com /permissions.

Escolha de modelo

# Modelo padrão (GPT-5.3-Codex)
codex

# Especificar modelo
codex -m gpt-5

# Trocar durante a sessão
> /model gpt-5.4-mini

Configuração persistente

Edite ~/.codex/config.toml:

[sandbox_policy]
mode = "workspace-write"
network_access = "enabled"

writable_roots = [
  "/tmp/codex-scratch"
]

protected_paths = [
  ".env",
  "secrets/"
]

[mcp]
servers = [
  { name = "github", command = "npx @modelcontextprotocol/server-github" },
  { name = "filesystem", command = "npx @modelcontextprotocol/server-filesystem /path/to/project" }
]

MCP Servers

O Codex suporta Model Context Protocol (MCP) via STDIO e HTTP, permitindo conectar ferramentas externas:

codex
> @github Liste PRs abertos prontos para review
> @github Crie um PR desta branch para main com resumo das mudanças

AGENTS.md — Instruções de projeto

Crie um AGENTS.md na raiz do repositório para dar contexto persistente ao Codex:

## Contexto do Projeto
- API Node.js com Express e PostgreSQL
- Frontend React com TypeScript
- Deploy via GitHub Actions para AWS ECS

## Padrões de Código
- ESLint + Prettier obrigatórios
- Testes com Vitest para todo código novo
- Nunca commitar direto na main

## Regras de Deploy
- Sempre rodar migrations antes de deploy
- Incluir rollback em scripts de deploy

O Codex lê AGENTS.md de múltiplos locais e faz merge:

• ~/.codex/AGENTS.md — preferências pessoais
• Raiz do repositório — convenções do projeto
• Diretório atual — instruções específicas da feature

Deep Dive

Arquitetura de Sandbox

O grande diferencial técnico do Codex é o sandbox habilitado por padrão. Enquanto o Claude Code opera com acesso direto ao sistema (pedindo confirmação por ação), o Codex isola a execução usando primitivas de segurança nativas do OS:

Linux — Landlock + seccomp:

• Landlock (kernel 5.13+): controle de acesso hierárquico baseado em paths
• seccomp: filtragem de syscalls — bloqueia operações de rede e escalação de privilégios
• Bubblewrap (experimental): isolamento completo com namespaces (PID, rede, mount)

macOS — Seatbelt:

• Perfis de sandbox dinâmicos gerados por sessão
• Integração com frameworks de segurança do macOS
• Restrições de filesystem e rede via sandbox-exec

Windows — Restricted Tokens + Job Objects:

• Tokens restritos removem privilégios admin
• Job objects impõem limites de recursos e isolamento de processos

Na prática, isso significa que mesmo no modo auto, o Codex só pode escrever dentro do seu workspace (cwd + /tmp). Paths como .git/, .codex/ e .env são protegidos por padrão — o agente não consegue corrompê-los acidentalmente.

[IMAGEM: Diagrama da arquitetura de sandbox do Codex por plataforma]

Codex vs Claude Code — Filosofias opostas

A diferença fundamental entre Codex e Claude Code não é de capacidade — é de filosofia de execução:

Quando escolher Codex: tarefas batch, automação CI/CD, refactoring em escala, ambientes que exigem isolamento de segurança, workflows onde velocidade importa mais que perfeição.

Quando escolher Claude Code: refactoring arquitetural complexo, tarefas que exigem raciocínio profundo sobre trade-offs, projetos onde você quer pair-programming interativo.

Modelos disponíveis

O Codex acessa a família de modelos da OpenAI otimizados para código:

O modelo padrão é o GPT-5.3-Codex, otimizado especificamente para engenharia de software. O GPT-5.4-Mini oferece 4x mais headroom de uso no mesmo plano — ideal para tarefas simples onde não precisa do modelo completo.

Modo Headless (codex exec)

Para CI/CD e automação, o codex exec roda sem interface interativa:

# Uso básico
codex exec "Atualize a versão no package.json para 2.1.0"

# Em GitHub Actions
jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update changelog via Codex
        run: |
          npm install -g @openai/codex
          export OPENAI_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          codex exec "Atualize o CHANGELOG para o próximo release baseado nos commits desde a última tag"

Git hooks:

# .git/hooks/pre-push
#!/bin/bash
codex exec "Revise as mudanças staged para problemas de segurança. 
            Exit com código 1 se encontrar issues críticos."

Batch processing:

# Adicionar type hints a todos os arquivos Python
for file in src/utils/*.py; do
  codex exec "Adicione type hints a todas as funções em $file"
done

Multi-agente (experimental)

O Codex suporta execução multi-agente — múltiplos agentes trabalhando em paralelo no mesmo repositório, cada um em worktrees Git isolados:

# config.toml
[agents]
parallel = true
max_agents = 3
isolation = "worktree"

Isso permite:

• Execução paralela de tarefas independentes
• Orquestração via OpenAI Agents SDK
• Handoffs auditáveis entre agentes
• Escalabilidade de single-agent para equipes coordenadas

Codex Cloud

Além do CLI local, o Codex oferece execução na nuvem via chatgpt.com/codex:

• Containers isolados com acesso completo ao repo
• Shell, test runner e file I/O disponíveis
• Tarefas assíncronas — inicie no celular, revise depois no desktop
• Integração bidirecional com o CLI local

Containers cloud têm custo adicional por sessão:

• 1 GB: $0.03 por 20 minutos
• 4 GB: $0.12 por 20 minutos
• 64 GB: $1.92 por 20 minutos

Sessões persistentes

O Codex salva conversas localmente. Você pode retomar sessões anteriores:

# Retomar última sessão
codex resume --last

# Retomar sessão específica
codex resume <SESSION_ID>

Isso é especialmente útil para tarefas longas que você precisa pausar e continuar depois.

Integrações e ecossistema

O Codex se integra com o ecossistema OpenAI completo:

• Codex App (desktop macOS) — interface gráfica para gerenciar múltiplos agentes
• VS Code Extension — mesmas capacidades dentro do editor
• JetBrains Plugin — suporte para IDEs JetBrains
• Chrome Extension — tarefas web com contexto do navegador
• GitHub Action (openai/codex-action) — integração nativa com GitHub
• Agents SDK — orquestração programática de múltiplos agentes

Avaliação: Spider Chart

Notas de 1 a 10 baseadas em benchmarks públicos + avaliação prática.

Média geral: 7.8/10

Metodologia: Código baseia-se em SWE-bench Verified (abril/2026) + SWE-bench Pro. Autonomia em Terminal-Bench 2.0 (fev/2026) + avaliação prática. Velocidade validada por comparativo de tokens/tarefa (OpenAI vs Anthropic). Demais eixos são avaliação prática comparativa. Escala: 1-4 (fraco), 5-6 (adequado), 7-8 (bom), 9-10 (excelente/líder).

[IMAGEM: Spider chart radar com 8 eixos mostrando o perfil do Codex CLI]

Prós e Contras

Prós

• Sandbox por padrão — segurança real com Landlock/Seatbelt/seccomp, não apenas confirmações de “sim/não”. Único agente CLI major com isolamento nativo habilitado automaticamente.

• Eficiência de tokens — usa ~50% menos tokens que o Claude Code para tarefas equivalentes. Na prática, isso significa menor custo e respostas mais rápidas.

• Open-source em Rust — código auditável, comunidade ativa (67K+ stars, 400+ contribuidores), extensível. Você pode inspecionar exatamente o que o agente faz.

• Ecossistema integrado — CLI, app desktop, extensão IDE, cloud, Chrome extension e GitHub Action. Tudo conectado com a mesma conta e contexto.

• Incluído no ChatGPT Plus — se você já paga $20/mês pelo ChatGPT, o Codex CLI vem sem custo adicional. Barreira de entrada baixíssima.

• Modo headless robusto — codex exec é genuinamente útil para CI/CD, git hooks e automação batch. Não é um afterthought.

• Líder em Terminal-Bench — 77.3% no benchmark de tarefas autônomas de terminal, o mais alto entre agentes CLI.

Contras

• Qualidade de código inferior ao Claude Code — em testes cegos de qualidade, Claude Code vence com 67% de win rate. Para refactoring arquitetural complexo, o Claude Code ainda produz código mais limpo.

• Windows é cidadão de segunda classe — requer WSL para funcionalidade completa. O sandbox nativo Windows (AppContainer) ainda é experimental.

• Curva de aprendizado do sandbox — o isolamento que é ponto forte também gera fricção. Comandos que precisam de rede ou acesso fora do workspace falham silenciosamente até você entender o modelo de permissões.

• Dependência do ecossistema OpenAI — diferente do OpenCode (75+ providers), o Codex só funciona com modelos da OpenAI. Se você quer flexibilidade de provider, não é a ferramenta certa.

• Custo pode escalar rápido — uso intensivo via API (sem assinatura) pode chegar a $200-400/mês facilmente, especialmente com tarefas cloud e GPT-5.3-Codex.

• Multi-agente ainda experimental — a feature existe mas não é production-ready. Documentação escassa e comportamento inconsistente em projetos grandes.

Veredicto

Ideal para:

• Desenvolvedores que já usam ChatGPT Plus e querem um agente CLI sem custo adicional
• Equipes que precisam de isolamento de segurança (compliance, ambientes regulados)
• Workflows de automação e CI/CD com codex exec
• Quem prioriza velocidade e eficiência de tokens sobre qualidade máxima de código

Não ideal para:

• Quem precisa de raciocínio profundo em refactoring arquitetural (Claude Code é superior)
• Desenvolvedores Windows sem WSL configurado
• Quem quer flexibilidade de provider/modelo (considere OpenCode)
• Projetos onde qualidade de código é mais importante que velocidade

O Codex CLI é a porta de entrada mais acessível para agentes de codificação autônomos no terminal. Com sandbox por padrão, inclusão no ChatGPT Plus e um ecossistema crescente, é uma escolha sólida para quem quer produtividade com segurança. Se você precisa da melhor qualidade absoluta de código, o Claude Code ainda leva vantagem — mas para o dia-a-dia de desenvolvimento, o Codex entrega um equilíbrio impressionante entre autonomia, velocidade e proteção.

Se você quer implementar agentes de codificação na sua equipe com configuração enterprise — sandbox policies, AGENTS.md customizados, integração com CI/CD — conheça nossos serviços de consultoria em ft.ia.br.