Codex CLI: a referência técnica definitiva

Resumo rápido: Codex é um agente de coding com várias superfícies que lê sua base de código, executa comandos em um sandbox no nível do sistema operacional, aplica patches em arquivos e delega tarefas para a nuvem. Domine 5 sistemas centrais (config.toml, modelo de sandbox/aprovação, AGENTS.md, MCP e skills) e o Codex vira um multiplicador de força. Use profiles para alternar 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), US$ 5/US$ 30 por MTok, 82,7% no Terminal-Bench 2.0 SOTA.⁸³ A partir do CLI v0.140.0 (stable, 15 de junho de 2026), /usage mostra a atividade diária/semanal/acumulada de tokens da conta, sessões podem ser excluídas permanentemente via codex delete / /delete (com salvaguardas de confirmação), /import migra seletivamente setup, configuração de projeto e chats recentes do Claude Code, digitar @ abre por padrão um menu unificado de menções para arquivos, plugins e skills, e a autenticação gerenciada por chave de API do Amazon Bedrock chega junto com armazenamento local criptografado para credenciais OAuth de CLI e MCP; os controles experimentais de voz /realtime foram removidos da TUI.¹⁰² A partir do CLI v0.139.0 (stable, 9 de junho de 2026), o code mode pode chamar web search autônomo diretamente (inclusive a partir de chamadas aninhadas da ferramenta JavaScript) e receber resultados em texto puro, os schemas de entrada de tools/connectors agora preservam construções oneOf/allOf para melhor compatibilidade com schemas grandes e MCP, codex doctor adiciona detalhes de ambiente do editor e pager (redigindo valores sensíveis em JSON), e o marketplace de plugins expõe sources em codex plugin marketplace list --json com listagem mais rápida por catálogo em cache.¹⁰⁵ v0.138.0 (8 de junho) adicionou /app para transferir uma sessão do CLI para o desktop app no macOS e Windows, expôs caminhos de imagens locais ao modelo, tornou a seleção de reasoning-effort mais flexível e deu à automação de plugins uma saída JSON estruturada.¹⁰⁶ v0.137.0 (4 de junho) trouxe multi-agent v2 (runtime mantido por thread, padrões mais limpos de follow-up e metadata, hide_spawn_agent_metadata true por padrão), atalhos de teclado F13-F24 na TUI e uma extensão de skills v1 com resolução de catálogo por turno.¹⁰⁷ A partir do CLI v0.135.0 (28 de maio de 2026), codex doctor relata inventário mais rico de ambiente, Git, terminal, app-server e threads; /status mostra detalhes da conexão remota e versão do servidor quando a TUI está conectada por uma sessão remota; o modo vim ganhou edição de text-object, comportamento melhorado de palavra/fim de linha e interrupt-turn configurável; /permissions agora entende named permission profiles e exibe os personalizados; builds empacotados do Codex descobrem e usam o helper zsh corrigido incluído nos macOS compatíveis; e o Python SDK expõe presets amigáveis de Sandbox para APIs de thread e turno.¹⁰⁹ v0.134.0 (26 de maio de 2026) introduziu busca no histórico local de conversas com correspondências de conteúdo sem diferenciar maiúsculas/minúsculas e previews de resultados, tornou --profile o seletor principal de profile em fluxos do CLI, permissões da TUI e sandbox (configs legadas de profile rejeitadas com orientação de migração), melhorou o setup de MCP com direcionamento de ambiente por servidor e opções OAuth para servidores HTTP streamable, tornou schemas de connector tools mais confiáveis ao preservar $ref/$defs locais e compactar schemas grandes demais, permitiu que tools MCP read-only rodem em paralelo quando anunciam readOnlyHint, e adicionou contexto mais rico de extensões e hooks, incluindo histórico de conversa para extension tools.¹⁰¹ v0.133.0 (21 de maio de 2026) habilitou goals por padrão com armazenamento dedicado e acompanhamento de progresso; codex remote-control ganhou prontidão/status em primeiro plano e start/stop em estilo daemon; permission profiles ganharam APIs de lista, herança, requirements.toml gerenciado, refresh em runtime e integração mais forte com o sandbox do Windows; a descoberta de plugins mostra versões instaladas, raízes do marketplace e coleções remotas; e extensões podem observar início/parada de subagentes, execução de tools, metadata de turn e processamento assíncrono de aprovação/turn. A atualização de 21 de maio do Codex app adicionou Appshots para janelas Mac em primeiro plano, Goal mode GA no app/IDE/CLI, melhorias de anotação no navegador dentro do app e Computer Use bloqueado opcional para usuários Mac elegíveis.⁹⁹¹⁰⁰ v0.132.0 (20 de maio de 2026) adicionou auth de primeira classe para Python SDK, APIs de turn mais simples somente texto, TurnResult mais rico, codex exec resume --output-schema, inicialização mais rápida da TUI, registro de remote executor com auth e preservação de fidelidade de imagem em turns do app-server. Continue preferindo flags explícitas de sandbox/aprovação ou permission profiles em vez do --full-auto legado; js_repl continua removido.^{86878991969798}

Codex opera como um agente de coding com várias superfícies, não como um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, aplica patches em arquivos, conecta-se a serviços externos via MCP e delega tarefas longas para a nuvem. Ele roda localmente, mas pensa de forma global; a mesma inteligência alimenta 5 superfícies distintas dependendo de como você trabalha, incluindo a nova extensão do Chrome que executa o Codex no seu navegador sem assumir o controle dele.⁹⁰

A diferença entre o uso casual e o uso eficaz do Codex se resume a 5 sistemas centrais. Domine estes pontos e o Codex vira um multiplicador de força:

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

Passei meses usando 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 condensa essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui sintaxe real, exemplos reais de configuração e os edge cases que atrapalham usuários experientes.

