Codex CLI: The Definitive Technical Reference

Resumo: Codex é um agente de codificação multi-superfície que lê sua base de código, executa comandos em um sandbox no nível do sistema operacional, aplica patches em arquivos e delega tarefas para a nuvem. Domine cinco sistemas centrais (config.toml, modelo de sandbox/aprovação, AGENTS.md, MCP e skills) e o Codex se torna um multiplicador de força. Use profiles para alternar entre contextos, /compact para gerenciar o orçamento de 272K tokens, e AGENTS.md para instruções de projeto cross-tool que funcionam no Codex, Cursor, Amp e outros.

Codex opera como um agente de codificação multi-superfície, não como um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, aplica patches em arquivos, conecta-se a serviços externos via MCP e delega tarefas de longa duração para a nuvem. Ele roda localmente, mas pensa globalmente; a mesma inteligência alimenta quatro superfícies distintas, dependendo de como você trabalha.

A diferença entre o uso casual e o uso eficiente do Codex se resume a cinco sistemas centrais. Domine-os e o Codex se torna um multiplicador de força:

1. Sistema de configuração: controla o comportamento via config.toml
2. Modelo de sandbox e aprovação: determina o que o Codex pode fazer
3. AGENTS.md: define contratos operacionais no nível do projeto
4. Protocolo MCP: estende as capacidades para serviços externos
5. Sistema de skills: empacota expertise de domínio reutilizável

Passei meses executando o Codex junto com o Claude Code em bases de código de produção, pipelines de CI/CD e fluxos de trabalho de equipe. Este guia destila essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui a sintaxe real, exemplos de configuração práticos e os casos extremos que confundem até usuários experientes.

Nota de estabilidade: Recursos marcados como [EXPERIMENTAL] estão sujeitos a alterações entre versões. O Codex Cloud e o grupo de comandos MCP são ambos experimentais a partir da v0.107.0. O CLI principal, sandbox, AGENTS.md, config.toml e Skills são estáveis.

Principais conclusões

• Quatro superfícies, um cérebro: CLI, aplicativo desktop, extensão para IDE e tarefas na nuvem compartilham a mesma inteligência GPT-5.x-Codex, então escolha a superfície que melhor se adapta ao seu fluxo de trabalho.
• Sandboxing em nível de sistema operacional: Codex aplica restrições de sistema de arquivos e rede no nível do kernel (Seatbelt no macOS, Landlock + seccomp no Linux), não dentro de contêineres.
• AGENTS.md é cross-tool: Suas instruções de projeto funcionam no Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed e em mais de 60.000 projetos open source. Escreva uma vez, use em qualquer lugar.
• Profiles economizam o custo de troca de contexto: Defina presets de configuração nomeados (fast, careful, auto) e alterne entre eles com --profile.
• 272K tokens de contexto de entrada se esgotam rápido: Use /compact, prompts focados e referências @file para gerenciar orçamentos de tokens proativamente.

Como usar este guia

Esta é uma referência com mais de 2.500 linhas — comece onde seu nível de experiência se encaixa:

O Cartão de referência rápida no final fornece um resumo escaneável de todos os principais comandos.

Como o Codex funciona: o modelo mental

Antes de mergulhar nos recursos, entenda como a arquitetura do Codex molda tudo o que você faz com ele. O sistema opera em quatro superfícies sustentadas por uma camada de inteligência compartilhada:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Camada principal (Core Layer): A família de modelos GPT-5.x-Codex alimenta tudo. Na versão v0.107.0, gpt-5.3-codex é o modelo padrão com uma janela de contexto de entrada de 272K tokens (128K de saída, 400K de orçamento total).³⁵ Ele lê arquivos, escreve patches, executa comandos shell e raciocina sobre sua base de código. Quando o contexto se esgota, o Codex compacta a conversa para liberar espaço. Esta camada consome tokens.

Camada de segurança (Security Layer): Cada comando que o Codex executa passa por um sandbox em nível de sistema operacional. No macOS, o framework Seatbelt da Apple aplica restrições no nível do kernel. No Linux, Landlock + seccomp filtram o acesso ao sistema de arquivos e chamadas de sistema. O sandbox opera no nível do kernel, não dentro de contêineres. A política de aprovação então decide quando solicitar confirmação humana.

Camada de extensão (Extension Layer): MCP conecta serviços externos (GitHub, Figma, Sentry). Skills empacotam workflows reutilizáveis que o Codex carrega sob demanda. Apps conectam-se a conectores do ChatGPT. A busca na web adiciona contexto em tempo real da internet.

Camada de superfície (Surface Layer): CLI para usuários avançados de terminal e automação. Aplicativo desktop para gerenciamento de projetos com múltiplas threads. Extensão para IDE para ciclos de editar-compilar-testar. Cloud para tarefas assíncronas que executam independentemente.

O insight principal: A maioria dos usuários usa apenas uma superfície. Usuários avançados usam todas as quatro: Cloud para tarefas de longa duração, CLI para operações determinísticas no repositório, extensão para IDE para ciclos de codificação rápidos e o aplicativo desktop para planejamento e coordenação.

Sumário

1. Como instalar o Codex?
2. Início rápido: sua primeira sessão
3. Superfícies de interação principais
4. Aprofundamento no sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Codex?
7. Frameworks de decisão
8. Como funciona o sandbox e o sistema de aprovação?
9. Como funciona o AGENTS.md?
10. Hooks
11. O que é MCP (Model Context Protocol)?
12. Runtime REPL JavaScript
13. O que são Skills?
14. Modo de planejamento e colaboração
15. Sistema de memória
16. Gerenciamento de sessões
17. Modo não interativo (codex exec)
18. Codex Cloud e tarefas em segundo plano
19. O aplicativo desktop do Codex
20. GitHub Action e CI/CD
21. Codex SDK
22. Otimização de desempenho
23. Como depurar problemas?
24. Implantação enterprise
25. Melhores práticas e anti-padrões
26. Receitas de workflow
27. Guia de migração
28. Cartão de referência rápida
29. Changelog
30. Referências

Como instalar o Codex?

Gerenciadores de pacotes

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# Upgrade to latest
npm install -g @openai/codex@latest

Script de instalação direta (v0.106.0+)

Para macOS e Linux, um script de instalação em uma única linha está disponível como asset de release no GitHub:⁶²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

O script detecta automaticamente sua plataforma e arquitetura, baixa o binário correto e o coloca no seu PATH.

Downloads de binários

Para ambientes sem npm ou Homebrew, baixe binários específicos para cada plataforma em Releases do GitHub¹:

Requisitos do sistema

• macOS: Apple Silicon ou Intel (suporte completo a sandbox via Seatbelt)
• Linux: x86_64 ou arm64 (sandbox via Landlock + seccomp)
• Windows: Sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é suportado²

Autenticação

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Dois caminhos de autenticação:

1. Conta ChatGPT (recomendado): Faça login com sua assinatura existente Plus, Pro, Team, Business, Edu ou Enterprise. Acesso completo a todos os recursos, incluindo tarefas na nuvem.
2. Chave API: Configure via variável de ambiente CODEX_API_KEY ou codex login --with-api-key. Alguns recursos (threads na nuvem) podem não estar disponíveis.

Dica avançada: O armazenamento de credenciais é configurável via cli_auth_credentials_store no config.toml. Opções: file (padrão), keyring (chaveiro do SO) ou auto (keyring se disponível, fallback para arquivo).

Completions do shell

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Verificar a instalação

codex --version
# Codex CLI v0.104.0

## Início Rápido: Sua Primeira Sessão

Vá do zero à produtividade em 5 minutos.

**1. Instale e autentique:**
```bash
npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Navegue até um projeto:

cd ~/my-project                  # Any git repo works

3. Inicie o Codex:

codex

Você verá a TUI interativa. O Codex lê a estrutura do seu projeto automaticamente.

4. Faça uma pergunta:

> What does this project do? Summarize the architecture.

O Codex lê os arquivos principais e explica a base de código. Nenhuma alteração é feita no modo suggest padrão.

5. Faça uma alteração:

> Add input validation to the login endpoint

O Codex propõe edições como um diff. Revise e aprove com y, ou rejeite com n.

6. Use um slash command:

> /plan Refactor the database layer to use connection pooling

O Codex cria um plano sem executar. Revise o plano e depois aprove para iniciar a execução.

7. Verifique seu trabalho:

> /diff

Veja todas as alterações que o Codex fez na sessão atual.

Próximos passos: - Configure o AGENTS.md com instruções do projeto (veja Como o AGENTS.md Funciona?) - Configure um perfil para seu fluxo de trabalho (veja Perfis) - Experimente o codex exec para automação não interativa (veja Modo Não Interativo)

Superfícies de Interação Principais

O Codex oferece quatro interfaces distintas respaldadas pela mesma inteligência. Cada superfície é otimizada para um padrão de fluxo de trabalho diferente.

1. CLI Interativo (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

A TUI é uma aplicação em tela cheia com:

• Composer: Digite prompts, anexe arquivos com @, execute comandos shell com o prefixo !
• Painel de saída: Respostas do modelo em streaming, chamadas de ferramentas e saída de comandos
• Barra de status: Modelo, uso de tokens, branch do git, modo sandbox

Atalhos principais da TUI:

Slash commands disponíveis na TUI:

2. Codex Desktop App (macOS)

codex app                    # Launch desktop app (auto-installs if missing)

O desktop app adiciona capacidades que o CLI não possui:

• Multitarefa: Execute múltiplos agentes em paralelo em diferentes projetos simultaneamente
• Isolamento com git worktree: Cada thread trabalha em uma cópia isolada do seu repositório
• Revisão de diff inline: Faça stage, reverta e commite alterações sem sair do app
• Terminal integrado: Terminal por thread para execução de comandos
• Bifurcação de conversas: Ramifique conversas para explorar alternativas
• Janelas flutuantes destacáveis: Destaque conversas em janelas portáteis
• Automações: Agende tarefas recorrentes (triagem de issues, monitoramento de CI, resposta a alertas)

Quando usar o app vs CLI: Use o desktop app quando estiver coordenando múltiplas frentes de trabalho ou precisar de revisão visual de diffs. Use o CLI quando quiser composabilidade no terminal, scripting ou integração com CI/CD.

3. Extensão para IDE (VS Code, Cursor, Windsurf)

A extensão do Codex para IDE se integra diretamente ao seu editor:

• Modo agente por padrão: Lê arquivos, faz edições, executa comandos
• Edições inline: Sugestões contextuais nos seus arquivos ativos
• Sessões compartilhadas: Sessões sincronizam entre CLI e extensão para IDE
• Mesma autenticação: Faça login com conta do ChatGPT ou API key

Instale pelo VS Code Marketplace ou pelas lojas de extensões do Cursor/Windsurf.³

4. Codex Cloud [EXPERIMENTAL]

Tarefas na nuvem executam de forma assíncrona em ambientes gerenciados pela OpenAI:

• Disparar e esquecer: Enfileire tarefas que executam independentemente da sua máquina local
• Execução paralela: Execute múltiplas tarefas na nuvem simultaneamente
• Criação de PR: O Codex cria pull requests a partir do trabalho concluído
• Aplicação local: Puxe resultados da nuvem para seu repositório local com codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Tarefas na nuvem também são acessíveis em chatgpt.com/codex.⁴

Mergulho profundo no sistema de configuração

Codex usa TOML para configuração. Entender a hierarquia de precedência é essencial porque ela determina quais configurações prevalecem quando há conflitos.

Precedência (da mais alta para a mais baixa)

1. Substituições de sessão (mais alta): flags CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) e substituições -c key=value
2. Configuração do projeto (.codex/config.toml, descoberta a partir do diretório atual subindo até a raiz do projeto; o diretório mais próximo prevalece)
3. Configuração do usuário ($CODEX_HOME/config.toml, padrão ~/.codex/config.toml)
4. Configuração do sistema (/etc/codex/config.toml em Unix)
5. Padrões integrados (mais baixa)

requirements.toml atua como uma camada de restrição de políticas que limita quais valores os usuários podem selecionar após a mesclagem normal de configurações. Veja Implantação empresarial.

Localização dos arquivos de configuração

Dica avançada: A variável de ambiente CODEX_HOME substitui o diretório padrão ~/.codex. Útil para CI/CD ou configurações com múltiplas contas.

Referência completa de configuração

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K input context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.2-codex"         # Model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-failure|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

Perfis

Predefinições de configuração nomeadas para diferentes modos de trabalho:

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Ativar um perfil:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Dica avançada: Defina um perfil padrão com profile = "fast" no nível superior da sua configuração. Substitua por sessão com --profile.

Provedores de modelo personalizados

Conecte-se ao Azure, modelos locais ou serviços proxy:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Aviso: A API wire chat/completions (wire_api = "chat") foi descontinuada para modelos hospedados na OpenAI, com a OpenAI anunciando a remoção em fevereiro de 2026.³⁶ Provedores locais (Ollama, LM Studio) ainda podem aceitar este formato. Para endpoints da OpenAI, use wire_api = "responses" em vez disso.

Use modelos locais com a flag --oss:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Ou defina na configuração:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Substituições de configuração inline

Substitua qualquer valor de configuração pela linha de comando:

codex -c model="gpt-5.2-codex" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Qual modelo devo escolher?

Modelos disponíveis (fevereiro de 2026)

A lista exata de modelos varia por conta e disponibilidade. A partir da v0.106.0, gpt-5.3-codex está visível na lista de modelos do CLI para usuários com chave API.⁶² Verifique seu cache local: ~/.codex/models_cache.json.

Fluxograma de seleção de modelo

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Esforço de raciocínio

Controle o quanto o modelo “pensa” antes de responder:

Os níveis suportados dependem do modelo. minimal está disponível apenas para modelos GPT-5. Nem todos os modelos suportam todos os níveis.

codex -c model_reasoning_effort="xhigh" "find the race condition"

Dica avançada: o raciocínio xhigh pode usar de 3 a 5x mais tokens do que medium para o mesmo prompt. Reserve-o para problemas genuinamente difíceis onde o raciocínio extra compensa.

Troca de modelo

Troque de modelo durante a sessão com o slash command /model, ou defina por execução via --model / -m:

codex -m gpt-5.3-codex-spark "pair with me on this component"

Quanto custa o Codex?

Veja também Seleção de Modelo para capacidades e Frameworks de Decisão para escolher o modelo certo por tarefa.

Acesso via planos do ChatGPT

A disponibilidade do Codex depende do seu plano do ChatGPT e das configurações da organização:⁵³

Tarifas promocionais: o acesso Free/Go e os limites 2x para planos pagos coincidiram com o lançamento do Codex Desktop App (fevereiro de 2026). Esses limites mais altos se aplicam em todas as plataformas — app, CLI, IDE e nuvem. A OpenAI não anunciou uma data de término.¹⁷

Custos de créditos

As operações do Codex consomem créditos da alocação do seu plano:

Planos Enterprise e Edu escalam créditos conforme a alocação do contrato. Verifique /status no TUI para o uso atual.

Cobrança da API

Ao usar o Codex através da API, a OpenAI cobra o uso por token sob a precificação padrão da API da OpenAI para o modelo selecionado (mais quaisquer descontos aplicáveis de cache de prompt). Consulte a página oficial de preços da API para as tarifas atuais.²¹

Estratégias de otimização de custos

1. Use perfis: crie um perfil fast com gpt-5.1-codex-mini e model_reasoning_effort = "low" para tarefas rotineiras
2. Reserve raciocínio alto: use xhigh apenas para problemas genuinamente difíceis, pois custa de 3 a 5x mais tokens
3. Use --ephemeral: pule a persistência de sessão em CI/CD para reduzir overhead
4. Minimize resumos de raciocínio: defina model_reasoning_summary = "none" quando não precisar de explicações
5. Agrupe com modo exec: codex exec evita o overhead do TUI para workflows de automação
6. Monitore o uso: verifique /status no TUI e nos painéis de cobrança da sua organização

Exemplos de custos reais

Custos representativos da API para tarefas comuns (gpt-5.3-codex com precificação padrão, raciocínio medium):

Os custos variam conforme o esforço de raciocínio, cache e comprimento da conversa. Use gpt-5.1-codex-mini para tarefas rotineiras para reduzir custos em ~40-60%. Tokens de entrada em cache são cobrados com desconto.

Overhead oculto de tokens

Cada chamada de ferramenta adiciona tokens além do seu prompt visível:

Dica avançada: monitore seu uso real via /status no TUI. A contagem de tokens inclui todo o overhead, não apenas suas mensagens visíveis. Se os custos surpreenderem você, verifique quantos servidores MCP estão conectados — cada um adiciona definições de ferramentas a cada chamada da API.

Gestão de custos para equipes

Estratégias para controle de custos da equipe: - Defina requirements.toml para impor limites de modelo e esforço de raciocínio em toda a organização - Use gpt-5.1-codex-mini para CI/CD — pipelines automatizados raramente precisam de raciocínio máximo - Orçamento baseado em perfis — defina perfis ci, review e dev com tetos de custo apropriados - Monitore via OpenTelemetry — implantações enterprise podem exportar telemetria de uso para stacks de observabilidade existentes

Frameworks de Decisão

Quando Usar Cada Superfície

Quando Usar Cada Modo de Sandbox

Quando Usar Cada Nível de Raciocínio

Modo Plan vs Execução Direta

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Modo Steer: Enter vs Tab

Regra geral: Enter = “pare, preste atenção nisso agora.” Tab = “quando terminar, faça isso também.”

Desktop App vs CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Qual Perfil Usar?

Associe sua tarefa a um perfil pré-configurado:

Configuração do config.toml:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Alternar perfis por sessão: codex --profile careful

Como funciona o sistema de sandbox e aprovação?

O Codex usa um modelo de segurança em duas camadas que separa o que é tecnicamente possível de quando o Codex solicita aprovação humana. A abordagem difere fundamentalmente do sistema de permissões do Claude Code — o Codex aplica restrições no nível do kernel do sistema operacional.⁵ Veja também Implantação empresarial para restrições de requirements.toml que administradores aplicam em toda a organização.

Camada 1: Sandbox (o que é possível)

O sandbox controla o acesso ao sistema de arquivos e à rede usando mecanismos nativos do sistema operacional:

Aplicação específica por plataforma:

• macOS: Framework Seatbelt da Apple via sandbox-exec com perfis específicos por modo compilados em tempo de execução e aplicados pelo kernel⁶
• Linux: Landlock para restrições de sistema de arquivos + seccomp para filtragem de syscalls. Um processo auxiliar independente (codex-linux-sandbox) fornece isolamento com defesa em profundidade.⁵ Bubblewrap (bwrap) é incluído e compilado como parte do build Linux (promovido de opcional na v0.100.0)⁷
• Windows: Sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é suportado (herda Linux Landlock + seccomp)

Por que isso importa: Diferente de sandboxing baseado em contêiner (Docker), sandboxing no nível do sistema operacional é mais rápido, mais leve e mais difícil de escapar. O kernel aplica as restrições antes mesmo do Codex ver a chamada de sistema.

Correções de segurança: - Bypass de sandbox por fork do zsh (v0.106.0): Corrigida uma vulnerabilidade onde a execução de shell via fork do zsh poderia contornar as restrições do sandbox.⁶² Se você está em uma versão anterior, atualize imediatamente. - Limite de tamanho de entrada (v0.106.0): O Codex agora aplica um limite de aproximadamente 1 milhão de caracteres na entrada para prevenir travamentos causados por payloads excessivamente grandes.⁶² - Sistema de arquivos /dev no Linux (v0.105.0): Comandos em sandbox no Linux agora recebem um sistema de arquivos /dev mínimo, melhorando a compatibilidade com ferramentas que esperam nós de dispositivo.⁶³

Política ReadOnlyAccess (v0.100.0+): Uma forma de política configurável para controle granular de acesso de leitura. Use-a para restringir de quais diretórios o Codex pode ler, mesmo no modo workspace-write:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Camada 2: Política de aprovação (quando perguntar)

A política de aprovação determina quando o Codex pausa para solicitar confirmação humana:

IDs de aprovação distintos (v0.104.0+)

O Codex agora atribui IDs de aprovação distintos a cada comando dentro de uma execução de shell em múltiplas etapas. Isso significa que as aprovações são granulares — aprovar um comando em uma sequência não aprova automaticamente os subsequentes na mesma invocação de shell.⁵¹

Controles de aprovação flexíveis (v0.105.0+)

O fluxo de aprovação agora suporta permissões extras de sandbox e rejeição granular:⁶³

• Permissões extras de sandbox: Quando um comando precisa de acesso além do modo de sandbox atual, o Codex pode solicitar permissões adicionais específicas em vez de exigir uma mudança completa de modo
• Rejeição granular: Rejeite chamadas de ferramentas individuais com feedback para que o Codex possa ajustar sua abordagem em vez de simplesmente tentar novamente o mesmo comando

O flag --full-auto

--full-auto é um atalho conveniente para:

codex --sandbox workspace-write --ask-for-approval on-request

Ponto crítico de atenção: --full-auto sobrescreve qualquer valor explícito de --sandbox. Se você passar --full-auto --sandbox read-only, obterá workspace-write porque --full-auto tem precedência.⁸

Configurações recomendadas

Desenvolvimento diário (padrão seguro):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Usuário avançado (acesso total, humano no controle):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

A combinação é o “ponto ideal” recomendado pela comunidade: capacidade máxima, mas aprovação necessária para cada comando.⁹

Automação CI/CD:

sandbox_mode = "workspace-write"
approval_policy = "never"

Habilitando acesso à rede

O Codex bloqueia o acesso à rede por padrão no modo workspace-write. Habilite quando necessário:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

Suporte a proxy WebSocket (v0.104.0+)

Para ambientes corporativos que roteiam tráfego WebSocket por um proxy, o Codex agora suporta as variáveis de ambiente WS_PROXY e WSS_PROXY:⁵¹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

Estas complementam o suporte existente a proxy HTTPS_PROXY e SOCKS5 (v0.93.0+), cobrindo todas as camadas de transporte.

Testando o sandbox

Verifique o comportamento do sandbox antes de confiar nele:

codex sandbox macos --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

Se o sandbox estiver funcionando corretamente, ambos os comandos devem falhar com um erro de permissão negada — o sandbox impede a leitura de arquivos sensíveis do sistema mesmo no modo --full-auto. Se algum dos comandos tiver sucesso, a configuração do seu sandbox precisa ser investigada.

Como funciona o AGENTS.md?

AGENTS.md é o sistema de instruções de projeto do Codex — um padrão aberto¹⁰ agora governado pela Agentic AI Foundation da Linux Foundation. Suportado por Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode e mais de 60.000 projetos open source. Ele define como o Codex se comporta dentro de um repositório ou diretório específico. Veja Skills para pacotes de expertise reutilizáveis que complementam o AGENTS.md.

Hierarquia de descoberta

O Codex constrói uma cadeia de instruções no início da sessão percorrendo a árvore de diretórios:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Projeto (raiz do git até o diretório atual): Cada nível é verificado para AGENTS.override.md > AGENTS.md > nomes de arquivo alternativos
3. Mesclagem: Os arquivos são concatenados da raiz para baixo; arquivos mais próximos aparecem depois no prompt e sobrescrevem orientações anteriores

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

O que faz um ótimo AGENTS.md

Baseado em orientação direta do próprio Codex e padrões da comunidade¹¹:

FAÇA: - Seja específico: "Use rg --files for discovery" é melhor que "search efficiently" - Defina conclusão: O que significa “pronto”? (testes passando, lint limpo, etc.) - Inclua comandos: Build, teste, lint, formatação (invocações exatas) - Organize por tarefa: Seções de codificação, revisão, release, incidente/debug - Defina escalação: O que fazer quando bloqueado ou encontrando estado inesperado

NÃO FAÇA: - Despejar guias de estilo inteiros sem regras de execução - Usar diretivas ambíguas (“tenha cuidado,” “otimize”) - Misturar prioridades contraditórias (velocidade + verificação exaustiva + sem orçamento de runtime) - Escrever documentação em prosa (AGENTS.md é política operacional, não README)

Exemplo: AGENTS.md de produção

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Segurança
- Nunca faça commit de segredos. Use `.env` para configuração local.
- Valide todas as chamadas externas de API com tratamento de erros adequado.

O mecanismo de substituição

AGENTS.override.md em qualquer nível de diretório substitui o AGENTS.md normal para aquele escopo. Use para:

• Congelamento de releases: “Nenhum recurso novo, apenas correções”
• Modo de incidente: “Todas as alterações devem ser revisadas pelo plantonista”
• Endurecimento temporário: “Nenhuma atualização de dependência nesta sprint”

Configuração

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Geração de scaffold

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Ou verifique sua cadeia de instruções:

codex --ask-for-approval never "Summarize your current instructions"

Hooks

O Codex adicionou hooks na v0.99.0 (AfterAgent) e v0.100.0 (AfterToolUse). O sistema de hooks está em estágio inicial comparado aos mais de 12 eventos de ciclo de vida do Claude Code, mas fornece pontos de entrada de automação para fluxos de trabalho comuns.

Eventos de hook disponíveis

Configuração de hooks

Os hooks são configurados em .codex/config.toml:

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

Replicando padrões de hooks do Claude Code

Se estiver migrando do Claude Code, veja como obter automação semelhante sem o conjunto completo de eventos de hook:

Dica de especialista: O sistema de hooks está em expansão ativa. Consulte o changelog do Codex para novos eventos de hook em cada release.

O que é MCP (Model Context Protocol)? [EXPERIMENTAL]

O MCP estende as capacidades do Codex conectando-o a ferramentas e serviços externos. O grupo de comandos codex mcp está atualmente marcado como experimental, e os comandos e formato de configuração podem mudar entre releases. O Codex suporta dois tipos de transporte: STDIO (processos locais) e Streamable HTTP (servidores remotos).¹²

Configurando servidores MCP

Servidores STDIO (processos locais):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

Servidores HTTP (remotos):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

Gerenciamento de CLI

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

Na sessão: /mcp mostra os servidores ativos e as ferramentas disponíveis.

Executando o Codex COMO um servidor MCP

O Codex pode se expor como um servidor MCP para orquestração multi-agente:¹³

codex mcp-server                        # Start as MCP server (stdio transport)

O servidor expõe duas ferramentas: 1. codex(): Inicia uma nova sessão com parâmetros de prompt, sandbox, modelo e aprovação 2. codex-reply(): Continua uma sessão existente com threadId e prompt

Uso com o Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Servidores MCP notáveis

Padrões práticos

Padrão 1: Desenvolvimento com consciência de contexto — Combine o Context7 com a documentação do seu framework para que o Codex sempre tenha referências atualizadas de API:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Padrão 2: Limites de saída — As respostas de ferramentas MCP são truncadas em ~25K caracteres por padrão. Para ferramentas que retornam payloads grandes (consultas de banco de dados, capturas de log), use enabled_tools para restringir a ferramentas específicas e manter as respostas focadas.

Padrão 2a: Saída multimodal de ferramentas (v0.107.0) — Ferramentas customizadas agora podem retornar saída multimodal (imagens, conteúdo rico) junto com texto. Isso permite que ferramentas que produzem artefatos visuais — capturas de tela, diagramas, renderizações de gráficos — os passem diretamente ao modelo para análise.⁶⁴

Padrão 3: Governança corporativa de MCP — Restrinja quais servidores MCP os desenvolvedores podem usar via requirements.toml:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Qualquer servidor que não corresponda a uma identidade em requirements.toml será bloqueado na inicialização. Consulte Implantação corporativa para a configuração completa de políticas.

Runtime REPL de JavaScript [EXPERIMENTAL]

O Codex v0.100.0 adicionou um runtime REPL experimental de JavaScript (js_repl) que persiste estado entre chamadas de ferramentas. Na v0.106.0, o REPL foi promovido ao slash command /experimental com verificações de compatibilidade na inicialização — ele requer Node.js 22.22.0 ou posterior.⁶²

Habilitando o JS REPL:

# In config.toml
[features]
js_repl = true

Ou ative durante a sessão via /experimental no TUI.

Exemplo de uso: Quando habilitado, o Codex pode manter estado entre chamadas de ferramentas dentro de uma sessão:

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

Requisitos: Node.js 22.22.0+ (verificações de inicialização confirmam a compatibilidade). A v0.105.0 adicionou relatórios de erros aprimorados e recuperação para falhas do REPL.⁶³

Este recurso é experimental. A interface pode mudar entre releases.

O que são Skills?

Skills são pacotes de capacidades reutilizáveis e específicos para tarefas que o Codex carrega sob demanda. Eles seguem o padrão aberto de skills para agentes.¹⁴

Estrutura de uma skill

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

Locais de descoberta

O Codex armazena skills instaladas pelo usuário em $CODEX_HOME/skills (padrão: ~/.codex/skills), incluindo skills de sistema integradas em .system/. O Codex suporta pastas de skills com links simbólicos.

Criando uma skill

Formato do SKILL.md:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Procedimento de auditoria de segurança

1. Escaneie segredos hardcoded usando `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Verifique injeção de SQL: procure interpolação de strings em consultas
3. Valide a validação de entrada em todos os endpoints API
4. Verifique vulnerabilidades de dependências: `pip audit` ou `npm audit`
5. Revise os padrões de autenticação e autorização
6. Reporte as descobertas com níveis de severidade (Crítico/Alto/Médio/Baixo)

