Do zero ao avançado com o agente de codificação da OpenAI.
Conteúdo extraído do canal AutomationsAI.Codex · Atualizado em maio 2026
O Codex é o agente de codificação da OpenAI — rival direto do Claude Code. Diferencial principal: roda agentes na nuvem, permitindo delegar tarefas de programação remotamente (até pelo celular) e receber pull requests prontos sem manter o terminal aberto.
O Codex tem contexto de 274K tokens (maior que o Claude Code), suporte nativo a worktrees para execução em paralelo e integração direta com GitHub Actions. Para quem já usa Claude Code, é um complemento natural para tarefas longas em nuvem.
| Versão | Melhor para | Detalhe |
|---|---|---|
| CLI (terminal) | Velocidade + controle local | macOS, Windows, Linux. Integração direta com comandos, testes e repositórios |
| App (Windows) | Interface visual completa | Skills, plugins, navegador interno, previews, várias threads paralelas, automações |
| Web (ChatGPT) | Delegar em nuvem | Conecta repositórios GitHub, roda agentes sem PC ligado, acessível pelo app do ChatGPT |
O Codex CLI é instalado via npm. Pré-requisito: Node.js (que já inclui o npm). Após instalar, o login usa device auth — você abre um link no browser e cola um código.
A instalação é simples mas tem armadilhas: versão do Node.js desatualizada causa erros. O login por device auth é mais seguro que API key — funciona mesmo em containers Docker.
winget install --id Git.Git -e --source winget # depois instale Node.js em nodejs.org
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs
npm -v # Deve retornar algo como: 10.x.x
npm install -g @openai/codex
codex login --device-auth # Saída esperada: # 1. Abra o link no browser: https://auth.openai.com/codex/device # 2. Digite o código: OJER-V4KD (expira em 15 min) # Device codes são alvo de phishing. NUNCA compartilhe. # Successfully logged in ✓
⚠️ O código expira em 15 minutos. Abra o link imediatamente após rodar o comando.
docker run --rm -it \ -v paperclip-codex-home:/codex-home \ -v "$PWD:/app" -w /app \ seu-container bash # Dentro do container: codex login --device-auth
Após instalar, você roda codex no terminal para abrir o modo interativo. Dentro dele, / acessa comandos internos e @ referencia arquivos do projeto.
O arquivo agents.md é o equivalente ao CLAUDE.md — define contexto permanente, objetivos do projeto e instruções que o Codex lembra entre sessões. Sem ele, o Codex parte do zero em cada chat.
codex # abre modo interativo codex "crie uma API" # prompt direto codex chat # modo conversa codex --full-auto "..." # executa sem pedir confirmação
/plan mode— ativa modo planejamento/model— trocar modelo (low/high)/reasoning— ajustar raciocínio/browser use— ativar navegador/skill creator— criar skill/personality— ajustar personalidadeCrie com codex init ou manualmente. Funciona como onboarding permanente para o agente.
# agents.md ## Sobre o projeto - App de gestão de portfólio de ações - Stack: Next.js + Convex + Alpha Vantage API ## Decisões já tomadas - Usar shadcn/ui para componentes - Banco de dados: Convex (não Supabase) ## Instruções para o Codex - Sempre rodar testes antes de commit - Não fazer deploy sem minha aprovação
O Codex pede confirmação para cada ação por padrão. As approval policies controlam quando e se ele pede aprovação — desde sempre perguntar até nunca perguntar nada.
Se você está em um ambiente seguro (container, VM isolada), desativar confirmações elimina atrito e acelera muito o ciclo. Para produção ou sistemas críticos, mantenha as confirmações.
| Flag | Comportamento | Risco |
|---|---|---|
| -a on-request | Codex decide quando pedir | Baixo |
| -a never | Nunca pede aprovação | Médio |
| --full-auto | Atalho: on-request + sandbox write | Médio |
| --dangerously-bypass-approvals-and-sandbox | Zero confirmações, zero sandbox | Alto ⚠️ |
# ~/.codex/config.toml # Configuração equilibrada (recomendada em containers) approval_policy = "never" sandbox_mode = "workspace-write" # Configuração mais agressiva (só em ambientes isolados) # approval_policy = "never" # sandbox_mode = "danger-full-access"
Skills são instruções reutilizáveis para tarefas recorrentes. Você cria uma vez e o Codex as invoca automaticamente quando a tarefa combina com a descrição, ou você chama explicitamente com $nome-da-skill.
Skills eliminam repetição. Uma skill de "revisão de PR" pode rodar 3 subagentes em paralelo (segurança, testes, arquitetura) sem você reescrever o prompt toda vez.
meu-projeto/
.agents/
skills/
pr-review-agent/
SKILL.md ← obrigatório
scripts/ ← opcional
references/ ← opcional
--- name: pr-review-agent description: Use esta skill quando o usuário pedir revisão de pull request, branch, diff ou código alterado. Revise segurança, testes, arquitetura e riscos. --- Ao revisar um PR: 1. Leia o diff completo 2. Identifique arquivos alterados 3. Procure riscos de segurança 4. Verifique cobertura de testes 5. Avalie arquitetura e manutenção 6. Classifique achados por severidade 7. Sugira ações concretas 8. Finalize com checklist
# Invocação explícita $pr-review-agent # Invocação natural (Codex detecta automaticamente) "Revise o PR #42 e encontre problemas de segurança" # Combinando com subagentes "Use a skill $pr-review-agent com 3 subagentes em paralelo: segurança, testes, arquitetura"
O Codex tem vários "nomes" para agentes, mas na prática você os cria de 3 formas: thread/tarefa normal, subagentes configurados e automações agendadas.
Entender a hierarquia evita confusão com a terminologia. Comece com threads + skills + automações. Subagentes e workers vêm depois.
| Nome | O que é | Como usar |
|---|---|---|
| Agente principal | Codex coordenando a tarefa | Chat/thread normal |
| Agent thread | Conversa/tarefa separada | Nova thread no projeto |
| Worker agent | Trabalhador para parte do trabalho | "Divida em workers…" |
| Task agent | Agente com tarefa específica | "Crie um task agent para…" |
| Subagente | Agente especializado em paralelo | "Use subagentes…" |
| Background agent | Agente em segundo plano | Thread/tarefa em background |
| Agente paralelo | Várias tarefas simultâneas | Threads, subagentes ou worktrees |
| Automação | Tarefa agendada | Aba Automations |
| Skill | Receita reutilizável | $nome-da-skill ou linguagem natural |
| AGENTS.md | Instruções permanentes | Arquivo no projeto |
Subagentes são agentes especializados disparados em paralelo. O Codex não os cria automaticamente — você precisa pedir explicitamente no prompt com "use subagentes em paralelo".
Tarefas complexas como auditoria de codebase, planejamento de features e refactoring podem ser divididas e executadas em paralelo — reduzindo o tempo total drasticamente.
Use subagentes em paralelo para [objetivo]. Divida o trabalho assim: 1. Subagente A: [papel específico] 2. Subagente B: [papel específico] 3. Subagente C: [papel específico] Regras: - Cada subagente trabalha de forma independente - Não edite arquivos ainda, apenas analise e planeje - Espere todos terminarem - Consolide os resultados - Remova duplicações - Priorize por impacto Formato final: 1. Resumo 2. Achados por agente 3. Plano consolidado 4. Riscos 5. Próximas ações
Use a skill $pr-review-agent com subagentes em paralelo. Crie: - 1 subagente foco segurança - 1 subagente foco testes - 1 subagente foco arquitetura - 1 subagente foco performance Cada um aplica o processo da skill para seu foco. Depois consolide sem duplicações.
Worktrees permitem que múltiplos agentes trabalhem em paralelo sem misturar alterações no mesmo branch ou diretório. A OpenAI destaca worktrees como parte central do fluxo multiagente do Codex.
Sem worktrees, dois agentes editando o mesmo arquivo criam conflitos. Com worktrees, cada agente trabalha em seu próprio diretório + branch e você faz merge depois.
Agentes em paralelo, sem conflito, cada um em branch próprio
Codex cria branch, faz commit, push e PR com resumo das mudanças
Codex pode rodar como CI, aplicar patches e postar revisões
Codex na nuvem permite delegar tarefas e receber PRs via app ChatGPT
Automações permitem configurar rotinas que o Codex executa em horário/frequência definida — sem você estar presente. Disponível na aba Automations do Codex App (Windows).
Automações transformam o Codex em um membro da equipe que trabalha enquanto você dorme — revisando código, rodando testes, gerando relatórios e criando commits.
Toda segunda-feira às 9h: 1. Atualizar dependências se for seguro 2. Rodar testes 3. Rodar build 4. Revisar erros recentes 5. Gerar relatório em reports/weekly-review.md 6. Se houver mudanças, criar commit com mensagem clara Use uma nova thread a cada execução. Use raciocínio médio. Não faça deploy sem minha aprovação.
Exemplo real documentado na comunidade: construção de um app de portfólio de ações completo usando Codex 5.5 — com interface, banco de dados, dados reais de mercado e material de marketing — sem experiência prévia em programação.
Mostra o Codex no limite: multitasking real com 3 agentes simultâneos (dev + vídeo + pesquisa), image generation para escolher interface, testes automáticos e reverse prompting.
Design com image generation — Codex gera opções visuais da interface, usuário escolhe o layout
Frontend + banco de dados — Cria UI em Next.js e conecta Convex para persistir portfólio
Dados reais — Adiciona gráficos de preço via Alpha Vantage API gratuita
Multitasking — 3 agentes simultâneos: dev construindo o app, segundo criando vídeo de lançamento (Remotion), terceiro pesquisando ações de IA no browser (computer use)
Reverse prompting — Perguntar ao Codex "o que você acha que deve ser feito em seguida?" para descobrir próximos passos