Nota de estabilidade: recursos marcados como [EXPERIMENTAL] ou under development podem mudar entre releases. A partir da v0.133.0 (21 de maio de 2026), goals ficam ativados por padrão, permission profiles são uma superfície gerenciada de primeira classe, a descoberta de plugins é mais inspecionável e remote-control ficou mais fácil de executar como comando app-server em primeiro plano ou daemonizado. Codex Cloud e code mode continuam experimentais ou em desenvolvimento, enquanto o CLI principal, sandboxing, AGENTS.md, config.toml, Skills, hooks, multi-agent tools, plugins, Browser, Computer Use e Appshots são superfícies estáveis ou documentadas para o usuário, dependendo da plataforma e do plano. v0.132.0 completa auth de Python SDK e automação estruturada de resume; v0.131.0 adicionou codex doctor, busca unificada de menções com @, comandos CLI do marketplace, compartilhamento de plugins com reconhecimento de versão, remote-control gerenciado por daemon com ativação/desativação em runtime, ambientes apoiados por registry e reforços adicionais no sandbox do Windows.⁹⁶⁹⁷⁹⁸ O --full-auto legado continua depreciado e js_repl continua removido.⁸⁶⁸⁷

principais aprendizados

• Cinco superfícies, um cérebro: CLI, desktop app, extensão de IDE, tarefas na cloud e a nova extensão do Chrome compartilham a mesma inteligência GPT-5.x-Codex, então escolha a superfície que combina com seu fluxo de trabalho.⁹⁰
• Sandboxing no nível do SO: Codex aplica restrições de sistema de arquivos e rede no nível do kernel (Seatbelt no macOS, Landlock + seccomp no Linux), não dentro de containers.
• AGENTS.md funciona entre ferramentas: As instruções do seu 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 todos os lugares.
• Profiles reduzem o custo da troca de contexto: Defina presets de configuração nomeados (fast, careful, auto) e alterne entre eles com --profile.
• Gerenciamento de contexto importa: GPT-5.5 oferece uma janela de contexto de 400K no Codex e 1M no API; GPT-5.4 mini também oferece 400K para trabalho de subagent com menor latência; GPT-5.3-Codex oferece 272K de entrada. Use /compact, prompts focados e referências @file para gerenciar orçamentos de tokens de forma proativa.⁸³

como usar este guia

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

O cartão de referência rápida no final oferece um resumo fácil de escanear de todos os principais comandos.

como o Codex funciona: o modelo mental

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

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

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

Camada de superfície: CLI para usuários avançados de terminal e automação. Desktop app para gerenciamento de projetos com múltiplas threads. Extensão de IDE para ciclos de edição-compilação-teste. Cloud para tarefas assíncronas executadas de forma independente.

O insight principal: A maioria dos usuários usa apenas uma superfície. Usuários avançados usam todas as cinco: Cloud para tarefas de longa duração, CLI para operações determinísticas no repo, extensão de IDE para ciclos de codificação rápidos, o desktop app para planejamento e coordenação, e Chrome para workflows em navegador com login.

sumário

1. Como instalo o Codex?
2. Início rápido: sua primeira sessão
3. Superfícies principais de interação
4. Análise profunda do sistema de configuração
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 o AGENTS.md funciona?
10. Hooks
11. O que é MCP (Model Context Protocol)?
12. Code Mode
13. Runtime REPL de 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 Codex Desktop App
22. GitHub Action e CI/CD
23. Codex SDK
24. Otimização de performance
25. Como depuro problemas?
26. Implantação enterprise
27. Boas práticas e 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 um 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 os binários específicos da 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: configure pela variável de ambiente CODEX_API_KEY ou por codex login --with-api-key. Alguns recursos (threads na nuvem) podem não estar disponí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).

Compleções de shell

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

Verificar a instalação

codex --version
# codex-cli 0.133.0

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

Vá do zero à produtividade 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ê automaticamente a estrutura do seu projeto.

4. Faça uma pergunta:

> What does this project do? Summarize the architecture.

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

5. Faça uma alteração:

> Add input validation to the login endpoint

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

6. Use um slash command:

> /plan Refactor the database layer to use connection pooling

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

7. Confira seu trabalho:

> /diff

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

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

superfícies principais de interação

Codex oferece quatro interfaces distintas baseadas na mesma inteligência. Cada superfície é otimizada para um padrão de workflow diferente.

