Codex CLI: A referência técnica definitiva

TL;DR: Codex é um agente de programação multi-superfície: ele lê sua base de código, executa comandos em um sandbox no nível do sistema operacional, aplica patches em arquivos e delega tarefas à nuvem. Domine cinco sistemas — config.toml, o modelo de sandbox/aprovação, AGENTS.md, MCP e skills — e ele se torna um multiplicador de força. GPT-5.6 Sol é o padrão recomendado (a configuração “Power”, raciocínio médio); GPT-5.5, o modelo principal da geração anterior, oferece 400K de contexto no Codex e 1M no API.⁸³¹¹⁷ Chegou agora? Vá direto para Instalação e Início rápido. Acompanhando os lançamentos? A versão estável mais recente é a v0.147.0 (7 de agosto de 2026) — veja os Destaques da versão para a narrativa das versões recentes e o Changelog para todas as atualizações.¹¹⁶

Codex funciona como um agente de programação multi-superfície, não como um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, aplica patches em arquivos, conecta-se a serviços externos por meio de MCP e delega tarefas de longa duração à nuvem. Ele é executado localmente, mas pensa globalmente; a mesma inteligência alimenta cinco superfícies distintas, dependendo de como você trabalha, incluindo a nova extensão do Chrome que executa o Codex no seu navegador sem assumir o controle dele.⁹⁰

A diferença entre usar o Codex casualmente e usá-lo de forma eficaz se resume a cinco sistemas principais. Domine-os e o Codex se torna um multiplicador de força:

1. Sistema de configuração: controla o comportamento por meio de config.toml
2. Modelo de sandbox e aprovação: define o que o Codex pode fazer
3. AGENTS.md: define contratos operacionais no nível do projeto
4. Protocolo MCP: amplia os recursos para serviços externos
5. Sistema de skills: reúne expertise reutilizável de domínio

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

Principais conclusões

• Cinco superfícies, um cérebro: CLI, aplicativo desktop, extensão de IDE, tarefas na nuvem e a nova extensão do Chrome compartilham a mesma inteligência GPT-5.x-Codex; por isso, escolha a superfície que melhor se encaixa no seu fluxo de trabalho.⁹⁰
• Sandboxing no nível do sistema operacional: Codex aplica restrições ao 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 qualquer lugar.
• Perfis reduzem a sobrecarga de alternar contexto: Defina predefinições de configuração nomeadas (fast, careful, auto) e alterne entre elas com --profile.
• O gerenciamento de contexto importa: a família GPT-5.6 (Sol, Terra, Luna) executa uma janela de contexto de 272K; GPT-5.5, o principal modelo da geração anterior, oferece 400K no Codex e 1M no API. Use /compact, prompts focados e referências @file para gerenciar proativamente os orçamentos de tokens.⁸³¹¹²

Como usar este guia

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

O Cartão de referência rápida, no final, fornece um resumo fácil de consultar de todos os comandos principais.

Destaques de lançamentos: o que mudou recentemente

A narrativa versão a versão, para leitores que acompanham o ciclo de lançamentos do Codex. É novo por aqui? Ignore esta seção e volte depois do Início rápido — nada nela é necessário para você começar a produzir.

GPT-5.6 Sol é o padrão recomendado no Codex — a configuração padrão “Power”, com raciocínio médio, ajustável para Smarter ou Faster; GPT-5.5 (23 de abril de 2026: contexto de 400K no Codex, 1M no API, US$ 5/US$ 30 por MTok, 82,7% SOTA no Terminal-Bench 2.0) é o principal modelo da geração anterior.⁸³¹¹⁷ A partir do CLI v0.147.0 (estável, 7 de agosto de 2026), codex exec --full-auto foi removido (descontinuado desde a v0.128) — scripts que ainda o utilizam agora geram erro; substitua-o por --sandbox workspace-write junto de uma flag de aprovação ou um perfil. A v0.147.0 também inclui --approve-for-me (prompts de aprovação decididos por uma revisão automática), Agent Plugins portáteis com busca em catálogos locais, pessoais, de workspace e remotos, o protocolo opcional MCP 2026-07-28 (descoberta paginada, solicitações em várias rodadas, inicialização de servidor sem bloqueio) e seções de conversa para organizar transcrições longas.¹¹⁶ A v0.146.0 (estável, 29 de julho) fez com que proxies configurados cobrissem todas as camadas de transporte, adicionou manifestos de Agent Plugins mais os marketplaces Amazon Bedrock e Claude Code, nomeação de sessões com fixação de threads e skills fornecidas pelo executor; a v0.146.1 (5 de agosto) reforçou os padrões de revisão automática para modelos com capacidade cibernética.¹¹⁴¹¹⁵ A partir do CLI v0.145.0 (estável, 21 de julho de 2026), /import migra do Cursor e também do Claude Code — configurações, servidores MCP, plugins, sessões, comandos e memórias com escopo de projeto — a voz retorna como conversas V3 em tempo real por streaming com entradas de áudio e saídas de ferramentas de áudio em formatos locais comuns, a experiência opcional multi-agent v2 foi estabilizada com modelos de subagentes, níveis de raciocínio e concorrência configuráveis, um histórico de threads paginado experimental traz retomada eficiente, busca, nomes persistentes, suporte a subagentes e memórias, o login experimental do Amazon Bedrock é disponibilizado com suporte a endpoint e autenticação personalizados (GPT-5.6 Sol como modelo Bedrock padrão), e as seleções de modelos GPT-5.4 incluídas migram para as variantes GPT-5.6 Terra e Luna; a v0.144.6 (18 de julho) corrigiu as janelas de contexto do GPT-5.6 Sol/Terra/Luna para 272.000 tokens.¹¹¹¹¹² A partir do CLI v0.140.0 (estável, 15 de junho de 2026), /usage mostra a atividade diária/semanal/acumulada de tokens da conta, sessões podem ser excluídas permanentemente com codex delete / /delete (com proteções de confirmação), /import migra seletivamente a configuração inicial, a configuração do 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 do Amazon Bedrock API é disponibilizada junto com armazenamento local criptografado para credenciais CLI e MCP OAuth; os controles de voz experimentais /realtime foram removidos da TUI (a voz retornou posteriormente na v0.145.0 como V3 em tempo real por streaming).¹⁰²¹¹² A partir do CLI v0.139.0 (estável, 9 de junho de 2026), o modo de código pode chamar diretamente a busca web independente (inclusive a partir de chamadas de ferramentas JavaScript aninhadas) e receber resultados em texto simples, os schemas de entrada de ferramentas/conectores agora preservam construções oneOf/allOf para melhor compatibilidade com schemas grandes e MCP, codex doctor adiciona detalhes do ambiente do editor e do pager (ocultando valores sensíveis em JSON), e o marketplace de plugins expõe fontes em codex plugin marketplace list --json com listagem mais rápida do catálogo em cache.¹²² A v0.138.0 (8 de junho) adicionou /app para transferir uma sessão CLI ao aplicativo desktop no macOS e no Windows, expôs caminhos de imagens locais ao modelo, tornou a seleção de esforço de raciocínio mais flexível e deu à automação de plugins uma saída JSON estruturada; também iniciou a criptografia do texto de tarefas de pai para subagente no multi-agent v2, para que instruções de delegação não apareçam mais em texto simples nos logs locais de sessão (consulte Multi-Agent).¹²³¹⁰⁸ A v0.137.0 (4 de junho) lançou o multi-agent v2 (runtime mantido por thread, melhores padrões de acompanhamento e metadados, hide_spawn_agent_metadata com padrão true), atalhos de teclado F13–F24 da 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 um inventário mais rico de ambiente, Git, terminal, app-server e threads; /status mostra detalhes da conexão remota e a versão do servidor quando a TUI está conectada por uma conexão remota; o modo vim ganhou edição de objetos de texto, comportamento melhorado para fim de palavra/linha e interrupção de turno configurável; /permissions agora entende perfis de permissão nomeados e exibe os personalizados; builds empacotadas do Codex descobrem e usam o helper zsh corrigido incluído em macOS compatíveis; e o Python SDK expõe predefinições amigáveis de Sandbox para APIs de thread e turno.¹²⁶ A v0.134.0 (26 de maio de 2026) introduziu busca no histórico local de conversas com correspondências de conteúdo que não diferenciam maiúsculas de minúsculas e prévias de resultados, tornou --profile o seletor principal de perfis em CLI, permissões da TUI e fluxos de sandbox (configurações de perfil legadas são rejeitadas com orientação de migração), melhorou a configuração de MCP com direcionamento de ambiente por servidor e opções OAuth para servidores HTTP streamable, tornou os schemas de ferramentas de conectores mais confiáveis ao preservar $ref/$defs locais e compactar schemas grandes demais, permitiu que ferramentas MCP somente leitura fossem executadas concomitantemente quando anunciam readOnlyHint, e adicionou contexto mais rico para extensões e hooks, incluindo o histórico de conversa para ferramentas de extensão.¹⁰¹ A v0.133.0 (21 de maio de 2026) ativou metas por padrão, com armazenamento dedicado e acompanhamento de progresso; codex remote-control recebeu prontidão/status em primeiro plano, além de início/parada no estilo daemon; perfis de permissão ganharam APIs de lista, herança, requirements.toml gerenciado, atualização em runtime e integração mais forte com o sandbox do Windows; a descoberta de plugins mostra versões instaladas, raízes de marketplace e coleções remotas; e extensões podem observar o início/parada de subagentes, execução de ferramentas, metadados de turnos e processamento assíncrono de aprovações/turnos. A atualização do aplicativo Codex de 21 de maio adicionou Appshots para janelas Mac em primeiro plano, GA do modo Goal no aplicativo/IDE/CLI, melhorias de anotação no navegador interno e Computer Use bloqueado opcional para usuários Mac qualificados.⁹⁹¹⁰⁰ A v0.132.0 (20 de maio de 2026) adicionou autenticação de primeira classe do Python SDK, APIs de turno somente texto mais simples, TurnResult mais rico, codex exec resume --output-schema, inicialização mais rápida da TUI, registro remoto de executor com autenticação e preservação da fidelidade de imagem em turnos de app-server. Use flags explícitas de sandbox/aprovação ou perfis de permissão — o legado --full-auto foi removido a partir da v0.147.0; js_repl continua removido.^{86878991969798116}

