Codex CLI: a referência técnica definitiva

TL;DR: O Codex é um agente de programação multi-superfície que lê sua base de código, executa comandos em um sandbox de nível de SO, 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 troca de contexto, /compact para gerenciar o orçamento de contexto, /goal para metas de trabalho persistidas e AGENTS.md para instruções de projeto entre ferramentas que funcionam no Codex, Cursor, Amp e mais. GPT-5.5 (lançado em 23 de abril de 2026) é o padrão recomendado no Codex — janela de contexto de 400K no Codex (1M no API), $5/$30 por MTok, 82,7% no Terminal-Bench 2.0 SOTA.⁸³ A partir do CLI v0.130.0 (8 de maio de 2026), o Codex traz um comando de nível superior codex remote-control para controle headless do app-server, resolução view_image multi-ambiente, autenticação Bedrock via credenciais de console-login do AWS aws login, paginação de threads do app-server, visibilidade de detalhes de plugin para hooks empacotados com metadados de share-link e controles de descoberta, atualização de config ao vivo em threads em execução, metadados configuráveis de trace do OpenTelemetry e endurecimento contínuo do sandbox no Linux e Windows. A v0.129.0 (7 de maio de 2026) adicionou edição modal Vim (/vim), um seletor de workflow redesenhado, um navegador /hooks no TUI, uma status line com reconhecimento de tema, compartilhamento de workspace de plugin com operações de marketplace e uma mudança no ciclo de vida de /goal. Continue a preferir flags explícitas de sandbox/aprovação ou permission profiles em vez do legado --full-auto; js_repl continua removido.^86878991

O Codex opera como um agente de programação multi-superfície, não um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, aplica patches em arquivos, conecta 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 cinco superfícies distintas dependendo de como você trabalha, incluindo a nova extensão do Chrome que executa o Codex no seu navegador sem dominá-lo.⁹⁰

A diferença entre o uso casual e efetivo 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: controla o que o Codex pode fazer
3. AGENTS.md: define contratos de operação de nível de projeto
4. Protocolo MCP: estende 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 sintaxe real, exemplos de configuração reais e os casos extremos que pegam até usuários experientes.

Nota de estabilidade: Recursos marcados como [EXPERIMENTAL] ou under development estão sujeitos a mudanças entre versões. A partir da v0.130.0 (8 de maio de 2026), o Codex Cloud e o code mode permanecem experimentais ou em desenvolvimento, enquanto CLI central, sandboxing, AGENTS.md, config.toml, Skills, hooks, ferramentas multi-agente e plugins são superfícies estáveis. A v0.130.0 adiciona o comando de nível superior codex remote-control (entrypoint mais simples para um app-server headless e controlável remotamente), resolução view_image multi-ambiente, autenticação Bedrock via credenciais de console-login do AWS aws login, paginação de threads do app-server com visualizações de turnos unloaded / summary / full, visibilidade de detalhes de plugin para hooks empacotados além de metadados de share-link e controles de descoberta, atualização de config ao vivo do app-server (threads em execução absorvem mudanças de config sem reiniciar), remoção da expressão “research preview” do banner de inicialização do codex exec, metadados configuráveis de trace do OpenTelemetry, endurecimento de inicialização do sandbox no Linux e concessão de sandbox no Windows para o cache de binários do runtime desktop.⁹¹ A v0.129.0 (7 de maio de 2026) adicionou edição modal Vim no composer (/vim + default-mode configurável), um seletor de workflow do TUI redesenhado (resume/fork mais fácil, scrollback bruto), o navegador /hooks, uma status line com reconhecimento de tema com resumos opcionais de PR + branch, compartilhamento de workspace de plugin + operações de marketplace + controles de acesso a compartilhamento + filtragem de fonte, uma mudança no ciclo de vida de /goal (metas experimentais permanecem pausadas no resume a menos que sejam reativadas), endurecimento de inicialização do sandbox no Linux, melhorias de confiabilidade do sandbox no Windows e uma atualização do Bubblewrap para 0.11.2 com patches de segurança upstream.⁸⁹ A v0.128.0 (30 de abril de 2026) introduziu fluxos de trabalho persistidos /goal, codex update, keymaps configuráveis do TUI e permission profiles expandidos; o legado --full-auto continua descontinuado e js_repl continua removido.⁸⁶⁸⁷

Principais conclusões

• Cinco superfícies, um cérebro: CLI, aplicativo desktop, extensão de IDE, tarefas em nuvem e a nova extensão para Chrome compartilham a mesma inteligência GPT-5.x-Codex, então escolha a superfície que se encaixa no seu workflow.⁹⁰
• Sandboxing em nível de OS: o Codex impõe 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 é multiferramenta: 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 todo lugar.
• Profiles economizam o 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.4 mini oferece 400K para trabalho de subagentes; GPT-5.3-Codex oferece 272K de input. Use /compact, prompts focados e referências @file para gerenciar o orçamento de tokens proativamente.

Como usar este guia

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

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

Como o Codex funciona: o modelo mental

Antes de mergulhar nos recursos, entenda como a arquitetura do Codex molda tudo que você faz com ele. O sistema opera em quatro superfícies apoiadas 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 Core: a família de modelos GPT-5.x alimenta tudo. A partir de 23 de abril de 2026, gpt-5.5 é o modelo recomendado quando disponível — 400K de contexto no Codex (1M no API), 82,7% no Terminal-Bench 2.0 SOTA. gpt-5.4 continua sendo o padrão de fallback durante o rollout (1M de contexto, computer use nativo).⁸³⁶⁴ Ele lê arquivos, escreve patches, executa comandos de shell e raciocina sobre seu codebase. Quando o contexto enche, o Codex compacta a conversa para liberar espaço. Esta camada custa tokens.

Camada de segurança: cada comando que o Codex executa passa por um sandbox em nível de OS. No macOS, o framework Seatbelt da Apple impõe restrições em nível de kernel. No Linux, Landlock + seccomp filtram acesso ao sistema de arquivos e syscalls. O sandbox opera em nível de kernel, não dentro de containers. A approval policy 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 o Codex carrega sob demanda. Apps conectam-se a ChatGPT connectors. A busca na web adiciona contexto em tempo real da internet.

Camada de superfície: CLI para usuários avançados de terminal e automação. Aplicativo desktop para gerenciamento de projetos com múltiplas threads. Extensão de IDE para loops de editar-compilar-testar. Cloud para tarefas assíncronas que rodam 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 longas, CLI para operações determinísticas em repositório, extensão de IDE para loops apertados de coding e o aplicativo desktop para planejamento e coordenação.

Sumário

1. Como instalo o Codex?
2. Quick Start: sua primeira sessão
3. Superfícies de interação principais
4. Sistema de configuração em profundidade
5. Qual modelo devo escolher?
6. Quanto custa o Codex?
7. Frameworks de decisão
8. Como funciona o sistema de Sandbox e 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. Plan Mode 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 background
21. O aplicativo Codex Desktop
22. GitHub Action e CI/CD
23. Codex SDK
24. Otimização de performance
25. Como faço debug de problemas?
26. Deployment enterprise
27. Boas práticas e anti-patterns
28. Receitas de workflow
29. Guia de migração
30. Cartão de referência rápida
31. Changelog
32. Referências