1. CLI interativo (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 terminal UI é uma aplicação em tela cheia com:

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

Principais atalhos da TUI:

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

Slash commands disponíveis na TUI:

Redesign do seletor de workflow (v0.129.0): Resume e fork agora são mais fáceis de acessar por um seletor redesenhado, e um novo modo de raw scrollback permite rolar pela transcrição não renderizada quando você precisa copiar comandos ou saída do modelo literalmente. Útil ao fazer triagem de uma sessão longa de debugging ou ao passar saída para outra ferramenta.⁸⁹

Menu unificado de menções com @ (v0.140.0): digitar @ no composer agora abre um único menu de menções que inclui arquivos, plugins e skills por padrão, substituindo o fluxo de anexar apenas arquivos — uma tecla para referenciar qualquer recurso do projeto.¹⁰²

2. Codex Desktop App (macOS + Windows)

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

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

• Multi-tasking: execute vários agentes paralelos em diferentes projetos ao mesmo tempo
• Isolamento por git worktree: cada thread trabalha em uma cópia isolada do seu repo
• Revisão de diff inline: faça stage, reverta e faça commit de mudanças sem sair do app
• Terminal integrado: terminal por thread para executar comandos
• Fork de conversas: crie branches de conversas para explorar alternativas
• Janelas flutuantes pop-out: destaque conversas em janelas portáteis
• Automações: agende tarefas recorrentes (triagem de issues, monitoramento de CI, resposta a alertas)
• Appshots: anexe a janela do app Mac em primeiro plano a uma thread com uma captura de tela mais o texto disponível
• Comentários no navegador dentro do app: visualize páginas locais ou públicas, deixe comentários em elementos/áreas e deixe o Codex lidar com feedback visual preciso
• Computer Use: permita que o Codex opere apps Mac autorizados para trabalho de GUI com escopo definido; o uso bloqueado é opt-in para turnos de Mac remoto elegíveis com Computer Use

Quando usar o app vs CLI: use o desktop app quando estiver coordenando vários fluxos de trabalho ou precisar de revisão visual de diff. Use o CLI quando quiser composabilidade 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 cientes do contexto nos seus arquivos ativos
• Sessões compartilhadas: sessões sincronizam entre CLI e a extensão de IDE
• Mesma autenticação: faça login com conta ChatGPT ou chave API

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

4. Codex Cloud [EXPERIMENTAL]

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

• Dispare e esqueça: enfileire tarefas que rodam independentemente da sua máquina local
• Execução paralela: execute várias tarefas em cloud ao mesmo tempo
• Criação de PR: Codex cria pull requests a partir do trabalho concluído
• Aplicação local: traga resultados da cloud para 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

Tarefas em cloud também podem ser acessadas em chatgpt.com/codex.⁴

5. Codex for Chrome [NEW]

Codex também vem como uma extensão de navegador para Chrome, adicionando uma quinta superfície junto do CLI, desktop app, extensão de IDE e cloud. A extensão foi projetada para acompanhar sua navegação normal em vez de assumir o controle dela: Codex trabalha em paralelo entre abas em background, e você mantém controle sobre quais sites ele acessa.⁹⁰

• Execução paralela em abas: Codex opera em várias abas ao mesmo tempo sem bloquear a aba em primeiro plano.
• Controle por site: você coloca em allow-list quais sites o Codex pode interagir; o padrão é sem acesso.
• Navegador como bancada de trabalho: 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 gerenciamento de conteúdo, sistemas de tickets — não uma substituição do CLI em repos locais.
• Mesma inteligência: Codex for Chrome executa a mesma inteligência GPT-5.x-Codex usada pelas outras superfícies, então uma configuração de AGENTS.md ou skills que funciona no CLI leva as mesmas convenções para o trabalho orientado por navegador.

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

análise profunda do sistema de configuração

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

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

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

requirements.toml atua como uma camada de restrição de política que limita quais valores os usuários podem selecionar depois da mesclagem normal de configuração. Veja implantação empresarial.

locais dos arquivos de configuração

Dica de especialista: A variável de ambiente CODEX_HOME substitui o diretório padrão ~/.codex. Útil para CI/CD ou configurações com várias 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 = 400000           # 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
service_tier = "fast"                  # Preferred service tier for new turns
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
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── 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)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Chrome extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed networking proxy (experimental)
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── 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

profiles

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

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

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

provedores de modelo personalizados

Conecte-se ao Azure, 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.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[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 API de fio chat/completions (wire_api = "chat") foi descontinuado para modelos hospedados pela OpenAI, com a OpenAI anunciando a remoção em fevereiro de 2026.³⁴ Provedores locais (Ollama, LM Studio) ainda podem aceitar esse formato. Para endpoints da OpenAI, use wire_api = "responses".

Use modelos locais com a flag --oss:

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

Ou defina na configuração:

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

substituições de configuração inline

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

codex -c model="gpt-5.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)

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.⁸³

O GPT-5.4 continua disponível em todas as plataformas do Codex (CLI, app, extensão de IDE, cloud).⁶⁴ 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.⁷¹

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.⁹²

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

Fluxograma de seleção de modelo

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ 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 Approval?

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

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

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

Aplicação específica por plataforma:

• macOS: framework Seatbelt da Apple via sandbox-exec, com perfis específicos por modo compilados em tempo de execução e aplicados pelo kernel⁶. A partir da v0.121.0, os perfis de sandbox do macOS podem permitir Unix sockets específicos (por exemplo, docker.sock, sockets IPC de editores), e a resolução de DNS privado não é mais bloqueada por padrão.⁸²
• Linux: Landlock para restrições do sistema de arquivos + seccomp para filtragem de syscalls. Um processo auxiliar independente (codex-linux-sandbox) oferece isolamento em profundidade.⁵ Bubblewrap (bwrap) é incluído como dependência vendorizada e compilado como parte do build para Linux (promovido de opcional na v0.100.0)⁷. A v0.117.0 melhorou a confiabilidade do sandbox em distros antigas com configurações legadas de kernel.⁷⁵ A v0.129.0 fortaleceu a inicialização do sandbox no Linux e atualizou o Bubblewrap vendorizado para 0.11.2 com patches de segurança upstream; a v0.130.0 adicionou mais endurecimento de inicialização.⁸⁹⁹¹
• Windows: sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é compatível (herda Linux Landlock + seccomp). A v0.117.0 inclui melhorias no sandbox com token restrito para melhor isolamento de processos.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários do runtime do desktop para que o sandbox do Windows consiga resolver binários de runtime de forma confiável para usuários com sandbox de workspace.⁹¹

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

Correções de segurança: - Bypass de sandbox por fork no zsh (v0.106.0): corrigida uma vulnerabilidade em que a execução de shell via fork do zsh podia contornar restrições do sandbox.⁶⁰ Se você estiver em uma versão anterior, atualize imediatamente. - Limite de tamanho de entrada (v0.106.0): Codex agora aplica um limite de entrada de aproximadamente 1 milhão de caracteres para evitar travamentos causados por payloads excessivamente grandes.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): um novo perfil endurecido para clientes em devcontainers Docker usa Bubblewrap para sandbox dentro do contêiner. WSL2 é compatível; WSL1 é rejeitado explicitamente (Bubblewrap é incompatível com o shim de kernel do WSL1).⁸² - Revisão Guardian + hooks (v0.121.0): hooks são desativados durante sessões de revisão Guardian para que hooks pré/pós-ferramenta não interfiram nas decisões do subagent Guardian.⁸² Se você depende de hooks para logging ou validação, saiba que uma revisão Guardian os ignora — use a observabilidade do app-server como fallback 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 nós de dispositivos.⁶¹

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 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: Approval Policy (quando pedir)

