Codex CLI: O Guia Técnico Definitivo

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 perfis para alternar entre contextos, /compact para gerenciar o orçamento de contexto e AGENTS.md para instruções de projeto cross-tool que funcionam no Codex, Cursor, Amp e outros. GPT-5.4 é agora o modelo recomendado com janelas de contexto de 1M.

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 uso casual e uso eficaz 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: define o que o Codex pode fazer
3. AGENTS.md: estabelece contratos operacionais no nível do projeto
4. Protocolo MCP: estende capacidades para serviços externos
5. Sistema de skills: empacota expertise de domínio reutilizável

Passei meses rodando o Codex junto com Claude Code em bases de código de produção, pipelines de CI/CD e fluxos de trabalho em equipe. Este guia destila essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui 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. Codex Cloud, grupo de comandos MCP, code mode e hooks engine são experimentais na versão v0.117.0. O CLI principal, sandbox, AGENTS.md, config.toml, Skills e o sistema de plugins 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 se encaixa no seu fluxo de trabalho.
• Sandboxing no nível do SO: 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 containers.
• AGENTS.md é cross-tool: Suas instruções de projeto funcionam no Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed e mais de 60.000 projetos open source. Escreva uma vez, use em qualquer lugar.
• Perfis economizam overhead de troca de contexto: Defina presets de configuração nomeados (fast, careful, auto) e alterne entre eles com --profile.
• Gerenciamento de contexto importa: GPT-5.4 oferece 1M de contexto; GPT-5.3-Codex fornece 272K de entrada. De qualquer forma, 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 comandos principais.

Como 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         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                          │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Camada central: A família de modelos GPT-5.x-Codex alimenta tudo. A partir da v0.111.0, gpt-5.4 é o modelo recomendado — o modelo frontier principal da OpenAI, combinando as capacidades de codificação do GPT-5.3-Codex com raciocínio mais forte, uso nativo de computador e janelas de contexto de 1M.⁶⁶ Ele lê arquivos, escreve patches, executa comandos shell e raciocina sobre seu codebase. Quando o contexto enche, Codex compacta a conversa para liberar espaço. Esta camada custa tokens.

Camada de segurança: Todo comando que Codex executa passa por um sandbox no nível do SO. No macOS, o framework Seatbelt da Apple impõe restrições no nível do kernel. No Linux, Landlock + seccomp filtram acesso ao sistema de arquivos e syscalls. O sandbox opera no nível do kernel, não dentro de containers. A política de aprovação então decide quando solicitar confirmação humana.

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

Camada de superfície: CLI para power users de terminal e automação. Aplicativo desktop para gerenciamento de projetos multi-thread. Extensão para IDE para ciclos de edição-compilação-teste. Cloud para tarefas assíncronas que rodam independentemente.

O insight principal: A maioria dos usuários usa apenas uma superfície. Power users 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 instalo o Codex?
2. Início rápido: sua primeira sessão
3. Superfícies de interação principais
4. Mergulho profundo 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. Code Mode
13. Runtime REPL JavaScript
14. O que são Skills?
15. Plugins
16. Modo planejamento e colaboração
17. Sistema de memória
18. Gerenciamento de sessão
19. Modo não interativo (codex exec)
20. Codex Cloud e tarefas em segundo plano
21. O aplicativo desktop Codex
22. GitHub Action e CI/CD
23. Codex SDK
24. Otimização de performance
25. Como depuro problemas?
26. Implantação enterprise
27. Boas práticas e antipadrões
28. Receitas de workflow
29. Guia de migração
30. Cartão de referência rápida
31. Changelog
32. Referências

Como instalo o Codex?

Gerenciadores de pacotes

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.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 de uma 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 por 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 de Plus, Pro, Team, Business, Edu ou Enterprise. Acesso completo aos 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 file).

Completions de 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 instalação

codex --version
# Codex CLI v0.104.0

Início rápido: sua primeira sessão

Saia do zero e fique produtivo em 5 minutos.

1. Instale e autentique:

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 padrão suggest.

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. Confira 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 sustentadas pela mesma inteligência. Cada superfície é otimizada para um padrão de fluxo de trabalho diferente.

1. CLI interativa (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 terminal UI é 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 + Windows)

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

O desktop app adiciona funcionalidades que a CLI não possui:

• Multitarefa: Execute múltiplos agentes paralelos 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 commit de alterações sem sair do app
• Terminal integrado: Terminal dedicado por thread para executar 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 a CLI: Use o desktop app quando estiver coordenando múltiplos fluxos de trabalho ou precisar de revisão visual de diffs. Use a 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: As sessões sincronizam entre a CLI e a extensão para IDE
• Mesma autenticação: Faça login com sua conta do ChatGPT ou chave API

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

4. Codex Cloud [EXPERIMENTAL]

Tarefas na nuvem são executadas de forma assíncrona em ambientes gerenciados pela OpenAI:

• Disparar e esquecer: Enfileire tarefas que rodam 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
• Aplicar localmente: Puxe os resultados da nuvem para o 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

As 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. Compreender a hierarquia de precedência é fundamental 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, descoberto a partir do CWD 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 no 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

Presets de configuração nomeados 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.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

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

Ative 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 de 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 esse 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 (março de 2026)

O GPT-5.4 está disponível em todas as superfícies do Codex (CLI, app, extensão IDE, nuvem).⁶⁶ A lista exata de modelos varia conforme a conta e o rollout. Verifique seu cache local: ~/.codex/models_cache.json.

Nota de descontinuação (11 de março de 2026): Os modelos GPT-5.1 não estão mais disponíveis no ChatGPT. Conversas existentes continuam automaticamente no GPT-5.3 Instant, GPT-5.4 Thinking ou GPT-5.4 Pro. O GPT-5.1-Codex-Mini permanece disponível via API e CLI para cargas de trabalho sensíveis a custos.⁷³

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 (near-instant, Pro only)
   │  └─ No
   │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │  └─ No → gpt-5.4 (recommended: coding + reasoning + computer use, 1M context)
   └─ Still unsure? → gpt-5.4

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 de taxa 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 superfícies — 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:

Os planos Enterprise e Edu escalam créditos conforme a alocação contratual. Verifique /status no TUI para o uso atual.

Faturamento via API

Ao usar o Codex através da API, a OpenAI cobra o uso por token conforme 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 alto raciocínio: Use xhigh apenas para problemas genuinamente difíceis, pois consome de 3 a 5x mais tokens
3. Use --ephemeral: Pule a persistência de sessão em CI/CD para reduzir a sobrecarga
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 a sobrecarga do TUI para fluxos de automação
6. Monitore o uso: Verifique /status no TUI e os painéis de faturamento da sua organização

Exemplos reais de custo

Custos representativos via 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 duração 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.

Sobrecarga oculta 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 toda a sobrecarga, 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 de 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, ouça isso 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?

Combine sua tarefa com 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"

Alterne 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 Enterprise Deployment 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) oferece isolamento com defesa em profundidade.⁵ Bubblewrap (bwrap) é incluído e compilado como parte do build Linux (promovido de opcional na v0.100.0)⁷. A v0.117.0 melhorou a confiabilidade do sandbox em distros mais antigas com configurações de kernel legadas.⁷⁷
• Windows: Sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é suportado (herda Landlock + seccomp do Linux). A v0.117.0 inclui melhorias no sandbox com tokens restritos para melhor isolamento de processos.⁷⁷

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 podia 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 impõe um limite de aproximadamente 1 milhão de caracteres na entrada para evitar travamentos com 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+): Um formato de política configurável para controle granular de acesso de leitura. Use 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 pedir 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 comandos seguintes 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 o mesmo comando novamente

Solicitações de permissão em tempo de execução (v0.113.0+)

O Codex agora inclui uma ferramenta integrada request_permissions que permite ao modelo solicitar permissões adicionais em tempo de execução.⁷¹ Quando o modelo encontra uma tarefa que requer acesso elevado, ele pode solicitar formalmente permissões específicas (caminhos do sistema de arquivos, acesso à rede, etc.) através do fluxo de aprovação na TUI em vez de falhar silenciosamente ou exigir que o usuário reinicie com flags diferentes.

Linguagem de configuração de perfis de permissão (v0.113.0+)

Uma nova linguagem de configuração para perfis de permissão divide as políticas de sandbox de sistema de arquivos e rede em seções separadas e combináveis:⁷¹

[permission_profile.filesystem]
read = ["~/Projects", "/usr/local"]
write = ["~/Projects/my-app"]

[permission_profile.network]
allow = ["api.github.com", "registry.npmjs.org"]
deny = ["*"]   # Global wildcard domains now rejected (hardened in v0.113.0)