Como instalar 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 do 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 GitHub Releases¹:

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 é compatível²

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 Plus, Pro, Team, Business, Edu ou Enterprise existente. Acesso completo aos recursos, incluindo tarefas na nuvem.
2. Chave API: Defina pela variável de ambiente CODEX_API_KEY ou por codex login --with-api-key. Alguns recursos (threads na nuvem) podem ficar indisponíveis.

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

Autocompletes 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 0.130.0

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

Saia do zero e comece a produzir 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 codebase. 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 aprove para iniciar a execução.

7. Verifique seu trabalho:

> /diff

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

O que vem a seguir: - Configure AGENTS.md com instruções do projeto (veja Como o AGENTS.md funciona?) - Configure um perfil para seu workflow (veja Perfis) - Experimente codex exec para automação não interativa (veja Modo não interativo)

Superfícies principais de interação

O Codex oferece quatro interfaces distintas apoiadas pela mesma inteligência. Cada superfície otimiza 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.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

A interface de terminal é uma aplicação em tela cheia com:

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

Atalhos principais da TUI:

Mudança na barra de status (v0.121.0): o antigo medidor de janela de contexto na barra de status foi substituído por um indicador de porcentagem de contexto que mostra o quão cheia está sua janela de contexto. Se você tiver scripts ou hooks fazendo parsing da barra de status, verifique essa mudança de formato.⁸² O Codex também exibirá um aviso de atualização da CLI quando uma nova versão estiver disponível.

Slash commands disponíveis na TUI:

Redesign do workflow picker (v0.129.0): resume e fork agora estão mais fáceis de acessar a partir de um picker redesenhado, e um novo modo de scrollback bruto permite percorrer o transcript não renderizado quando você precisa copiar comandos ou saídas do modelo na íntegra. Útil ao triar uma sessão longa de debugging ou ao redirecionar a saída para outra ferramenta.⁸⁹

2. Codex Desktop App (macOS + Windows)

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

O desktop app adiciona capacidades que a CLI não tem:

• Multitarefa: execute múltiplos agents paralelos em diferentes projetos simultaneamente
• Isolamento por git worktree: cada thread trabalha em uma cópia isolada do seu repo
• Inline diff review: faça stage, revert e commit das mudanças sem sair do app
• Terminal integrado: terminal por thread para executar comandos
• Forking de conversas: ramifique conversas para explorar alternativas
• Janelas pop-out flutuantes: destaque conversas em janelas portáteis
• Automations: 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últiplos fluxos de trabalho ou precisar de revisão visual de diff. Use a CLI quando quiser composability de terminal, scripting ou integração com CI/CD.

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

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

• Agent mode por padrão: lê arquivos, faz edições, executa comandos
• Edições inline: sugestões com consciência de contexto nos arquivos ativos
• Sessões compartilhadas: as sessões sincronizam entre a CLI e a extensão de IDE
• Mesma autenticação: faça login com a conta do ChatGPT ou chave da API

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

4. Codex Cloud [EXPERIMENTAL]

As cloud tasks rodam de forma assíncrona em ambientes gerenciados pela OpenAI:

• Fire and forget: enfileire tarefas que rodam de forma independente da sua máquina local
• Execução paralela: execute múltiplas cloud tasks simultaneamente
• Criação de PR: o Codex cria pull requests a partir do trabalho concluído
• Apply local: traga os resultados da cloud para o seu repo 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 cloud tasks também ficam acessíveis em chatgpt.com/codex.⁴

5. Codex for Chrome [NEW]

O Codex é distribuído como uma extensão de navegador para Chrome, adicionando uma quinta superfície ao lado da CLI, do desktop app, da extensão de IDE e da cloud. A extensão foi pensada para acompanhar sua navegação normal em vez de tomá-la para si: o Codex trabalha em paralelo entre abas em segundo plano, e você mantém o controle sobre quais sites ele toca.⁹⁰

• Execução paralela em abas: o Codex opera em múltiplas abas ao mesmo tempo sem travar a aba em primeiro plano.
• Controle por site: você define uma allow-list de quais sites o Codex pode interagir; o padrão é nenhum acesso.
• Navegador como bancada: a extensão é melhor para trabalho em apps e sites em que a página é a fonte da verdade — consoles administrativos, dashboards internos, UIs de gestão de conteúdo, sistemas de tickets — não como substituta da CLI em repos locais.
• Mesmo cérebro: o Codex for Chrome roda a mesma inteligência GPT-5.x-Codex usada pelas outras superfícies, então uma configuração de AGENTS.md ou de skills que funciona na CLI carrega as mesmas convenções para o trabalho conduzido pelo navegador.

Instale pela documentação da extensão Codex Chrome.⁹⁰

Mergulho profundo no sistema de configuração

O Codex usa TOML para configuração. Entender a hierarquia de precedência é fundamental porque ela determina quais configurações vencem quando há conflito.

Precedência (do mais alto ao mais baixo)

1. Sobrescritas de sessão (mais alto): flags CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) e sobrescritas -c key=value
2. Configuração do projeto (.codex/config.toml, descoberta a partir do CWD subindo até a raiz do projeto; o diretório mais próximo vence)
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 baixo)

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 Enterprise Deployment.

Localização dos arquivos de configuração

Dica de especialista: A variável de ambiente CODEX_HOME sobrescreve 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.5"                      # Recommended model when available
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.5"               # Optional 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-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.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 de especialista: Defina um perfil padrão com profile = "fast" no nível superior da sua configuração. Sobrescreva por sessão com --profile.

Provedores de modelo personalizados

Conecte-se ao Azure, AWS Bedrock, 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"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

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

Aviso: O wire API chat/completions (wire_api = "chat") foi descontinuado para modelos hospedados pela OpenAI, e a OpenAI anunciou 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"

Sobrescritas inline de configuração

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

codex -c model="gpt-5.5" "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 (abril de 2026)

| Modelo | Entrada / Contexto total | Reasoning padrão | Melhor para |
|-------|--------:|-------------------|----------|
| **gpt-5.5** (Codex) | 400K / 400K | `medium` | **Novo flagship (23 de abril de 2026)** — SOTA de 82,7% no Terminal-Bench 2.0; padrão recomendado para a maioria das tarefas do Codex. **Na API**: janela de contexto de 1M.[^160] |
| **gpt-5.5-pro** | 1M / 1M | `high` | Camada de maior esforço no GPT-5.5 (24 de abril de 2026, disponível na API)[^160] |
| **gpt-5.4** | 1M / 1M | `medium` | Flagship anterior; mantido como padrão enquanto o GPT-5.5 é distribuído nas plataformas |
| **gpt-5.4-mini** | 400K / 400K | `medium` | Trabalho de subagentes, tarefas mais simples — 30% da cota do GPT-5.4, 2x mais rápido[^81] |
| **gpt-5.3-codex** | 272K / 400K | `medium` | Especialista em código: engenharia de software complexa |
| **gpt-5.3-codex-spark** | 128K / 128K | `high` | Iteração quase instantânea, somente texto (usuários Pro, parceria com a Cerebras)[^69] |
| **gpt-5.2-codex** | 272K / 400K | `medium` | Modelo legado; a OpenAI lista o `gpt-5.4` como substituto para o desligamento de 23 de julho de 2026[^165] |
| **gpt-5.1-codex-mini** | 272K / 400K | `medium` | Modelo legado sensível a custo; a OpenAI lista o `gpt-5.4-mini` como substituto para o desligamento de 23 de julho de 2026[^165] |