A approval policy determina quando 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 o marca como obsoleto. Prefira on-request para execuções interativas e never para execuções não interativas que já tenham um limite externo de segurança.⁸⁷

IDs de Approval distintos (v0.104.0+)

Codex agora atribui IDs de approval distintos a cada comando dentro de uma execução de shell com várias etapas. Isso significa que as aprovações são granulares: aprovar um comando em uma sequência não aprova automaticamente os comandos seguintes na mesma invocação de shell.⁴⁹

Controles flexíveis de Approval (v0.105.0+)

O fluxo de approval agora oferece suporte a permissões extras de sandbox e rejeição granular:⁶¹

• Permissões extras de sandbox: quando um comando precisa de acesso além do modo de sandbox atual, 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 Codex possa ajustar a abordagem em vez de simplesmente tentar o mesmo comando novamente

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

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

Permission Profiles (v0.113.0+, expandidos na v0.128.0 e v0.133.0)

Permission profiles separam políticas de sandbox do sistema de arquivos e da rede em seções nomeadas e reutilizáveis. Defina default_permissions para um perfil integrado, como :read-only, :workspace, ou aponte para uma tabela personalizada [permissions.<name>].⁸⁷ A v0.133.0 promove profiles como uma superfície gerenciada: list APIs expõem metadados de perfis disponíveis, profiles podem herdar uns dos outros, requirements.toml gerenciado pode declarar requisitos de permissão, profiles ativos são atualizados em runtime, e a configuração do sandbox do Windows agora consome o perfil resolvido em vez de uma política ad hoc separada.⁹⁸

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 devem ficar ilegíveis mesmo quando a raiz do projeto for gravável. Para exceções pontuais de comando, prefira regras em vez de expandir amplamente um perfil.⁸⁷

Orientação legada sobre --full-auto

Guias antigos descreviam --full-auto como um alias conveniente para:

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

Na v0.128.0, as notas de versão marcam --full-auto como obsoleto, e a ajuda atual de CLI não o lista mais para execuções interativas. Use as flags explícitas acima ou um permission profile nomeado.⁸⁶

Confiabilidade do sandbox (v0.129.0): o endurecimento da inicialização do sandbox no Linux reduz condições de corrida em sistemas de arquivos lentos ou checkouts com symlinks; melhorias de confiabilidade do sandbox no Windows tratam várias falhas de caso extremo durante execuções longas; e o Bubblewrap vendorizado foi atualizado para 0.11.2 com patches de segurança upstream. Nenhuma mudança de configuração é necessária. Execute codex update para receber essas melhorias.⁸⁹

Configurações recomendadas

Desenvolvimento diário (padrão seguro):

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

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

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

A combinação é o “ponto ideal” recomendado pela comunidade: capacidade máxima, mas com aprovação exigida para todos os comandos.⁸

Automação de CI/CD:

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

Smart Approvals com subagent Guardian (v0.115.0+)

Smart Approvals podem encaminhar solicitações de revisão por meio de um subagent 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 overhead de inicialização. Cada revisão recebe um histórico limpo (decisões anteriores não vazam para revisões posteriores).⁷³

Configure o revisor em config.toml:

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

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

Ativando acesso à rede

Codex bloqueia o acesso à rede por padrão no modo workspace-write. Ative 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 de WebSocket (v0.104.0+)

Para ambientes corporativos que roteiam tráfego WebSocket por um proxy, Codex agora oferece suporte às 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 a proxy HTTPS_PROXY e SOCKS5 (v0.93.0+), cobrindo todas as camadas de transporte.

Testando o sandbox

Verifique o comportamento do sandbox antes de confiar nele:

codex sandbox macos --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 em um perfil limitado ao workspace. Se qualquer um dos comandos for bem-sucedido, sua configuração de sandbox precisa ser investigada.

Como o AGENTS.md funciona?

AGENTS.md é o sistema de instruções de projeto do Codex — um padrão aberto⁹ agora governado pela Agentic AI Foundation da Linux Foundation. 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 conectá-lo 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 releases. Codex oferece suporte a dois tipos de transporte: STDIO (processos locais) e Streamable HTTP (servidores remotos).¹¹

Mudanças de 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. Um novo flag supports_parallel_tool_calls foi integrado aos MCPs incluídos, permitindo execução paralela para servidores que declaram suporte. Metadados de estado do sandbox agora passam pelos metadados das ferramentas MCP, para que os servidores possam adaptar o comportamento (por exemplo, avisar se estiverem 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 rollout de MCP Apps chega aqui com suporte a tool-call; chamadas de ferramenta diferidas achatadas agora têm suporte para servidores que usam o padrão de chamada diferida.⁸²

Configurando servidores MCP

Servidores STDIO (processos locais):

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

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

Servidores HTTP (remotos):

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

Gerenciamento de CLI

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

Na sessão: /mcp mostra servidores ativos e ferramentas disponíveis. /mcp verbose (v0.123.0+)⁸⁴ retorna diagnósticos completos do servidor, recursos e modelos de recursos — útil quando um servidor não carrega ou as ferramentas não aparecem onde esperado. 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 de nível superior em .mcp.json, então plugins criados com qualquer uma das convenções carregam corretamente.⁸⁴

Rodando Codex COMO um servidor MCP

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 duas ferramentas: 1. codex(): inicia uma nova sessão com parâmetros de prompt, sandbox, modelo e aprovação 2. codex-reply(): continua uma sessão existente com threadId e prompt

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 notáveis

Padrões práticos

Padrão 1: desenvolvimento com contexto — Combine Context7 com a documentação do seu framework para que 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 de ferramentas MCP são truncadas em ~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 passem 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]