Isso substitui o modo de sandbox monolítico por políticas granulares por recurso. Perfis de permissão executáveis também se integram com a política de sandbox por turno para execução de skills (v0.112.0).⁷⁰

A flag --full-auto

--full-auto é um atalho conveniente para:

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

Atenção importante: --full-auto sobrescreve qualquer valor explícito de --sandbox. Se você passar --full-auto --sandbox read-only, o resultado será 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 circuito):

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

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

Automação CI/CD:

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

Aprovações inteligentes com subagente guardião (v0.115.0+)

As aprovações inteligentes podem encaminhar solicitações de revisão através de um subagente guardião em vez de exigir aprovação humana para cada ação. A sessão do guardião persiste entre aprovações para reutilizar o cache de prompt e evitar overhead de inicialização. Cada revisão recebe um histórico limpo (decisões anteriores não vazam para revisões posteriores).⁷⁵

Configure o revisor no config.toml:

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

Isso é particularmente útil para workflows de CI/CD onde você quer revisão automatizada com raciocínio em vez de simplesmente usar 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 através de 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"

Essas complementam o suporte existente a HTTPS_PROXY e proxy 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 qualquer um dos comandos for bem-sucedido, sua configuração de sandbox precisa ser investigada.

Como o AGENTS.md Funciona?

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 Torna um AGENTS.md Excelente

Com base em orientações diretas 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 estiver bloqueado ou encontrar um 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.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

O Mecanismo de Override

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

• Congelamento de releases: “Sem novos recursos, apenas correções”
• Modo de incidente: “Todas as alterações devem ser revisadas pelo plantonista”
• Endurecimento temporário: “Sem atualizações de dependências neste 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 introduziu hooks na v0.99.0 (AfterAgent) e v0.100.0 (AfterToolUse), depois adicionou um engine de hooks experimental na v0.114.0 com os eventos SessionStart e Stop.⁷² O sistema agora cobre o ciclo de vida da sessão e automação em nível de ferramenta, fechando a lacuna com o modelo de hooks do Claude Code.

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"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

O stdout do hook SessionStart alimenta o contexto do modelo, tornando-o ideal para injetar informações dinâmicas (datas, nomes de branches, variáveis de ambiente) no início da sessão.

Replicando Padrões de Hook do Claude Code

Se você está migrando do Claude Code, veja como obter automação semelhante:

Dica avançada: O engine de hooks é experimental e está em expansão ativa. Confira o changelog do Codex para novos eventos de hook em cada release.

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

MCP amplia 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 o formato de configuração podem mudar entre versões. 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 via 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 contexto — Combine o Context7 com a documentação do seu framework para que o Codex sempre tenha referências atualizadas da 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 MCP corporativa — Controle 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 Enterprise Deployment para a configuração completa de políticas.

Code Mode [EXPERIMENTAL]

O Code Mode (v0.114.0) oferece fluxos de trabalho de codificação mais isolados, restringindo o escopo do agente a operações focadas em código.⁷² Quando ativado, o agente se concentra em ler, escrever e testar código sem interações mais amplas com o sistema.

Este recurso é experimental. Consulte as notas de versão para atualizações.

JavaScript REPL Runtime [EXPERIMENTAL]

O Codex v0.100.0 adicionou um runtime JavaScript REPL experimental (js_repl) que mantém o 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 superior.⁶²

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 o 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 na inicialização confirmam a compatibilidade). A v0.105.0 adicionou relatórios de erro aprimorados e recuperação para falhas do REPL.⁶³