Metadados (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Invocando skills

• Explícita: menu /skills ou menção $skill-name no prompt
• Implícita: Codex detecta automaticamente skills correspondentes a partir da descrição da tarefa (se allow_implicit_invocation: true)
• Criador: Use $skill-creator para construir interativamente uma nova skill
• Instalador: Use $skill-installer install <name> para instalar skills da comunidade

Ativar/Desativar

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills vs slash commands

Depurando skills

Se uma skill não está sendo ativada:

1. Verifique a descoberta: /skills deve listá-la no TUI
2. Verifique o caminho: Certifique-se de que a pasta da skill está em um local reconhecido (~/.codex/skills/, raiz do projeto ou /etc/codex/skills/)
3. Verifique enabled: Skills com enabled = false no config.toml não serão carregadas
4. Verifique a ativação implícita: Se depender da detecção automática, certifique-se de que allow_implicit_invocation: true está no agents/openai.yaml
5. Use palavras-chave: Inclua os termos da description da skill no seu prompt para melhorar a correspondência implícita

Exemplo de produção: skill de deploy

Uma skill completa com múltiplos arquivos mostrando referências e scripts trabalhando juntos:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Invoque com: $deploy to staging ou $deploy production with canary rollout

Modo plan e colaboração

O modo plan permite que o Codex projete uma abordagem antes de executar alterações. Ele é habilitado por padrão (desde a v0.94.0).¹⁵ Consulte Frameworks de decisão para a árvore de decisão “Modo plan vs execução direta”.

Entrando no modo plan

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

No modo plan, o Codex: - Lê arquivos e analisa a base de código - Propõe um plano de implementação - Não faz alterações até que você aprove - Transmite o plano em uma visualização dedicada no TUI

Modo steer

O modo steer (habilitado por padrão desde a v0.98.0) permite que você injete novas instruções enquanto o Codex está trabalhando ativamente, sem interromper a tarefa atual.¹⁵

Existem dois métodos de injeção:

Exemplos práticos:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

O modo steer está sempre ativo no TUI. Se você preferir esperar até que o Codex termine antes de dar instruções, basta digitar normalmente após o turno ser concluído — nenhum modo especial é necessário.

Melhorias no TUI (v0.105.0–v0.106.0)

Destaque de sintaxe (v0.105.0): O TUI agora destaca blocos de código cercados e diffs inline com sintaxe colorida. Use /theme para escolher um esquema de cores.⁶³

Novos comandos do TUI (v0.105.0+):⁶³

Transcrição por voz (v0.105.0, experimental): Pressione a barra de espaço para ditar prompts via transcrição de voz. Este recurso é experimental e pode exigir permissões de microfone.⁶³ A partir da v0.107.0, sessões de voz em tempo real suportam seleção de dispositivo de microfone e alto-falante, permitindo que você escolha hardware específico de entrada/saída de áudio.⁶⁴

Outras melhorias: - Links longos agora permanecem clicáveis mesmo quando quebrados em múltiplas linhas no TUI (v0.105.0)⁶³ - Links de arquivos locais são renderizados com formatação aprimorada (v0.106.0)⁶² - O tratamento de Ctrl+C para subagentes foi corrigido para encerrar adequadamente os processos filhos (v0.106.0)⁶²

Sistema de memória

O Codex possui um sistema de memória persistente (v0.100.0+) que armazena fatos, preferências e contexto de projeto entre sessões.²⁵

Comandos de memória

As memórias são armazenadas em arquivos markdown em ~/.codex/memory/. O Codex as carrega no início da sessão e as utiliza para orientar o comportamento em todas as sessões futuras.

O que armazenar

As memórias funcionam melhor para preferências persistentes e fatos do projeto:

• Convenções do projeto: “Este projeto usa tabs, não espaços” ou “Respostas API sempre incluem um campo meta“
• Preferências de ferramentas: “Use pnpm em vez de npm” ou “Execute testes com pytest -x --tb=short“
• Decisões de arquitetura: “O módulo de autenticação está em src/core/auth/, não em src/middleware/“
• Preferências de workflow: “Sempre execute o linter antes de me mostrar um diff”

Memória em pipelines

Ao executar codex exec, as memórias são carregadas automaticamente. Isso significa que pipelines de CI/CD e scripts se beneficiam do mesmo contexto das sessões interativas — sem necessidade de repetir instruções a cada invocação.

Refinamentos de memória (v0.101.0–v0.107.0)

• Sanitização de segredos: As memórias são automaticamente escaneadas em busca de segredos antes de serem gravadas em disco
• Consciência de CWD: Os arquivos de memória agora incluem o contexto do diretório de trabalho para recuperação específica do projeto
• Exclusão de mensagens do desenvolvedor: Mensagens de desenvolvedor/sistema são excluídas da entrada de memória da fase 1, melhorando a qualidade da memória ao focar nas interações do usuário
• Esquecimento baseado em diff (v0.106.0): A memória agora utiliza esquecimento baseado em diff para remover fatos obsoletos, mantendo o armazenamento de memória enxuto e relevante ao longo do tempo⁶²
• Seleção consciente de uso (v0.106.0): A recuperação de memória agora é consciente de uso, priorizando memórias acessadas frequentemente e recentemente relevantes⁶²
• Memórias configuráveis (v0.107.0): As memórias agora são totalmente configuráveis. Use codex debug clear-memories para redefinir todas as memórias armazenadas para um estado limpo — útil ao alternar contextos entre projetos não relacionados ou quando o estado da memória divergiu⁶⁴

Memória vs AGENTS.md

Dica: Use /m_update para fatos que devem persistir indefinidamente. Para contexto específico da sessão, basta informar o Codex diretamente na conversa. Para contexto compartilhado da equipe, use AGENTS.md.

Gerenciamento de sessões

O Codex persiste sessões em ~/.codex/sessions/, permitindo retomada, fork e fluxos de trabalho multi-thread entre CLI e interfaces desktop.

Retomar

Continue de onde parou:

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

O comando /resume dentro do TUI abre o mesmo seletor interativo com busca.

Fork

Ramifique uma conversa para explorar alternativas sem perder o progresso atual:

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Forks criam threads independentes que compartilham o mesmo histórico até o ponto do fork. Alterações em um fork não afetam o outro. Isso é útil para comparar abordagens (por exemplo, “fork e tentar Redis em vez de Memcached”) ou explorar mudanças arriscadas com segurança.

Fork de threads em sub-agentes (v0.107.0): Threads agora podem ser bifurcadas em sub-agentes independentes, permitindo que uma conversa gere fluxos de trabalho paralelos que executam de forma autônoma. Isso estende o modelo de fork existente — em vez de apenas ramificar a conversa, a thread bifurcada se torna um sub-agente com seu próprio contexto de execução.⁶⁴

Listagem de threads

Visualize e gerencie sessões ativas:

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

No aplicativo desktop, as threads são visíveis na barra lateral com histórico completo e pré-visualização de diffs.

Ciclo de vida da sessão

As sessões sincronizam entre CLI e o aplicativo desktop — comece em um, continue no outro.

Modo não interativo (codex exec)

codex exec executa o Codex de forma não interativa para scripts, CI/CD e automação.¹⁶

Uso básico

codex exec "summarize the repository structure"
codex exec --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Por padrão, codex exec envia progresso/eventos para stderr e a mensagem final do agente para stdout. O design o torna componível com pipelines Unix padrão.

Saída em linhas JSON

Com --json, stdout se torna um fluxo de eventos JSONL:

codex exec --json "fix the tests" | jq

Tipos de evento: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Saída estruturada

Imponha o formato da resposta com JSON Schema:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message grava a mensagem final em um arquivo.

Retomada e revisão de sessão

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Flags principais

Autenticação em CI

codex exec suporta CODEX_API_KEY para autenticação não interativa em ambientes de automação.

Codex Cloud e tarefas em segundo plano [EXPERIMENTAL]

Status: Codex Cloud é um recurso experimental. Interfaces, preços e disponibilidade podem mudar. A OpenAI gerencia os ambientes na nuvem, e você não controla a infraestrutura.

O Codex Cloud executa tarefas de forma assíncrona em ambientes gerenciados pela OpenAI.⁴ Consulte também GitHub Action e CI/CD para integrar o Codex ao seu pipeline de CI.

Como funciona

1. Envie uma tarefa (via chatgpt.com/codex, integração com Slack ou CLI)
2. O Codex clona seu repositório em um sandbox isolado na nuvem
3. O agente trabalha de forma independente: lê código, executa testes, faz alterações
4. Quando termina, o Codex cria um PR ou fornece um diff para revisão
5. Aplique os resultados localmente com codex apply <TASK_ID>

Acesso à internet na nuvem

O acesso à internet do agente está desativado por padrão e é configurado por ambiente:

• Desativado: Sem acesso à internet para o agente (padrão)
• Ativado: Lista de domínios permitidos opcional + restrições de métodos HTTP

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Scripts de configuração ainda podem usar a internet para instalar dependências, mesmo quando o acesso à internet do agente está desativado.

Integração com Slack

Mencione @Codex em um canal ou thread do Slack para iniciar uma tarefa na nuvem.

Pré-requisitos: 1. Plano elegível do ChatGPT (Plus, Pro, Business, Enterprise ou Edu) 2. Conta GitHub conectada 3. Pelo menos um ambiente de nuvem configurado 4. Aplicativo Slack instalado no seu workspace

O Codex responde com um link para a tarefa e publica os resultados quando concluídos.

CLI na nuvem

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

## O Codex Desktop App

O Codex desktop app (somente macOS, Apple Silicon) oferece uma interface gráfica otimizada para gerenciamento de múltiplos projetos.[^17]

### Instalação

```bash
codex app                      # Auto-downloads and installs on first run

Ou baixe diretamente: Codex.dmg

Recursos principais

Modos de thread

Cada thread é executada em um dos três modos, selecionado ao criá-la:

Mecânica de isolamento do Worktree:

Quando você inicia uma thread Worktree, o desktop app: 1. Cria um novo git worktree (git worktree add) em um diretório temporário 2. Faz checkout de uma branch nova a partir do HEAD atual 3. Executa o agente dentro do worktree — todas as alterações de arquivos ficam isoladas 4. Apresenta uma revisão de diff ao finalizar — você escolhe quais alterações mesclar de volta

Isso significa que múltiplas threads Worktree podem ser executadas simultaneamente no mesmo repositório sem conflitos. Cada uma recebe sua própria branch e diretório de trabalho.

Automações

As automações são executadas localmente no app, então o app deve estar em execução e o projeto disponível no disco:

• Em repositórios Git, as automações usam worktrees dedicadas em segundo plano (isoladas do seu diretório de trabalho)
• Em projetos não-Git, as execuções acontecem diretamente no diretório do projeto
• As automações utilizam suas configurações padrão de sandbox

Configurando uma automação: 1. Abra um projeto no desktop app 2. Clique na aba Automações na barra lateral 3. Defina um gatilho (agendamento, webhook ou manual) 4. Escreva o prompt e selecione o modo de thread 5. As automações são executadas conforme o agendamento e enfileiram resultados para revisão

Exemplos de casos de uso: - Triagem de issues: Categorize e priorize automaticamente novas issues - Monitoramento de CI: Observe falhas de build e sugira correções - Resposta a alertas: Reaja a alertas de monitoramento com análise diagnóstica - Atualizações de dependências: Verifique e aplique patches de segurança

Os resultados aparecem em uma fila de revisão para aprovação humana.

Suporte ao Windows

O suporte ao Windows está planejado. Consulte a página do Codex Desktop App ou as releases do GitHub para atualizações de disponibilidade.¹⁸

GitHub Action e CI/CD

A Action oficial do GitHub integra o Codex ao seu pipeline de CI/CD.¹⁹

Uso básico

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Opções de configuração

Saída: final-message, o texto da resposta final do Codex para etapas/jobs subsequentes.

Estratégias de segurança

Controles de acesso

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Padrão: Apenas colaboradores com acesso de escrita podem acionar workflows do Codex.

Codex SDK

O TypeScript SDK incorpora as capacidades de agente do Codex em aplicações personalizadas.²⁰

Instalação

npm install @openai/codex-sdk

Uso básico

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Recursos avançados do SDK

• runStreamed(...): Stream assíncrono de eventos para atualizações intermediárias
• outputSchema: Impõe saída final com formato JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })

Configuração de thread e cliente

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.2-codex" },
});

As sessões persistem em ~/.codex/sessions.

Runtime: Node.js 18+.

Otimização de desempenho

Gerenciamento de contexto

Os modelos principais possuem janelas de entrada de 272K tokens (128K de saída, 400K de orçamento total), mas ainda assim preenchem mais rápido do que se imagina. Gerencie proativamente:

1. Use /compact regularmente: Resume o histórico da conversa para liberar tokens
2. Forneça documentação local: Um AGENTS.md de alta qualidade e documentação local reduzem a sobrecarga de exploração (que consome contexto)
3. Use @ para anexar arquivos específicos: Referencie arquivos diretamente em vez de pedir ao Codex para encontrá-los
4. Mantenha os prompts focados: Prompts com escopo definido e arquivos exatos consomem menos contexto do que exploração aberta

Eficiência de tokens

Otimização de velocidade

1. gpt-5.3-codex-spark: Variante de menor latência para pareamento interativo
2. --profile fast: Modelo mini pré-configurado com baixo raciocínio
3. Execução paralela de ferramentas: O Codex executa leituras/verificações independentes simultaneamente, então estruture seus prompts para viabilizar isso
4. Loops orientados a resultado: Peça “implemente, teste, corrija, pare quando estiver verde” em vez de instruções passo a passo

Como depurar problemas?

Problemas comuns e soluções

Referência de mensagens de erro

Ferramentas de diagnóstico

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

Diagnósticos da TUI durante a sessão:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Nota: codex --verbose não é uma flag válida de nível superior. Use os subcomandos de debug e os diagnósticos da TUI acima.

Reinstalação limpa

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Modo de debug

codex debug app-server send-message-v2  # Test app-server client

Reportando problemas

/feedback                              # Send logs to Codex maintainers (in TUI)

Ou registre issues em github.com/openai/codex/issues.¹

Implantação empresarial

Controles administrativos (requirements.toml)

Administradores aplicam políticas empresariais via requirements.toml, um arquivo de configuração imposto pelo administrador que restringe configurações sensíveis de segurança que os usuários não podem sobrescrever:²²

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "on-failure"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

Diferentemente do config.toml de nível de usuário que define preferências, o requirements.toml é uma camada de restrição rígida que limita quais valores os usuários podem selecionar, e os usuários não podem sobrescrevê-lo. As regras de requisitos do administrador só podem solicitar confirmação ou proibir (nunca permitir silenciosamente).

Configuração MDM para macOS

Distribua via MDM usando o domínio de preferência com.openai.codex.²² O Codex respeita payloads padrão de MDM do macOS (Jamf Pro, Fleet, Kandji, etc.). Codifique o TOML como base64 sem quebras de linha:

Precedência (da mais alta para a mais baixa):

1. Preferências gerenciadas do macOS (MDM)
2. Requisitos obtidos da nuvem (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (sistema de arquivos local)

Os requisitos da nuvem apenas preenchem campos de requisitos não definidos, então camadas gerenciadas de maior precedência sempre prevalecem. Os requisitos da nuvem são fornecidos com base no melhor esforço; se a busca falhar ou expirar, o Codex continua sem a camada da nuvem.

Integração com OpenTelemetry

O Codex suporta propagação de contexto de rastreamento OpenTelemetry a partir de variáveis de ambiente OTel padrão até as chamadas à API da OpenAI. Defina as variáveis de ambiente padrão antes de iniciar o Codex:

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• As variáveis de ambiente OTEL_* padrão são respeitadas (endpoint, nome do serviço, atributos de recurso)
• O contexto de rastreamento se propaga pelo Codex até as chamadas à API, permitindo observabilidade de ponta a ponta
• Use atributos de recurso para marcar rastreamentos por equipe, ambiente ou projeto
• Tenha em mente os requisitos de privacidade ao habilitar o registro de prompts/ferramentas — os rastreamentos podem conter trechos de código

Acesso empresarial

• ChatGPT Business / Enterprise / Edu: Acesso controlado pelo administrador da organização, com requisitos obtidos da nuvem aplicados automaticamente. Suporta SSO via SAML/OIDC através do seu provedor de identidade (Okta, Entra ID, etc.)
• API: Autenticação padrão da API, cobrança e controles de organização/projeto. A OpenAI publica relatórios SOC 2 Type II e SOC 3; BAA HIPAA disponível para o nível Enterprise
• Codex SDK: Incorpore em ferramentas e fluxos de trabalho internos
• Aplicação de políticas em escala: Use requirements_toml_base64 distribuído via MDM ou /etc/codex/requirements.toml no nível do sistema de arquivos

Tratamento de dados e conformidade: - Entradas/saídas da API não são usadas para treinamento sob os termos Business/Enterprise/API da OpenAI - Para residência de dados, o tráfego da API da OpenAI é roteado por infraestrutura baseada nos EUA por padrão; para requisitos de residência de dados na UE, consulte a equipe de vendas Enterprise da OpenAI - As transcrições das sessões são armazenadas localmente; apenas as chamadas à API saem da máquina - O ChatGPT Enterprise suporta frameworks de conformidade incluindo SOC 2, GDPR e CCPA

Estratégia de implantação

Implantação em fases recomendada para organizações:

1. Piloto (Semana 1-2): Implante para 3-5 engenheiros seniores com requirements.toml aplicando o modo sandbox untrusted e busca web cached. Colete feedback sobre padrões do AGENTS.md e necessidades de servidores MCP.
2. Expansão para a equipe (Semana 3-4): Distribua para a equipe completa. Distribua o config.toml padrão da equipe via MDM ou repositório. Habilite o sandbox workspace-write para repositórios confiáveis.
3. Integração com CI (Semana 5-6): Adicione codex-action aos pipelines de CI/CD para revisão automatizada de PRs e geração de testes. Use --ephemeral para manter os custos previsíveis.
4. Toda a organização (Mês 2+): Implante via MDM com requirements.toml aplicando servidores MCP aprovados, políticas de sandbox e listas de modelos permitidos.

Padrões de auditoria

Monitore o uso do Codex e aplique conformidade:

• Rastreamentos OpenTelemetry: Monitore o volume de chamadas à API, uso de tokens e latência por equipe
• Persistência de sessão: Audite ~/.codex/sessions/ para revisão de conformidade (desabilite com --ephemeral em contextos sensíveis)
• Aplicação de identidade MCP: O requirements.toml registra tentativas de servidores bloqueados — revise para detectar uso não autorizado de ferramentas
• Trilha de auditoria do Git: Todas as alterações de arquivo do Codex passam pelo git padrão — revise via histórico de branches e diffs de PRs

Melhores Práticas e Anti-Padrões

Padrões de Prompt

1. Prompts orientados por restrições: Comece com limites. “Do NOT change the API contracts. Only refactor internal implementation.”
2. Passos de reprodução estruturados: Passos numerados produzem correções de bugs melhores do que descrições vagas
3. Solicitações de verificação: Termine com “Run lint + the smallest relevant test suite. Report commands and results.”
4. Referências a arquivos: Use @filename para anexar arquivos específicos ao contexto
5. Loops orientados a resultados: “Implement, run tests, fix failures, stop only when all tests pass.” O Codex itera até concluir

Filosofia de Testes

A comunidade converge para a colaboração com IA orientada por testes:²³

• Defina testes antecipadamente como sinais de conclusão
• Deixe o Codex iterar até que os testes passem (red → green → refactor)
• Adote padrões de programação Tiger Style
• Forneça o texto exato do arquivo ao solicitar patches. O Codex usa correspondência estrita, não patching fuzzy baseado em AST

Melhores Práticas de Gerenciamento de Contexto

• Forneça documentação local de alta qualidade em vez de depender de busca na web
• Mantenha markdown estruturado com sumários e arquivos de progresso (“progressive disclosure”)
• Normalize terminações de linha (LF vs CRLF) em arquivos rastreados para evitar falhas em patches
• Mantenha o AGENTS.md conciso, pois instruções longas são empurradas para fora do contexto

Fluxo de Trabalho com Git

• Sempre crie um novo branch antes de executar o Codex em repositórios desconhecidos
• Use fluxos baseados em patch (git diff / git apply) em vez de edições diretas
• Revise as sugestões do Codex como revisões de código em PRs
• Use /diff para verificar as alterações antes de fazer commit

Skills e Prompts da Comunidade

O repositório feiskyer/codex-settings fornece configurações mantidas pela comunidade:²⁴

Prompts reutilizáveis (em ~/.codex/prompts/): - deep-reflector: Extrair aprendizados de sessões de desenvolvimento - github-issue-fixer [issue-number]: Análise sistemática de bugs e criação de PRs - github-pr-reviewer [pr-number]: Fluxos de revisão de código - ui-engineer [requirements]: Desenvolvimento frontend de nível de produção

Skills da comunidade: - claude-skill: Delegar tarefas ao Claude Code com modos de permissão - autonomous-skill: Automação de tarefas multi-sessão com rastreamento de progresso - deep-research: Orquestração paralela de sub-tarefas - kiro-skill: Pipeline de requisitos → design → tarefas → execução

Anti-Padrões

Erros comuns que desperdiçam tokens, produzem resultados ruins ou criam fluxos de trabalho frustrantes.

Anti-Padrões de Custo

Anti-Padrões de Contexto

Anti-Padrões de Fluxo de Trabalho

Anti-Padrões de Prompt

Receitas de Fluxo de Trabalho

Padrões de ponta a ponta para cenários comuns de desenvolvimento.

Receita 1: Configuração de Novo Projeto

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Revise o AGENTS.md gerado, edite para corresponder às suas convenções, e então:

> Run the health endpoint test and confirm it passes

Receita 2: Fluxo de Desenvolvimento Diário

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Revise com /diff, e então faça commit.

Receita 3: Refatoração Complexa com Modo de Planejamento

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Revise o plano. Aprove ou direcione:

[Tab] Also add a migration script using Alembic

Após o Codex executar, verifique:

> Run the full test suite and report results
> /diff

Receita 4: Revisão de PR com codex exec

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Receita 5: Depuração com Cloud Tasks [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

Verifique o progresso depois:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Aplique a correção localmente quando terminar:

codex apply <TASK_ID>

Guia de Migração

A partir do Claude Code

Principais diferenças a entender:

• Sandbox é em nível de SO: Codex usa Seatbelt/Landlock, não contêineres. As restrições operam no nível do kernel, abaixo da camada de aplicação.
• Hooks são nascentes: Codex adicionou hooks na v0.99.0 (AfterAgent) e v0.100.0 (AfterToolUse), mas o sistema está em estágio inicial comparado aos 12+ eventos de ciclo de vida do Claude Code. Para padrões de automação ainda não cobertos, use instruções no AGENTS.md ou skills.
• Sub-agents são internos, mas agora configuráveis: Codex possui mecanismo de sub-agents (máx. 6 concorrentes, reduzido de 12 na v0.91.0). A partir da v0.104.0, funções multi-agente são personalizáveis via configuração, permitindo funções de agente nomeadas com perfis distintos.⁴⁹ A v0.105.0 adicionou spawn_agents_on_csv para distribuição entre linhas com acompanhamento de progresso e ETA.⁶³ Codex ainda não possui o UX explícito da ferramenta Task do Claude Code para delegação direcionada pelo usuário — use tarefas na nuvem ou orquestração SDK para padrões de delegação.
• AGENTS.md é multi-ferramenta: Seu AGENTS.md funciona no Cursor, Copilot, Amp, Jules, Gemini CLI e em mais de 60.000 projetos open source. CLAUDE.md é exclusivo do Claude.
• Perfis substituem alternância manual: Em vez de alterar flags por execução, defina perfis no config.toml.

A partir do GitHub Copilot

O que você ganha: - Sandbox em nível de SO (Seatbelt/Landlock — imposto pelo kernel vs baseado em contêiner) - Delegação de tarefas na nuvem com codex apply - Perfis de configuração para alternância de fluxos de trabalho - Aplicativo desktop com isolamento via worktree

A partir do Cursor

Cartão de Referência Rápida

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --full-auto                workspace-write + on-request      ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║  /experimental Toggle experimental features (js_repl)        ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --full-auto "task"          Sandboxed auto        ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026, v0.106.0)                                  ║
║  gpt-5.3-codex         Default flagship (272K in / 400K)     ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Changelog

Referências

Nota sobre URLs do blog OpenAI: As referências ¹⁷, ²⁶–³¹ e ³⁴ apontam para posts no blog openai.com/index/ que retornam HTTP 403 para acesso automatizado devido à proteção contra bots do Cloudflare. Essas URLs são válidas quando acessadas por um navegador web padrão.