Code mode (v0.114.0) oferece fluxos de trabalho 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.

A partir do v0.139.0, code mode pode chamar standalone web search diretamente — inclusive a partir de chamadas de ferramenta JavaScript aninhadas — e recebe resultados em texto simples, então um fluxo em code mode pode buscar informações ao vivo sem sair do contexto de programação em sandbox.¹⁰⁵

Este recurso é experimental. Consulte as notas de release para ver atualizações.

Runtime REPL de JavaScript [REMOVED]

Codex v0.100.0 adicionou um runtime REPL experimental de JavaScript (js_repl), e o v0.106.0 o promoveu pela superfície /experimental.⁶⁰ Essa orientação agora é histórica. No v0.128.0, o changelog de release 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 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 capacidades específicas para tarefas que o Codex carrega sob demanda. Elas seguem o padrão aberto de agent skills.¹³

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 oferece suporte a pastas de skills com symlink.

Como criar 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)

Metadata (agents/openai.yaml):

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

policy:
  allow_implicit_invocation: false    # Require explicit $skill

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

Como invocar skills

• Explícita: menu /skills ou menção a $skill-name no prompt
• Implícita: o Codex detecta automaticamente skills compatíveis a partir da 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

Como depurar skills

Se uma skill não estiver ativando:

1. Verifique a descoberta: /skills deve listá-la na TUI
2. Verifique o caminho: garanta que a pasta da skill esteja 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 você depende da detecção automática, garanta que allow_implicit_invocation: true esteja 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 em produção: skill de deploy

Uma skill completa com vários arquivos mostrando referências e scripts funcionando juntos:

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

SKILL.md:

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

## Deployment Procedure

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

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

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

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

Plugins

Plugins unificam skills, entradas MCP, hooks e app connectors 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 da TUI para descoberta e gerenciamento.⁷⁵ A v0.128.0 expandiu os fluxos de trabalho de plugins com instalação pelo 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 plugins no workspace (envie um conjunto de plugins para colegas de equipe sem republicar), controles de acesso de compartilhamento (ativar/desativar por destinatário, revogar), filtragem de fontes (limite de quais marketplaces um workspace puxa conteúdo) e operações de marketplace que podem ser acionadas diretamente pelo navegador /plugins em vez do CLI.⁸⁹ v0.133.0 (21 de maio de 2026) torna a descoberta de plugins mais fácil de auditar: a saída de listagem reconhece marketplaces, versões instaladas ficam visíveis, raízes de marketplace são listadas, e coleções remotas de plugins podem aparecer sem você precisar adivinhar de qual registro veio um resultado.⁹⁸ 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 mais efeitos colaterais inesperados de hooks vindos de um plugin no qual você confia apenas pelas ferramentas.
• Metadados de compartilhamento de plugin em shareContext. Quando um plugin é compartilhado a partir de um workspace, o payload do link de compartilhamento agora expõe metadados do link (criador, escopo, atualização) para que 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 uma opção de descoberta para que equipes possam publicar plugins em workspaces específicos ou listas de destinatários sem torná-los listáveis para toda a organização.

Fontes de plugins

Descoberta de plugins

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.⁷⁵ A partir da v0.142.0, o menu /plugins organiza plugins remotos nas seções OpenAI Curated, Workspace e Shared with me, e turnos elegíveis podem recomendar e instalar plugins relevantes inline.¹⁰⁴

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 personalizados, servidores MCP e app connectors.

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 tenham credenciais válidas antes da instalação. Um endpoint de desinstalação remove plugins e suas configurações associadas de forma limpa.

Como adicionar 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 próprio da OpenAI e oferece suporte a abreviação de repo 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 repos 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 plugin com suas permissões do Codex. Avalie as fontes antes de adicioná-las e prefira execução em sandbox nas primeiras execuções.

Como gerenciar 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

Na 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, instalação de skills e configuração de app connectors separadas. Um único plugin pode incluir os três — tornando o onboarding da equipe mais rápido e a configuração mais portátil.

Plan Mode e colaboração

Plan mode permite que o Codex desenhe uma abordagem antes de executar mudanças. Ele vem ativado por padrão (desde a v0.94.0).¹⁴ Veja Frameworks de decisão para a árvore de decisão “Plan Mode vs Direct Execution”.

Como entrar no Plan Mode

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

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

Steer Mode