Nota de estabilidade: Recursos marcados como [EXPERIMENTAL] ou under development estão sujeitos a mudanças entre lançamentos. A partir da v0.133.0 (21 de maio de 2026), metas estão ativadas por padrão, perfis de permissão são uma superfície gerenciada de primeira classe, a descoberta de plugins é mais inspecionável e remote-control é mais fácil de executar como um comando app-server em primeiro plano ou daemonizado. Codex Cloud e o modo de código continuam experimentais ou em desenvolvimento, enquanto CLI principal, sandboxing, AGENTS.md, config.toml, Skills, hooks, ferramentas multi-agent, plugins, Browser, Computer Use e Appshots são superfícies estáveis ou documentadas voltadas ao usuário, dependendo da plataforma e do plano. A v0.132.0 complementa a autenticação do Python SDK e a automação estruturada de retomada; a v0.131.0 adicionou codex doctor, busca unificada de menções @, comandos de marketplace CLI, 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 ao sandbox do Windows.⁹⁶⁹⁷⁹⁸ O legado --full-auto foi removido na v0.147.0 (descontinuado desde a v0.128), e js_repl continua removido.^8687116

Como o Codex funciona: o modelo mental

Antes de explorar os recursos, entenda como a arquitetura do Codex molda tudo o que você faz com ele. O sistema opera em cinco 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   │
│  ┌──────────┐                                           │
│  │  Chrome  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  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 alimenta tudo. Em agosto de 2026, gpt-5.6-sol é o padrão recomendado — a configuração “Power”, com raciocínio médio —, com Terra (uso diário) e Luna (rápido e acessível) ao lado; gpt-5.5 é o carro-chefe da geração anterior (contexto de 400K no Codex, 1M no API), e gpt-5.4 deixa o Codex em 31 de agosto de 2026.⁸³¹¹⁷ Ele lê arquivos, escreve patches, executa comandos de shell e raciocina sobre sua base de código. Quando o contexto fica cheio, o Codex compacta a conversa para liberar espaço. Essa camada consome tokens.

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

Camada de extensões: MCP conecta serviços externos (GitHub, Figma, Sentry). Skills agrupam fluxos de trabalho reutilizáveis que o 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ícies: CLI para usuários avançados de terminal e automação. App para desktop para gerenciamento de projetos com várias threads. Extensão de IDE para ciclos de editar-compilar-testar. Cloud para tarefas assíncronas executadas de forma independente.

A principal ideia: A maioria dos usuários usa apenas uma superfície. Usuários avançados usam as cinco: Cloud para tarefas de longa duração, CLI para operações determinísticas no repositório, extensão de IDE para ciclos de programação mais ágeis, o app para desktop para planejamento e coordenação, e Chrome para fluxos de trabalho no navegador com login.

Índice

1. Como instalo o Codex?
2. Início rápido: sua primeira sessão
3. Superfícies principais de interação
4. Análise detalhada do sistema de configurações
5. Qual modelo devo escolher?
6. Quanto custa o Codex?
7. Frameworks de decisão
8. Como o sistema de sandbox e aprovação funciona?
9. Como o AGENTS.md funciona?
10. Hooks
11. O que é MCP (Model Context Protocol)?
12. Modo Code
13. Runtime REPL de JavaScript
14. O que são skills?
15. Plugins
16. Modo Plan e colaboração
17. Sistema de memória
18. Gerenciamento de sessões
19. Modo não interativo (codex exec)
20. Codex Cloud e tarefas em segundo plano
21. O Codex Desktop App
22. Ação GitHub e CI/CD
23. Codex SDK
24. Otimização de desempenho
25. Como depuro problemas? – incluindo codex doctor
26. Implantação empresarial
27. Boas práticas e antipadrões
28. Receitas de fluxo de trabalho
29. Guia de migração
30. Cartão de referência rápida
31. Registro de alterações
32. Referências

Como instalo o Codex?

Gerenciadores de pacotes

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

Como atualizo, faço downgrade ou desinstalo o Codex CLI?

O Codex inclui um comando de autoatualização desde a v0.128.0; todo o restante funciona por meio do gerenciador de pacotes que fez a instalação.⁸⁶ Desde a v0.146.0, os artefatos de lançamento, os metadados de canal e os aliases do instalador são disponibilizados pela infraestrutura de lançamentos hospedada pela OpenAI, com GitHub como alternativa.¹¹⁴ Se a sua rede permite GitHub para instalações e atualizações do Codex, adicione também o host de lançamentos da OpenAI — a alternativa faz com que uma falha na allowlist se degrade silenciosamente, em vez de falhar de forma explícita.

# Check what you are running
codex --version                          # -> codex-cli 0.147.0
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

Fixar uma versão é a escolha certa quando uma versão quebra seu fluxo. O Codex segue uma linha estável de atualizações rápidas, portanto instalar uma versão exata é a maneira mais rápida de voltar atrás — abra uma issue, fixe a versão e siga em frente. Confirme o rollback com codex --version, pois uma segunda instalação oculta no seu PATH continuará fornecendo silenciosamente o binário antigo (codex doctor sinaliza exatamente isso em Environment).

Desinstalar o pacote não remove seu estado. A autenticação, as configurações e o histórico de sessões ficam em ~/.codex/. Mantenha essa pasta para preservar logins e histórico após uma reinstalação; exclua-a somente se quiser realmente começar do zero — rm -rf ~/.codex também descarta config.toml, auth.json e todas as sessões armazenadas.

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

Para macOS e Linux, há um script de instalação de uma linha disponível como um recurso de lançamento do GitHub:⁶⁰

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

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

Downloads de binários

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

Requisitos do sistema

• macOS: Apple Silicon ou Intel (suporte completo a sandbox via Seatbelt)
• Linux: x86_64 ou arm64 (sandbox via Landlock + seccomp)
• Windows: Sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é 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 existente Plus, Pro, Team, Business, Edu ou Enterprise. Acesso completo aos recursos, incluindo tarefas na nuvem.
2. Chave API: Defina pela variável de ambiente CODEX_API_KEY ou por codex login --with-api-key. Alguns recursos (threads na nuvem) talvez não estejam disponíveis.

Dica para especialistas: O armazenamento de credenciais pode ser configurado por cli_auth_credentials_store em config.toml. Opções: file (padrão), keyring (chaveiro do sistema operacional) ou auto (keyring quando disponível, com file como alternativa).

Login do Amazon Bedrock (v0.145.0, experimental): Equipes cujo acesso aos modelos ocorre pelo Amazon Bedrock têm um caminho de login experimental com suporte a endpoint e autenticação personalizados, além da autenticação gerenciada existente por chave API (v0.140.0+) e da cadeia de credenciais da AWS (consulte Provedores de modelos personalizados). GPT-5.6 Sol é o modelo Bedrock padrão.¹¹²

Completações do shell

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

Verifique a instalação

codex --version
# codex-cli 0.147.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. Uma pergunta como esta não faz alterações — o Codex só aplica patches aos arquivos quando você pede uma mudança, e a política de sandbox e aprovação determina quando ele precisa pedir autorização primeiro.

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 executá-lo. Revise o plano e, então, aprove-o para iniciar a execução.

7. Verifique seu trabalho:

> /diff

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

O que fazer em seguida:

• Configure AGENTS.md com instruções do projeto (consulte Como o AGENTS.md funciona?)
• Configure um perfil para seu fluxo de trabalho (consulte Perfis)
• Experimente codex exec para automação não interativa (consulte Modo não interativo)

Superfícies principais de interação

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