> **GPT-5.5 (23 de abril de 2026)** é a escolha recomendada pela OpenAI para a maioria das tarefas do Codex: codificação complexa, uso de computador, trabalho de conhecimento e fluxos de pesquisa. Disponível no Codex CLI / web / desktop em 23 de abril para ChatGPT Plus / Pro / Business / Enterprise / Edu / Go; na API da OpenAI em 24 de abril. **Janela de contexto: 400K no Codex, 1M na API** — o Codex limita a janela em 400K para equilibrar throughput e custo entre os tiers de assinantes; a API expõe o 1M completo. Preço (API): **$5 input / $30 output por MTok** (2× a taxa do GPT-5.4; a OpenAI afirma um aumento efetivo de ~20% após melhorias de eficiência de tokens). Benchmarks: **82,7% no Terminal-Bench 2.0** (SOTA atual entre os modelos disponíveis publicamente), 84,9% no GDPval (44 ocupações), 78,7% no OSWorld-Verified, 98,0% no Tau2-bench Telecom (sem prompt tuning). A OpenAI usou o GPT-5.5 + Codex internamente para reescrever a infraestrutura de serving antes do lançamento — gerou um aumento de 20% na velocidade de geração de tokens.[^160]
>
> O GPT-5.4 continua disponível em todas as plataformas do Codex (CLI, app, extensão de IDE, cloud).[^66] A lista exata de modelos varia por conta e por 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. As 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 custo.[^73]
>
> **Nota sobre o tier gratuito (5 de maio de 2026)**: o GPT-5.5 Instant foi disponibilizado para o tier gratuito do ChatGPT em 5 de maio de 2026. Isso amplia o público da família GPT-5.5 para além dos planos pagos, embora o acesso ao Codex CLI continue exigindo uma assinatura elegível Plus / Pro / Business / Enterprise / Edu / Go ou uma chave da API.[^169]
>
> **GPT-5.4 mini (17 de março de 2026)**: uma variante menor e mais rápida do GPT-5.4 com contexto de 400K a $0,75/$4,50 por MTok — usa apenas 30% da cota do GPT-5.4. Ideal para delegação a subagentes: deixe o GPT-5.4 cuidar do planejamento e da coordenação enquanto subagentes GPT-5.4 mini lidam com subtarefas mais restritas (busca em base de código, revisão de arquivos, processamento de documentos) em paralelo.[^81]

### Fluxograma de seleção de modelo