Steer mode (ativado 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.¹⁴

Há 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

Steer mode está sempre ativo na TUI. Se você prefere esperar o Codex terminar antes de dar instruções, basta digitar normalmente depois que o turno acabar — não é necessário nenhum modo especial.

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

Realce de sintaxe (v0.105.0): A TUI agora aplica realce de sintaxe inline a blocos de código cercados e diffs. Use /theme para escolher um esquema de cores.⁶¹

Novos comandos da TUI (v0.105.0+):⁶¹

Transcrição de voz (v0.105.0, experimental): Pressione a barra de espaço para ditar prompts por transcrição de voz. Esse recurso é experimental e pode exigir permissões de microfone.⁶¹ A partir da v0.107.0, sessões de voz em tempo real têm suporte à seleção de dispositivo de microfone e alto-falante, permitindo que você escolha hardware específico de entrada/saída de áudio.⁶² Removido na v0.140.0: os controles de voz experimentais de /realtime e suas dependências de áudio foram removidos da TUI; a transcrição de voz pela barra de espaço não foi afetada.¹⁰²

Outras melhorias: - Links longos agora continuam clicáveis mesmo quando quebrados entre linhas da TUI (v0.105.0)⁶¹ - Links de arquivos locais são renderizados com formatação melhorada (v0.106.0)⁶⁰ - O markdown da TUI mantém links da web clicáveis via metadados OSC 8, e tabelas apertadas voltam para registros chave/valor legíveis sem perder os destinos dos links (v0.136.0)¹⁰⁸ - O tratamento de Ctrl+C para sub-agents foi corrigido para encerrar processos filhos corretamente (v0.106.0)⁶⁰

Sistema de memória

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

Comandos de memória

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

O que armazenar

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

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

Memória em pipelines

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

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

• Sanitização de segredos: As memórias são verificadas automaticamente em busca de segredos antes de serem gravadas no disco
• Consciência do 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 de desenvolvedor: Mensagens de developer/system 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 sensível ao uso (v0.106.0): A recuperação de memória agora considera o 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 se desviou⁶²
• Upgrade do modelo da fase 2 (v0.121.0): O modelo de consolidação de memória da fase 2 agora é gpt-5.4 (acima do padrão anterior). O pipeline da fase 2 roda 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 pelo mesmo custo em tokens.⁸²
• Menu de memórias na TUI (v0.121.0): Uma nova UI dentro da sessão expõe o modo de memória, a exclusão de memórias individuais e um botão de redefinição. A redefinição de memória agora preserva rollouts anteriores em vez de invalidá-los, então redefinir limpa a superfície de recuperação futura sem quebrar o replay 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, apenas diga diretamente ao Codex na conversa. Para contexto compartilhado com a equipe, use AGENTS.md.

Gerenciamento de sessões

Codex persiste sessões em ~/.codex/sessions/, permitindo retomar, criar forks e workflows multi-thread entre CLI e superfícies desktop.

Retomar

Continue de onde parou:

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

O slash command /resume dentro da TUI abre o mesmo seletor interativo com busca.

Fork

Crie uma ramificação de uma conversa para explorar alternativas sem perder seu progresso atual:

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

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

Fork de threads para sub-agents (v0.107.0): Threads agora podem ser transformadas em forks para sub-agents independentes, permitindo que uma conversa gere fluxos de trabalho paralelos que são executados de forma autônoma. Isso amplia o modelo de fork existente — em vez de apenas ramificar a conversa, a thread em fork se torna um sub-agent com seu próprio contexto de execução.⁶² A partir da v0.117.0, sub-agents usam endereços baseados em caminho (por exemplo, /root/agent_a) com mensagens estruturadas entre agents, tornando a coordenação multi-agent mais explícita e depurável.⁷⁵

Listagem de threads

Visualize e gerencie sessões ativas:

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

No desktop app, 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 são sincronizadas entre CLI e o desktop app — comece em um e continue no outro.

Modo não interativo (codex exec)

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

Uso básico

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

Por padrão, codex exec grava progresso/eventos em stderr e a mensagem final do agente em stdout. O design permite composição com pipelines Unix padrão.

Arquivamento de sessões (v0.136.0)

As sessões podem ser arquivadas para manter a lista de retomada/fork focada sem excluir o histórico. Arquive pela TUI com /archive ou pelo shell:¹⁰⁸

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

Uma sessão arquivada fica protegida contra operações de retomada ou fork até você desarquivá-la — uma proteção contra continuar por acidente uma sessão que você pretendia encerrar. Na mesma versão: codex app-server --stdio inicia o app-server em modo stdio para integrações com editores/hosts, e /diff agora é impedido de executar auxiliares Git fornecidos pelo repositório (uma correção de segurança de comando). No Windows, um caminho de provisionamento alpha adiciona codex sandbox setup --elevated para administradores.¹⁰⁸

Saída em linhas JSON

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

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

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

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

Saída estruturada

Aplique 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 aceita 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 exibe mais o texto legado “research preview”. Se a sua CI extrai dados da saída de inicialização, o texto do banner agora é mais enxuto; os eventos estruturados de --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 personalizados ou planos de controle remoto. Ele substitui a invocação com múltiplas flags de codex app-server que muitos integradores vinham montando manualmente e oferece às ferramentas de terceiros um único ponto de entrada estável para o mesmo runtime do app-server distribuído nas superfícies desktop e IDE.⁹¹ A v0.133.0 melhora o formato de runtime do comando: ele pode rodar como um comando em primeiro plano, aguardar prontidão, informar o status da máquina e ainda expor comandos explícitos de estilo daemon start / stop para configurações de controladores de longa duração.⁹⁸

# 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 criando UIs que precisam enumerar históricos extensos de threads sem carregar todos os turnos na memória de uma só vez.

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

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

Combine a paginação com a interface ThreadStore introduzida na v0.121.0 para percorrer threads de longa duração com eficiência, especialmente em implantações de remote-control em que o orquestrador pode estar em uma máquina diferente dos arquivos de rollout.⁸²

Atualização dinâmica da configuração do app-server (v0.130.0+)

Threads ativas do app-server agora captam alterações em config.toml sem exigir reinicialização — edite a configuração, salve, e a thread em execução reflete os novos valores no próximo turno. Esta é a contrapartida de correção de bug do codex remote-control: um servidor headless de longa duração pode ser reconfigurado no lugar em vez de ser derrubado.⁹¹

Executores remotos criptografados (v0.141.0)

A partir da v0.141.0 (stable, 18 de junho de 2026), executores remotos se conectam por canais Noise-relay autenticados e criptografados de ponta a ponta — o plano de controle e o executor não precisam mais confiar no relay entre eles, o que importa sempre que seu orquestrador controla um app-server através de uma fronteira de rede. A mesma versão fez a execução remota cross-platform preservar o diretório de trabalho e o shell nativos do executor, então um controlador em um OS que controla um executor em outro não tem mais caminhos ou semântica de shell reescritos por baixo. Agora o TLS também aceita assinaturas de certificado P-521 para compatibilidade com proxies corporativos.¹⁰³

Codex Cloud e tarefas em background [EXPERIMENTAL]

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

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

Como funciona

1. Envie uma tarefa (via chatgpt.com/codex, integração com Slack ou CLI)
2. O Codex clona seu repo em um cloud sandbox isolado
3. O agente trabalha de forma independente: lê código, executa testes, faz alterações
4. Ao terminar, 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 cloud

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

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

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

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

Integração com Slack

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

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

O Codex responde com um link da tarefa e publica os resultados quando ela termina.

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 gerenciar vários 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 baixe diretamente: Codex.dmg (macOS) | Disponível na Microsoft Store (Windows)

Principais recursos

Appshots, comentários no navegador e Computer Use

As atualizações do app de 21 de maio tornam o desktop app uma superfície de contexto mais forte, não apenas um gerenciador de threads. Use Appshots quando o Codex precisar do estado de outro app Mac antes de agir: o Codex captura a janela em primeiro plano, o texto visível/fora da tela disponível exposto pelo app e armazena o anexo localmente no histórico da sessão.⁹⁹

Para trabalho web e frontend, use primeiro o navegador dentro do app quando a página não exigir autenticação: ele oferece a você e ao Codex uma prévia renderizada compartilhada, oferece suporte a ações de uso do navegador, como cliques, screenshots, downloads de assets e inspeção somente leitura JavaScript, e permite marcar regiões da página com comentários que o Codex pode resolver no próximo turno.⁹⁹ Para sites com login, continue usando a extensão do Chrome.

Use Computer Use somente quando uma integração estruturada ou uma prévia no navegador não conseguir verificar a tarefa. Ele pode inspecionar e operar apps Mac permitidos, mas herda as aprovações e regras de sandbox do Codex para edições de arquivos e comandos shell, e o uso bloqueado continua restrito: o Codex pode acessar temporariamente apps permitidos durante turnos ativos e confiáveis de Computer Use depois que o Mac bloqueia, com proteções de rebloqueio e detecção de entrada local.⁹⁹

Modos de thread

Cada thread roda em um dos 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 um branch novo 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 terminar — você escolhe quais alterações quer mesclar de volta

Isso significa que várias threads Worktree podem rodar simultaneamente no mesmo repo sem conflitos. Cada uma recebe seu próprio branch e diretório de trabalho.

Automações

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

• Em repos Git, as automações usam worktrees de background dedicados (isolados do seu diretório de trabalho)
• Em projetos que não usam Git, as execuções acontecem diretamente no diretório do projeto
• As automações usam suas configurações padrão de sandbox

Configurando uma automação: 1. Abra um projeto no desktop app 2. Clique na aba Automations na barra lateral 3. Defina um gatilho (agenda, webhook ou manual) 4. Escreva o prompt e selecione o modo de execução (local ou worktree) 5. Defina o nível de reasoning para a execução da automação (App v26.312)⁷² 6. As automações rodam no horário agendado e enfileiram resultados para revisão

Exemplos de casos de uso: - Triagem de issues: Categorize e priorize novas issues automaticamente - 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, automações 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

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

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: somente colaboradores com acesso de escrita podem acionar workflows do Codex.

Codex SDK

O SDK do TypeScript incorpora os recursos 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
• Auth do SDK do Python (v0.132.0+): login com chave API, fluxos de código de dispositivo/navegador do ChatGPT, inspeção de conta e logout são caminhos de primeira classe do SDK.⁹⁷
• Conveniência de turno somente texto (v0.132.0+): APIs de turno do Python aceitam strings simples e retornam metadados TurnResult mais ricos com itens coletados, tempo e uso.⁹⁷
• outputSchema: Impõe saída final no formato JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })
• Fluxos de trabalho com imagem (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas, e o histórico de imagens sobrevive à retomada da sessão⁷⁵
• view_image multiambiente (v0.130.0): Para sessões que passam por vários ambientes (introduzidas na v0.124.0 com seleção de ambiente + diretório de trabalho por turno, refinadas na v0.125.0 com ambientes persistentes), view_image agora resolve caminhos de arquivo pelo ambiente selecionado, em vez do sistema de arquivos local do orquestrador. Uma imagem anexada de um ambiente remoto é buscada em relação ao diretório de trabalho desse 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: GPT-5.5 no Codex oferece 400K (1M no API). GPT-5.4 / GPT-5.4-mini oferecem 1M / 400K, respectivamente (equivalente ao API no Codex). A família GPT-5.3-Codex / GPT-5.2-Codex roda com 272K de entrada + 128K de saída (orçamento total de 400K). Todas elas enchem mais rápido do que você imagina — gerencie de forma proativa:

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 custo de exploração (que consome contexto)
3. Use @ para anexar arquivos específicos: Referencie arquivos diretamente em vez de pedir ao Codex para encontrá-los
4. Mantenha os prompts focados: Prompts delimitados com arquivos exatos consomem menos contexto do que exploração em aberto

Eficiência de tokens

Otimização de velocidade

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

Como depuro problemas?

Problemas comuns e soluções

Referência de mensagens de erro

Ferramentas de diagnóstico

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

Diagnósticos da TUI na sessão:

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

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

Reinstalação limpa

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

Modo de debug

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

Relatar problemas

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

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

Codex Security [PREVIEW]

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

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

Performance: Durante o research preview, 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 supernotificada em mais de 90% e cortando pela metade as taxas de falso positivo. O sistema encontrou vulnerabilidades reais em OpenSSH, GnuTLS e Chromium, com 14 CVEs atribuídos.⁷⁷

Observação: Codex Security é separado do modelo de segurança de sandbox integrado do CLI. O sandbox protege sua máquina do Codex; Codex Security protege sua base de código contra vulnerabilidades.

Implantação Enterprise

Controles administrativos (requirements.toml)

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

# /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"

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

Configuração MDM no macOS

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

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 as camadas gerenciadas de maior precedência sempre vencem. Os requisitos da nuvem funcionam em regime de melhor esforço; se a busca falhar ou atingir timeout, o Codex continua sem a camada da nuvem.

Integração com OpenTelemetry

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

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

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

• Variáveis de ambiente OTEL_* padrão são respeitadas (endpoint, nome do serviço, atributos de recurso)
• O contexto de rastreamento se propaga pelo Codex até chamadas API, permitindo observabilidade de ponta a ponta
• Use atributos de recurso para marcar traces por equipe, ambiente ou projeto
• Tenha em mente os requisitos de privacidade ao ativar logs de prompts/tools — os traces podem conter trechos de código
• Metadados configuráveis de traces OpenTelemetry (v0.130.0+). Além do envelope padrão OTEL_RESOURCE_ATTRIBUTES, o crate codex-otel agora expõe metadados configuráveis de trace para que 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 análises mais ricas de review/feedback lançadas na mesma versão para depuração e triagem unificadas em sessões CLI, app-server e remote-control.⁹¹

Acesso Enterprise

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

Tratamento de dados e conformidade: - Entradas/saídas da API não são usadas para treinamento nos 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 - Transcrições de sessão são armazenadas localmente; apenas chamadas API saem da 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 (semanas 1-2): Implante para 3-5 engenheiros seniores com requirements.toml impondo o modo de sandbox untrusted e busca na web cached. Colete feedback sobre padrões de AGENTS.md e necessidades de servidores MCP.
2. Expansão para a equipe (semanas 3-4): Faça o rollout para a equipe inteira. Distribua o config.toml padrão da equipe via MDM ou repositório. Ative o sandbox workspace-write para repositórios confiáveis.
3. Integração com CI (semanas 5-6): Adicione 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 (mês 2+): Implante via MDM com requirements.toml impondo servidores MCP aprovados, políticas de sandbox e listas de modelos permitidos.

Padrões de auditoria

Acompanhe o uso do Codex e aplique conformidade:

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

Práticas recomendadas e anti-patterns

Padrões de prompt

1. Prompts orientados por restrições: Comece pelos limites. “NÃO altere os contratos de API. Apenas refatore a implementação interna.”
2. Etapas estruturadas de reprodução: Etapas numeradas produzem correções de bugs melhores do que descrições vagas
3. Solicitações de verificação: Termine com “Execute lint + a menor suíte de testes relevante. Informe comandos e resultados.”
4. Referências a arquivos: Use @filename para anexar arquivos específicos ao contexto
5. Loops orientados a resultados: “Implemente, execute os testes, corrija falhas, pare somente quando todos os testes passarem.” Codex itera até terminar

Filosofia de testes

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

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

Práticas recomendadas de gerenciamento de contexto

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

Workflow de Git

• Sempre crie uma nova branch antes de executar Codex em repos desconhecidos
• Use workflows baseados em patch (git diff / git apply) em vez de edições diretas
• Revise sugestões do Codex como PRs de code review
• Use /diff para verificar 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]: Workflows de code review - ui-engineer [requirements]: Desenvolvimento frontend em nível de produção