1. CLI interativo (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

A interface de terminal é um aplicativo em tela cheia com:

• Compositor: Digite prompts, anexe arquivos com @, execute comandos de 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 de sandbox

Atalhos principais 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 da sua janela de contexto está preenchida. Se você tiver scripts ou hooks que analisam a linha de status, verifique essa mudança de formato.⁸² O Codex também exibirá um aviso de atualização do CLI quando uma nova versão estiver disponível.

Slash commands disponíveis na TUI:

Redesign do seletor de fluxo de trabalho (v0.129.0): Agora é mais fácil acessar retomar e fazer fork a partir de um seletor redesenhado, e um novo modo de scrollback bruto permite navegar pela transcrição não renderizada quando você precisa copiar comandos ou a saída do modelo literalmente. Útil ao fazer triagem de uma sessão longa de debugging ou ao enviar a saída para outra ferramenta.⁸⁹

Menu unificado de menções com @ (v0.140.0): Digitar @ no compositor agora abre um único menu de menções que abrange 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 aplicativo para desktop adiciona recursos que o CLI não tem:

• Multitarefas: Execute vários agentes em paralelo em diferentes projetos simultaneamente
• Isolamento com git worktree: Cada thread trabalha em uma cópia isolada do seu repositório
• Revisão de diff embutida: Adicione ao stage, reverta e faça commit de alterações sem sair do aplicativo
• Terminal integrado: Terminal por thread para executar comandos
• Fork de conversas: Ramifique conversas para explorar alternativas
• Janelas pop-out flutuantes: Desanexe conversas em janelas portáteis
• Automações: Agende tarefas recorrentes (triagem de issues, monitoramento de CI, resposta a alertas)
• Appshots: Anexe a janela do aplicativo Mac em primeiro plano a uma thread, com screenshot e o texto disponível
• Comentários no navegador do app: Visualize páginas locais ou públicas, deixe comentários sobre elementos/áreas e permita que o Codex resolva feedback visual preciso
• Computer Use: Permita que o Codex opere aplicativos Mac autorizados para trabalho de GUI com escopo definido; o uso bloqueado é opcional para turnos elegíveis de Computer Use remoto no Mac

ChatGPT Voice, com tecnologia GPT-Live (desktop 26.715, 23 de julho de 2026): Agora você pode controlar o aplicativo para desktop por voz — converse sobre o trabalho e coordene tarefas em Chat, Work e Codex sem digitar. No macOS, ativar Screen context compartilha um appshot da janela em primeiro plano com a conversa, para que você possa perguntar sobre o que está vendo em vez de descrevê-lo. Disponível nos planos Plus, Pro, Business, Edu e Enterprise, no aplicativo para desktop e pelo Remote no iOS. Esta é a voz da superfície desktop; a transcrição por voz com a barra de espaço do próprio CLI é um recurso separado e experimental.¹¹³

Quando usar o app ou o CLI: Use o aplicativo para desktop ao coordenar vários fluxos de trabalho ou quando precisar de revisão visual de diffs. Use o CLI quando quiser composabilidade no terminal, scripting ou integração com CI/CD.

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

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

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

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

4. Codex Cloud [EXPERIMENTAL]

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

• Dispare e esqueça: Coloque tarefas na fila para serem executadas independentemente da sua máquina local
• Execução paralela: Execute várias tarefas na nuvem simultaneamente
• Criação de PR: O Codex cria pull requests a partir do trabalho concluído
• Aplicação local: Traga resultados da nuvem para o seu repositório local com codex apply <TASK_ID>

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

As tarefas na nuvem também podem ser acessadas em chatgpt.com/codex.⁴

5. Codex para Chrome [NOVO]

O Codex é disponibilizado como uma extensão de navegador para Chrome, adicionando uma quinta superfície ao lado do CLI, do aplicativo para desktop, da extensão IDE e da nuvem. A extensão foi projetada para acompanhar sua navegação normal, em vez de assumir o controle dela: o Codex trabalha em paralelo entre abas em segundo plano, e você continua controlando quais sites ele pode acessar.⁹⁰

• Execução paralela entre abas: O Codex opera em várias abas de uma vez sem bloquear a aba em primeiro plano.
• Controle por site: Você inclui em uma allow-list os sites com os quais o Codex pode interagir; o padrão é não ter acesso.
• Navegador como ambiente de trabalho: A extensão é ideal para trabalhar com aplicativos e sites em que a página é a fonte da verdade — consoles de administração, dashboards internos, UIs de gerenciamento de conteúdo, sistemas de tickets — e não substitui o CLI em repositórios locais.
• Mesma inteligência: O Codex para 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 mantém as mesmas convenções no trabalho conduzido pelo navegador.

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

Análise detalhada do sistema de configuração

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

Precedência (da maior para a menor)

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

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

Localizações dos arquivos de configuração

Dica para especialistas: A variável de ambiente CODEX_HOME substitui o diretório padrão ~/.codex. É útil para configurações de CI/CD ou com várias contas.

Projetos desktop com várias pastas (26.715, 23 de julho de 2026): Um projeto local no aplicativo desktop do ChatGPT agora pode abranger várias pastas relacionadas, com uma delas designada como pasta principal (menu do projeto → Editar projeto). A descoberta automática de config.toml é executada apenas na pasta principal; as pastas secundárias continuam disponíveis para pesquisa, leitura e edição de arquivos, mas não contribuem com configurações. Um .codex/config.toml em uma pasta secundária é um arquivo que o Codex pode ler, não uma configuração que ele carrega. Isso é um escopo de projeto do aplicativo desktop, não uma mudança nas regras de precedência acima — o CLI ainda resolve a configuração do projeto subindo a partir do diretório de trabalho atual.¹¹³

Referência completa de configuração

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.6-sol"                  # Recommended default (the "Power" setting)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
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

Perfis

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

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

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

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

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

Ative um perfil:

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

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

Provedores de modelos 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 comunicação chat/completions (wire_api = "chat") foi descontinuado para modelos hospedados pela OpenAI, e a OpenAI anunciou sua 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 (agosto de 2026)

GPT-5.5 (23 de abril de 2026) era a escolha recomendada pela OpenAI para a maioria das tarefas no Codex no lançamento: programaçã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; no API da OpenAI em 24 de abril. Janela de contexto: 400K no Codex, 1M no API — o Codex limita a janela a 400K para equilibrar throughput e custo entre os níveis de assinatura; o API expõe o 1M completo. Preços (API): US$ 5 de entrada / US$ 30 de saída por MTok (2× a taxa do GPT-5.4; a OpenAI indica um aumento efetivo de ~20% após melhorias na 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 ajuste de prompt). A OpenAI usou GPT-5.5 + Codex internamente para reescrever a infraestrutura de serving antes do lançamento — o que resultou em um aumento de 20% na velocidade de geração de tokens.⁸³

GPT-5.4 e GPT-5.4 mini serão removidos do Codex em 31 de agosto de 2026.¹¹⁷ Até lá, o GPT-5.4 continua selecionável em todas as superfícies do Codex.⁶⁴ A lista exata de modelos varia conforme a conta e a disponibilização. Verifique seu cache local: ~/.codex/models_cache.json.

Nota sobre descontinuação (11 de março de 2026): os modelos GPT-5.1 não estão mais disponíveis no ChatGPT. Conversas existentes continuam automaticamente no GPT-5.3 Instant, GPT-5.4 Thinking ou GPT-5.4 Pro. GPT-5.1-Codex-Mini permaneceu disponível via API e CLI até a desativação em 23 de julho de 2026.⁷¹⁸⁸

Nota sobre o nível gratuito (5 de maio de 2026): GPT-5.5 Instant foi disponibilizado para o nível gratuito do ChatGPT em 5 de maio de 2026. Isso amplia o público da família GPT-5.5 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 do API.⁹²

GPT-5.4 mini (17 de março de 2026): uma variante menor e mais rápida do GPT-5.4, com 400K de contexto a US$ 0,75/US$ 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 em paralelo com subtarefas mais específicas (busca no codebase, revisão de arquivos, processamento de documentos).⁷⁶

Bedrock GPT-5.6 (Sol, Terra, Luna) (v0.143.0, 8 de julho de 2026): o Codex adicionou suporte de primeira classe para três variantes do modelo GPT-5.6 hospedadas no Amazon Bedrock, incluindo suporte ao nível de esforço de raciocínio max. Para equipes cujo acesso a modelos passa por um provedor Bedrock, elas podem ser selecionadas da mesma forma que outros modelos de provedores personalizados (consulte Provedores de modelos personalizados); o nível de esforço max é destinado às cargas de trabalho de raciocínio e de agentes mais difíceis.¹⁰⁶ v0.144.6 (18 de julho de 2026) atualizou as instruções incluídas para Sol, Terra e Luna e corrigiu suas janelas de contexto para 272.000 tokens.¹¹¹ v0.145.0 (21 de julho de 2026) adiciona login experimental no Bedrock com suporte a endpoint e autenticação personalizados, torna o GPT-5.6 Sol o modelo padrão do Bedrock e migra as seleções incluídas do modelo GPT-5.4 para as variantes correspondentes Terra e Luna.¹¹²

Fluxograma de seleção de modelo

Is this a quick fix or simple question?
├─ Yes → gpt-5.6-luna (fastest, most affordable)
└─ 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.6-luna (the bundled subagent pick since v0.145.0)
   │     │  └─ No
   │     │     ├─ Everyday coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.6-terra (everyday model, 272K context)
   │     │     │  └─ No → gpt-5.6-sol (flagship — the default "Power" setting)
   └─ Still unsure? → gpt-5.6-sol

Esforço de raciocínio

Controle quanto o modelo “pensa” antes de responder:

Os níveis compatíveis dependem do modelo. minimal está disponível apenas para modelos GPT-5. Nem todos os modelos são compatíveis com todos os níveis.

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

Dica para especialistas: o raciocínio xhigh pode usar de 3 a 5 vezes mais tokens que o medium para o mesmo prompt. Reserve-o para problemas realmente difíceis, nos quais o raciocínio adicional compensa.

Controles rápidos de raciocínio na TUI (v0.124.0+).⁸⁵ Em uma sessão interativa na TUI, Alt+, reduz o raciocínio em um nível e Alt+. o aumenta em um nível — útil quando um problema difícil durante a sessão justifica uma progressão temporária de medium → high → xhigh sem /effort ou -c. Ao aceitar uma atualização de modelo durante a sessão, o raciocínio é redefinido para o padrão do novo modelo, em vez de manter o nível anterior.

Alternância de modelo

Alterne modelos durante a sessão com o slash command /model ou defina um 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 modelos para conhecer os recursos e Frameworks de decisão para escolher o modelo adequado para cada tarefa.

Acesso pelos 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 US$ 25 para US$ 20/assento/mês. Assentos somente Codex com preços pay-as-you-go agora estão disponíveis para workspaces Business e Enterprise — sem taxa fixa por assento, cobrados pelo consumo de tokens.⁷⁹ A página de preços agora publica limites como faixas por modelo (veja a tabela acima), em vez dos multiplicadores promocionais de 2x do lançamento do Desktop App em fevereiro de 2026.¹⁶¹¹⁹

Aumento do limite de uso de maio de 2026 (expirado em 31 de maio de 2026): O Codex no plano Plus operou com um limite de 25× em 5 horas (em comparação com o aumento padrão de 20×), e a faixa de US$ 100/mês foi dobrada na mesma janela.⁸⁹

Custos de créditos

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

Na prática, “o uso do GPT-5.6 tem média de 5 a 40 créditos por mensagem”; o modo rápido consome créditos em uma taxa maior nos modelos compatíveis, e a geração de imagens esgota os limites incluídos de 3 a 5x mais rápido do que interações comparáveis somente com texto.¹¹⁹

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

Cobrança da API

Ao usar o Codex pela API, a OpenAI cobra o uso por token segundo os preços padrão da OpenAI para a API do modelo selecionado (além de eventuais descontos aplicáveis de cache de prompts). Consulte a página oficial de preços da API para ver as tarifas atuais.²⁰

Estratégias de otimização de custos

1. Use perfis: Crie um perfil fast com gpt-5.6-luna e model_reasoning_effort = "low" para tarefas rotineiras
2. Reserve alto raciocínio: Use xhigh apenas para problemas realmente difíceis, pois ele custa de 3 a 5x mais tokens
3. Use --ephemeral: Ignore a persistência da sessão em CI/CD para reduzir a sobrecarga
4. Minimize os resumos de raciocínio: Defina model_reasoning_summary = "none" quando não precisar de explicações
5. Agrupe com o modo exec: codex exec evita a sobrecarga do TUI em fluxos de automação
6. Monitore o uso: Verifique /status no TUI e os dashboards de cobrança da sua organização

Exemplos de custos no mundo real

Custos representativos da API para tarefas comuns (um retrato dos preços do gpt-5.3-codex em meados de 2026, com raciocínio médio — os tamanhos relativos se aplicam entre os modelos):

Os custos variam conforme o esforço de raciocínio, o cache e a duração da conversa. Use gpt-5.6-luna para tarefas rotineiras e reduza substancialmente os gastos com esse tipo de tarefa. Tokens de entrada em cache são cobrados com desconto.

Sobrecarga oculta de tokens

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

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

Gerenciamento de custos da equipe

Estratégias para controlar os custos da equipe:

• Defina requirements.toml para impor limites de modelo e esforço de raciocínio em toda a organização
• Use gpt-5.6-luna para CI/CD — pipelines automatizados raramente precisam do máximo de raciocínio
• Orçamento baseado em perfis — defina os perfis ci, review e dev com limites de custo apropriados
• Monitore com OpenTelemetry — implantações Enterprise podem exportar a telemetria de uso para as stacks de observabilidade existentes

Estruturas de decisão

Quando usar cada interface

Quando usar cada modo de sandbox

Quando usar cada nível de raciocínio

Modo Plan vs execução direta

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

Modo Steer: Enter vs Tab

Regra prática: Enter = “pare, ouça isto agora.” Tab = “quando terminar, faça isto também.”

Desktop App vs CLI

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

Qual perfil?

Associe sua tarefa a um perfil pré-configurado:

Configuração do config.toml:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

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

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

[profiles.ci]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Alterne os perfis por sessão: codex --profile careful

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

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

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

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

Aplicação específica por plataforma:

• macOS: framework Seatbelt da Apple via sandbox-exec, com perfis específicos para cada modo compilados em tempo de execução e aplicados pelo kernel⁶. Desde a v0.121.0, os perfis de sandbox do macOS podem incluir sockets Unix específicos em uma lista de permissões (por exemplo, docker.sock e sockets IPC do editor), 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 chamadas de sistema. Um processo auxiliar independente (codex-linux-sandbox) oferece isolamento em profundidade.⁵ O Bubblewrap (bwrap) é incluído no código-fonte e compilado como parte da build para Linux (deixou de ser opcional na v0.100.0)⁷. A v0.117.0 melhorou a confiabilidade do sandbox em distribuições mais antigas com configurações legadas do kernel.⁷⁵ A v0.129.0 reforçou a inicialização do sandbox no Linux e atualizou o Bubblewrap incluído para a versão 0.11.2, com patches de segurança upstream; a v0.130.0 acrescentou outras medidas de proteção à inicialização.⁸⁹⁹¹
• Windows: sandbox nativo com tokens restritos (deixou de ser experimental na v0.100.0). Também há suporte ao WSL, que herda Landlock + seccomp do Linux. A v0.117.0 inclui melhorias no sandbox com tokens restritos para aumentar o isolamento de processos.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários do runtime do desktop, permitindo que o sandbox do Windows localize esses binários de forma confiável para usuários do sandbox do workspace.⁹¹

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

Correções de segurança: - Contorno do sandbox por fork do zsh (v0.106.0): corrigida uma vulnerabilidade em que a execução do shell por meio de fork do zsh podia contornar as restrições do sandbox.⁶⁰ Se você usa uma versão anterior, atualize imediatamente. - Limite do tamanho da entrada (v0.106.0): agora, o Codex impõe um limite de aproximadamente 1 milhão de caracteres à entrada para evitar travamentos causados por payloads excessivamente grandes.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): um novo perfil reforçado para clientes que usam devcontainers do Docker utiliza Bubblewrap para criar o sandbox dentro do contêiner. Há suporte ao WSL2; o WSL1 é explicitamente rejeitado (o Bubblewrap é incompatível com a camada de compatibilidade do kernel do WSL1).⁸² - Revisão do Guardian + hooks (v0.121.0): os hooks ficam desabilitados durante as sessões de revisão do Guardian para impedir que hooks executados antes ou depois das ferramentas interfiram nas decisões do subagente Guardian.⁸² Se você depende de hooks para registro ou validação, lembre-se de que uma revisão do Guardian não os executa — use a observabilidade do app-server como alternativa se precisar de uma trilha de auditoria completa. - Sistema de arquivos /dev no Linux (v0.105.0): os comandos executados no sandbox no Linux agora recebem um sistema de arquivos /dev mínimo, o que melhora a compatibilidade com ferramentas que esperam encontrar nós de dispositivos.⁶¹

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

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

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

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

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

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