```text
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
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

Esforço de reasoning

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 de especialista: o reasoning xhigh pode usar de 3 a 5x mais tokens do que o medium para o mesmo prompt. Reserve-o para problemas genuinamente difíceis onde o pensamento extra compensa.

Controles rápidos de reasoning na TUI (v0.124.0+).⁸⁵ Em uma sessão interativa de TUI, Alt+, reduz o reasoning em um nível e Alt+. o aumenta em um nível — útil quando um problema difícil no meio da sessão justifica uma escalada temporária medium → high → xhigh sem usar /effort ou -c. Quando você aceita um upgrade de modelo no meio da sessão, o reasoning é redefinido para o padrão do novo modelo em vez de manter o nível anterior.

Troca de modelo

Troque de modelo no meio da 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:⁵¹

Atualização de preços de abril de 2026: O preço anual do Business caiu de $25 para $20/assento/mês. Assentos somente Codex com preço pay-as-you-go agora estão disponíveis para workspaces Business e Enterprise — sem taxa fixa de assento, cobrado pelo consumo de tokens.⁷⁹ Os limites de taxa promocionais de 2x para planos pagos (do lançamento do Desktop App em fevereiro de 2026) permanecem ativos.¹⁶

Aumento de limite de uso de maio de 2026 (até 31 de maio de 2026): O Codex no plano Plus roda com um limite de 5 horas de 25× (vs o aumento padrão de 20×), e o tier de $100/mês está dobrado durante o mesmo período. Use esse intervalo para executar lotes de tarefas em nuvem mais longos ou agent runs com maior throughput sem esbarrar no seu teto normal de 5 horas.⁸⁹

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 do contrato. Verifique /status no TUI para ver o uso atual.

Cobrança via API

Ao usar o Codex pela API, a OpenAI cobra o uso por token sob o preço padrão da API da OpenAI para o modelo selecionado (mais qualquer desconto aplicável de prompt-caching). Verifique a página oficial de preços da API para as taxas atuais.²⁰

Estratégias de otimização de custos

1. Use profiles: Crie um profile fast com gpt-5.1-codex-mini e model_reasoning_effort = "low" para tarefas rotineiras
2. Reserve reasoning alto: Use xhigh apenas para problemas genuinamente difíceis, pois custa 3-5x mais tokens
3. Use --ephemeral: Pule a persistência de sessão em CI/CD para reduzir overhead
4. Minimize resumos de reasoning: Defina model_reasoning_summary = "none" quando você não precisar de explicações
5. Batch com modo exec: codex exec evita o overhead do TUI para fluxos de automação
6. Monitore o uso: Verifique /status no TUI e os dashboards de cobrança da sua organização

Exemplos reais de custos

Custos representativos da API para tarefas comuns (gpt-5.3-codex com preço padrão, reasoning médio):

Os custos variam conforme o esforço de reasoning, caching 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.

Overhead oculto de tokens

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

Dica de especialista: 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 te surpreenderem, verifique quantos servidores MCP estão conectados — cada um adiciona definições de ferramentas a cada chamada da API.

Gestão de custos em equipe

Estratégias para controle de custos em equipe: - Configure requirements.toml para impor limites de modelo e esforço de reasoning em toda a organização - Use gpt-5.1-codex-mini para CI/CD — pipelines automatizados raramente precisam de reasoning máximo - Orçamento baseado em profiles — defina profiles 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

Estruturas de decisão

Quando usar cada superfície

Quando usar cada modo de sandbox

Quando usar cada nível de raciocínio

Plan Mode 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

Steer Mode: Enter vs Tab

Regra geral: Enter = “pare, escute isto agora.” Tab = “quando terminar, faça também isto.”

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 profile?

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

Troque de profile 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 pede 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 conhecer as restrições de requirements.toml que os 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 de cada 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⁶. A partir da v0.121.0, os perfis de sandbox do macOS podem permitir Unix sockets específicos (por exemplo, docker.sock, sockets de IPC de editores) em uma allowlist, e a resolução de DNS privada não é mais bloqueada por padrão.⁸²
• Linux: Landlock para restrições de sistema de arquivos + seccomp para filtragem de syscalls. Um processo auxiliar autônomo (codex-linux-sandbox) fornece isolamento de defesa em profundidade.⁵ O Bubblewrap (bwrap) é incluído e compilado como parte do build do 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.⁷⁵ A v0.129.0 reforçou a inicialização do sandbox no Linux e atualizou o Bubblewrap incluído para 0.11.2 com patches de segurança upstream; a v0.130.0 adicionou mais reforços de inicialização.⁸⁹⁹¹
• 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 de tokens restritos para melhor isolamento de processos.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários do runtime de desktop, para que o sandbox do Windows consiga resolver binários do runtime de forma confiável para usuários do workspace-sandbox.⁹¹

Por que isso importa: ao contrário do sandbox baseado em contêineres (Docker), o sandbox em nível de sistema operacional é mais rápido, mais leve e mais difícil de escapar. O kernel aplica as restrições antes mesmo de o Codex enxergar a chamada de sistema.

Correções de segurança: - Bypass de sandbox via fork do zsh (v0.106.0): corrigida uma vulnerabilidade em que 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 evitar travamentos causados por payloads excessivamente grandes.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): um novo perfil de cliente endurecido para devcontainers do Docker usa Bubblewrap para sandbox dentro do contêiner. WSL2 é suportado; WSL1 é explicitamente rejeitado (Bubblewrap é incompatível com o shim de kernel do WSL1).⁸² - Revisão Guardian + hooks (v0.121.0): os hooks ficam desabilitados durante sessões de revisão Guardian, para que hooks pré e pós-ferramenta não interfiram nas decisões do subagente Guardian.⁸² Se você depende de hooks para logging ou validação, esteja ciente de que uma revisão Guardian os ignora — recorra à observabilidade do app-server se precisar de uma trilha de auditoria completa. - 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 encontrar device nodes.⁶¹

Política ReadOnlyAccess (v0.100.0+): um formato de política configurável para controle granular de acesso de leitura. Use-o 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:

on-failure ainda aparece em alguns exemplos antigos e caminhos de compatibilidade, mas a documentação atual de configuração da OpenAI a marca como obsoleta. Prefira on-request para execuções interativas e never para execuções não interativas que já tenham um limite de segurança externo.⁸⁷

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 flexíveis de aprovação (v0.105.0+)

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

• Permissões adicionais 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 ferramenta individuais com feedback para que o Codex possa ajustar sua abordagem em vez de simplesmente repetir o mesmo comando

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

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

Perfis de permissão (v0.113.0+, expandidos na v0.128.0)

Os perfis de permissão dividem as políticas de sandbox de sistema de arquivos e de rede em seções nomeadas e reutilizáveis. Defina default_permissions como um perfil integrado, como :read-only, :workspace ou :danger-no-sandbox, ou aponte-o para uma tabela [permissions.<name>] personalizada.⁸⁷

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

Use none para arquivos sensíveis e globs que devam permanecer ilegíveis mesmo quando a raiz do projeto for gravável. Para exceções pontuais a comandos, prefira rules em vez de expandir um perfil de forma ampla.⁸⁷

Orientação legada sobre --full-auto

Guias mais antigos descreviam --full-auto como um alias de conveniência para:

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

Na v0.128.0, as notas de release marcam --full-auto como obsoleto, e o help atual do CLI não o lista mais para execuções interativas. Use as flags explícitas acima ou um perfil de permissões nomeado.⁸⁶

Confiabilidade do sandbox (v0.129.0): o reforço da inicialização do sandbox no Linux reduz race conditions em sistemas de arquivos lentos ou checkouts com symlinks; melhorias de confiabilidade do sandbox no Windows resolvem várias falhas em casos de borda durante execuções longas; e o Bubblewrap incluído foi atualizado para 0.11.2 com patches de segurança upstream. Nenhuma alteração de configuração é necessária. Execute codex update para obter essas atualizações.⁸⁹

Configurações recomendadas

Desenvolvimento diário (padrão seguro):

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

Power user (acesso total, human-in-the-loop):

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

A combinação é o “sweet spot” recomendado pela comunidade: capacidade máxima, mas com aprovação obrigatória para cada comando.⁸

Automação CI/CD:

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

Smart Approvals com subagente Guardian (v0.115.0+)

O Smart Approvals pode rotear solicitações de revisão por meio de um subagente guardian em vez de exigir aprovação humana para cada ação. A sessão do guardian persiste entre aprovações para reutilizar o cache de prompt e evitar a sobrecarga de inicialização. Cada revisão recebe um histórico limpo (decisões anteriores não vazam para revisões posteriores).⁷³

Configure o revisor em config.toml:

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

Isso é particularmente útil para fluxos de CI/CD em que você quer revisão automatizada com raciocínio, em vez de um approval_policy = "never" genérico.

Habilitando o acesso à rede

O Codex bloqueia o acesso à rede por padrão no modo workspace-write. Habilite-o 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 meio 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"

Elas complementam o suporte existente para 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 --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

Se o sandbox estiver funcionando corretamente, ambos os comandos devem falhar com um erro de permissão negada sob um perfil com escopo de workspace. Se qualquer um dos comandos tiver sucesso, sua configuração de sandbox precisa de investigação.

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. Com suporte do 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 em um repositório ou diretório específico. Consulte Skills para pacotes de expertise reutilizáveis que complementam o AGENTS.md.

Hierarquia de descoberta

O Codex cria 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 (da raiz do git até o diretório atual): cada nível é verificado para AGENTS.override.md > AGENTS.md > nomes de arquivo de fallback
3. Mesclagem: os arquivos são concatenados da raiz para baixo; arquivos mais próximos aparecem mais tarde no prompt e substituem 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 em padrões da comunidade¹⁰:

FAÇA: - Seja específico: "Use rg --files for discovery" é melhor que "search efficiently" - Defina o fechamento: o que significa “concluído”? (testes passam, lint limpo etc.) - Inclua comandos: build, teste, lint, formatação (invocações exatas) - Organize por tarefa: seções de codificação, review, release, incidente/debug - Defina escalonamento: 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 + nenhum orçamento de runtime) - Escrever documentação em prosa (AGENTS.md é uma política operacional, não um 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.

Tratamento de segredos em sessões de agente

Trate o histórico visível ao Codex como uma superfície de segurança, não apenas como código-fonte. As release notes do Codex documentam o trabalho de snapshotting do shell e de redação de variáveis de ambiente, e o sistema de memória verifica gravações de memória em busca de segredos, mas essas proteções não transformam saída de comandos, transcrições de sessão, snapshots do shell, logs locais ou scripts auxiliares em lugares seguros para imprimir credenciais.³⁷⁵⁵⁹⁵

A regra operacional é simples: não imprima segredos para o modelo inspecionar; mantenha credenciais auxiliares em configurações exigidas pelo ambiente; separe código-fonte executável, docs, caches gerados, transcrições de sessão, snapshots do shell, logs e armazenamentos intencionais de segredos durante auditorias; redija o histórico local quando aparecer um formato de segredo de alta confiança; e promova hooks de prevenção somente depois que o ciclo manual de higiene estiver comprovado. A lição pública é o mapa de superfície e os critérios de aceitação, não valores privados de tokens, caminhos exatos ou detalhes internos dos detectores.⁹⁵

O mecanismo de override

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

• Congelamentos de release: “Nenhum recurso novo, apenas correções”
• Modo de incidente: “Todas as alterações devem ser revisadas por quem estiver de plantão”
• Hardenização temporária: “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 introduziu hooks na v0.99.0 (AfterAgent) e na v0.100.0 (AfterToolUse), depois adicionou um engine experimental de hooks na v0.114.0 com eventos SessionStart e Stop.⁷⁰ A partir da v0.124.0 (23 de abril de 2026), hooks são estáveis.⁸⁵ Agora eles podem ser configurados inline em config.toml e requirements.toml — sem exigir mais um arquivo separado de scripts de hooks — e observam ferramentas MCP junto com apply_patch e sessões longas de Bash. O sistema agora cobre o ciclo de vida da sessão e a 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

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 entra no contexto do modelo, o que o torna ideal para injetar informações dinâmicas (datas, nomes de branch, variáveis de ambiente) no início da sessão.

Replicando padrões de hooks do Claude Code

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

Dica de especialista: a partir da v0.124.0 (23 de abril de 2026), o engine de hooks é estável. Novos eventos de hook ainda chegam em releases — confira o changelog do Codex.

Navegador de hooks no TUI (v0.129.0): execute /hooks no TUI para descobrir hooks disponíveis, ver quais estão ativos no momento e alternar hooks individuais sem editar config.toml. Útil para solucionar problemas com um hook empacotado em plugin que esteja se comportando mal ou para desativar temporariamente um linter AfterToolUse durante uma sessão de edição focada.⁸⁹

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

MCP amplia os recursos do Codex ao se conectar a ferramentas e serviços externos. O grupo de comandos codex mcp está marcado atualmente como experimental, e os comandos e o formato de configuração podem mudar entre versões. O Codex oferece suporte a 2 tipos de transporte: STDIO (processos locais) e Streamable HTTP (servidores remotos).¹¹

Mudanças no MCP no v0.121.0: As ferramentas agora são registradas com um namespace, então os nomes das ferramentas nas listagens aparecem como <server>:<tool> em vez de nomes simples — atualize scripts ou prompts que usem grep em nomes de ferramentas não qualificados. Uma nova flag supports_parallel_tool_calls foi conectada aos MCPs incluídos, permitindo execução paralela para servidores que declaram suporte. Os metadados de estado do sandbox agora passam pelos metadados das ferramentas MCP, para que os servidores possam adaptar o comportamento (por exemplo, avisar se estão rodando em um sandbox read-only). A solicitação personalizada codex/sandbox-state foi removida — use o caminho de metadados em vez disso. A fase 3 do lançamento dos Apps MCP chega aqui com suporte a chamadas de ferramenta; chamadas de ferramenta adiadas achatadas agora têm suporte para servidores que usam o padrão de chamada adiada.⁸²

Como configurar 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 servidores ativos e ferramentas disponíveis. /mcp verbose (v0.123.0+)⁸⁴ retorna diagnósticos completos do servidor, recursos e templates de recursos — útil quando um servidor falha ao carregar ou as ferramentas não aparecem onde deveriam. O /mcp simples continua rápido.

O carregamento de MCP de plugins (v0.123.0+) aceita tanto o schema padrão mcpServers quanto mapas de servidor no nível superior em .mcp.json, então plugins criados para qualquer uma das convenções carregam sem problemas.⁸⁴

Executando o Codex COMO um servidor MCP

O Codex pode expor a si mesmo como um servidor MCP para orquestração multiagente:¹²

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

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

Use 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 importantes

Padrões práticos

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

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

Padrão 2: Limites de saída — As respostas das ferramentas MCP são truncadas em cerca de 25 mil 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 personalizadas agora podem retornar saída multimodal (imagens, conteúdo rico) junto com texto. Isso permite que ferramentas que produzem artefatos visuais — screenshots, diagramas, renderizações de gráficos — os enviem diretamente ao modelo para análise.⁶²

Padrão 3: Governança empresarial 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 empresarial para a configuração completa de políticas.

Code mode [EXPERIMENTAL]

O Code mode (v0.114.0) oferece workflows de programação mais isolados ao restringir 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 acompanhar atualizações.

Runtime REPL JavaScript [REMOVED]

O Codex v0.100.0 adicionou um runtime REPL JavaScript experimental (js_repl), e a v0.106.0 o promoveu pela superfície /experimental.⁶⁰ Essa orientação agora é histórica. Na v0.128.0, o changelog da versão inclui “Remove js_repl feature”, e a lista atual de recursos marca tanto js_repl quanto js_repl_tools_only como removidos.⁸⁶

Não adicione features.js_repl = true a novas configurações. Use comandos de shell, scripts versionados, ferramentas MCP ou uma skill do Codex com um diretório scripts/ quando precisar de lógica executável repetível.

O que são skills?

Skills são pacotes reutilizáveis de capacidade específica para tarefas que o Codex carrega sob demanda. Elas 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 aceita pastas de skills com symlink.

Criando uma skill

Formato do SKILL.md:

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

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

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ícito: menu /skills ou menção a $skill-name no prompt
• Implícito: o Codex detecta automaticamente skills compatíveis pela descrição da tarefa (se allow_implicit_invocation: true)
• Creator: use $skill-creator para criar uma nova skill interativamente
• Installer: 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 estiver sendo ativada:

1. Verifique a descoberta: /skills deve listá-la no TUI
2. Verifique o caminho: confirme 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 estiver usando detecção automática, confirme allow_implicit_invocation: true em agents/openai.yaml
5. Use palavras-chave: inclua 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 vários 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

Plugins

Plugins unificam skills, entradas MCP, hooks e conectores de app em um único pacote instalável (v0.110.0+).⁶⁵ A partir da v0.117.0, plugins são recursos de primeira classe: plugins com escopo de produto sincronizam automaticamente na inicialização, e /plugins oferece um navegador dentro do TUI para descoberta e gerenciamento.⁷⁵ A v0.128.0 expandiu os fluxos de plugins com instalação via marketplace, cache de bundles remotos, APIs de desinstalação remota, hooks empacotados em plugins, estado de ativação de hooks e importação de configuração de agentes externos.⁸⁶ v0.129.0 (7 de maio de 2026) adiciona compartilhamento de workspace de plugins (envie um conjunto de plugins para colegas sem republicar), controles de acesso de compartilhamento (ativar/desativar por destinatário, revogar), filtragem de fontes (limitar de quais marketplaces um workspace puxa) e operações de marketplace que podem ser invocadas diretamente pelo navegador /plugins em vez do CLI.⁸⁹ v0.130.0 (8 de maio de 2026) torna o empacotamento de plugins mais transparente e o fluxo de compartilhamento mais controlável:⁹¹

• Hooks incluídos visíveis nos detalhes do plugin. A visualização de detalhes de /plugins agora lista todos os hooks de ciclo de vida que um plugin inclui (SessionStart, UserPromptSubmit, Stop etc.). Antes de instalar um plugin, você pode ver exatamente quais hooks ele registrará na sua sessão — sem efeitos colaterais surpresa de hooks vindos de um plugin em que você confia apenas pelas ferramentas.
• Metadados de compartilhamento de plugin em shareContext. Quando um plugin é compartilhado de um workspace, o payload do link de compartilhamento agora expõe metadados do link (criador, escopo, atualização) para que as sessões receptoras possam mostrar a procedência e decidir se aceitam.
• Controles de descoberta nas configurações de compartilhamento. As configurações de compartilhamento expõem um toggle de descoberta para que equipes possam publicar plugins em workspaces específicos ou listas de destinatários sem torná-los listáveis em toda a organização.

Fontes de plugins

Descoberta de plugins

O Codex informa ao modelo quais plugins estão ativados no início da sessão (v0.111.0), melhorando a descoberta de MCPs, apps 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, o contexto dele (capacidades, ferramentas, configuração) é incluído automaticamente na janela de contexto do modelo — sem precisar 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 app.

Plugin Marketplace (v0.113.0+)

O plugin marketplace agora inclui descoberta mais rica com metadados, categorias e avaliações.⁶⁹ Verificações de autenticação no momento da instalação confirmam que plugins que exigem chaves API ou OAuth têm credenciais válidas antes da instalação. Um endpoint de desinstalação remove plugins e suas configurações associadas de forma limpa.

Adicionando marketplaces de terceiros (v0.121.0+)

A documentação atual do OpenAI Codex mantém o gerenciamento de fontes de marketplace em codex plugin marketplace. Isso formaliza a distribuição de plugins de terceiros além do marketplace first-party da OpenAI e oferece suporte a atalhos de repositório GitHub, URLs Git HTTP(S), URLs SSH e diretórios raiz de marketplace locais; use --ref para fixar uma ref Git e repita --sparse PATH apenas para repositórios de marketplace baseados em Git.⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add [email protected]:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

Depois de adicionado, os plugins de um marketplace aparecem no navegador /plugins junto com os padrões. Chamadores do app server (integrações de IDE/desktop) têm um endpoint paralelo para registrar marketplaces programaticamente.⁸²

Consideração de segurança: marketplaces de terceiros executam código arbitrário de plugins com suas permissões do Codex. Avalie as fontes antes de adicioná-las e prefira execução em sandbox nas primeiras execuções.

Gerenciando plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

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

Dica avançada: plugins consolidam o que antes exigia configuração MCP separada, instalação de skill e configuração de conector de app. Um único plugin pode incluir os três — tornando o onboarding da equipe mais rápido e a configuração mais portátil.

Modo Plan e Colaboração

O modo Plan permite que o Codex projete uma abordagem antes de executar mudanças. Ele está habilitado por padrão (desde a v0.94.0).¹⁴ Veja 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 mudanças até você aprovar - Transmite o plano em uma visualização TUI dedicada

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ê prefere esperar até o Codex terminar antes de dar instruções, basta digitar normalmente após o turno ser concluído — nenhum modo especial é necessário.

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

Realce de sintaxe (v0.105.0): O TUI agora aplica realce de sintaxe inline em blocos de código delimitados e diffs. 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 por 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 dispositivos 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 várias linhas no TUI (v0.105.0)⁶¹ - Links para arquivos locais são renderizados com formatação aprimorada (v0.106.0)⁶⁰ - Tratamento de Ctrl+C para sub-agentes corrigido para encerrar processos filhos corretamente (v0.106.0)⁶⁰

Sistema de Memória

O Codex tem 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 sob ~/.codex/memory/. O Codex as carrega no início da sessão e as usa para informar 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 de 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 auth está em src/core/auth/, não em src/middleware/“
• Preferências de fluxo de trabalho: “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 as 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
• 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 usa esquecimento baseado em diff para remover fatos obsoletos, mantendo o armazenamento de memória enxuto e relevante ao longo do tempo⁶⁰
• Seleção consciente do uso (v0.106.0): A recuperação de memória agora é consciente do 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 contextos entre projetos não relacionados ou quando o estado da memória ficou desviado⁶²
• Atualização do modelo da fase-2 (v0.121.0): O modelo de consolidação de memória da fase-2 agora é o gpt-5.4 (acima do padrão anterior). O pipeline da fase-2 é executado entre sessões para destilar transcrições da fase-1 em fatos duráveis; a mudança de modelo melhora a qualidade da recuperação com o mesmo custo de tokens.⁸²
• Menu de memórias no TUI (v0.121.0): Uma nova UI dentro da sessão expõe o modo de memória, exclusão individual de memórias e um botão de reset. O reset de memória agora preserva rollouts passados em vez de invalidá-los, então redefinir limpa a superfície de recuperação futura sem quebrar a reprodução da sessão.⁸²

Memória vs AGENTS.md

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

Gerenciamento de Sessões

O Codex persiste sessões em ~/.codex/sessions/, possibilitando retomar, bifurcar e fluxos de trabalho 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 slash command /resume dentro do TUI abre o mesmo seletor interativo com pesquisa.

Bifurcar

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

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

Bifurcações criam threads independentes que compartilham o mesmo histórico até o ponto da bifurcação. Mudanças em uma bifurcação não afetam a outra. Isso é útil para comparar abordagens (ex.: “bifurque e tente 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 fácil de depurar.⁷⁵

Listagem de Threads

Visualize e gerencie sessões ativas:

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

No app desktop, as threads ficam visíveis na barra lateral com histórico completo e prévias de diff.

Ciclo de Vida da Sessão

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

Modo não interativo (codex exec)

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

Uso básico

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Por padrão, o codex exec grava progresso/eventos em stderr e a mensagem final do agente em stdout. O design o torna combiná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 em CI

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

Banner de inicialização do codex exec (v0.130.0). O banner de inicialização do codex exec não imprime mais o texto legado “research preview”. Se seu CI faz scraping da saída de inicialização, o texto do banner agora está mais enxuto; os eventos estruturados --json permanecem inalterados.⁹¹

codex remote-control (v0.130.0+)

codex remote-control é um comando de nível superior que inicia um app-server headless destinado a ser controlado por outro processo — extensões de IDE, orquestradores customizados ou planos de controle remotos. Ele substitui a invocação multi-flag codex app-server que muitos integradores vinham montando manualmente e oferece a ferramentas de terceiros um único entrypoint estável para o mesmo runtime de app-server que vem nas superfícies desktop e IDE.⁹¹

# Start a headless, remotely controllable app-server
codex remote-control

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

Combine codex remote-control com as APIs de paginação do app-server abaixo quando estiver construindo UIs que precisam enumerar grandes históricos de threads sem hidratar todos os turns na memória de uma vez.

Paginação de threads no app-server (v0.130.0+)

Clientes do app-server agora podem paginar threads grandes por meio de três visualizações distintas de itens de turn:⁹¹

Combine a paginação com a interface ThreadStore introduzida na v0.121.0 para percorrer threads de longa duração de forma eficiente, especialmente em deployments com remote-control onde o orquestrador pode estar em uma máquina diferente dos arquivos de rollout.⁸²

Atualização ao vivo da configuração do app-server (v0.130.0+)

Threads ativas do app-server agora capturam alterações em config.toml sem exigir um reinício — edite a config, salve, e a thread em execução refletirá os novos valores no próximo turn. Este é o complemento de bug-fix para o codex remote-control: um servidor headless de longa duração pode ser reconfigurado no local em vez de derrubado.⁹¹

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 na 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 & CI/CD para integrar o Codex em 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ê o 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

A internet do agente está desativada por padrão e é configurada por ambiente:

• Off: Sem acesso à internet pelo agente (padrão)
• On: Allowlist de domínios opcional + restrições de métodos HTTP

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

Scripts de setup ainda podem usar internet para instalar dependências, mesmo quando a internet do agente está desligada.

Integração com Slack

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

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

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

Cloud CLI

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.¹⁶ 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.⁶⁶

Instalação

codex app                      # Auto-downloads and installs on first run

Ou faça o download diretamente: Codex.dmg (macOS) | Disponível na Microsoft Store (Windows)

Recursos principais

Modos de thread

Cada thread é executada em um de três modos, selecionado quando você a cria:

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 seu 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 concluir — 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.

Automations

As Automations são executadas localmente no app, então o app precisa estar em execução e o projeto disponível em disco:

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

Configurando uma automation: 1. Abra um projeto no desktop app 2. Clique na aba Automations 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 automation (App v26.312)⁷² 6. As automations 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 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 total de recursos, incluindo skills, automations e worktrees, sem exigir 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

Output: final-message, o texto da 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 disparar 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íncrono para atualizações intermediárias
• outputSchema: Aplica saída final no formato JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })
• Fluxos de trabalho com imagens (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas e o histórico de imagens persiste após retomar a sessão⁷⁵
• view_image multi-ambiente (v0.130.0): Para sessões que abrangem múltiplos ambientes (introduzido na v0.124.0 com seleção de ambiente + diretório de trabalho por turno, refinado na v0.125.0 com ambientes persistentes), o view_image agora resolve caminhos de arquivos através do ambiente selecionado em vez do filesystem local do orquestrador. Uma imagem anexada a partir de um ambiente remoto é buscada relativa ao diretório de trabalho daquele ambiente, não ao host que executa o SDK.⁹¹

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.5" },
});

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

Runtime: Node.js 18+.

Otimização de performance

Gerenciamento de contexto

As janelas de contexto variam por modelo. Em abril de 2026: o GPT-5.5 no Codex oferece 400K (1M na API). GPT-5.4 / GPT-5.4-mini oferecem 1M / 400K respectivamente (equivalente à API no Codex). A família GPT-5.3-Codex / GPT-5.2-Codex roda em 272K de input + 128K de output (orçamento total de 400K). Todos eles enchem mais rápido do que você esperaria — gerencie proativamente:

1. Use /compact regularmente: Resume o histórico da conversa para liberar tokens
2. Forneça documentação local: AGENTS.md de alta qualidade e documentação local reduzem o overhead 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 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 prompts para habilitar isso
4. Loops orientados a resultados: Peça “implementar, testar, corrigir, parar quando estiver verde” em vez de instruções passo a passo

Como faço para 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 no 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 do TUI acima.

Reinstalação limpa

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

Modo de depuração

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

Reportando problemas

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

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

Codex Security [PREVIEW]

O Codex Security entrou em research preview em 6 de março de 2026, trazendo revisão de segurança de aplicações com reconhecimento de contexto para o stack do Codex.⁷⁷ Disponível para clientes ChatGPT Pro, Enterprise, Business e Edu via Codex web.

Como funciona: o Codex Security analisa repositórios para construir um modelo de ameaças específico do projeto, identifica vulnerabilidades classificadas por impacto no mundo real e testa as descobertas sob pressão em um ambiente sandbox para validá-las. O agente revela descobertas de maior confiança com correções, reduzindo o ruído de bugs insignificantes.

Desempenho: durante o research preview, o Codex Security escaneou 1,2 milhão de commits e identificou 10.561 vulnerabilidades de alta severidade. A precisão melhorou ao longo do tempo — reduzindo o ruído em 84%, diminuindo a severidade superestimada em mais de 90% e cortando pela metade as taxas de falsos positivos. O sistema encontrou vulnerabilidades reais em OpenSSH, GnuTLS e Chromium, com 14 CVEs atribuídos.⁷⁷

Nota: o Codex Security é separado do modelo de segurança de sandbox embutido no CLI. O sandbox protege sua máquina do Codex; o Codex Security protege seu código-base de vulnerabilidades.

Implantação Empresarial

Controles de Administrador (requirements.toml)

Os administradores aplicam políticas empresariais por meio do requirements.toml, um arquivo de configuração imposto pelo administrador que restringe configurações sensíveis à 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", "never"]

# 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 em nível de usuário, que define preferências, o requirements.toml é uma camada de restrição rígida que limita os valores que os usuários podem selecionar, e os usuários não podem sobrescrevê-lo. As regras de requisitos do administrador só podem prompt ou forbid (nunca permitir silenciosamente).

Configuração MDM no macOS

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

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

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

Os requisitos da nuvem só preenchem campos de requisitos não definidos, então camadas gerenciadas de maior precedência sempre prevalecem. Os requisitos da nuvem são best-effort; se a busca falhar ou expirar, o Codex continua sem a camada da nuvem.

Integração com OpenTelemetry

O Codex oferece suporte à propagação do contexto de trace do OpenTelemetry a partir das variáveis de ambiente OTel padrão até as 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

• Variáveis de ambiente OTEL_* padrão são respeitadas (endpoint, nome do serviço, atributos de recursos)
• O contexto de trace se propaga pelo Codex até as chamadas da API, permitindo observabilidade ponta a ponta
• Use atributos de recursos para marcar traces por equipe, ambiente ou projeto
• Considere os requisitos de privacidade ao habilitar o logging de prompts/ferramentas — os traces podem conter trechos de código
• Metadados de trace do OpenTelemetry configuráveis (v0.130.0+). Além do envelope padrão OTEL_RESOURCE_ATTRIBUTES, o crate codex-otel agora expõe metadados de trace configuráveis para que os administradores possam marcar traces com dimensões específicas da organização (centro de custo, ID do projeto, referência de ticket) sem reconstruir OTEL_RESOURCE_ATTRIBUTES do zero a cada invocação. Combine isso com as analytics enriquecidas de review/feedback lançadas na mesma versão para um debugging e triagem unificados em sessões de CLI, app-server e remote-control.⁹¹

Acesso Empresarial

• ChatGPT Business / Enterprise / Edu: Acesso controlado pelo admin da organização, com requisitos buscados na nuvem aplicados automaticamente. Suporta SSO via SAML/OIDC por meio do seu provedor de identidade (Okta, Entra ID, etc.)
• API: Auth, billing e controles de organização/projeto padrão da API. A OpenAI publica relatórios SOC 2 Type II e SOC 3; BAA HIPAA disponível no tier 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 em nível de sistema de arquivos

Tratamento de dados e conformidade: - Inputs/outputs da API não são usados 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 - Os transcripts de sessão são armazenados localmente; apenas as chamadas da API deixam a máquina - O ChatGPT Enterprise oferece suporte a frameworks de conformidade incluindo SOC 2, GDPR e CCPA

Estratégia de Rollout

Rollout em fases recomendado para organizações:

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

Padrões de Auditoria

Acompanhe o uso do Codex e aplique conformidade:

• Traces do OpenTelemetry: Monitore o volume de chamadas da API, uso de tokens e latência por equipe
• Persistência de sessões: 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 bloqueadas de servidores — revise para identificar uso não autorizado de ferramentas
• Trilha de auditoria do Git: Todas as alterações de arquivos 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 Prompt

1. Prompts orientados por restrições: Comece com os limites. “NÃO altere os contratos da API. Apenas refatore a implementação interna.”
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 “Execute o lint + a menor suíte de testes relevante. Reporte os comandos e resultados.”
4. Referências a arquivos: Use @filename para anexar arquivos específicos ao contexto
5. Loops orientados por resultados: “Implemente, execute os testes, corrija as falhas, pare apenas quando todos os testes passarem.” O Codex itera até concluir

Filosofia de Testes

A comunidade converge em torno da colaboração com IA orientada por testes:²²

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

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 sumários e arquivos de progresso (“divulgação progressiva”)
• Normalize as quebras de linha (LF vs CRLF) entre os 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 uma nova branch antes de executar o Codex em repositórios desconhecidos
• Use fluxos de trabalho baseados em patches (git diff / git apply) em vez de edições diretas
• Revise as sugestões do Codex como se fossem PRs em 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: Extrai aprendizados de sessões de desenvolvimento - github-issue-fixer [issue-number]: Análise sistemática de bugs e criação de PR - github-pr-reviewer [pr-number]: Fluxos de trabalho de code review - ui-engineer [requirements]: Desenvolvimento de frontend de qualidade para produção

Skills da comunidade: - claude-skill: Repassa tarefas ao Claude Code com modos de permissão - autonomous-skill: Automação de tarefas em múltiplas sessões com acompanhamento de progresso - deep-research: Orquestração paralela de subtarefas - 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 um 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-o para se adequar à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 o 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 concluído:

codex apply <TASK_ID>

## Guia de migração

### Do Claude Code

| Conceito do Claude Code | Equivalente no Codex |
|---------------------|------------------|
| `CLAUDE.md` | `AGENTS.md` (padrão aberto) |
| `.claude/settings.json` | `.codex/config.toml` (formato TOML) |
| Flag `--print` | Subcomando `codex exec` |
| `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` |
| Hooks (mais de 12 eventos) | Hooks (SessionStart, Stop, UserPromptSubmit, AfterAgent, AfterToolUse; v0.99.0–v0.116.0) |
| Subagents (ferramenta Task) | Sub-agents (internos, máximo de 6; sem equivalente da ferramenta Task voltada ao usuário) |
| `/compact` | `/compact` (idêntico) |
| `/cost` | `/status` (mostra o uso de tokens) |
| Modelo: Opus/Sonnet/Haiku | Modelo: gpt-5.5 / gpt-5.4 / gpt-5.4-mini / variantes legadas do gpt-5.3-codex (o Codex usa a família de modelos GPT-5.x da OpenAI) |
| `claude --resume` | `codex resume` |
| Regras de permissão | Sandbox modes + políticas de aprovação |
| Configuração de MCP em settings.json | Configuração de MCP em config.toml |

**Diferenças principais para entender:**

- **O sandbox é em nível de SO**: o Codex usa Seatbelt/Landlock, não containers. As restrições operam em nível de kernel, abaixo da camada de aplicação.
- **Os hooks estão se expandindo**: o Codex agora suporta 5 eventos de hook: `SessionStart`, `Stop` e `UserPromptSubmit` (v0.114.0–v0.116.0, experimentais), além de `AfterAgent` (v0.99.0) e `AfterToolUse` (v0.100.0). O sistema cobre o ciclo de vida da sessão, interceptação de prompts e automação em nível de ferramenta, embora os mais de 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 em AGENTS.md ou skills.
- **Sub-agents v2 (v0.117.0)**: os sub-agents agora usam endereços baseados em caminho (por exemplo, `/root/agent_a`) com mensagens estruturadas entre agentes e listagem de agentes.[^80] Isso estende a infraestrutura existente (máximo de 6 simultâneos, reduzido a partir de 12 na v0.91.0). Os papéis multi-agente continuam customizáveis via configuração (v0.104.0+).[^57] A v0.105.0 adicionou `spawn_agents_on_csv` para fanout em linhas com rastreamento de progresso e ETA.[^63] O Codex ainda não tem a UX explícita da ferramenta Task do Claude Code para delegação direcionada pelo usuário — use cloud tasks ou orquestração via 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.
- **Profiles substituem a troca manual**: em vez de mudar flags por execução, defina profiles em config.toml.

### Do GitHub Copilot

| Conceito do Copilot | Equivalente no Codex |
|-----------------|------------------|
| Copilot CLI (terminal agêntico) | CLI interativa ou aplicativo desktop |
| Agentes especializados (Explore, Plan) | Skills + plan mode + steer mode |
| `copilot-instructions.md` / AGENTS.md | `AGENTS.md` (mesmo padrão) |
| Suporte a MCP | Suporte a MCP (STDIO + HTTP) |
| ACP (Agent Client Protocol) | Hooks (AfterAgent, AfterToolUse) |
| Copilot SDK | Codex SDK (TypeScript) |
| Workflows de coding agent | Agente Codex com controles de sandbox/aprovação + cloud tasks |

**O que você ganha:**
- Sandboxing em nível de SO (Seatbelt/Landlock — aplicado pelo kernel vs. baseado em container)
- Delegação de cloud tasks com `codex apply`
- Profiles de configuração para troca de workflows
- Aplicativo desktop com isolamento de worktree

### Do Cursor

| Conceito do Cursor | Equivalente no Codex |
|---------------|------------------|
| Project rules (`.cursor/rules`) / `AGENTS.md` | `AGENTS.md` + profiles/configuração |
| Workflows de chat/composer com agente | CLI interativa ou aplicativo desktop |
| Referências a arquivos com `@` | Referências a arquivos com `@` (idênticas) |
| Apply/edit + review | Patching e diff review integrados |

---

## Cartão de referência rápida

```text
╔═══════════════════════════════════════════════════════════════╗
║                    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                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --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   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /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 ║
║                                                               ║
║  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 --sandbox workspace-write "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 marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  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-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