Skills da comunidade: - claude-skill: Encaminha tarefas para Claude Code com modos de permissão - autonomous-skill: Automação de tarefas em várias sessões com acompanhamento de progresso - deep-research: Orquestração paralela de subtarefas - kiro-skill: Pipeline requisitos → design → tarefas → execução

Anti-patterns

Erros comuns que desperdiçam tokens, produzem resultados ruins ou criam workflows frustrantes.

Anti-patterns de custo

Anti-patterns de contexto

Anti-patterns de workflow

Anti-patterns de prompt

Receitas de workflow

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

Receita 1: configuração de novo projeto

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

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

> /init

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

> Run the health endpoint test and confirm it passes

Receita 2: fluxo diário de desenvolvimento

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

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

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

Receita 3: refatoração complexa com 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

Depois que Codex executar, verifique:

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

Receita 4: PR review com codex exec

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

Receita 5: debugging com Cloud Tasks [EXPERIMENTAL]

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

Verifique o progresso depois:

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

Aplique a correção localmente quando terminar:

codex apply <TASK_ID>

Guia de migração

A partir de Claude Code

Principais diferenças que você precisa entender:

• O sandbox é no nível do sistema operacional: Codex usa Seatbelt/Landlock, não containers. As restrições operam no nível do kernel, abaixo da camada da aplicação.
• Hooks estão se expandindo: Codex agora oferece suporte a 5 eventos de hook: SessionStart, Stop e UserPromptSubmit (v0.114.0–v0.116.0, experimental), além de AfterAgent (v0.99.0) e AfterToolUse (v0.100.0). O sistema cobre o ciclo de vida da sessão, interceptação de prompts e automação no nível de ferramentas, 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): Sub-agents agora usam endereços baseados em caminho (por exemplo, /root/agent_a), com mensagens estruturadas entre agentes e listagem de agentes.⁷⁵ Isso amplia a infraestrutura existente (máximo de 6 simultâneos, reduzido de 12 na v0.91.0). Papéis multiagente continuam personalizáveis via configuração (v0.104.0+).⁴⁷ A v0.105.0 adicionou spawn_agents_on_csv para fanout entre linhas, com acompanhamento de progresso e ETA.⁶¹ Codex ainda não tem a UX explícita da ferramenta Task do Claude Code para delegação orientada pelo usuário — use tarefas em nuvem ou orquestração de SDK para padrões de delegação.
• AGENTS.md é cross-tool: 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 alterar flags a cada execução, defina profiles em config.toml.

A partir do GitHub Copilot

O que você ganha: - Sandboxing no nível do sistema operacional (Seatbelt/Landlock — imposto pelo kernel vs baseado em container) - Delegação de tarefas em nuvem com codex apply - Config profiles para alternar entre fluxos de trabalho - App desktop com isolamento de worktree

A partir do Cursor

Cartão de referência rápida

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --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               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Changelog

Referências

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