Agora, o Codex atribui IDs de aprovação distintos a cada comando em uma execução de shell com várias etapas. Isso torna as aprovações granulares — aprovar um comando de uma sequência não aprova automaticamente os comandos seguintes na mesma invocação do shell.⁴⁹

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

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

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

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

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

Modo de aprovação de apps writes (v0.144.0+)

Apps e conectores ganham um nível intermediário de aprovação: o modo de aprovação de apps writes permite que as ações declaradas como somente leitura por um app sejam executadas sem solicitar aprovação, mas ainda pausa diante de qualquer ação de gravação.¹⁰⁷ Antes, as aprovações de apps funcionavam mais como tudo ou nada; writes corresponde ao nível de confiança que a maioria dos operadores realmente deseja para integrações — liberdade para consultar, aprovação para alterar.

Aprovações revisadas automaticamente: --approve-for-me (v0.147.0+)

A nova flag --approve-for-me do CLI transforma as solicitações de aprovação em aprovações revisadas automaticamente: em vez de interromper você, cada solicitação é avaliada por uma etapa de revisão e aprovada ou recusada em seu nome.¹¹⁶ Esse recurso fica entre “aprovar tudo” (a postura que --full-auto costumava incentivar e que agora foi removida) e “interromper para tudo” — as solicitações continuam existindo como pontos de decisão, mas um revisor responde a elas. Combine-o com os padrões de revisão automática mais seguros para modelos com recursos cibernéticos introduzidos na v0.146.1, que essa flag herda. Trate-o como qualquer delegação de autoridade: adequado para execuções longas e não supervisionadas, nas quais uma interrupção causaria uma paralisação, mas inadequado para sessões que envolvam credenciais ou o estado de produção, nas quais você deve ser o revisor.

Perfis de permissão (v0.113.0+, ampliados nas versões v0.128.0 e v0.133.0)

Os perfis de permissão dividem as políticas de sandbox do sistema de arquivos e da rede em seções nomeadas e reutilizáveis. Defina default_permissions como um perfil integrado, como :read-only ou :workspace, ou aponte-o para uma tabela [permissions.<name>] personalizada.⁸⁷ A v0.133.0 consolida os perfis como uma interface gerenciada: listas de APIs expõem os metadados dos perfis disponíveis, os perfis podem herdar uns dos outros, o requirements.toml gerenciado pode declarar requisitos de permissão, os perfis ativos são atualizados em tempo de execução e a configuração do sandbox do Windows agora usa 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 permanecer ilegíveis mesmo quando a raiz do projeto permite gravação. Para exceções pontuais de comandos, prefira regras em vez de ampliar um perfil de forma abrangente.⁸⁷

Orientações sobre o antigo --full-auto

Guias mais 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 do CLI não o inclui mais nas execuções interativas. Em vez disso, use as flags explícitas acima ou um perfil de permissões nomeado.⁸⁶

A v0.147.0 conclui a remoção: codex exec --full-auto não existe mais. Agora, um script que ainda passa essa flag retorna um erro em vez de ser executado. A migração é mecânica — substitua-a por --sandbox workspace-write (além de uma flag de aprovação ou um perfil, caso a invocação antiga dependesse do comportamento de aprovação de --full-auto). Antes de atualizar, audite qualquer automação que invoque codex exec pelo shell: a falha aparece como um pipeline interrompido, não como um aviso de obsolescência.¹¹⁶

Confiabilidade do sandbox (v0.129.0): o reforço da inicialização do sandbox no Linux reduz condições de corrida em sistemas de arquivos lentos ou checkouts com links simbólicos; as melhorias de confiabilidade do sandbox no Windows corrigem várias falhas em casos extremos durante execuções prolongadas; e o Bubblewrap incluído foi atualizado para a versão 0.11.2, com patches de segurança upstream. Nenhuma alteração de configuração é necessária. Execute codex update para obter 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 supervisão humana):

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

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

Automação de CI/CD:

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

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

As Aprovações Inteligentes podem encaminhar as solicitações de revisão para um subagente Guardian, em vez de exigir aprovação humana para cada ação. A sessão do Guardian persiste entre aprovações para reutilizar o cache do prompt e evitar o custo adicional de inicialização. Cada revisão recebe um histórico limpo (as decisões anteriores não influenciam as revisões seguintes).⁷³

Configure o revisor em config.toml:

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

Isso é especialmente útil em fluxos de trabalho de CI/CD nos quais você deseja uma revisão automatizada com raciocínio, em vez de simplesmente usar approval_policy = "never" para tudo.

Classificação mais rigorosa do PowerShell (v0.142.2): agora, comandos do PowerShell que contenham regiões executáveis da AST que o classificador de segurança não consegue inspecionar exigem aprovação, em vez de passarem pela aprovação automática — isso elimina uma brecha pela qual códigos PowerShell ofuscados ou criados dinamicamente podiam escapar da classificação no Windows.¹⁰⁵

Detecção ampliada de comandos perigosos (v0.144.5): a detecção agora reconhece mais formas forçadas de rm, e comandos rejeitados retornam motivos de rejeição mais claros, em vez de uma negativa vaga — útil quando você está ajustando políticas de aprovação e precisa saber por que um comando foi bloqueado.¹¹⁰

Como habilitar o acesso à rede

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

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

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

Suporte a proxy do WebSocket (v0.104.0+)

Para ambientes corporativos que encaminham o tráfego do WebSocket por um proxy, agora o Codex 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 HTTPS_PROXY e proxies SOCKS5 (v0.93.0+).

A v0.146.0 foi a versão que tornou a expressão “todas as camadas de transporte” realmente verdadeira. Agora, os proxies configurados são respeitados na autenticação, nos downloads de plugins, na autorização do MCP, na execução remota, nas conexões do WebSocket, nos redirecionamentos HTTP e nas conexões com o LM Studio — sete caminhos que, segundo o changelog, antes ignoravam o proxy.¹¹⁴ Se você executava o Codex atrás de um proxy corporativo antes da v0.146.0 e os logins ou as instalações de plugins falhavam enquanto chamadas comuns ao modelo funcionavam, essa lacuna é a explicação provável.

Proxy do sistema no macOS (v0.142.2+): com respect_system_proxy habilitado, os clientes de autenticação do macOS respeitam as configurações de proxy, PAC e WPAD do sistema — portanto, Macs corporativos que recebem configurações de proxy por meio de perfis não precisam mais de variáveis de ambiente de proxy específicas em cada shell para o tráfego de autenticação.¹⁰⁵ Desde a v0.143.0, isso também se aplica ao Windows e ao tráfego de API do Responses: o Codex encaminha tanto a autenticação quanto as chamadas de API do Responses pelo proxy do sistema do macOS ou do Windows, incluindo a configuração automática por PAC e WPAD, eliminando a última lacuna em redes corporativas restritas nos dois sistemas operacionais.¹⁰⁶

Como testar 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 deverão falhar com um erro de permissão negada em um perfil limitado ao workspace. Se algum dos comandos for executado com sucesso, será necessário investigar a configuração do sandbox.

Como funciona o AGENTS.md?

AGENTS.md é o sistema de instruções de projeto do Codex — um padrão aberto⁹ agora administrado pela Agentic AI Foundation da Linux Foundation. Ele é compatível com Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode e mais de 60.000 projetos de código aberto. Ele define como o Codex se comporta em um repositório ou diretório específico. Consulte Skills para conhecer pacotes reutilizáveis de conhecimento especializado 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): Em cada nível, verifica AGENTS.override.md > AGENTS.md > nomes de arquivo alternativos
3. Mesclagem: Os arquivos são concatenados da raiz para baixo; arquivos mais próximos aparecem depois no prompt e 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