Este recurso é experimental. A interface pode mudar entre versões.

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. Procure por segredos hardcoded usando `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Verifique SQL injection: procure por interpolação de strings em queries
3. Valide a validação de entrada em todos os endpoints API
4. Verifique vulnerabilidades em 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)

Metadata (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)
• Criação: Use $skill-creator para construir uma nova skill interativamente
• Instalação: 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 na 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 em config.toml não serão carregadas
4. Verifique a ativação implícita: Se está dependendo da detecção automática, certifique-se de que allow_implicit_invocation: true está definido em 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 funcionando 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

Plugins

Plugins unificam skills, entradas MCP e conectores de aplicativos em um único pacote instalável (v0.110.0+).⁶⁷ A partir da v0.117.0, plugins são cidadãos de primeira classe: plugins com escopo de produto são sincronizados automaticamente na inicialização, /plugins oferece um navegador dentro da TUI para descoberta e gerenciamento, e operações de instalação/remoção funcionam tanto no CLI quanto na TUI.⁷⁷

Fontes de plugins

Descoberta de plugins

Codex informa ao modelo quais plugins estão habilitados no início da sessão (v0.111.0), melhorando a descoberta de MCPs, aplicativos e skills instalados.⁶⁷ O modelo pode sugerir plugins relevantes durante uma sessão com base no contexto da tarefa. Na v0.117.0, plugins com escopo de produto são sincronizados na inicialização, garantindo que o catálogo de plugins mais recente esteja disponível sem intervenção manual.⁷⁷

Menções @plugin (v0.112.0+)

Referencie qualquer plugin instalado diretamente no chat com @plugin-name.⁷⁰ Quando você menciona um plugin, seu contexto (capacidades, ferramentas, configuração) é automaticamente incluído na janela de contexto do modelo — sem necessidade de descrever o que o plugin faz.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

Isso funciona com qualquer plugin instalado, incluindo skills personalizadas, servidores MCP e conectores de aplicativos.

Marketplace de plugins (v0.113.0+)

O marketplace de plugins agora inclui descoberta mais rica com metadata, categorias e avaliações.⁷¹ Verificações de autenticação na instalação confirmam que plugins que requerem chaves API ou OAuth possuem credenciais válidas antes da instalação. Um endpoint de desinstalação remove plugins e suas configurações associadas de forma limpa.

Gerenciando plugins

codex plugin list              # Show installed plugins
codex plugin install <name>    # Install from marketplace
codex plugin uninstall <name>  # Remove plugin and config (v0.113.0+)

Na TUI, use /plugins (v0.117.0+) para navegar, instalar e remover plugins interativamente sem sair da sua sessão.⁷⁷

Dica avançada: Plugins consolidam o que antes exigia configuração separada de MCP, instalação de skills e configuração de conectores de aplicativos. Um único plugin pode agrupar os três — tornando a integração do time mais rápida e a configuração mais portável.

Plan mode e colaboração

O plan mode permite que Codex projete uma abordagem antes de executar mudanças. Ele é habilitado por padrão (desde a v0.94.0).¹⁵ Consulte Frameworks de decisão para a árvore de decisão “Plan Mode vs Execução Direta”.

Entrando no plan mode

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

No plan mode, Codex: - Lê arquivos e analisa o codebase - Propõe um plano de implementação - Não faz alterações até que você aprove - Transmite o plano em uma visualização dedicada na TUI

Steer mode

O steer mode (habilitado por padrão desde a v0.98.0) permite que você injete novas instruções enquanto Codex está trabalhando ativamente, sem interromper sua 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 steer mode está sempre ativo na TUI. Se você preferir esperar até que Codex termine antes de dar instruções, basta digitar normalmente após o turno ser concluído — nenhum modo especial é necessário.

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

Destaque de sintaxe (v0.105.0): A TUI agora aplica destaque de sintaxe em blocos de código cercados e diffs inline. Use /theme para escolher um esquema de cores.⁶³

Novos comandos na 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 entre linhas na TUI (v0.105.0)⁶³ - Links de arquivos locais são renderizados com formatação aprimorada (v0.106.0)⁶² - Tratamento de Ctrl+C para sub-agentes corrigido para encerrar corretamente 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 da 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 que sessões interativas — sem necessidade de repetir instruções em cada invocação.

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

• Sanitização de segredos: As memórias são automaticamente verificadas em busca de segredos antes de serem gravadas em disco
• Reconhecimento de CWD: Os arquivos de memória agora incluem o contexto do diretório de trabalho para recall específico por projeto
• Exclusão de mensagens de 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 usa esquecimento baseado em diff para remover fatos obsoletos, mantendo o armazenamento de memória enxuto e relevante ao longo do tempo⁶²
• Seleção baseada em uso (v0.106.0): A recuperação de memória agora é baseada em uso, priorizando memórias acessadas com frequência 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 e começar do zero — útil ao alternar entre projetos não relacionados ou quando o estado da memória ficou inconsistente⁶⁴

Memória vs AGENTS.md

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

Gerenciamento de sessões

O Codex persiste sessões em ~/.codex/sessions/, permitindo retomada, bifurcação e workflows multi-thread entre CLI e superfícies 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.

Bifurcação

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

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

As bifurcações criam threads independentes compartilhando o mesmo histórico até o ponto de bifurcação. Alterações em uma bifurcação não afetam a outra. Isso é útil para comparar abordagens (ex.: “bifurcar e tentar Redis em vez de Memcached”) ou explorar mudanças arriscadas com segurança.

Bifurcação 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 bifurcação existente — em vez de apenas ramificar a conversa, a thread bifurcada se torna um sub-agente com seu próprio contexto de execução.⁶⁴ A partir da v0.117.0, sub-agentes usam endereços baseados em caminho (ex.: /root/agent_a) com mensagens estruturadas entre agentes, tornando a coordenação multi-agente mais explícita e depurável.⁷⁷

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 ficam 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)

O 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, o codex exec escreve progresso/eventos em stderr e a mensagem final do agente em stdout. O design o torna componível com pipelines Unix padrão.

Saída em linhas JSON

Com --json, o stdout se torna um stream 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 para CI

O 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: O Codex Cloud é um recurso experimental. Interfaces, preços e disponibilidade podem mudar. A OpenAI gerencia os ambientes em nuvem, e você não controla a infraestrutura.

O Codex Cloud executa tarefas de forma assíncrona em ambientes gerenciados pela OpenAI.⁴ Veja 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 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 ChatGPT elegível (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 da tarefa e publica os resultados quando completa.

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 (macOS e Windows) oferece uma interface gráfica otimizada para gerenciamento de múltiplos projetos.[^17] A versão para Windows foi lançada em 4 de março de 2026 com suporte nativo a PowerShell e sandbox nativo do Windows.[^68]

### Instalação

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

Ou baixe diretamente: Codex.dmg (macOS) | Disponível na Microsoft Store (Windows)

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 nova branch a partir do HEAD atual 3. Executa o agente dentro do worktree — todas as alterações de arquivo ficam isoladas 4. Apresenta uma revisão de diff ao concluir — você escolhe quais alterações integrar 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 precisa estar aberto e o projeto disponível em disco:

• Em repositórios Git, as automações usam worktrees dedicadas em segundo plano (isoladas do seu diretório de trabalho)
• Em projetos sem Git, as execuções acontecem diretamente no diretório do projeto
• As automações usam 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 execução (local ou worktree) 5. Defina o nível de raciocínio para a execução da automação (App v26.312)⁷⁴ 6. As automações são executadas conforme o agendamento e enfileiram resultados para revisão

Exemplos de uso: - Triagem de issues: Categorize e priorize automaticamente novas issues - Monitoramento de CI: Acompanhe falhas de build e sugira correções - Resposta a alertas: Reaja a alertas de monitoramento com análise de diagnóstico - Atualização 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 Codex Desktop App foi lançado no Windows em 4 de março de 2026 (App v26.304) com suporte nativo a PowerShell, sandbox nativo do Windows e paridade completa de recursos, incluindo skills, automações e worktrees sem necessidade de WSL.⁶⁸

GitHub Action e CI/CD

A GitHub Action oficial 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 de resposta final do Codex para steps/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 de eventos assíncronos para atualizações intermediárias
• outputSchema: Impõe saída final no formato JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })
• Workflows de imagem (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas, e o histórico de imagens persiste entre sessões⁷⁷

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 são persistidas em ~/.codex/sessions.

Runtime: Node.js 18+.

Otimização de desempenho

Gerenciamento de contexto

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

1. Use /compact regularmente: Resume o histórico da conversa para liberar tokens
2. Forneça documentação local: AGENTS.md e documentação local de alta qualidade 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 raciocínio baixo
3. Execução paralela de ferramentas: O Codex executa leituras/verificações independentes simultaneamente, então estruture 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 de nível superior válida. Use os subcomandos de debug e os diagnósticos da TUI descritos acima.

Reinstalação limpa

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

Modo 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 corporativas 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"

Diferente 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 requirements do administrador só podem solicitar confirmação ou proibir (nunca permitir silenciosamente).

Configuração via MDM no macOS

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

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

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

Os requirements da nuvem só preenchem campos de requirement não definidos, então as camadas gerenciadas de maior precedência sempre prevalecem. Os requirements da nuvem funcionam em regime de 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 trace-context do OpenTelemetry a partir de variáveis de ambiente padrão do OTel para chamadas da 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 padrão OTEL_* são respeitadas (endpoint, nome do serviço, atributos de recurso)
• O contexto de rastreamento se propaga pelo Codex até as chamadas da API, permitindo observabilidade de ponta a ponta
• Use atributos de recurso para marcar traces por equipe, ambiente ou projeto
• Considere os requisitos de privacidade ao habilitar logging de prompts/ferramentas — os traces podem conter trechos de código

Acesso empresarial

• ChatGPT Business / Enterprise / Edu: Acesso controlado pelo administrador da organização, com requirements 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 para HIPAA disponível no tier Enterprise
• Codex SDK: Incorpore em ferramentas internas e fluxos de trabalho
• 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 passa 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 de sessão são armazenadas localmente; apenas chamadas da 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 gradual recomendada para organizações:

1. Piloto (Semana 1-2): Implante para 3-5 engenheiros seniores com requirements.toml impondo 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): Implante para toda a equipe. 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 impondo servidores MCP aprovados, políticas de sandbox e listas de modelos permitidos.

Padrões de auditoria

Acompanhe o uso do Codex e garanta a conformidade:

• Traces do OpenTelemetry: Monitore o volume de chamadas da 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)
• Imposição de identidade MCP: O requirements.toml registra tentativas de servidores bloqueados — revise para 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

Boas Práticas e Anti-Padrões

Padrões de Prompts

1. Prompts orientados por restrições: Comece pelas limitações. “Do NOT change the API contracts. Only refactor internal implementation.”
2. Passos de reprodução estruturados: Passos numerados produzem correções 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 por resultado: “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é os testes passarem (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

Boas 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 índices e arquivos de progresso (“progressive disclosure”)
• Normalize finais de linha (LF vs CRLF) em arquivos rastreados para evitar falhas de patch
• Mantenha o AGENTS.md conciso, já que instruções longas são empurradas para fora do contexto

Fluxo de Trabalho 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 se fossem PRs de code review
• 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 code review - ui-engineer [requirements]: Desenvolvimento frontend de nível 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 completos 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 faça commit.

Receita 3: Refatoração Complexa com Plan Mode

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: Debugging 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 opera no nível do SO: O Codex usa Seatbelt/Landlock, não containers. As restrições operam no nível do kernel, abaixo da camada de aplicação.
• Hooks estão em expansão: O Codex agora suporta 5 eventos de hooks: SessionStart, Stop e UserPromptSubmit (v0.114.0–v0.116.0, experimental) além de AfterAgent (v0.99.0) e AfterToolUse (v0.100.0). O sistema cobre ciclo de vida da sessão, interceptação de prompts e automação no nível de ferramentas, embora os 12+ eventos de ciclo de vida do Claude Code ainda ofereçam cobertura mais ampla. Para padrões de automação ainda não cobertos, use instruções do AGENTS.md ou skills.
• Sub-agents v2 (v0.117.0): Sub-agents agora usam endereços baseados em caminhos (ex.: /root/agent_a) com mensagens estruturadas entre agentes e listagem de agentes.⁷⁷ Isso estende o mecanismo existente (máx. 6 simultâneos, reduzido de 12 na v0.91.0). Funções multi-agente continuam customizáveis via config (v0.104.0+).⁴⁹ A v0.105.0 adicionou spawn_agents_on_csv para distribuição em linhas com rastreamento de progresso e ETA.⁶³ O Codex ainda não possui a UX explícita da ferramenta Task do Claude Code para delegação direcionada pelo usuário — use cloud tasks ou orquestração SDK para padrões de delegação.
• AGENTS.md é multiplataforma: Seu AGENTS.md funciona no Cursor, Copilot, Amp, Jules, Gemini CLI e mais de 60.000 projetos open source. CLAUDE.md é exclusivo do Claude.
• Profiles substituem troca manual: Em vez de alterar flags por execução, defina profiles no config.toml.

A partir do GitHub Copilot

O que você ganha: - Sandboxing no nível do SO (Seatbelt/Landlock — imposto pelo kernel vs baseado em container) - Delegação de tarefas na nuvem com codex apply - Profiles de configuração para alternância de workflows - Desktop app com isolamento de 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       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /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               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin list              List installed plugins        ║
║  codex plugin install <name>    Install from marketplace      ║
║                                                               ║
║  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 (March 2026, v0.116.0)                                ║
║  gpt-5.4               Recommended flagship (1M context)     ║
║  gpt-5.3-codex         Coding specialist (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 de blog da OpenAI: As referências ¹⁷, ²⁶–³¹, ³⁴, ⁶⁶, ⁶⁸ e ⁶⁹ apontam para posts em openai.com/index/ que retornam HTTP 403 para acesso automatizado devido à proteção contra bots Cloudflare. Essas URLs são válidas quando acessadas por um navegador web padrão.