# Guia Definitivo: Codex (OpenAI)

> Domine o Codex CLI da OpenAI — instalação, configuração, sandbox, modelos e workflow completo do agente de codificação no terminal.

Source: https://agentify.ia.br/blog/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:

- Analisa o contexto do projeto (arquivos, estrutura, `AGENTS.md`)

- Planeja as mudanças necessárias

- Executa edições e comandos dentro do sandbox

- Verifica o resultado (roda testes, checa output)

- 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:

 Plano Acesso Limites Free/Go Codex Mini (limitado) Uso diário restrito Plus ($20/mês) Completo Limites generosos Pro ($200/mês) Completo + GPT-5.3-Codex-Spark Limites dobrados Business ($30/user/mês) Completo Limites por equipe Enterprise Completo Custom

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:

- Ler a estrutura do projeto

- Encontrar o arquivo do endpoint

- Implementar a validação

- 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:

 Modo Permissões Quando usar read-only Lê arquivos, não modifica nada Consultoria, review, exploração auto (padrão) Lê, edita e executa no workspace Desenvolvimento diário full-access Acesso irrestrito ao sistema Automação confiável, CI/CD

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**:

 Aspecto Codex CLI Claude Code Filosofia Autonomia com isolamento Colaboração em tempo real Sandbox Habilitado por padrão (Landlock/Seatbelt) Sem sandbox nativo Interação Delega → executa → revisa Mostra raciocínio → pede input Tokens por tarefa ~82k (média) ~173k (média) Força Velocidade, eficiência, batch Qualidade de código, raciocínio profundo SWE-bench [VERIFICAR: score exato Codex 2026] 80.9% (mais alto entre agentes) Terminal-Bench 77.3% (líder) [VERIFICAR: score Claude Code Terminal-Bench]

**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:

 Modelo Perfil Caso de uso GPT-5.3-Codex Alta capacidade Loops agênticos complexos, code review GPT-5.4-Mini Rápido, econômico Edições simples, subagentes, tarefas leves GPT-5.5 Máxima capacidade Tarefas complexas (menos tokens por resultado) GPT-5.3-Codex-Spark Tempo real (Pro only) Coding interativo rápido

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 =
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.

 Eixo Nota Justificativa Código (qualidade) 9/10 SWE-bench Verified 85% (GPT-5.3-Codex, abril/2026) — 2º lugar geral, atrás apenas do Claude Mythos Preview. SWE-bench Pro 57% (líder). Contexto (compreensão) 7/10 Sandbox limita acesso ao filesystem real; context window competitivo mas inferior ao 1M tokens do Claude/Gemini. AGENTS.md hierárquico ajuda. Autonomia 9/10 Terminal-Bench 2.0: 77.3% — líder absoluto em tarefas autônomas de terminal. OSWorld-Verified 64.7%. Execução full-auto com sandbox. Velocidade 9/10 ~4x menos tokens que Claude Code para tarefas equivalentes (~82k vs ~173k). Inferência 25% mais rápida que GPT-5.2-Codex. Custo-benefício 8/10 Incluído no ChatGPT Plus ($20/mês). Via API, custo médio $100–200/dev/mês. Eficiência de tokens compensa preço por token. Especialização (skills) 6/10 AGENTS.md funcional mas menos flexível que CLAUDE.md hierárquico ou .cursorrules. Sandbox limita customização profunda de ambiente. Multi-agente 7/10 Cloud tasks paralelas, worktrees Git isolados, Agents SDK. Funcional mas menos maduro que subagents do Claude Code. Ecossistema 7/10 CLI + App desktop + IDE extensions + Chrome + GitHub Action. Ecossistema OpenAI robusto, mas MCP ainda limitado vs concorrentes.

**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](https://ft.ia.br).

-->