Projetos com várias pastas no desktop (26.715, 23 de julho de 2026): O percurso acima descreve o CLI, que resolve tudo em relação ao diretório de trabalho atual. O aplicativo ChatGPT para desktop agora permite que um projeto local abranja várias pastas relacionadas, mas realiza a descoberta em exatamente uma delas: “Novos chats, operações do Git e a descoberta automática de AGENTS.md, skills e config.toml usam a pasta principal. As pastas secundárias continuam disponíveis para pesquisar, ler e editar arquivos.” Você escolhe qual pasta será a principal no menu do projeto, em Editar projeto.¹¹³

Essa única configuração controla simultaneamente três dos cinco sistemas centrais do Codex — instruções, skills e configuração seguem a pasta principal. Na prática: um AGENTS.md em uma pasta secundária é um arquivo que o Codex pode abrir, não um contrato operacional que ele carrega. Se o repositório que contém suas regras foi o segundo que você anexou, promova-o a principal ou repita essas regras no AGENTS.md da pasta principal; o mesmo vale para pastas de skills do repositório que você esperava que fossem detectadas. Nada mudou no percurso de diretórios do CLI — isso é apenas a definição de escopo de projetos no aplicativo para desktop.

O que torna um AGENTS.md excelente

Com base nas orientações diretas do próprio Codex e nos padrões da comunidade¹⁰:

FAÇA: - Seja específico: "Use rg --files for discovery" é melhor que "search efficiently" - Defina os critérios de conclusão: O que significa estar “pronto”? (testes aprovados, lint sem erros etc.) - Inclua comandos: Build, testes, lint e formatação (comandos exatos) - Organize por tarefa: Seções de desenvolvimento, revisão, lançamento e incidente/depuração - Defina como escalar problemas: O que fazer quando houver um bloqueio ou um estado inesperado

NÃO FAÇA: - Inclua guias de estilo inteiros sem regras de execução - Use instruções ambíguas (“tenha cuidado”, “otimize”) - Misture prioridades contraditórias (velocidade + verificação exaustiva + nenhum orçamento de execução) - Escreva 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 agentes

Trate o histórico visível para o Codex como uma superfície de segurança, não apenas o código-fonte. As notas de versão do Codex documentam o snapshot do shell e o trabalho de ocultação de variáveis de ambiente, e o sistema de memória verifica se há segredos nas gravações de memória. Porém, essas proteções não tornam a saída de comandos, as transcrições de sessões, os snapshots do shell, os logs locais ou os scripts auxiliares locais seguros para exibir credenciais.³⁷⁵⁵⁹⁵

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

O mecanismo de substituição

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

• Congelamentos de versão: “Nenhum recurso novo, apenas correções”
• Modo de incidente: “Todas as alterações devem ser revisadas pela pessoa de plantão”
• Reforço temporário: “Nenhuma atualização de dependências 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 da estrutura inicial

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) e, depois, adicionou um mecanismo experimental de hooks na v0.114.0 com os eventos SessionStart e Stop.⁷⁰ Desde a v0.124.0 (23 de abril de 2026), os hooks são estáveis.⁸⁵ Agora eles podem ser configurados diretamente em config.toml e requirements.toml — não é mais necessário ter um arquivo separado de scripts de hooks — e observam as ferramentas MCP, além de apply_patch e sessões Bash de longa duração. O sistema agora abrange o ciclo de vida da sessão e a automação no nível das ferramentas, eliminando a diferença em relação ao modelo de hooks do Claude Code.

Eventos de hooks disponíveis

Configuração de hooks

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

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

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

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

Como reproduzir os padrões de hooks do Claude Code

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

Dica de especialista: Desde a v0.124.0 (23 de abril de 2026), o mecanismo de hooks é estável. Novos eventos de hooks continuam sendo lançados — consulte o changelog do Codex.

Navegador de hooks na TUI (v0.129.0): Execute /hooks na TUI para descobrir os hooks disponíveis, ver quais estão ativos no momento e ativar ou desativar hooks individuais sem editar config.toml. Isso é útil para investigar um hook com comportamento incorreto incluído em um plugin ou 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. Atualmente, o grupo de comandos codex mcp está marcado como experimental, e os comandos e o formato de configuração podem mudar entre versões. O Codex oferece suporte a dois tipos de transporte: STDIO (processos locais) e Streamable HTTP (servidores remotos).¹¹

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

Mudanças no MCP v0.142.2 (25 de junho de 2026): As ferramentas do MCP agora usam busca de ferramentas por padrão quando há suporte — em vez de carregar antecipadamente a definição de cada ferramenta, o Codex descobre ferramentas sob demanda, melhorando a descoberta em configurações com muitas ferramentas e mantendo a compatibilidade com modelos e provedores mais antigos. Servidores MCP de stdio remotos também aceitam diretórios de trabalho absolutos escritos no formato de caminho da plataforma remota (um caminho no estilo Windows de um cliente macOS, ou vice-versa).¹⁰⁵

Mudanças no MCP v0.147.0 (7 de agosto de 2026): O Codex adiciona suporte opcional à revisão de protocolo MCP 2026-07-28 — descoberta paginada (catálogos grandes de ferramentas são transmitidos em páginas em vez de uma única listagem muito grande), solicitações de várias rodadas (um servidor pode manter uma troca de várias etapas dentro de uma solicitação lógica) e inicialização não bloqueante do servidor, com ferramentas MCP em cache expostas antes que o servidor termine de iniciar, para que um servidor lento não bloqueie mais o início da sessão. É opcional, portanto servidores na revisão anterior continuam funcionando sem alterações.¹¹⁶

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 do CLI

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

Na sessão: /mcp mostra os servidores ativos e as ferramentas disponíveis. /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 deveriam. O /mcp simples continua rápido. A partir da v0.144.0, as ferramentas MCP podem solicitar autenticação interativamente sem uma ativação experimental — um servidor que precisa de autenticação durante a sessão solicita isso pelo fluxo normal, em vez de falhar até que você faça a pré-autenticação com codex mcp login.¹⁰⁷

O carregamento de MCP de plugins (v0.123.0+) aceita tanto o esquema padrão mcpServers quanto mapas de servidores de nível superior em .mcp.json, para que plugins criados seguindo qualquer uma das convenções sejam carregados corretamente.⁸⁴

Executando o Codex COMO um servidor MCP

O Codex pode se expor 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 relevantes

Padrões práticos

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

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

Padrão 2: Limites de saída — As respostas das ferramentas MCP são truncadas em aproximadamente 25 mil caracteres por padrão. Para ferramentas que retornam payloads grandes (consultas de banco de dados, capturas de logs), use enabled_tools para restringir 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 avançado) junto com texto. Isso permite que ferramentas que produzem artefatos visuais — capturas de tela, diagramas e gráficos renderizados — os encaminhem diretamente ao modelo para análise.⁶²

Padrão 3: Governança empresarial do MCP — Restrinja quais servidores MCP os desenvolvedores podem usar com 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 ver a configuração completa de políticas.

Modo de código [EXPERIMENTAL]

O modo de código (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 da v0.139.0, o modo de código pode chamar a busca web independente diretamente — inclusive a partir de chamadas aninhadas de ferramentas JavaScript — e recebe resultados em texto simples, para que um fluxo do modo de código possa buscar informações atuais sem sair do contexto de programação em sandbox.¹²² A v0.146.0 estende a busca web independente a provedores de modelos personalizados compatíveis, portanto esse recurso não fica mais limitado a modelos hospedados pela OpenAI.¹¹⁴

A v0.146.0 permite que o app-server se conecte a hosts remotos do Code Mode por WebSocket, portanto o runtime do modo de código não precisa mais estar na mesma máquina que o cliente.¹¹⁴

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

Runtime REPL do JavaScript [REMOVED]

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

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

O que são skills?

Skills são pacotes reutilizáveis de recursos específicos para determinadas 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 as skills instaladas pelo usuário em $CODEX_HOME/skills (padrão: ~/.codex/skills), incluindo as skills de sistema integradas em .system/. O Codex aceita pastas de skills vinculadas por links simbólicos.

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)

Metadados (agents/openai.yaml):

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

policy:
  allow_implicit_invocation: false    # Require explicit $skill

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

Como invocar skills

• Explícita: menu /skills ou menção a $skill-name no prompt
• Implícita: o Codex detecta automaticamente as skills correspondentes com base na descrição da tarefa (se allow_implicit_invocation: true)
• Criador: use $skill-creator para criar uma nova skill de forma interativa
• Instalador: use $skill-installer install <name> para instalar skills da comunidade
• Fornecida pelo executor (v0.146.0): o Codex descobre skills oferecidas pelo executor e lê os recursos associados, incluindo as skills que você selecionar explicitamente¹¹⁴

Os limites de contexto podem truncar os catálogos de skills. A v0.146.0 mantém mais skills disponíveis quando o contexto é limitado e avisa quando um catálogo precisa ser truncado.¹¹⁴ Antes disso, uma biblioteca grande de skills podia ser reduzida silenciosamente, fazendo com que uma skill que você esperava encontrar no escopo simplesmente não fosse oferecida. Se você depende da invocação implícita de muitas skills, fique atento a esse aviso.

Ativar/desativar

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

Skills versus slash commands

Como depurar skills

Se uma skill não estiver sendo ativada:

1. Verifique a descoberta: /skills deve listá-la na TUI
2. Verifique o caminho: confirme se a pasta da skill está em um local reconhecido (~/.codex/skills/, na raiz do projeto ou em /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, confirme se allow_implicit_invocation: true está definido em agents/openai.yaml
5. Use palavras-chave: inclua no prompt termos presentes na description da skill para melhorar a correspondência implícita

Exemplo de produção: skill de deploy

Uma skill completa com vários arquivos, mostrando referências e scripts trabalhando em conjunto:

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 de MCP, hooks e conectores de apps 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 são sincronizados automaticamente na inicialização, e /plugins oferece um navegador na TUI para descoberta e gerenciamento.⁷⁵ A v0.128.0 expandiu os fluxos de trabalho de plugins com instalação via marketplace, cache de bundles remotos, APIs de desinstalação remota, hooks incluídos em plugins, estado de ativação de hooks e importação de configurações de agentes externos.⁸⁶ A v0.129.0 (7 de maio de 2026) adiciona compartilhamento de workspace de plugins (envie um conjunto de plugins para colegas sem republicá-lo), controles de acesso ao compartilhamento (ativar/desativar por destinatário, revogar), filtragem de fontes (limite de quais marketplaces um workspace usa) e operações de marketplace que podem ser invocadas diretamente no navegador /plugins, em vez do CLI.⁸⁹ A v0.133.0 (21 de maio de 2026) torna a descoberta de plugins mais fácil de auditar: a saída de listagem considera o marketplace, versões instaladas ficam visíveis, raízes de marketplaces são listadas e coleções remotas de plugins podem ser exibidas sem adivinhar de qual registro veio um resultado.⁹⁸ A 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 de um plugin no qual você confia apenas pelas ferramentas.
• Metadados de compartilhamento de plugins em shareContext. Quando um plugin é compartilhado a partir de um workspace, a carga útil do link de compartilhamento agora expõe metadados do link (criador, escopo, atualidade), para que as sessões destinatárias possam mostrar a procedência e decidir se devem aceitá-lo.
• Controles de descoberta nas configurações de compartilhamento. As configurações de compartilhamento expõem uma alternância de descoberta para que equipes possam publicar plugins em workspaces específicos ou listas de destinatários sem torná-los listáveis de forma geral em toda a organização.

A v0.143.0 (8 de julho de 2026) ativa plugins remotos por padrão. Plugins remotos agora são ativados sem uma flag de adesão, o catálogo de /plugins ganha linhas mais completas (fontes de marketplace npm junto com git e locais), e cada entrada mostra tanto sua versão remota quanto a instalada localmente, para que divergências fiquem visíveis de imediato.¹⁰⁶ Para uma equipe que está padronizando um conjunto compartilhado de plugins, o padrão remoto elimina a etapa de ativação por máquina que antes bloqueava a adoção.

Fontes de plugins

A partir da v0.147.0, a busca de plugins abrange catálogos locais, pessoais, de workspace e remotos em uma única consulta — você busca uma capacidade, não o catálogo que por acaso a contém. Combinado aos pacotes portáteis Agent Plugin, um plugin criado em um ambiente é instalado corretamente em outro, em vez de ficar vinculado à máquina ou ao workspace onde foi criado.¹¹⁶

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 a @plugin (v0.112.0+)

Faça referência a qualquer plugin instalado diretamente no chat com @plugin-name.⁶⁸ Quando você menciona um plugin, o contexto dele (recursos, ferramentas, configuração) é incluído automaticamente na janela de contexto do modelo — não é necessário 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 conectores de apps.

Marketplace de plugins (v0.113.0+)

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

Adição de 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 primário da OpenAI e oferece suporte a abreviações de repositórios GitHub, URLs Git HTTP(S), URLs SSH e diretórios raiz de marketplaces locais; use --ref para fixar uma referência Git e repita --sparse PATH apenas para repositórios de marketplace baseados em Git.⁹³

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

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

# SSH Git URL
codex plugin marketplace add git@example.com: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 plugins padrão. Chamadores do app server (integrações de IDE/desktop) têm um endpoint paralelo para registrar marketplaces programaticamente.⁸²

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

Agent Plugins: o padrão multiplataforma (v0.146.0–v0.147.0)

“Agent Plugins” não é apenas o nome de um recurso do Codex — é um padrão aberto e neutro em relação a fornecedores para empacotamento, publicado como Agent Plugins 1.0.0 em 6 de agosto de 2026, cujo site oficial o resume como “A portable package format for reusable components that extend AI agents.”¹¹⁸ Um plugin é um diretório com um manifesto plugin.json obrigatório (um schema fechado de exatamente dez campos de nível superior permitidos — $schema, name, version, description, author, homepage, repository, license, keywords, extensions — em que “Clients MUST report and ignore each unknown field”), uma pasta skills/ opcional (cada diretório filho imediato que contém um SKILL.md é uma skill), um mcp.json opcional que declara servidores stdio, Streamable HTTP ou HTTP+SSE legado, e diretórios opcionais de namespace de cliente com domínio reverso que outros clientes “MUST ignore.” Seu escopo normativo é o empacotamento: a especificação “defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins” — Agent Skills e MCP mantêm suas próprias especificações abaixo dela.¹¹⁸

A governança é a história. A Vercel iniciou a proposta e desenvolveu a especificação 1.0 com Amazon, Anysphere (Cursor), GitHub, Microsoft e OpenAI; a lista de mantenedores do repositório da especificação abrange Amazon, Cursor, Microsoft, OpenAI e Vercel, e o Google anunciou no dia do lançamento que está se juntando aos mantenedores principais.¹¹⁸ Os clientes nomeados no lançamento abrangem ChatGPT, Codex, Cursor, GitHub Copilot, Kiro e VS Code. Uma ausência notável: Anthropic, que criou o formato subjacente Agent Skills e o próprio MCP, não está entre os mantenedores — Claude Code mantém seu próprio formato de plugin, e Codex preenche essa lacuna do seu lado com a fonte de marketplace Claude Code (v0.146.0) e /import.¹¹⁸

Em termos de Codex: a v0.146.0 adiciona manifestos Agent Plugins, publicação de plugins de workspace e dois marketplaces adicionais de plugins — Amazon Bedrock e Claude Code¹¹⁴ — e a v0.147.0 completa o ciclo com instalação de Agent Plugins portáteis e busca em catálogos locais, pessoais, de workspace e remotos.¹¹⁶ A publicação no workspace é a metade operacionalmente útil para equipes: publique plugins no seu próprio workspace, em vez de criar um marketplace público ou pedir que cada desenvolvedor adicione manualmente uma fonte Git.

As notas de lançamento anunciam as superfícies do Codex sem publicar suas chaves de configuração ou a sintaxe do CLI. Esta entrada registra que a capacidade foi disponibilizada e o que o padrão especifica, não como usá-la no Codex — trate o fluxo de criação de manifestos e qualquer invocação de codex plugin publish como não verificados até que a documentação da OpenAI os aborde.

Gerenciamento de 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 sessão.⁷⁵

Dica de especialista: Plugins consolidam o que antes exigia configuração MCP separada, instalação de skills e configuração de conectores de apps. Um único plugin pode incluir os três — tornando a integração de equipes mais rápida e a configuração mais portátil.

Plan Mode e colaboração

O Plan Mode permite que o Codex defina uma abordagem antes de executar alterações. Ele vem ativado por padrão (desde a v0.94.0).¹⁴ Consulte Frameworks de decisão para ver a árvore de decisão “Plan Mode vs execução direta”.

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é que você aprove - Exibe o plano em tempo real em uma visualização específica da TUI

Steer Mode

O Steer Mode (ativado por padrão desde a v0.98.0) permite inserir novas instruções enquanto o Codex está trabalhando, sem interromper a tarefa atual.¹⁴

Há duas formas de inserir instruções:

Exemplos práticos:

# Codex is refactoring the auth module...

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

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

O Steer Mode está sempre ativo na TUI. Se você preferir esperar o Codex terminar antes de dar novas instruções, basta digitar normalmente após a conclusão do turno — nenhum modo especial é necessário.

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

Destaque de sintaxe (v0.105.0): agora, a TUI destaca a sintaxe de blocos de código delimitados e diffs diretamente no conteúdo. 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ão de acesso ao microfone.⁶¹ Desde a v0.107.0, sessões de voz em tempo real permitem selecionar os dispositivos de microfone e alto-falante, para que você escolha o hardware específico de entrada e saída de áudio.⁶² Removido na v0.140.0 e retomado na v0.145.0: os controles experimentais de voz /realtime e suas dependências de áudio foram removidos da TUI na v0.140.0 (a transcrição de voz pela barra de espaço não foi afetada).¹⁰² A v0.145.0 traz a voz de volta em um novo formato: entradas de áudio e saídas de ferramentas de áudio em formatos locais comuns, além de conversas V3 em tempo real via streaming.¹¹²

Outras melhorias: - Links longos agora continuam clicáveis mesmo quando quebrados entre linhas da TUI (v0.105.0)⁶¹ - Links para arquivos locais são exibidos com formatação aprimorada (v0.106.0)⁶⁰ - O markdown da TUI mantém os links da web clicáveis por meio de metadados OSC 8, e tabelas sem espaço suficiente passam a ser exibidas como registros legíveis de chave/valor sem perder os destinos dos links (v0.136.0)¹²⁵ - O tratamento de Ctrl+C para sub-agents foi corrigido para encerrar corretamente os processos filhos (v0.106.0)⁶⁰

Sistema de memória

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

Comandos de memória

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

O que armazenar

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

• Convenções do projeto: “Este projeto usa tabulações, 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 “Execute os testes com pytest -x --tb=short“
• Decisões de arquitetura: “O módulo de autenticação fica em src/core/auth/, não em src/middleware/“
• Preferências de fluxo de trabalho: “Sempre execute o linter antes de me mostrar um diff”

Memória em pipelines

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

Aprimoramentos da 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
• Reconhecimento do CWD: agora, os arquivos de memória incluem o contexto do diretório de trabalho para recuperar informações específicas do projeto
• Exclusão de mensagens do desenvolvedor: mensagens de desenvolvedor/sistema são excluídas da entrada da memória da fase 1, melhorando a qualidade da memória ao manter o foco nas interações com o usuário
• Esquecimento baseado em diff (v0.106.0): agora, a memória usa o esquecimento baseado em diff para remover fatos obsoletos, mantendo o armazenamento de memórias enxuto e relevante ao longo do tempo⁶⁰
• Seleção baseada no uso (v0.106.0): agora, a recuperação de memórias considera o uso e prioriza memórias acessadas com frequência e relevantes recentemente⁶⁰
• Memórias configuráveis (v0.107.0): agora, as memórias são totalmente configuráveis. Use codex debug clear-memories para redefinir todas as memórias armazenadas e começar do zero — útil ao alternar entre projetos sem relação entre si ou quando o estado da memória deixou de refletir o contexto atual⁶²
• Atualização do modelo da fase 2 (v0.121.0): agora, o modelo de consolidação de memória da fase 2 é o gpt-5.4 (em substituição ao padrão anterior). O pipeline da fase 2 é executado entre sessões para condensar as transcrições da fase 1 em fatos duradouros; a mudança de modelo melhora a qualidade da recuperação pelo mesmo custo de tokens.⁸²
• Menu de memórias da TUI (v0.121.0): uma nova interface disponível durante a sessão oferece acesso ao modo de memória, à exclusão de memórias individuais e a um botão de redefinição. Agora, a redefinição da memória preserva rollouts anteriores em vez de invalidá-los. Assim, a redefinição limpa o que poderá ser recuperado no futuro sem prejudicar a reprodução da sessão.⁸²

Memória vs AGENTS.md

Dica: use /m_update para fatos que devem persistir por tempo indeterminado. Para contextos específicos da sessão, basta informar o Codex diretamente na conversa. Para contextos compartilhados com a equipe, use AGENTS.md.

Gerenciamento de sessões

Codex persiste sessões em ~/.codex/sessions/, permitindo retomar, bifurcar e realizar fluxos de trabalho com múltiplas threads no CLI e nas superfícies desktop.

v0.146.0 torna as threads endereçáveis. /new e /clear agora aceitam um nome de sessão, threads importantes podem ser fixadas, e conversas paralelas permanecem abertas em vez de forçar você a fechar uma para acessar outra.¹¹⁴ Na prática, um projeto de longa duração deixa de ser uma lista de timestamps que você precisa reconhecer pela data. v0.147.0 adiciona seções de conversa: as conversas se organizam em seções persistentes, ordenadas manualmente, e transcrições longas são navegadas de forma incremental em vez de serem carregadas por inteiro.¹¹⁶

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.

Histórico paginado de threads (v0.145.0) [EXPERIMENTAL]: Um histórico paginado experimental de threads traz retomada eficiente, busca em todo o histórico, nomes de threads persistidos, suporte a sub-agents e memórias para o gerenciamento de sessões — o histórico é carregado página por página, em vez de todo de uma vez, o que importa para diretórios de trabalho de longa duração com centenas de sessões. Experimental: espere que a interface mude entre versões.¹¹²

Bifurcar

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

As bifurcações criam threads independentes que compartilham o mesmo histórico até o ponto da bifurcação. A partir da v0.146.0, o histórico de bifurcações é paginado, e as bifurcações podem ser criadas como temporárias — uma bifurcação temporária não aparece nas listagens de threads, o que mantém experimentos descartáveis fora da lista de threads que você realmente navega.¹¹⁴ Alterações em uma bifurcação não afetam a outra. Isso é útil para comparar abordagens (por exemplo, “bifurque e tente Redis em vez de Memcached”) ou explorar mudanças arriscadas com segurança.

Bifurcação de threads em sub-agents (v0.107.0): Agora as threads podem ser bifurcadas em sub-agents independentes, permitindo que uma conversa gere fluxos de trabalho paralelos executados de forma autônoma. Isso estende o modelo de bifurcação existente — em vez de apenas ramificar a conversa, a thread bifurcada se torna um sub-agent com seu próprio contexto de execução.⁶² A partir da v0.117.0, os 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.⁷⁵

Mensagens criptografadas entre agents (v0.138.0+): O multi-agent v2 agora criptografa o texto da tarefa que um agent pai envia ao criar ou enviar uma mensagem para um sub-agent. Os parâmetros de mensagem de spawn_agent, send_message e followup_task são marcados como criptografados: o API Responses criptografa a carga útil quando o modelo pai emite a chamada de ferramenta, o Codex em execução local carrega apenas o texto cifrado (InterAgentCommunication.encrypted_content, com conteúdo em texto simples vazio), e o API o descriptografa no servidor ao entregá-lo ao modelo receptor.¹⁰⁸ Três consequências práticas:

• Os logs da sua sessão local não contêm mais texto simples de delegação. Você pode ver que um agent pai criou um sub-agent e o que ele retornou, mas não a instrução exata enviada. Se você auditar ou depurar execuções multi-agent a partir do histórico de sessões, esse registro não estará disponível; a issue de regressão aberta que acompanha isso não tinha correção vinculada até meados de julho de 2026.¹⁰⁹ Eventos do ciclo de vida de extensões (início/parada de subagent, execução de ferramentas, metadados de turnos — v0.133.0+) e a observabilidade do app-server são os hooks restantes para reconstruir o que aconteceu.⁹⁸
• Modelos de provedores personalizados podem falhar. Um endpoint de modelo que não esteja configurado para uso de ferramentas criptografadas rejeita o schema criptografado de spawn_agent com um 400 ("declares encrypted parameters but is not configured for encrypted tool use"). Se a delegação multi-agent falhar com esse erro em um provedor personalizado, essa é a mudança de criptografia, não a sua configuração.¹⁰⁹
• Notificações geradas pelo Codex continuam legíveis. As notificações de conclusão de agentes filhos são produzidas pelo próprio Codex, portanto permanecem em texto simples e agora são renderizadas como itens tipados de agent_message, em vez de envelopes JSON serializados.¹⁰⁸

A OpenAI não publicou o modelo de ameaças por trás da mudança; o PR descreve o fluxo de texto cifrado sem informar contra o que ele protege.

Multi-agent v2 estabilizado (v0.145.0, opt-in): A experiência multi-agent v2, que estreou na v0.137.0 e recebeu delegação criptografada na v0.138.0, agora está estabilizada como um recurso opt-in. A v0.145.0 adiciona modelos de sub-agent configuráveis, níveis de raciocínio por sub-agent, concorrência configurável, papéis multi-agent restaurados e navegação aprimorada entre agents. Se você adiou o uso da v2 durante os ajustes das versões v0.137/v0.138, esta é a versão em que a superfície de configuração se estabiliza — as escolhas de modelo e raciocínio dos sub-agents agora ficam na configuração, em vez de serem fixadas pelo runtime.¹¹²

Listagem de threads

Veja e gerencie sessões ativas:

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

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

Ciclo de vida da sessão

As sessões são sincronizadas entre o CLI e o aplicativo desktop — 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 o progresso e os eventos em stderr e a mensagem final do agente em stdout. Esse design permite a 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 retomadas e forks organizada 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é que você a desarquive — uma proteção contra a continuação acidental de uma sessão que pretendia encerrar. Na mesma versão, codex app-server --stdio inicia o app-server no modo stdio para integrações com editores e hosts, e /diff agora está impedido de executar auxiliares do Git fornecidos pelo repositório (uma correção de segurança de comandos). No Windows, um fluxo de provisionamento alfa adiciona codex sandbox setup --elevated para administradores.¹²⁵

Saída em linhas JSON

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

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

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

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

Saída estruturada

Imponha o formato da resposta com um Schema JSON:

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ões

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

Principais flags

Autenticação em CI

codex exec oferece suporte a 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 antigo texto “research preview”. Se a sua CI extrai informações da saída de inicialização, o texto do banner agora está 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, projetado para ser controlado por outro processo — extensões de IDE, orquestradores personalizados ou planos de controle remoto. Ele substitui a invocação de codex app-server com várias flags que muitos integradores montavam manualmente e oferece a ferramentas de terceiros um ponto de entrada único e estável para o mesmo runtime do app-server fornecido nas interfaces para desktop e IDE.⁹¹ A v0.133.0 melhora o funcionamento do comando: ele pode ser executado como um comando em primeiro plano, aguardar até estar pronto, informar o status da máquina e ainda oferecer os comandos explícitos start / stop no estilo daemon para configurações de controladores de longa duração.⁹⁸ A v0.143.0 adiciona codex remote-control pair, que gera um código de pareamento manual a partir de um daemon em execução para que um controlador possa se conectar sem o handshake de descoberta automática — útil quando o processo controlador está em um host ou segmento de rede diferente do daemon.¹⁰⁶

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

# Generate a manual pairing code for an out-of-band controller (v0.143.0+)
codex remote-control pair

# 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 ao criar interfaces 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+)

Agora, os clientes do app-server podem paginar threads extensas usando três visualizações distintas dos itens de cada 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 nas quais o orquestrador pode estar em uma máquina diferente dos arquivos de rollout.⁸² A v0.143.0 amplia o que um controlador pode inspecionar: agora, os clientes do app-server podem enumerar os ambientes disponíveis, listar as threads descendentes de uma thread e criar um fork do histórico a partir de um turno específico — os recursos básicos de que uma interface precisa para ramificar uma execução a partir de um ponto anterior sem reproduzi-la até esse ponto.¹⁰⁶

Atualização da configuração do app-server em tempo real (v0.130.0+)

Agora, as threads ativas do app-server incorporam alterações em config.toml sem exigir reinicialização — edite a configuração, salve, e a thread em execução refletirá os novos valores no turno seguinte. Essa é a correção de bug complementar ao codex remote-control: um servidor headless de longa duração pode ser reconfigurado sem precisar ser encerrado.⁹¹

Executores remotos criptografados (v0.141.0)

Desde a v0.141.0 (estável, 18 de junho de 2026), os 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 é importante sempre que o seu orquestrador controla um app-server através dos limites de uma rede. A mesma versão fez com que a execução remota entre plataformas preservasse o diretório de trabalho e o shell nativos do executor, evitando que um controlador em um sistema operacional, ao controlar um executor em outro, tenha os caminhos ou a semântica do shell alterados durante a operação. Agora, o TLS também aceita assinaturas de certificado P-521 para oferecer compatibilidade com proxies corporativos.¹⁰³

Codex Cloud e tarefas em segundo plano [EXPERIMENTAL]

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

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

Como funciona

1. Envie uma tarefa (por chatgpt.com/codex, pela integração com o Slack ou pela CLI)
2. O Codex clona seu repositório em um sandbox isolado na nuvem
3. O agente trabalha de forma independente: lê o código, executa testes e 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 nuvem

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

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

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

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

Integração com o Slack

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

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

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

CLI da nuvem

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

O Codex Desktop App

O Codex Desktop App (macOS e Windows) oferece uma interface gráfica otimizada para gerenciar vários projetos.¹⁶ A versão para Windows foi lançada em 4 de março de 2026 com suporte nativo ao PowerShell e sandbox nativa do Windows.⁶⁶

Instalação

codex app                      # Auto-downloads and installs on first run

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

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 completa, em vez de apenas um gerenciador de threads. Use os Appshots quando o Codex precisar conhecer o estado de outro app do Mac antes de agir: o Codex captura a janela em primeiro plano, o texto visível e fora da tela disponibilizado pelo app e armazena o anexo localmente no histórico da sessão.⁹⁹

Para trabalhos web e de frontend, use primeiro o navegador integrado quando a página não exigir autenticação: ele oferece a você e ao Codex uma visualização renderizada compartilhada, permite ações no navegador, como cliques, capturas de tela, downloads de recursos e inspeção somente leitura de JavaScript, além de permitir que você marque regiões da página com comentários que o Codex pode resolver no turno seguinte.⁹⁹ Para sites que exigem login, continue usando a extensão do Chrome.

Use o Computer Use somente quando uma integração estruturada ou visualização no navegador não puder verificar a tarefa. Ele pode inspecionar e operar apps autorizados do Mac, mas segue as aprovações e as regras de sandbox do Codex para edições de arquivos e comandos de shell. O uso bloqueado continua restrito: o Codex pode acessar temporariamente os apps autorizados durante turnos ativos e confiáveis do Computer Use depois que o Mac é bloqueado, com mecanismos de bloqueio automático e detecção de entradas locais.⁹⁹

Modos de thread

Cada thread é executada em um dos três modos, selecionado no momento da criação:

Mecânica de isolamento do Worktree:

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

Isso permite executar várias threads no modo Worktree simultaneamente no mesmo repositório sem conflitos. Cada uma recebe seu próprio branch e diretório de trabalho.

Automações

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

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

Como configurar uma automação: 1. Abra um projeto no desktop app 2. Clique na aba Automations na barra lateral 3. Defina um gatilho (agendamento, webhook ou manual) 4. Escreva o prompt e selecione o modo de execução (local ou worktree) 5. Defina o nível de raciocínio da execução da automação (App v26.312)⁷² 6. As automações são executadas conforme o agendamento e colocam os resultados em uma fila para revisão

Exemplos de uso: - Triagem de issues: Categorize e priorize automaticamente novas issues - Monitoramento de CI: Monitore falhas de build e sugira correções - Resposta a alertas: Reaja a alertas de monitoramento com análises de diagnóstico - 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 para Windows em 4 de março de 2026 (App v26.304), com suporte nativo ao PowerShell, sandbox nativa do Windows e paridade completa 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 subsequentes.

Estratégias de segurança

Controles de acesso

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

Padrão: somente colaboradores com acesso de gravação podem acionar fluxos de trabalho do Codex.

Codex SDK

O TypeScript SDK 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(...): Fluxo de eventos assíncrono para atualizações intermediárias
• Autenticação do Python SDK (v0.132.0+): Login com chave API, fluxos de navegador/código de dispositivo do ChatGPT, inspeção de conta e logout são caminhos de primeira classe do SDK.⁹⁷
• Conveniência para turnos somente de texto (v0.132.0+): As APIs de turno do Python aceitam strings simples e retornam metadados mais completos de TurnResult, com itens coletados, tempo e uso.⁹⁷
• outputSchema: Impõe uma saída final no formato de JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })
• Fluxos de trabalho com imagens (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas e o histórico de imagens é preservado ao retomar a sessão⁷⁵
• view_image em vários ambientes (v0.130.0): Em sessões que abrangem vários ambientes (introduzidas na v0.124.0 com seleção de ambiente e diretório de trabalho por turno, e refinadas na v0.125.0 com ambientes persistentes), view_image agora resolve caminhos de arquivo por meio do 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 são persistidas em ~/.codex/sessions.

Runtime: Node.js 18+.

Otimização de desempenho

Gerenciamento de contexto

As janelas de contexto variam conforme o modelo. A atual família GPT-5.6 (Sol, Terra, Luna) opera com uma janela de 272K; GPT-5.5, o carro-chefe da geração anterior, oferece 400K no Codex (1M no API); GPT-5.4 / GPT-5.4-mini (que serão descontinuados do Codex em 31 de agosto de 2026) oferecem 1M / 400K; a família legada GPT-5.3-Codex operava com 272K de entrada + 128K de saída (orçamento total de 400K). Todos eles enchem mais rápido do que você imagina — gerencie proativamente:

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

Eficiência de tokens

Otimização de velocidade

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

Como faço para depurar problemas?

Problemas comuns e soluções

Referência de mensagens de erro

O que faz codex doctor?

codex doctor é o único comando a executar antes de registrar um bug ou depurar uma instalação com falha. Ele reúne o runtime local, a configuração, a autenticação, o terminal, a rede e o estado em um único relatório, e o próprio modelo de issue do projeto pede que você cole sua saída.¹²⁰

codex doctor                           # Full human-readable report (the default)
codex doctor --summary                 # Compact view
codex doctor --json                    # Redacted structured JSON, for bug reports
codex doctor --all                     # Expand truncated lists
codex doctor --no-color                # Strip ANSI color

O relatório é organizado em seções estáveis, então você pode ir direto à que precisa:¹²⁰

Cada verificação traz um marcador de status – ✓ ok, ✗ falha, ⚠ aviso, ○ inativo – com uma linha de resumo. --json identifica cada verificação com um identificador estável, o que permite usá-lo em CI ou em um script de suporte, em vez de apenas inspecioná-lo visualmente.¹²⁰

O comando evoluiu ao longo das versões: chegou na v0.131.0, ganhou relatórios de ambiente, Git, terminal, app-server e inventário de threads na v0.135.0, e adicionou detalhes de editor e paginador (com valores confidenciais ocultados em JSON) na v0.139.0.^96126122

Use-o primeiro, não por último. A maioria dos relatos de “o Codex está quebrado” se resume a algo que o doctor já aponta: um modo de autenticação desatualizado, um config.toml que não conseguiu ser analisado ou uma segunda instalação ocultando a que está no seu PATH.

Ferramentas de diagnóstico

codex doctor                           # Full local diagnostic (start here)
codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

Diagnósticos da TUI durante a sessão:

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

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

Reinstalação limpa

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

Preserva ~/.codex/ (autenticação, configuração, sessões). Para fixar uma versão exata, fazer downgrade após uma versão problemática ou apagar totalmente o estado, consulte Atualizar, fazer downgrade ou desinstalar.

Modo de depuração

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

Como relatar problemas

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

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

Codex Security [PREVIEW]

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

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

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

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

Implantação empresarial

Controles administrativos (requirements.toml)

Os administradores aplicam a política empresarial por meio de requirements.toml, um arquivo de configuração imposto por administradores que restringe configurações sensíveis à segurança e que os usuários não podem substituir:²¹

A v0.146.0 adiciona reconhecimento de planos empresariais e controles administrativos sobre atualizações no aplicativo.¹¹⁴ Em uma frota gerenciada, essa é a diferença entre desenvolvedores atualizarem por conta própria o CLI sempre que percebem uma nova versão e o administrador decidir quando uma versão será distribuída. As notas da versão anunciam o controle sem publicar sua chave de requirements.toml — considere o nome exato da configuração como não verificado até que a OpenAI o documente.

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

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

Configuração de MDM no macOS

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

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

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

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

Integração com OpenTelemetry

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

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

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

• As variáveis de ambiente padrão OTEL_* são respeitadas (endpoint, nome do serviço, atributos de recurso)
• O contexto de rastreamento é propagado pelo Codex para chamadas ao API, possibilitando observabilidade de ponta a ponta
• Use atributos de recurso para marcar rastreamentos por equipe, ambiente ou projeto
• Considere os requisitos de privacidade ao habilitar o registro de prompts/ferramentas — os rastreamentos podem conter trechos de código
• Metadados de rastreamento do OpenTelemetry configuráveis (v0.130.0+). Além do envelope padrão OTEL_RESOURCE_ATTRIBUTES, o crate codex-otel agora expõe metadados de rastreamento configuráveis para que administradores possam marcar rastreamentos 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 execução. Combine isso com as análises mais ricas de revisão/feedback lançadas na mesma versão para depuração e triagem unificadas em sessões de CLI, app-server e controle remoto.⁹¹

Acesso empresarial

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

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

Estratégia de rollout

Rollout em fases recomendado para organizações:

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

Padrões de auditoria

Acompanhe o uso do Codex e aplique a conformidade:

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

Boas práticas e antipadrões

Padrões de prompt

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

Filosofia de testes

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

• Defina os testes antecipadamente como sinais de conclusão
• Deixe o Codex iterar até os testes passarem (vermelho → verde → refatorar)
• Adote os padrões de programação do Tiger Style
• Forneça o texto exato do arquivo ao solicitar patches. O Codex usa correspondência estrita, não aplicação de patches aproximada baseada em AST

Boas práticas de gerenciamento de contexto

• Forneça documentação local de alta qualidade em vez de depender de pesquisa na web
• Mantenha Markdown estruturado com sumários e arquivos de progresso (“divulgação progressiva”)
• Normalize as terminações de linha (LF vs CRLF) entre os arquivos rastreados para evitar falhas de patch
• Mantenha o AGENTS.md conciso, pois instruções longas saem do contexto

Fluxo de trabalho com Git

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

Skills e prompts da comunidade

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

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

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

Antipadrões

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

Antipadrões de custo

Antipadrões de contexto

Antipadrões de fluxo de trabalho

Antipadrões de prompt

Receitas de fluxo de trabalho

Padrões completos para cenários comuns de desenvolvimento.

Receita 1: Configuração de novo projeto

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

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

> /init

Revise o AGENTS.md gerado, edite-o para corresponder às suas convenções e, em seguida:

> 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 depois faça o commit.

Receita 3: Refatoração complexa com o modo de planejamento

codex

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

Revise o plano. Aprove ou direcione:

[Tab] Also add a migration script using Alembic

Depois que o Codex executar, verifique:

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

Receita 4: Revisão de PR com codex exec

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

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

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

Verifique o progresso mais tarde:

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

Do Claude Code

Principais diferenças a entender:

• O sandbox é no nível do sistema operacional: o Codex usa Seatbelt/Landlock, não containers. As restrições operam no nível do kernel, abaixo da camada da aplicação.
• Os hooks estão evoluindo: o Codex agora oferece suporte a 5 eventos de hook: SessionStart, Stop e UserPromptSubmit (v0.114.0–v0.116.0, experimentais), além de AfterAgent (v0.99.0) e AfterToolUse (v0.100.0). O sistema abrange o ciclo de vida da sessão, a interceptação de prompts e a automação no nível de ferramentas, embora os mais de 12 eventos de ciclo de vida do Claude Code ainda ofereçam uma cobertura mais ampla. Para padrões de automação ainda não contemplados, use instruções no AGENTS.md ou skills.
• Sub-agentes v2 (v0.117.0): os sub-agentes 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). As funções de múltiplos agentes continuam personalizáveis via configuração (v0.104.0+).⁴⁷ A v0.105.0 adicionou spawn_agents_on_csv para fanout entre linhas, com acompanhamento do progresso e ETA.⁶¹ O Codex ainda não tem a UX explícita da ferramenta Task do Claude Code para delegação direcionada pelo usuário — use cloud tasks ou a orquestração de SDK para padrões de delegação.
• AGENTS.md funciona em várias ferramentas: seu AGENTS.md funciona no Cursor, Copilot, Amp, Jules, Gemini CLI e em mais de 60.000 projetos de código aberto. CLAUDE.md é exclusivo do Claude.
• Perfis substituem a alternância manual: em vez de mudar as flags a cada execução, defina perfis em config.toml.

Do Copilot GitHub

O que você ganha: - Sandboxing no nível do sistema operacional (Seatbelt/Landlock — imposto pelo kernel em vez de baseado em containers) - Delegação de cloud tasks com codex apply - Perfis de configuração para alternar fluxos de trabalho - Aplicativo desktop com isolamento por worktree

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 (Aug 2026)                                            ║
║  gpt-5.6-sol           Recommended default ("Power", 272K)    ║
║  gpt-5.6-terra         Everyday model (272K)                  ║
║  gpt-5.6-luna          Fast + affordable (272K)               ║
║  gpt-5.5               Previous-gen flagship (400K in Codex)  ║
║  gpt-5.4 / -mini       Retire from Codex Aug 31, 2026         ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Registro de alterações