Codex CLI: a referência técnica definitiva

TL;DR: Codex é um agente de programação para múltiplas interfaces: ele lê sua base de código, executa comandos em um sandbox no nível do sistema operacional, modifica arquivos e delega tarefas à nuvem. Domine cinco sistemas — config.toml, o modelo de sandbox/aprovação, AGENTS.md, MCP e skills — e ele se tornará um multiplicador de produtividade. Qual modelo usar: a documentação de modelos da OpenAI agora recomenda o GPT-6.1 Sol (gpt-6.1-sol, padrão incluído no CLI desde a v0.159.1) para trabalhos complexos de programação e com agentes, o GPT-6-Astra para os trabalhos completos mais difíceis e o GPT-6 Luna para tarefas específicas e repetíveis. A disponibilidade depende do plano, do cliente e das configurações do workspace; o GPT-6 Sol e os modelos GPT-5.6 continuam no seletor, enquanto o GPT-5.5 será descontinuado no Codex para quem usa login do ChatGPT em 14 de outubro de 2026.^146171178 Está começando agora? Vá direto para Instalação e Início rápido. Acompanhando os lançamentos? A versão estável mais recente é a v0.162.1 (9 de outubro de 2026), com duas correções sobre a v0.162.0, que ativa a interrupção instantânea por padrão; os Destaques dos lançamentos começam com um resumo do estado atual (o que vem ativado por padrão e o que ainda é experimental), seguido dos detalhes de cada versão, e o Changelog lista todas as atualizações do guia.^116178182183

O Codex funciona como um agente de programação para múltiplas interfaces, não como um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, modifica arquivos, conecta-se a serviços externos via MCP e delega tarefas de longa duração à nuvem. Ele é executado localmente, mas pensa de forma global; a mesma inteligência está presente em cinco interfaces distintas, dependendo da sua forma de trabalhar, incluindo a extensão para navegador (Chrome, Edge, Brave, Opera e Vivaldi), que executa o Codex no seu navegador sem assumir o controle dele.⁹⁰¹²⁷

A diferença entre usar o Codex casualmente e usá-lo com eficiência se resume a cinco sistemas fundamentais. Domine-os e o Codex se tornará um multiplicador de produtividade:

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

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

Principais conclusões

• Cinco interfaces, um só cérebro: CLI, o aplicativo para desktop, a extensão para IDE, as tarefas na nuvem e a extensão para navegador (Chrome, Edge, Brave, Opera e Vivaldi) compartilham a mesma família de modelos, então escolha a interface mais adequada ao seu fluxo de trabalho.⁹⁰
• Sandbox no nível do sistema operacional: o 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 contêineres.
• AGENTS.md funciona em várias 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 de código aberto. Escreva uma vez e use em qualquer lugar.
• Os perfis reduzem o custo da troca de contexto: defina predefinições de configuração nomeadas (fast, careful, auto) e alterne entre elas com --profile.
• O gerenciamento de contexto faz diferença: o catálogo incluído no Codex oferece ao GPT-6.1 Sol, GPT-6 Astra, Sol e Luna e à família GPT-5.6 uma janela de contexto de 272K (o API indica 1,05M para GPT-6.1 Sol, GPT-6 Sol e Luna); o GPT-5.5 oferece 400K no Codex até ser descontinuado nessa plataforma em 14 de outubro de 2026. Use /compact, prompts específicos e referências @file para gerenciar os limites de tokens de forma proativa.^83112178

Como usar este guia

Esta é uma referência com mais de 3.300 linhas — comece pela seção correspondente ao seu nível de experiência:

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

Destaques da versão: o que mudou recentemente

O histórico versão por versão, começando pela mais recente, para quem acompanha o ciclo de lançamentos do Codex. Chegou agora? Pule para o início rápido; nada abaixo é necessário para começar a produzir. Os detalhes da verificação (comparações, listas de commits e verificações da documentação) estão nas notas de rodapé.

Estado atual

Codex CLI em 13 de outubro de 2026

• Estável: v0.162.1 (9 de outubro, npm latest), com duas correções, após a v0.162.0 (8 de outubro), que ativa instant_interrupt por padrão e adiciona ferramentas de worktrees, fixação no Command Center e cópia de transcrições, e a v0.161.0 (7 de outubro), que adiciona /mcp login, seleção de dispositivos de voz, descoberta de modelos por chave API ativada por padrão e o sinalizador opcional Daybreak.
• Alpha: o npm alpha está na versão 0.163.0-alpha.9 (13 de outubro); a linha 0.163 ainda não gerou uma versão estável.
• Modelo padrão desde a v0.159.1: GPT-6.1 Sol, substituindo o GPT-6-Astra, inclusive no Amazon Bedrock. Defina model em config.toml para manter outro modelo. O catálogo incluído na v0.162.1 lista os mesmos modelos da v0.159.1.
• Ativado por padrão desde a v0.162.0: instant_interrupt, para que novas entradas interrompam a resposta de um modelo (instant_interrupt = false em [features] desativa esse comportamento); o sinalizador continua marcado como em desenvolvimento.
• Ativada por padrão desde a v0.161.0: descoberta de modelos por chave API (api_key_model_discovery = false em [features] a desativa).
• Ativados por padrão desde a v0.158.0: aprovação para entradas em terminais elevados (write_stdin_approval = false em [features] a desativa), além de copiar ao selecionar e colar com o botão direito na TUI em tela cheia (copy_on_select = "never", right_click_paste = "off" em [tui]). O contexto de threads do Guardian está sempre ativado; thread_context é ignorado.
• Ativados por padrão desde a v0.157.0: a transcrição em tela cheia (fullscreen_transcript = false em [tui]) e a inicialização automática do servidor em segundo plano (daemon_auto_start = false em [features] ou --no-daemon).
• Ativados por padrão desde a v0.156.0: /voice, worktrees gerenciadas e reutilização da compactação do processo pai pelo Guardian.
• Opcionais ou experimentais: Codex Cloud, code mode e sua busca classificada de ferramentas (code_mode_tool_search, v0.162.0), Daybreak (cli_daybreak, v0.161.0), recuperação do histórico pelo Guardian (guardian_conversation_history_tools, v0.160.0). O gerenciamento experimental de contexto não está disponível no momento.
• Modelos: GPT-6.1 Sol para programação complexa, GPT-6-Astra para os trabalhos mais difíceis e GPT-6 Luna para tarefas repetíveis. GPT-6 Sol e Luna começam no modo Fast (2,5x créditos); GPT-6.1 Sol não. GPT-5.5 deixa o Codex em 14 de outubro de 2026.
• Fixação da versão: npm install -g @openai/codex@0.162.1 e depois codex --version.^{176178186187188189}

v0.162.1 (9 de outubro de 2026)

Duas correções, três commits sobre a v0.162.0. Foi corrigida uma falha da TUI em perguntas assíncronas com várias linhas, preservando as quebras de linha e os destinos completos dos hyperlinks. E acabaram as falhas de inicialização que alguns usuários da v0.162.0 encontraram, causadas por diferenças entre as configurações de recursos de um servidor em segundo plano em execução e os padrões do CLI: agora, a verificação de compatibilidade se aplica somente a substituições explícitas de recursos pela linha de comando. Nenhum padrão, chave de configuração ou modelo muda.

O que fazer: atualize, especialmente se a v0.162.0 se recusava a iniciar enquanto um servidor em segundo plano de uma versão anterior estava em execução.¹⁸⁸

v0.162.0 (8 de outubro de 2026)

instant_interrupt é ativado por padrão. O sinalizador que a v0.159.0 lançou como opcional, permitindo que uma nova entrada interrompa a resposta de um modelo ou libere uma chamada demorada do code mode, passa a ser ativado para todos a partir desta versão (PR #51812, incorporada em 7 de outubro); ele continua marcado como em desenvolvimento. Defina instant_interrupt = false em [features] para restaurar o comportamento anterior, no qual a entrada digitada aguarda a conclusão da resposta.

Novidades na TUI: ferramentas para criar e listar Git worktrees gerenciadas a partir de projetos locais confiáveis, quando o recurso de worktrees está ativado, permitindo que o próprio modelo abra uma worktree (#50148); fixação no Command Center do agente com p, que mantém as tarefas fixadas em um grupo compartilhado chamado Pinned quando há suporte do servidor (#51500); /copy navega pelos blocos da transcrição, Ctrl+Insert copia uma seleção e tui.mouse_scroll_speed (um número positivo finito, com padrão 1.0) ajusta a rolagem da roda do mouse (#50434, #50215, #50209); URLs podem ser clicadas em cabeçalhos de aprovação, perguntas, prompts de MCP, avisos e banners, inclusive quando os links ocupam mais de uma linha. Novas threads da TUI respeitam os padrões de modelo e resumo do raciocínio do servidor, mantendo substituições explícitas na inicialização. codex doctor informa o modo configurado da TUI, e /status volta a mostrar o e-mail da conta após uma atualização da conta.

Provedores e modelos: um provedor personalizado compatível com Responses pode declarar external_web_access e remote_compaction em [model_providers.<name>.capabilities] (#50459). O recurso ultrafast_mode é lançado ativado, permitindo que um catálogo de modelos que anuncie uma categoria Ultra Fast (os modelos Astra do Amazon Bedrock, #50472) a ofereça independentemente do modo Fast; o catálogo incluído nesta tag não lista nenhuma categoria desse tipo. O code mode ganha auxiliares de JavaScript para transmitir resultados de promises e uma busca classificada de ferramentas opcional (code_mode_tool_search). apply_patch sempre preserva as terminações de linha CRLF existentes, e o sinalizador apply_patch_preserve_line_endings foi removido. Falhas recuperáveis de Responses e WebSocket respeitam a orientação Retry-After do servidor.

Sandbox e plataforma: foi corrigida a inicialização do sandbox do Linux com vários arquivos negados, executáveis graváveis usados na construção do sandbox são rejeitados e a configuração do ripgrep não pode mais enfraquecer as máscaras de padrões glob de negação; o Windows 10 recupera o acesso normal a arquivos por letras de unidade, as permissões temporárias do sandbox passam a corresponder às do processo filho, a verificação de checksums de arquivos compactados funciona com caminhos de módulos do PowerShell 7 e as versões para Windows incluem um instalador assinado do PowerShell.

O que fazer: atualize; se você dependia de digitar antecipadamente sem interromper o modelo, defina instant_interrupt = false.¹⁸⁷¹⁸⁹

v0.161.0 (7 de outubro de 2026)

Criada a partir da 0.161.0-alpha.13.1 mais um commit de lançamento, 155 commits à frente da v0.160.1. As notas da versão listam o GPT-6.1 Sol como o novo padrão (#49318, #49339), mas essas são as alterações de catálogo que já foram lançadas na v0.159.1: o models.json incluído nesta tag é idêntico, byte por byte, ao da v0.160.1, portanto nada muda para quem está na 0.159.1 ou posterior.

Novidades: /mcp login <name> faz login em um servidor MCP a partir de uma sessão de terminal em execução (#49290). Seleção de dispositivos de voz: escolha o microfone, o alto-falante e os canais de entrada do microfone para conversas com /voice, com as preferências salvas localmente (#49437, #49836). A descoberta de modelos por chave API está ativada por padrão (api_key_model_discovery, promovida a estável, #49807): ao fazer login com uma chave API da OpenAI em um endpoint compatível, o Codex atualiza o catálogo de modelos por meio da API, em vez de depender somente da lista incluída; api_key_model_discovery = false em [features] desativa o recurso, e a alteração entra em vigor em uma nova sessão. O Amazon Bedrock oferece suporte a multiagente V2 e raciocínio Ultra em modelos compatíveis, e o Bedrock Mantle aceita regiões do AWS GovCloud (#49345, #49813).

Daybreak (opcional). Um novo sinalizador cli_daybreak, desativado por padrão e em desenvolvimento, adiciona controles do Daybreak ao CLI: um botão de alternância /daybreak, indicadores e roteamento automático pelo programa de acesso Cyber, para logins do ChatGPT no provedor OpenAI cuja conta e catálogo de modelos anunciem compatibilidade. Ative-o com --enable cli_daybreak ou cli_daybreak = true em [features]; uma preferência salva daybreak = true, por si só, não faz nada. Independentemente disso, codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red> (e o cyberAccessProgram do TypeScript SDK) solicita um programa de acesso Cyber para um turno, com ou sem o sinalizador, e não altera a opção salva (#49856 a #49861, #49939, #51207). O catálogo incluído já contém as entradas ocultas gpt-daybreak-blue-latest e gpt-daybreak-red-latest.

Correções: uma elevação aprovada do sistema de arquivos pode conceder acesso de gravação mais amplo sem remover as restrições de leitura e rede, e as tarefas em segundo plano mantêm as permissões do turno em que foram originadas; permissões explícitas de inicialização persistem após reconexões do terminal; sessões elevadas do terminal no Windows podem ser iniciadas com um servidor incorporado; Enter envia a entrada armazenada em buffer após expirar a detecção de colagem, inclusive no modo de inserção do Vim; a retomada de uma thread inclui o histórico confirmado mais recente, e a inicialização detecta mais cedo danos recuperáveis no SQLite, mantendo os bancos de dados danificados como backups; novas tentativas de Responses e o fallback de WebSocket para HTTP respeitam as orientações de repetição do servidor. A documentação de autenticação agora informa que as credenciais podem ficar no keyring, em vez de sempre em auth.json.

O que fazer: atualize. Nada aqui altera um padrão que você perceberia, a menos que faça login com uma chave API; nesse caso, verifique o catálogo descoberto em /model.¹⁸⁶¹⁸⁹

v0.160.1 (5 de outubro de 2026)

Uma correção para servidores MCP remotos no Windows. Quando o Codex em um host macOS ou Linux inicia um servidor MCP stdio em um executor Windows remoto, e a configuração desse servidor define explicitamente variáveis de ambiente remotas, agora o Codex também repassa SYSTEMROOT, TEMP e TMP, para que o processo do Windows mantenha o ambiente de inicialização necessário. As variáveis que você não solicitou, incluindo segredos, continuam excluídas. A versão contém apenas um backport sobre a v0.160.0 e não altera padrões, chaves de configuração nem modelos.

O que fazer: atualize se você executa servidores MCP stdio remotos em um executor Windows a partir de um host Unix.¹⁸³

v0.160.0 (1º de outubro de 2026)

A versão estável da linha 0.160, criada a partir da 0.160.0-alpha.6.1 com um backport. Nenhuma alteração nos padrões. O catálogo de modelos incluído na tag é idêntico, byte por byte, aos das versões v0.159.1 e v0.159.2. Portanto, o GPT-6.1 Sol continua sendo o padrão, e os dois novos feature flags vêm desativados. O backport (#49763) atualizou o candidato congelado da 0.160, ramificado antes da v0.159.1, para acompanhar a linha de manutenção 0.159: os catálogos incluído e do Amazon Bedrock para o GPT-6.1 Sol, além dos lembretes de segurança da conta da v0.159.3. Sem ele, a 0.160 teria sido lançada sem o GPT-6.1 Sol.

Novidades opcionais do Guardian (ambas em desenvolvimento e desativadas por padrão):

• O Guardian pode ler mensagens anteriores do usuário. Defina guardian_conversation_history_tools = true em [features]. Com Apps habilitados, o revisor recebe user_message.search_messages e user_message.read_messages pela conexão de Apps da própria sessão principal. Assim, ele pode verificar instruções, restrições e permissões revogadas anteriormente antes de aprovar uma ação com efeitos colaterais. Cada chamada verifica novamente a política atual de aplicativos e ferramentas da sessão principal. Por padrão, as respostas são limitadas a uma estimativa de 4.000 tokens (auto_review.conversation_history_max_output_tokens), e auto_review.experimental_conversation_history_prompt substitui as instruções de recuperação integradas.
• Contexto raiz com reconhecimento de handoff (guardian_root_handoff_context): quando o Guardian revisa a ação de um agente worker, ele seleciona as três mensagens raiz anteriores a cada handoff para esse worker ou seus ancestrais, além das três mensagens raiz mais recentes, para que um cancelamento recente continue visível.

Sempre ativo: as mensagens criptografadas dos agentes agora aparecem, em ordem, nas transcrições do Guardian, em vez de serem descartadas.

Alterações na TUI: em uma pasta sem configuração de projeto nem decisão de confiança salva, uma nova sessão pode começar com permissões workspace-write e aprovações granulares, mas somente quando a execução local, sua configuração e a política gerenciada permitirem. As sessões retomadas restauram as permissões salvas, a menos que você as substitua, e /cd pode solicitar que você decida se confia na pasta, com a opção “Manter o diretório atual”. A central de comandos dos agentes ganhou uma linha “Mostrar mais”, que carrega tarefas anteriores de dez em dez. Em terminais X11 locais no Linux (não no Wayland, SSH, tmux, WSL ou VS Code), as seleções da transcrição em tela cheia vão para a seleção primária, e um clique com o botão do meio cola o conteúdo no editor. Quando há espaço, a linha de status em tela cheia mostra Plan mode (shift+tab to cycle). Agora, os níveis Pro aparecem como “Pro 100”, “Pro 200” e “Pro 500” em /status e nas análises. As dicas de inicialização indicam o aplicativo para desktop da sua plataforma, em vez de promover planos ou o modo Fast, e as mensagens enfileiradas que nunca foram enviadas são retomadas após uma reconexão sem duplicações.

Provedores e conexões: a TUI preserva as configurações de provedor, resumo de raciocínio e detalhamento de um app server, exibe as sessões corretas nos históricos de retomada e fork e oculta as configurações de resumo de raciocínio em /status nas conexões de servidor. Um provedor com um catálogo de modelos explícito (model_catalog_url) agora recebe somente esse catálogo: nenhum modelo incluído é mesclado, os metadados correspondem ao ID exato do modelo, uma atualização com falha descarta as entradas em cache em vez de reutilizá-las, e uma inicialização sem nenhum modelo disponível informa um erro de configuração, a menos que model esteja definido. Quando um filtro de conteúdo interrompe uma resposta, a nova tentativa orienta o modelo a explicar a limitação, oferecer uma alternativa permitida e continuar as outras tarefas.

Correções: fallbacks do PowerShell no sandbox do Windows, reparo de ACL para caminhos de runtime longos e eliminação de janelas de console abertas por utilitários em segundo plano; os subagentes mantêm ambientes que ainda estão sendo iniciados; o SQLite não trava mais durante a configuração da conexão e informa erros de inicialização em vez de timeouts. O banco de dados de logs recupera espaço não utilizado em segundo plano, e o carregamento de plugins armazena manifests analisados em cache e reutiliza conexões HTTP. Agora, a documentação de provedores informa que as credenciais de requires_openai_auth usam o backend escolhido por cli_auth_credentials_store e que env_key identifica a variável de ambiente que contém a chave API.

O que fazer: atualize. Se um provedor personalizado definir model_catalog_url, confirme se o catálogo dele contém todos os modelos que você seleciona.¹⁸²

v0.159.3 (30 de setembro de 2026)

Lembretes opcionais de segurança da conta. Sessões locais da TUI conectadas ao ChatGPT pelo provedor OpenAI podem exibir um banner dispensável pedindo que você conclua a configuração de segurança da conta, com um botão que abre chatgpt.com. O servidor decide quem recebe o aviso; o CLI o busca em segundo plano sem bloquear um turno, não mostra nada quando o estado é desconhecido, ignora workspaces remotos e contas FedRAMP e se lembra quando ele é dispensado entre threads e reconexões. Os banners de uso têm prioridade. Essa é a única alteração da versão, e a v0.160.0 contém o mesmo código.

O que fazer: nada. O lembrete é opcional.¹⁸⁴

v0.159.2 (29 de setembro de 2026)

Uma correção para janelas de console que piscavam no Windows. No Windows, o Codex não abre mais uma janela de console sempre que inicia um processo em segundo plano. Isso inclui comandos de ferramentas de shell, hooks, chamadas do Git e do npm, atualizações de credenciais do Amazon Bedrock executadas sem terminal, verificações do doctor, atualizações da configuração do sandbox e comandos no sandbox legado do Windows. Os comandos que precisam do seu terminal ainda herdam o console dele. A versão é um único backport de duas correções da branch principal, publicada cerca de três horas e meia após a v0.159.1. Ela não altera padrões, chaves de configuração nem modelos, e o novo utilitário de inicialização mantém o comportamento anterior no macOS e no Linux.

O que fazer: no Windows, atualize se as janelas de console piscarem enquanto o Codex trabalha, especialmente se o servidor em segundo plano estiver instalado.¹⁸⁰

v0.159.1 (29 de setembro de 2026)

O GPT-6.1 Sol passa a ser o modelo padrão. Quando nenhum modelo está definido em config.toml, agora o CLI inicia com o GPT-6.1 Sol (gpt-6.1-sol) em vez do GPT-6-Astra, e o GPT-6.1 Sol substitui o GPT-6 Sol como padrão nos catálogos Mantle e Runtime do Amazon Bedrock. O seletor /model o exibe em primeiro lugar, como “Modelo de uso geral mais recente para programação e tarefas cotidianas”, seguido por GPT-6-Astra, GPT-6 Sol (agora “Modelo de uso geral da geração anterior”), GPT-6 Luna e os modelos mais antigos. As escolhas salvas não são migradas: uma configuração que especifica gpt-6-sol ou gpt-6-astra mantém esse modelo, e as solicitações de migração para seleções mais antigas do GPT-5 continuam indicando o GPT-6 Sol ou o GPT-6 Luna.

A documentação da OpenAI adicionou o modelo no mesmo dia e agora o recomenda para programação complexa e fluxos de trabalho com agentes: “desempenho próximo ao Astra para trabalhos complexos, com custo menor que o Astra”. Ele custa 50 créditos por 1 milhão de tokens de entrada (2,5 em cache e 250 de saída), e a faixa Plus permite de 15 a 160 mensagens. Dois detalhes do catálogo diferem do GPT-6 Sol: ele não tem um nível de serviço padrão, portanto a sessão começa na velocidade Standard em vez de Fast, e o esforço de raciocínio padrão é low em vez de medium. O lançamento abrange Plus, Pro, Business, Enterprise e Edu; no Enterprise e no Edu, ele permanece desativado até que um administrador o habilite, e os planos Free e Go não estão incluídos no lançamento.

O que fazer: atualize e depois verifique o modelo em /status. Se a sua conta ainda não tiver acesso ao GPT-6.1 Sol, fixe um modelo disponível usando model em config.toml ou -m.¹⁷⁸

v0.159.0 (29 de setembro de 2026)

Criada a partir da 0.159.0-alpha.13, cerca de 27 horas após a v0.158.0. Vários itens nas notas da versão já haviam sido lançados como backports na v0.158.0: as correções da janela de console e do inicializador no Windows, a cópia que preserva Markdown, a tela de boas-vindas e as dicas de turno, além das correções de login. A configuração tui.prompt_suggestions, listada nas notas como removida, nunca apareceu em uma versão estável.

Novidades desta versão:

• instant_interrupt (opcional, em desenvolvimento): uma nova entrada interrompe antecipadamente a resposta de um modelo ou faz uma chamada longa do modo de código devolver o controle. Defina instant_interrupt = true em [features] para testar. Ativado por padrão desde a v0.162.0.
• O visualizador de avisos dispensa os avisos que você já viu quando é fechado; pressione k para manter um deles para consultar depois.
• Você pode rolar a transcrição enquanto decide se deseja implementar um plano.
• A renderização de Mermaid aceita mais arestas, rótulos e grupos de nós em fluxogramas.
• Sessões em branco mantêm seus rascunhos quando você alterna entre tarefas, e as threads podem ser arquivadas antes do primeiro turno.
• /status é renderizado sem bordas e quebra valores longos em várias linhas.
• Clientes do app-server podem paginar o histórico de uma thread a partir de um item específico. Alterações no sandbox: comandos aprovados mantêm negações explícitas do sistema de arquivos, diretórios .aws em raízes graváveis são protegidos por padrão (regras explícitas ainda têm precedência), sandboxes do macOS com acesso à rede permitem a avaliação de confiança TLS e ambientes de execução que exigem um proxy agora recebem um. A skill plugin-creator incluída foi removida.

O que fazer: se uma tarefa em sandbox gravar em .aws, espere que ela seja bloqueada, a menos que você adicione uma regra explícita.¹⁷⁷

v0.158.0 (28 de setembro de 2026)

A versão estável da linha 0.158, criada a partir da 0.158.0-alpha.15.4: alpha.15 mais dezesseis backports, incluindo as quatro correções do Windows da v0.157.1. Ela está 207 commits à frente da v0.157.0.

Padrões que mudaram:

• A aprovação de entrada no terminal está ativada. Quando o Codex envia uma entrada para um comando em execução com permissões elevadas (concessões de permissão adicionais, bypass do sandbox ou uma política que mudou após o início do comando), a entrada precisa de aprovação primeiro. Concessões válidas apenas em runtime, como as usadas por plugins para métricas, não acionam mais uma revisão. Para desativar, defina write_stdin_approval = false em [features].
• Copy-on-select na transcrição em tela cheia: as seleções feitas com o mouse são copiadas quando você solta o botão. O padrão, auto, ignora terminais diretos que encaminham o próprio atalho de cópia (Ghostty 1.2+, Kitty no macOS, Windows Terminal e VS Code no Windows). As cópias preservam a formatação Markdown. Defina copy_on_select = "never" (ou "always") em [tui].
• Colar com o botão direito na TUI em tela cheia no Windows, WSL e Linux. Defina right_click_paste = "off" em [tui] ou "on" para incluir o macOS.
• O contexto da thread do Guardian está sempre ativado. A opção para desativá-lo da v0.157.0 foi removida: thread_context em [features.guardianv2] é ignorado, inclusive nos perfis, e o Codex exibe um aviso pedindo que você o remova.

Modelos e planos: o GPT-5.4 deixa os catálogos incluído e do Bedrock, e seleções salvas do GPT-5.4 ainda recebem a solicitação de migração para o GPT-6 Sol. O Codex reconhece o plano Pro Max e identifica os níveis Pro como “Pro”, “Pro (More)” e “Pro (Max)”. Os atalhos de raciocínio podem chegar a Max.

Outras novidades: servidores MCP que precisam de um segredo de cliente OAuth pré-registrado (codex mcp add --oauth-client-secret), tokens bearer para conexões WebSocket do exec-server, fundos transparentes para imagens geradas e prévias de comandos com várias linhas em /ps. As correções abrangem falhas do sandbox no Windows (caminhos comuns do Windows 10, credenciais armazenadas rejeitadas e políticas de permissão grandes), inicialização do sandbox no Linux com raízes graváveis aninhadas, proteção dos metadados do Git em todas as raízes graváveis, aliases de caminho do macOS nas aprovações de patches e revisões do Guardian que agora tentam novamente, em vez de serem interrompidas, quando você envia uma mensagem durante a revisão.

O que fazer: se uma automação enviar teclas para comandos com permissões elevadas, espere solicitações de aprovação ou desative o recurso e remova thread_context da sua configuração.¹⁷⁶

v0.157.1 (26 de setembro de 2026)

Um patch para Windows com quatro correções trazidas da branch principal por backport. O Codex não abre mais uma janela do console ao iniciar o host do code-mode ou um servidor MCP stdio local. O servidor em segundo plano consegue iniciar quando o Windows mantém o processo dentro de um job object externo, e um servidor em segundo plano desvinculado não mantém mais abertos os pipes de saída do inicializador, o que poderia deixar o comando chamador aguardando depois que o inicializador fosse encerrado. As notas da versão GitHub e a entrada do changelog dizem apenas que os destaques “não puderam ser determinados”; a lista acima vem dos commits da versão.

O que fazer: atualize se você executa o Codex no Windows. As quatro correções são exclusivas do Windows.¹⁷⁴

v0.157.0 (25 de setembro de 2026)

A versão que altera mais três padrões.

• A transcrição em tela cheia está ativada por padrão. A interface em tela cheia que a v0.156.0 oferecia por meio de /tui agora é a interface aberta pelas sessões, inclusive quando a configuração não tem uma seção [tui]. Para manter o histórico de rolagem do terminal, escolha Scrollback em /tui ou defina fullscreen_transcript = false em [tui]; --no-alt-screen e tui.alternate_screen = "never" ainda têm precedência. Agora, clicar com Shift pressionado estende uma seleção na transcrição.
• O servidor em segundo plano inicia automaticamente em execuções interativas compatíveis, e a opção deixa /experimental. Execuções com --no-daemon, --oss, --profile ou a maioria das substituições -c não o utilizam. Se as configurações de um servidor em execução não corresponderem às da sessão, o Codex oferece as opções de executar sem ele, reiniciá-lo com as configurações necessárias ou cancelar (o padrão). Para desativar a inicialização automática, defina daemon_auto_start = false em [features].
• O contexto da thread do Guardian está ativado por padrão para revisões síncronas e assíncronas, independentemente do seletor enabled do Guardian v2. Para desativá-lo, defina thread_context = false em [features.guardianv2].

Modelos: GPT-6 Sol e Luna, lançados inicialmente na v0.156.1, também estão nesta versão, e os catálogos do Amazon Bedrock agora os incluem, com o GPT-6 Sol substituindo o GPT-5.6 Sol como padrão do Bedrock. O GPT-5.6 Sol perde seu nível de serviço ultrafast, mantendo apenas Fast. O catálogo incluído não indica mais que o GPT-6-Astra oferece suporte ao gerenciamento experimental de contexto (consulte Gerenciamento de contexto).

Outras novidades: um atalho f cria um fork de uma conversa aberta em outro app, preservando rascunhos e prompts na fila; /import funciona em sessões remotas e do servidor em segundo plano; e o terminal renderiza marcadores Unicode, caixas de seleção e equações alinhadas. As correções mantêm as conversas por voz em execução quando você troca de thread, recuperam respostas não enviadas quando um turno termina, respeitam as configurações do mouse no tmux, encaminham conexões em tempo real e pesquisas independentes na web por proxies configurados, repetem uploads de arquivos após falhas temporárias com um timeout de cinco minutos e aplicam restrições de rede em redirecionamentos e conexões HTTP e WebSocket abertas. No Windows, o acesso a objetos do sandbox fica limitado à sessão de login do runner.¹⁷⁴

v0.156.1 (23 de setembro de 2026)

Um patch com uma única alteração que leva o GPT-6 Sol e o GPT-6 Luna para a versão estável CLI. Agora, ambos aparecem no seletor /model abaixo do GPT-6-Astra, que permanece em primeiro lugar e continua sendo o padrão incluído quando config.toml não define um modelo. O seletor passa a identificar a família GPT-5.6 como modelos antigos (o GPT-5.6 Sol aparece como “Modelo de programação antigo para trabalhos complexos”) e o GPT-5.5 como um “Modelo de programação legado”. Quando você se aproxima de um limite de uso, a solicitação de troca agora sugere gpt-6-luna em vez de gpt-5.6-luna.

Se a sua configuração especificar um modelo antigo, espere uma solicitação única de migração: seleções salvas de gpt-5.6-sol, gpt-5.6-terra, gpt-5.5 e gpt-5.4 apontam para o GPT-6 Sol, enquanto gpt-5.6-luna e gpt-5.4-mini apontam para o GPT-6 Luna. Os catálogos do Amazon Bedrock não mudam nesta versão: eles não incluem o GPT-6 Sol nem o Luna, e o GPT-5.6 Sol continua sendo o padrão do Bedrock.

Um detalhe de custo que a documentação não menciona: o catálogo incluído define Fast (priority) como o nível de serviço padrão do GPT-6 Sol e do Luna. Por isso, uma sessão da TUI sem service_tier definido pode iniciar no modo Fast, que, com login pelo ChatGPT, cobra 2,5 vezes mais créditos que o Standard. Verifique com /fast status; /fast off muda para Standard.

O que fazer: atualize e depois experimente codex -m gpt-6-sol em uma tarefa conhecida. A disponibilidade depende do seu plano, das configurações do workspace e da distribuição gradual; administradores Enterprise precisam habilitar os novos modelos primeiro.¹⁷¹

v0.156.0 (22 de setembro de 2026)

A versão que altera três padrões de uma só vez; o changelog da documentação anunciou os dois primeiros no mesmo dia.

• O recurso de voz está ativado por padrão. /voice inicia uma conversa ao vivo em builds compatíveis sem que você precise acessar /experimental. Também são novidades: um seletor configurável pela tecla F8, um seletor /voice settings para definir a voz usada em conversas futuras, runtimes de voz incluídos para Linux e Windows e suporte à redução de movimento.
• Os worktrees gerenciados estão ativados por padrão. --worktree e /worktree não precisam mais de uma feature flag. Sessões de worktree podem se conectar a um daemon local existente e ser criadas pela visão geral de agentes.
• A reutilização da compactação da thread principal pelo Guardian está ativada por padrão: quando o Guardian reinicia uma sessão de revisão, ele pode reutilizar a compactação criptografada da thread principal.

As instruções para desativar cada recurso estão nas linhas de /voice e /worktree da tabela de slash commands e na seção do Guardian.

Outras novidades: uma TUI em tela cheia opcional, selecionada com /tui, com pesquisa na transcrição, seleção e cópia com o mouse, cópia com o botão direito, links clicáveis e um visualizador de avisos; seis temas incluídos no seletor /theme; o painel de análise /usage; diagramas Mermaid e fórmulas TeX renderizados no terminal, cada um com seu próprio seletor; um menu /daemon e uma flag --no-daemon; e resumos de raciocínio desativados por padrão em novas threads da TUI. Correções de segurança eliminam falhas do sandbox no Windows relacionadas a tráfego de entrada, sockets privilegiados e identificadores de arquivos somente leitura, e codex doctor não exibe mais os valores de configuração nos erros. As correções de bugs preservam respostas transmitidas após turnos com falha ou interrompidos, corrigem o encaminhamento da área de transferência no tmux e no SSH, restauram o Plan mode ao retomar uma sessão e permitem que o login seja recuperado por meio de proxies do sistema.¹⁶⁹

v0.155.1 (18 de setembro de 2026)

Um hotfix com uma única correção. Na versão 0.155.0, uma nova thread local da TUI sem model_reasoning_summary na configuração solicitava resumos detailed, e provedores sem suporte a resumos de raciocínio rejeitavam a solicitação por completo. A versão 0.155.1 restaura none como valor padrão, portanto, quando a chave não está definida, nenhum resumo é solicitado. As configurações explícitas auto, concise e detailed sempre foram respeitadas e continuam sendo. A mesma alteração de uma linha também foi incorporada à branch principal e lançada na versão 0.156.0.

O que fazer: se novas sessões da TUI na versão 0.155.0 falharam com um provedor que não seja da OpenAI ou seja auto-hospedado, atualize. Se quiser resumos, defina a chave explicitamente (consulte a referência de configuração).¹⁵⁸

v0.155.0 (17 de setembro de 2026)

O recurso de voz chegou à TUI estável como uma funcionalidade experimental e opcional: /voice iniciava uma conversa ao vivo com transcrição em streaming e controles do microfone, habilitada por meio de /experimental nas builds compatíveis, com um atalho configurável para silenciar e recursos de voz assinados nos pacotes para macOS. A v0.156.0 ativou o recurso por padrão cinco dias depois. Os worktrees gerenciados continuaram desativados por padrão nesta versão.

Também na versão 0.155.0:

• Verificação de usuário do MCP: verificação por Touch ID das solicitações do MCP, assinada pelo Secure Enclave, em sessões locais da TUI em Macs compatíveis, com restrição de identidade por workspace e verificação nativa nas continuações de ferramentas do MCP.
• O slash command /sandbox-add-read-dir do Windows foi removido.
• Gerenciamento de worktrees: oculte, arquive e exclua sessões de worktree na visão geral dos agentes, consulte detalhes de propriedade e confirme antes de excluir um worktree gerenciado sem alterações.
• Resumos de raciocínio ao vivo são exibidos em streaming na linha de status da TUI, com horários de conclusão para trabalhos finalizados.
• Daemon: agendas de atualização configuráveis, um comando codex app-server daemon update e recuperação de threads após reinicializações do daemon.
• Comandos de credenciais da AWS para Amazon Bedrock e publicação de Python SDK alinhada às versões estáveis do CLI.

As correções de segurança eliminam escapes de interoperabilidade do WSL e a exposição de credenciais em snapshots do shell. O Memory v2 chega apenas como base para armazenamento e consolidação, não como um recurso utilizável.¹⁵⁶

v0.154.0 (9 de setembro de 2026)

Esta versão foi criada aproximadamente no ponto da 0.154.0-alpha.6, portanto, tudo o que apareceu pela primeira vez na alpha.7 (voz ao vivo na TUI, verificação de usuário do MCP, Memory v2, configuração de atualização automática do daemon e fixação do nível de esforço de raciocínio) ficou para a versão 0.155.

Removidos: codex mcp-server e o binário independente codex-mcp-server. Migre as integrações para o protocolo app-server ou para o plugin do Codex para Claude Code; codex mcp, que conecta o Codex a servidores MCP externos, não foi afetado (consulte Executando o Codex COMO um servidor MCP). Os fluxos legados de revisão de aprovações do Guardian também foram removidos, e agora as aprovações são rejeitadas quando novas instruções do usuário as invalidam.

Novidades:

• Worktrees gerenciados experimentais por meio de --worktree ou /worktree, com suporte no codex exec e um navegador de worktrees na TUI.
• Mensagens assíncronas do usuário: responda a perguntas em linha enquanto o Codex continua trabalhando, sem perder seu rascunho.
• Suporte a serviços do Windows: provisionamento do sandbox, daemon do app-server no Windows e atualizações gerenciadas do daemon.
• Perfis de permissão remotos, encontrados no app-server e selecionáveis por nome na TUI.
• Modo de substituição R do Vim, status de compactação de contexto ao vivo e gerenciamento de contexto experimental condicionado à capacidade do modelo na inicialização da sessão.

Segurança: os auxiliares de PATH não são mais executados antes de o workspace ser considerado confiável, e o sandbox do macOS foi reforçado contra injeção de entrada no terminal. As conexões do MCP coordenam as atualizações de token do OAuth, retomadas e forks remotos preservam as permissões salvas, e retomar uma conversa aberta em outro aplicativo exibe uma transcrição somente leitura. O recurso de voz foi lançado apenas como infraestrutura de runtime, e as primeiras referências ao Daybreak no código chegaram sem documentação pública.¹⁵²¹⁵³

v0.153.3 e v0.153.4 (4 de setembro de 2026)

Patches lançados no mesmo dia que levaram o GPT-6-Astra ao CLI. A v0.153.3 adicionou o Astra aos catálogos do Amazon Bedrock (o GPT-5.6 Sol continuou sendo o padrão do Bedrock) e corrigiu as orientações do Astra para esclarecimentos assíncronos. A v0.153.4 incluiu o Astra no seletor de modelos, tornou-o o padrão incluído quando nenhum modelo está configurado e condicionou as orientações sobre perguntas assíncronas à disponibilidade das ferramentas.

O que fazer: o Astra funciona com -m gpt-6-astra desde a v0.153.1 e aparece no seletor a partir da v0.153.4; como nenhuma versão mínima do CLI está documentada, considere essas versões como os requisitos mínimos. Se sua conta não tiver acesso ao modelo selecionado pelo padrão incluído, defina model explicitamente no config.toml em vez de depender do padrão.^145146147148

v0.153.1 e v0.153.2 (3 de setembro de 2026)

A v0.153.1 faz com que a pontuação de uso do computador do Guardian respeite os requisitos do modelo: a pontuação exclusiva para uso do computador e as decisões rápidas de aprovação são executadas somente quando os metadados do modelo ativo definem node_repl_auto_review_required. Além disso, uma troca para um modelo que ignore a pontuação invalida pontuações anteriores ou em andamento, impedindo que a troca de volta para o modelo anterior reative uma aprovação obsoleta. As notas da versão listam apenas uma entrada do GPT-6-Astra retroportada para o catálogo, configurável por meio do API; o seletor e o padrão só mudaram na v0.153.4. A v0.153.2 corrige a descrição do nível Fast do Astra de “1,5x” para “velocidade 2x, maior uso” (apenas no texto exibido).¹⁴²¹⁴³

v0.153.0 (3 de setembro de 2026)

• Desfazer e refazer no Vim: u e Ctrl+R restauram rascunhos completos do compositor, incluindo conteúdo colado e anexos de imagem; vim_normal.redo é uma ação configurável do mapa de teclas.
• Marketplaces remotos de plugins: o CLI de plugins pode listar, instalar e remover plugins remotos, e codex plugin list mostra origem, versão, política de instalação e política de autenticação.
• tui.auto_recap = false desativa as recapitulações automáticas; /recap manual continua funcionando.
• Avisos antecipados de limite de uso para Plus e Team quando resta menos da metade da cota em uma janela de aproximadamente cinco horas; os outros planos mantêm os limites de 75%, 90% e 95%.
• O escopo do Guardian acompanha o modo de aprovação: Full Access ignora as revisões do Guardian para ações que exigem apenas confirmação, e o modo de aprovação User ignora a pontuação e o pré-aquecimento em segundo plano.
• features.context_management.experimental_mode (desativado por padrão) habilita contexto baseado em orçamento de tokens, notas do histórico e a ferramenta new_context para sessões qualificadas dos planos Plus, Pro e Pro Lite no backend do Codex.
• tui.disable_paste_burst substitui a chave de nível superior, que ainda funciona como fallback.

Correções: as sessões da TUI se reconectam após uma interrupção do app-server sem perder os rascunhos, o histórico de revisões do Guardian persiste após compactações, reinicializações e forks, e as aprovações lembradas do MCP ficam restritas à conta selecionada.¹⁴⁰

v0.152.0 e v0.152.1 (1º de setembro de 2026)

update_plan passou a ser opcional: tools.update_plan.enabled usa false por padrão e, enquanto estiver desativado, as orientações incluídas sobre update_plan são removidas dos prompts do modelo, do modo de colaboração, de múltiplos agentes, de compactação, de pré-aquecimento e de continuação de objetivos (consulte Modo Plan e colaboração). Também são novidades: pesquisa no Vim com / e ?, além de n/N, combinável com operadores e com novos rascunhos iniciando no modo Insert; banners acionáveis de limite de uso; progresso da atualização de credenciais, incluindo a reautenticação no Amazon Bedrock; nomes de servidores MCP no estilo de pacotes (:, @, / e . são permitidos); solicitações de formulário openai/elicitation do MCP; um output_token_limit por ferramenta do MCP; credenciais de tarefas na nuvem restritas a origens confiáveis; tempos limite configuráveis para thread/shellCommand; e orçamento de tokens habilitado por padrão por meio dos metadados do modelo. A v0.152.1 permite que a revisão de aprovação do Guardian obtenha sua política de Node REPL dos metadados do modelo.¹³⁸¹³⁹

v0.151.0 (29 de agosto de 2026)

• /recap resume a conversa sob demanda, e o Codex recapitula automaticamente conversas qualificadas que estejam ociosas e fora de foco.
• Hosts no modo de código removem o transporte WebSocket (apenas stdio e gRPC).
• Threads duráveis passam a usar histórico paginado por padrão nos armazenamentos compatíveis.
• O esforço de raciocínio persistent chega com ferramentas de relógio e orientações de proatividade incluídas.
• O Guardian v2 passa a usar por padrão revisões de uso do computador com imagens.
• O Vim ganha os movimentos de busca f/F/t/T, além de gg/G.
• A entrada em terminais com privilégios elevados pode exigir uma nova aprovação (write_stdin_approval, desativado por padrão).
• Um período de tolerância configurável para servidores MCP opcionais (mcp_optional_startup_grace_ms, padrão de 1.000 ms), e as extensões podem inspecionar ou substituir os resultados das ferramentas do MCP.

As correções impedem que /cd enfraqueça as restrições do sandbox e que classificações obsoletas do Guardian autorizem ações após alterações de permissão. As notas da versão listam apenas os últimos PRs; o conjunto completo de alterações está na comparação.¹³⁴¹³⁵

v0.150.0 e v0.150.1 (26 e 27 de agosto de 2026)

Os hooks ganham um evento Interrupt, executado quando um turno ativo de nível superior é interrompido (timeout padrão de 1 segundo, limite de 3 segundos, nunca para subagentes). /copy abre um seletor para a resposta completa, blocos de código individuais ou citações em bloco. As tarefas passam a poder ser referenciadas com menções @, os agentes podem ler, criar e enviar mensagens para tarefas, e /rename sugere um título editável. Links em Markdown são renderizados como rótulos clicáveis, atalhos podem alternar entre modos de permissão, o Vim ganha a repetição com ., e projetos não confiáveis deixam de fornecer instruções de AGENTS.md no nível do projeto. features.network_proxy.credential_broker e review_scope.computer_use_only do Guardian v2 chegam como opções configuráveis, desativadas por padrão. A v0.150.1 contabiliza imagens mantidas no orçamento de tokens da compactação remota.¹³²¹³³

v0.149.0 e v0.149.1 (20 a 24 de agosto de 2026)

A política de aprovação untrusted foi descontinuada; migre as configurações que a utilizam para on-request. Novidades: um painel interativo codex agents, /cd, /pwd e /cwd, codex queue para enviar mensagens a sessões locais ou remotas existentes, mais movimentos de alteração do Vim, um codex doctor mais abrangente (proteção de endpoint, falhas de rede e proxy, estado do aplicativo para desktop e conectividade para atualizações) e níveis de raciocínio max/ultra nos SDKs. Threads retomadas e bifurcadas restauram seu perfil de permissões. A v0.149.1 adiciona codex exec --thread-source <SOURCE> (user, subagent, memory_consolidation ou o nome de um recurso; threadSource no TypeScript SDK).

Preços no mesmo período: a OpenAI reduziu em mais de 20% o preço do GPT-5.6 Sol durante três meses a partir de 21 de agosto (até pelo menos 21 de novembro de 2026), e a taxa de créditos do Codex para o Sol caiu de 125/12,5/750 para 100/10/500 créditos por 1 milhão de tokens de entrada, em cache e de saída.^120121126

v0.147.0 e v0.148.0 (7 a 18 de agosto de 2026)

A v0.147.0 remove codex exec --full-auto (obsoleto desde a v0.128); use --sandbox workspace-write com uma flag de aprovação ou um perfil. Ela também adiciona --approve-for-me, Agent Plugins portáteis com busca em catálogos, o protocolo MCP 2026-07-28 opcional e seções de conversa. A v0.148.0 adiciona /export para Markdown, codex exec fork, estimativas de créditos ou custo em /status, Amazon Bedrock Runtime como provedor integrado, hooks assíncronos e capazes de invocar MCP, além de restrições de sandbox que bloqueiam a operação quando os caminhos são negados ou estão ilegíveis.¹¹⁶¹¹⁸

Versões anteriores (maio a julho de 2026)

• v0.146.0 e v0.146.1 (29 de julho e 5 de agosto): proxies configurados abrangem todos os transportes; manifestos de Agent Plugins, além dos marketplaces do Amazon Bedrock e do Claude Code; nomenclatura de sessões com fixação de threads; skills fornecidas pelo executor; padrões de revisão automática reforçados para modelos com recursos cibernéticos.¹¹⁴¹¹⁵
• v0.145.0 (21 de julho): /import do Cursor e do Claude Code; a voz retorna como conversas V3 em tempo real via streaming; a experiência multiagente v2 opcional é estabilizada; histórico experimental paginado de threads e login no Amazon Bedrock; as seleções incluídas do GPT-5.4 migram para GPT-5.6 Terra e Luna. A v0.144.6 definiu as janelas de contexto do GPT-5.6 em 272.000 tokens.¹¹¹¹¹²
• v0.140.0 (15 de junho): /usage, codex delete e /delete, /import do Claude Code, o menu unificado de menções @, autenticação por chave API do Amazon Bedrock e armazenamento local criptografado para credenciais OAuth de CLI e MCP; os antigos controles de voz /realtime foram removidos.¹⁰²
• v0.139.0 (9 de junho): o modo de código pode chamar diretamente a busca na web, os esquemas de ferramentas mantêm oneOf/allOf, codex doctor informa detalhes do editor e do paginador, e as fontes de marketplace aparecem na saída de JSON.¹⁶⁵
• v0.138.0 (8 de junho): /app transfere uma sessão CLI para o aplicativo para desktop, e o texto das tarefas enviado do agente principal aos subagentes é criptografado no multiagente v2.¹⁶⁶¹⁰⁸
• v0.137.0 (4 de junho): multiagente v2, atalhos de teclado F13-F24 na TUI e uma extensão v1 de skills.¹⁶⁷
• v0.132.0 a v0.135.0 (20 a 28 de maio): busca no histórico local de conversas, --profile como o seletor principal de perfil, objetivos ativados por padrão, herança de perfis de permissão e requirements.toml gerenciado, início e encerramento com codex remote-control, codex doctor e /status mais detalhados, objetos de texto do Vim, perfis de permissão nomeados em /permissions, autenticação SDK do Python e predefinições de Sandbox, além de codex exec resume --output-schema. A atualização do aplicativo de 21 de maio adicionou Appshots, disponibilidade geral do modo Goal e Computer Use bloqueado e opcional.^{96979899100101191}

O antigo --full-auto foi removido na v0.147.0, e js_repl continua removido.^86878991116

Nota sobre estabilidade: Superfícies estáveis e documentadas: o CLI principal e a TUI, sandboxing e políticas de aprovação, config.toml, AGENTS.md, skills, hooks, plugins, ferramentas multiagente, objetivos, perfis de permissão, /voice e worktrees gerenciadas (padrão desde a v0.156.0), a transcrição em tela cheia e a inicialização automática do servidor em segundo plano (padrão desde a v0.157.0), aprovação de entrada do terminal, cópia ao selecionar e colagem com o botão direito (padrão desde a v0.158.0), além da interrupção instantânea (padrão desde a v0.162.0, ainda marcada como em desenvolvimento). Browser, Computer Use e Appshots são superfícies documentadas voltadas ao usuário cuja disponibilidade depende da plataforma e do plano. Experimentais ou em desenvolvimento: Codex Cloud, modo de código e busca de ferramentas no modo de código, Memory v2, o quadro local de mensagens dos agentes, Daybreak (cli_daybreak, v0.161.0), as flags de histórico e contexto de transferência do Guardian (v0.160.0) e tudo que estiver marcado como [EXPERIMENTAL] neste guia ou listado em /experimental; esses recursos podem mudar entre versões. Segundo a referência de configuração, o gerenciamento experimental de contexto “não está disponível no momento”. Removidos: --full-auto (v0.147.0), a política de aprovação untrusted (v0.149.0), codex mcp-server (v0.154.0), a opção de desativar thread_context do Guardian (v0.158.0) e js_repl.

Canal alpha: builds alpha são lançadas várias vezes ao dia, as descrições das versões nas linhas alpha são provisórias, e builds lançadas fora do ciclo e derivadas de bases mais antigas aparecem regularmente. Em pelo menos duas ocasiões, a tag alpha do npm apontou para uma delas, então @alpha instalou uma build mais antiga que latest. A linha 0.158 foi da 0.158.0-alpha.2 (23 de setembro) até a alpha.15 (25 de setembro); sua versão estável, v0.158.0 (28 de setembro), foi derivada da build fora do ciclo 0.158.0-alpha.15.4, composta pela alpha.15 mais dezesseis backports, e permaneceu como latest no npm até a publicação da v0.159.0, 27 horas depois. A linha 0.159 foi da alpha.1 (25 de setembro) até a alpha.13 (28 de setembro) e foi lançada como v0.159.0 a partir da alpha.13. A linha 0.160 chegou à 0.160.0-alpha.6 (29 de setembro) e parou nela; a 0.161.0-alpha.1 é a alpha.6 com apenas o número da versão alterado. Em 30 de setembro, a 0.160.0-alpha.6.1 adicionou à alpha.6 a única correção do console do Windows da v0.159.2 que faltava. No mesmo dia, a linha 0.159 recebeu mais um patch, a v0.159.3. A linha 0.160 então ganhou uma versão estável, a v0.160.0 (1º de outubro), derivada da alpha.6.1 mais um backport, seguida pela v0.160.1 (5 de outubro). A linha 0.161 produziu versões alpha e backports fora do ciclo, sendo a mais recente a 0.161.0-alpha.13.1 (6 de outubro), mas nenhuma versão estável; ela não é considerada pulada porque nenhuma versão superior foi lançada como estável. alpha agora aponta para a 0.162.0-alpha.16. Se você acompanha versões alpha, verifique npm view @openai/codex dist-tags e instale uma versão exata em vez de @alpha.^176179181185 Um histórico datado de como as linhas alpha recentes resultaram em versões estáveis está em ¹⁷³. A linha 0.161 foi lançada como v0.161.0 em 7 de outubro a partir da 0.161.0-alpha.13.1 (com um commit de lançamento sobre ela); a v0.162.0 veio em seguida, em 8 de outubro, a partir da 0.162.0-alpha.18.1, enquanto a 0.162.0-alpha.20 estava 52 commits à frente dessa versão estável; a v0.162.1 adicionou três commits em 9 de outubro; alpha estava na 0.163.0-alpha.5 em 10 de outubro e está na 0.163.0-alpha.9 desde 13 de outubro, com a alpha.8 e a alpha.9 publicadas nesse mesmo dia.¹⁸⁹¹⁹⁰

Como o Codex funciona: o modelo mental

Antes de conhecer os recursos em detalhes, entenda como a arquitetura do Codex influencia tudo o que você faz com ele. O sistema opera em cinco interfaces sustentadas por uma camada de inteligência compartilhada:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  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 (on-request → 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 é a base de tudo. Em 29 de setembro de 2026, a geração atual é a GPT-6: gpt-6.1-sol para programação complexa e trabalho agêntico (o padrão integrado do CLI quando nenhum modelo está configurado, desde a v0.159.1), gpt-6-astra para os trabalhos completos mais difíceis, gpt-6-luna para tarefas específicas e em grande volume e o modelo da geração anterior gpt-6-sol. Os modelos GPT-5.6 (Sol, Terra, Luna) continuam disponíveis durante o lançamento gradual; o gpt-5.5 (contexto de 400K no Codex e 1M no API) deixará de estar disponível no Codex para login com o ChatGPT em 14 de outubro de 2026, e o gpt-5.4 deixou de estar disponível no Codex em 31 de agosto de 2026.^{83117146148149171178} Essa camada lê arquivos, escreve patches, executa comandos do 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: Todos os comandos executados pelo Codex passam por um sandbox no nível do sistema operacional. No macOS, o framework Seatbelt da Apple impõe 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 contêineres. Em seguida, a política de aprovação determina quando solicitar confirmação humana.

Camada de extensões: O MCP conecta serviços externos (GitHub, Figma, Sentry). As skills agrupam fluxos de trabalho reutilizáveis que o Codex carrega sob demanda. Os Apps se conectam aos conectores do ChatGPT. A pesquisa na web adiciona contexto em tempo real da internet.

Camada de interfaces: CLI para usuários avançados do terminal e automação. Aplicativo desktop para gerenciamento de projetos com várias threads. Extensão de IDE para ciclos de edição, compilação e teste. Cloud para tarefas assíncronas executadas de forma independente.

O principal insight: A maioria dos usuários utiliza apenas uma interface. 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 rápidos de programação, aplicativo desktop para planejamento e coordenação e extensão do navegador para fluxos de trabalho no navegador com login ativo.

Sumário

1. Como instalar o Codex?
2. Início rápido: sua primeira sessão
3. Principais interfaces de interação
4. Análise detalhada do sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Codex?
7. Estruturas para tomada de decisões
8. Como funciona o sistema de sandbox e aprovação?
9. Como funciona o AGENTS.md?
10. Hooks
11. O que é MCP (Model Context Protocol)?
12. Code Mode
13. Runtime REPL do JavaScript
14. O que são skills?
15. Plugins
16. Plan Mode 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 aplicativo Codex Desktop
22. GitHub Action e CI/CD
23. Codex SDK
24. Otimização de desempenho
25. Como diagnosticar problemas? – incluindo codex doctor
26. Implantação empresarial
27. Boas práticas e antipadrões
28. Receitas de fluxos de trabalho
29. Guia de migração
30. Cartão de referência rápida
31. Histórico de alterações
32. Referências

Como instalar o Codex?

Gerenciadores de pacotes

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

Como atualizar, fazer downgrade ou desinstalar o Codex CLI?

Desde a v0.128.0, o Codex inclui um comando de atualização automática; todas as outras operações são realizadas pelo gerenciador de pacotes usado na instalação.⁸⁶ Desde a v0.146.0, os artefatos de versões, os metadados de canais e os aliases do instalador são fornecidos pela infraestrutura de releases hospedada pela OpenAI, com o GitHub como fallback.¹¹⁴ Se a lista de permissões da sua rede inclui o GitHub para instalações e atualizações do Codex, adicione também o host de releases da OpenAI — graças ao fallback, a ausência desse host na lista de permissões causa uma degradação silenciosa, em vez de uma falha explícita.

# Check what you are running
codex --version                          # -> codex-cli 0.162.1
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 decisão certa quando uma release causa problemas. O Codex segue uma linha estável com atualizações frequentes, então instalar uma versão exata é a maneira mais rápida de fazer rollback — registre o problema, 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 identifica exatamente esse problema em Environment).

Desinstalar o pacote não remove seu estado. Autenticação, configurações e histórico de sessões ficam em ~/.codex/. Mantenha essa pasta para preservar logins e o histórico após uma reinstalação; exclua-a apenas se quiser realmente começar do zero — rm -rf ~/.codex também remove 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 artefato de release do GitHub:⁶⁰

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

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

Downloads de binários

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

Requisitos do sistema

• macOS: Apple Silicon ou Intel (suporte completo a sandbox via Seatbelt)
• Linux: x86_64 ou arm64 (sandbox via Landlock + seccomp)
• Windows: Sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é 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

Há duas formas de autenticação:

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

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

Login no Amazon Bedrock (v0.145.0, experimental): equipes cujo acesso a modelos ocorre por meio do Amazon Bedrock contam com uma opção experimental de login compatível com endpoint e autenticação personalizados, além da autenticação gerenciada por chave do API já existente (v0.140.0+) e da cadeia de credenciais da AWS (consulte Provedores de modelos personalizados). GPT-5.6 Sol é o modelo padrão do Bedrock.¹¹² A v0.150.0 corrige a compactação de conversas e a compatibilidade com múltiplos agentes nos modelos do Amazon Bedrock.¹³² A v0.151.0 adiciona uma opção do Amazon Bedrock, controlada por feature flag, aos fluxos de login elegíveis da TUI: a integração inicial detecta perfis da AWS e credenciais de ambiente existentes, oferece configuração manual para perfis, chaves de acesso, variáveis de ambiente e chaves do API para o Bedrock, solicita a região da AWS, oculta os segredos durante a digitação e reinicia o servidor integrado quando o provedor é alterado.¹³⁵ A v0.152.0 exibe o progresso da atualização de credenciais: a TUI e o codex exec mostram o progresso enquanto um provedor de modelos atualiza credenciais expiradas, incluindo a reautenticação de sessões do Amazon Bedrock, com as notificações estáveis modelProvider/authRecoveryStarted e modelProvider/authRecoveryCompleted do app-server, que incluem a thread, o turno, o provedor e uma mensagem para o usuário.¹³⁸

Preenchimento automático no shell

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

Verificar a instalação

codex --version
# codex-cli 0.162.1

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

Comece do zero e seja produtivo em 5 minutos.

1. Instale e faça a autenticação:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Acesse 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 principais arquivos e explica a base de código. Uma pergunta como essa não faz nenhuma alteração — o Codex só modifica arquivos quando você solicita uma mudança, e a sandbox e a política de aprovação determinam quando ele precisa pedir sua autorização primeiro.

5. Faça uma alteração:

> Add input validation to the login endpoint

O Codex propõe as edições em formato de 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 depois aprove para iniciar a execução.

7. Confira o trabalho:

> /diff

Veja todas as alterações feitas pelo Codex na sessão atual.

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

Principais interfaces de interação

O Codex oferece cinco interfaces distintas, todas com a mesma inteligência. Cada interface é otimizada para um padrão de fluxo de trabalho diferente.

1. CLI interativa (interface de terminal)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-6-sol          # 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 @ e execute comandos de shell com o prefixo !
• Painel de saída: Respostas do modelo transmitidas em tempo real, chamadas de ferramentas e saída de comandos
• Barra de status: Modelo, uso de tokens, branch do git e modo de sandbox

Principais atalhos da TUI:

Mudança na linha de status (v0.121.0): O antigo medidor da janela de contexto na linha de status foi substituído por um indicador percentual de contexto, que mostra quanto da sua janela de contexto está preenchido. Se você tem 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 da CLI quando houver uma nova versão disponível.

Slash commands disponíveis na TUI:

Novo design do seletor de fluxo de trabalho (v0.129.0): Retomar e criar forks agora estão mais acessíveis em um seletor reformulado, e um novo modo de histórico de rolagem bruto permite percorrer a transcrição não renderizada quando você precisa copiar comandos ou a saída do modelo literalmente. É útil ao analisar uma longa sessão de depuração ou encaminhar a saída para outra ferramenta.⁸⁹

Menu unificado de menções com @ (v0.140.0): Digitar @ no compositor agora abre por padrão um único menu de menções que reúne arquivos, plugins e skills, substituindo o fluxo de anexação exclusivo para arquivos — basta 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 a CLI não oferece:

• Multitarefa: Execute vários agentes em paralelo e simultaneamente em projetos diferentes
• Isolamento com worktrees do Git: Cada thread trabalha em uma cópia isolada do seu repositório
• Revisão de diff integrada: Adicione ao stage, reverta e faça commit de alterações sem sair do aplicativo
• Terminal integrado: Um terminal por thread para executar comandos
• Forks de conversas: Crie ramificações das conversas para explorar alternativas
• Janelas flutuantes destacáveis: Destaque conversas em janelas portáteis
• Automações: Agende tarefas recorrentes (triagem de issues, monitoramento de CI, resposta a alertas)
• Appshots: Anexe a janela do aplicativo em primeiro plano no Mac a uma thread, com uma captura de tela e o texto disponível
• Comentários no navegador integrado: Pré-visualize páginas locais ou públicas, deixe comentários em elementos ou áreas e permita que o Codex responda a um feedback visual preciso
• Computer Use: Permita que o Codex opere aplicativos autorizados do Mac em trabalhos de GUI com escopo definido; o uso bloqueado é opcional para turnos qualificados de Computer Use em Macs remotos

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 entre Chat, Work e Codex sem digitar. No macOS, ativar Screen context compartilha um appshot da janela em primeiro plano com a conversa, permitindo que você pergunte sobre o que está vendo em vez de precisar descrevê-lo. Disponível nos planos Plus, Pro, Business, Edu e Enterprise, no aplicativo para desktop e por meio do Remote no iOS. Este é o recurso de voz da interface para desktop. A CLI tem recursos de voz próprios e separados: conversas ao vivo com /voice na TUI (ativadas por padrão desde a v0.156.0) e ditado pela barra de espaço (adicionado experimentalmente na v0.105.0).¹¹³¹⁶⁹

Snapshots compartilhados de threads (20 de agosto de 2026): Em todos os planos do Codex, o aplicativo para desktop do macOS pode compartilhar um snapshot somente leitura de uma thread local do Codex. O snapshot não é atualizado quando a thread original muda; links de contas pessoais podem ser abertos por qualquer pessoa que tenha o link, enquanto links de contas de workspace só podem ser abertos por membros do workspace de origem. O Codex oculta padrões de segredos conhecidos antes do compartilhamento, mas a OpenAI recomenda revisar o conteúdo compartilhado porque ainda pode haver informações confidenciais. Visualize ou revogue links nos controles de dados do ChatGPT, em Shared links.¹²⁸

Quando usar o aplicativo ou a CLI: Use o aplicativo para desktop quando estiver coordenando vários fluxos de trabalho ou precisar revisar diffs visualmente. Use a CLI quando quiser composição com outras ferramentas do terminal, criação de scripts ou integração com CI/CD.

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

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

• Modo de agente por padrão: Lê arquivos, faz edições e executa comandos
• Edições integradas: Sugestões sensíveis ao contexto nos arquivos ativos
• Sessões compartilhadas: As sessões são sincronizadas entre a CLI e a extensão para IDE
• Mesma autenticação: Faça login com uma conta do 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 siga em frente: Coloque na fila tarefas que são executadas independentemente da sua máquina local
• Execução paralela: Execute várias tarefas na nuvem simultaneamente
• Criação de PRs: O Codex cria pull requests a partir do trabalho concluído
• Aplicação local: Traga os resultados da nuvem para seu repositório local com codex apply <TASK_ID>

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

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

5. Extensão para navegador (Chrome, Edge, Brave, Opera, Vivaldi)

O Codex está disponível como uma extensão para Google Chrome, Microsoft Edge, Brave, Opera e Vivaldi, adicionando uma quinta interface à CLI, ao aplicativo para desktop, à extensão para IDE e à nuvem. A extensão foi lançada para o Chrome em maio de 2026; o changelog de 25 de agosto de 2026 adicionou os outros quatro navegadores, com configuração em Settings > Computer Use no aplicativo do ChatGPT para desktop. Os cinco oferecem suporte a menções de abas e controle do navegador; o Opera não oferece suporte a chats laterais, portanto inicie as tarefas dele pelo aplicativo para desktop. A extensão foi projetada para acompanhar sua navegação normal, não para assumir o controle dela: o Codex trabalha em paralelo nas abas em segundo plano, enquanto você mantém o controle sobre quais sites ele pode acessar.⁹⁰¹²⁷

• Execução paralela em abas: O Codex opera em várias abas ao mesmo tempo sem bloquear a aba em primeiro plano.
• Controle por site: Você define uma lista de sites com os quais o Codex pode interagir; por padrão, nenhum acesso é permitido.
• O navegador como bancada de trabalho: A extensão é mais indicada para trabalhos com aplicativos e sites nos quais a página é a fonte da verdade — consoles administrativos, painéis internos, interfaces de gerenciamento de conteúdo e sistemas de tickets — e não substitui a CLI em repositórios locais.
• Mesma inteligência: a extensão para navegador usa a mesma inteligência GPT-5.x-Codex das outras interfaces, portanto uma configuração de AGENTS.md ou skills que funciona na CLI mantém as mesmas convenções em trabalhos realizados pelo navegador.

Instale pela documentação da extensão para navegador, a página anteriormente intitulada Codex for Chrome.¹²⁷

Análise detalhada do sistema de configuração

O Codex usa TOML para configuração. Entender a hierarquia de precedência é fundamental, pois ela determina quais configurações prevalecem em caso de conflito.

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

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

requirements.toml funciona 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.

Locais dos arquivos de configuração

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

Projetos com várias pastas no desktop (26.715, 23 de julho de 2026): um projeto local no aplicativo ChatGPT para desktop agora pode abranger várias pastas relacionadas, com uma delas designada como a 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 fornecem nenhuma configuração. Um .codex/config.toml localizado em uma pasta secundária é um arquivo que o Codex pode ler, não uma configuração que ele carrega. Esse é o escopo de projetos do aplicativo para desktop, não uma alteração nas regras de precedência acima — o CLI ainda resolve a configuração do projeto percorrendo os diretórios acima a partir do diretório de trabalho atual.¹¹³

Referência completa de configuração

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
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-6-sol"             # 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"          # on-request|never (untrusted retired in v0.149.0)

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

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── 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 (global; per-tool MCP overrides in v0.152.0)
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"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

# ─── 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)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (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             # Browser-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-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

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

# ─── Guardian Auto-Review (v0.160.0 history keys) ─────
[auto_review]
conversation_history_max_output_tokens = 4000   # Per history-tool response, estimated tokens (default 4,000)
experimental_conversation_history_prompt = ""   # Blank = built-in retrieval instructions

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

features.network_proxy é boolean | table. A forma booleana apenas inicia ou interrompe o proxy; a forma de tabela contém a política. O proxy é responsável por aplicar as regras de domínio do perfil de permissões aos comandos executados no sandbox: quando ele está desativado, as regras de domínio de [permissions.<name>.network] não são aplicadas, e o acesso dos comandos à rede é direto. Ele não filtra pesquisas na web, aplicativos, servidores MCP nem outras ferramentas hospedadas.¹³⁰

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

Os requisitos experimental_network gerenciados pelo administrador em requirements.toml podem iniciar o proxy sem features.network_proxy.¹³⁰

Perfis

Predefinições de configuração nomeadas para diferentes modos de trabalho. Desde o Codex 0.134.0, cada perfil tem seu próprio arquivo — ~/.codex/<name>.config.toml, contendo apenas chaves de nível superior — e --profile <name> sobrepõe esse arquivo a ~/.codex/config.toml. As antigas tabelas [profiles.<name>] dentro de config.toml e o seletor de nível superior profile = "<name>" não são mais lidos; uma tabela [profiles.<name>] remanescente faz com que --profile <name> se recuse a iniciar até que você mova suas chaves para o arquivo do perfil.¹²²

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-6.1-sol"
# GPT-6.1 Sol starts at Standard speed; /fast toggles Fast (2.5x credits)
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Um arquivo de perfil é uma camada acima da configuração base do usuário e abaixo das configurações do projeto e do CLI, por isso ele precisa conter apenas os valores que diferem da sua configuração base.¹²²

Ative um perfil:

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

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

Provedores de modelos personalizados

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

env_key especifica o nome da variável de ambiente que contém a chave API do provedor; a chave em si nunca é incluída em config.toml. Um provedor com requires_openai_auth = true exibe a tela de login na primeira execução e armazena as credenciais no backend escolhido por cli_auth_credentials_store (file, keyring ou auto), não necessariamente em auth.json. Desde a v0.160.0, um provedor que define model_catalog_url recebe apenas os modelos presentes nesse catálogo, sem mesclar os modelos integrados, e uma falha ao atualizar o catálogo descarta as entradas em cache em vez de reutilizar versões desatualizadas.¹⁸² Desde a v0.162.0, um provedor personalizado compatível com Responses também pode declarar os recursos aos quais oferece suporte em [model_providers.<name>.capabilities]: external_web_access = false impede que a pesquisa hospedada na web acesse a internet ao vivo para esse provedor, e remote_compaction = "v2" faz com que ele adote o protocolo compaction_trigger do Responses, que, caso contrário, só é usado por provedores OpenAI e Azure Responses ("unsupported" mantém a compactação local).¹⁸⁷

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 (setembro de 2026)

GPT-5.5 (23 de abril de 2026) era a escolha recomendada pela OpenAI para a maioria das tarefas do Codex no lançamento: programação complexa, uso do computador, trabalho intelectual e fluxos de pesquisa. Disponível no Codex CLI / web / desktop em 23 de abril para ChatGPT Plus / Pro / Business / Enterprise / Edu / Go; na API da OpenAI em 24 de abril. Janela de contexto: 400K no Codex, 1M na API — o Codex limita a janela a 400K para equilibrar capacidade de processamento e custo entre os níveis de assinatura; a API disponibiliza o total de 1M. Preços (API): US$ 5 de entrada / US$ 30 de saída por MTok (2× a tarifa do GPT-5.4; a OpenAI declara um aumento efetivo de cerca de 20% após melhorias na eficiência de tokens). Benchmarks: 82,7% no Terminal-Bench 2.0 (atual estado da arte entre os modelos disponíveis publicamente), 84,9% no GDPval (44 profissões), 78,7% no OSWorld-Verified, 98,0% no Tau2-bench Telecom (sem ajuste de prompt). A OpenAI usou o GPT-5.5 + Codex internamente para reescrever a infraestrutura de serviço antes do lançamento — isso gerou um aumento de 20% na velocidade de geração de tokens.⁸³

O GPT-5.5 será desativado no Codex com login pelo ChatGPT em 14 de outubro de 2026 – a documentação de modelos limita a desativação ao ChatGPT, ChatGPT Work e Codex em todos os planos (incluindo consumidor, Business, Enterprise e Edu) e afirma que ela não se aplica à API da OpenAI.¹⁵⁵ A orientação de substituição mudou com o lançamento do GPT-6: nos planos Plus, Pro, Business, Enterprise e Edu, escolha gpt-6-sol; nos planos Free e Go, escolha gpt-6-luna no aplicativo para desktop, ambos “quando disponíveis”. Substitua gpt-5.5 nos padrões do espaço de trabalho, nas configurações de modelo salvas, nas configurações gerenciadas, nos agentes personalizados, nas tarefas agendadas e nos scripts.¹⁷¹

O GPT-5.4 e o GPT-5.4 mini foram desativados no Codex com login pelo ChatGPT em 31 de agosto de 2026.¹¹⁷ A documentação de modelos agora indica gpt-6-sol e gpt-6-luna como substitutos (no Enterprise e no Edu, um administrador precisa habilitar o Luna primeiro); o uso com uma chave da API não é afetado.⁶⁴¹⁷¹ A lista exata de modelos varia conforme a conta e a etapa de 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. As conversas existentes continuam automaticamente no GPT-5.3 Instant, GPT-5.4 Thinking ou GPT-5.4 Pro. O GPT-5.1-Codex-Mini 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): o GPT-5.5 Instant foi disponibilizado no nível gratuito do ChatGPT em 5 de maio de 2026. Isso amplia o público da família GPT-5.5 para além dos planos pagos, embora o acesso ao Codex CLI continue exigindo uma assinatura Plus / Pro / Business / Enterprise / Edu / Go elegível ou uma chave da API.⁹²

GPT-5.4 mini (17 de março de 2026): uma variante menor e mais rápida do GPT-5.4, com contexto de 400K por 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 executam subtarefas mais específicas (pesquisa na base de código, revisão de arquivos e processamento de documentos) em paralelo.⁷⁶

GPT-5.6 no Bedrock (Sol, Terra, Luna) (v0.143.0, 8 de julho de 2026): o Codex adicionou suporte nativo a 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 aos modelos ocorre por meio de 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 raciocínio e aos trabalhos agênticos mais difíceis.¹⁰⁶ A 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.¹¹¹ A 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.¹¹²

GPT-6-Astra (lançado em 3 de setembro de 2026; no Codex pelas versões v0.153.1-v0.153.4): esta é a cronologia, com datas explícitas: a v0.153.1 preparou uma entrada de catálogo exclusiva da API em 3 de setembro de 2026; a OpenAI anunciou o GPT-6-Astra no mesmo dia; e a v0.153.4 adicionou a entrada ao seletor e tornou o modelo o padrão incluído do CLI em 4 de setembro. O anúncio descreve uma implementação gradual que começa com um conjunto limitado de organizações (primeiro os parceiros do programa de segurança cibernética) e se estende ao ChatGPT Plus, Pro, Business e Enterprise “nos próximos dias”, além da API da OpenAI e da AWS – as informações sobre a implementação foram divulgadas pela imprensa (CNBC, Axios, Forbes, Al Jazeera, 9to5Mac).¹⁴⁵ Superado em 4 de setembro: a OpenAI anunciou no X que o GPT-6 Astra “agora está disponível para todos os usuários Pro, Enterprise e Business Premium no ChatGPT Work e no Codex” e “ativo na API”, com previsão de disponibilidade para Plus e Business em alguns dias, e Tibo Sottiaux, líder do Codex, acrescentou na mesma noite: “O Astra agora também foi disponibilizado para todos os usuários Plus e Business.” Na prática, o acesso continua desigual – relatos da comunidade em 5 de setembro mostram contas Plus que ainda só viam modelos GPT-5.6 no Codex – e a linha sobre disponibilidade na documentação de modelos citada abaixo não mudou, por isso ela continua sendo a declaração oficial vigente.¹⁴⁹ A documentação oficial está disponível: a página do modelo na API lista o gpt-6-astra como o modelo principal, “Nosso modelo mais capaz, criado para os trabalhos completos mais difíceis” – US$ 10/MTok de entrada, US$ 50/MTok de saída nas tarifas padrão de contexto curto, uma janela de contexto de 1,05M tokens com entrada máxima de 922.000 tokens, saída máxima de 128K e corte de conhecimento em 30 de abril de 2026 – com um nível de contexto longo documentado: prompts acima de 272K tokens de entrada custam 2x na entrada e 1,5x na saída para a solicitação inteira, US$ 20/MTok de entrada e US$ 75/MTok de saída na página de preços – acima do GPT-5.6 Terra (equilibrado) e do Luna (econômico), e a documentação do Codex classifica o Astra como o modelo recomendado do Codex, com disponibilidade que “depende da implementação gradual, do seu método de login e do seu cliente” e elegibilidade indicada para contas Pro, Business (US$ 100) e Enterprise. Os níveis de raciocínio documentados do Astra no Codex são: Low, Medium, High, Extra High, Max, Ultra – a página de modelos da documentação marca Medium como padrão, enquanto o catálogo incluído da v0.153.4 define default_reasoning_level como low; portanto, considere que o padrão efetivo depende da interface e verifique /status em uma sessão. Os níveis permanecem iguais no novo acesso de 15 de setembro, agora com descrições por nível no seletor (Ultra, literalmente: “Raciocínio máximo com delegação automática de tarefas”), e os níveis Max e Ultra incluem confirmação do SDK – a versão 0.154.0 do SDK do Python (10 de setembro de 2026) adiciona os valores de esforço de raciocínio max e ultra (#39662).^146148153 No CLI, o Astra pode ser configurado pela API desde a v0.153.1 (-m gpt-6-astra), passa a integrar os catálogos do Amazon Bedrock na v0.153.3 (o GPT-5.6 Sol permaneceu como padrão do Bedrock até a v0.157.0 torná-lo GPT-6 Sol¹⁷⁴) e aparece no seletor de modelos e como padrão incluído quando nenhum modelo está explicitamente configurado desde a v0.153.4 – nenhuma versão mínima do CLI está documentada, portanto considere essas versões como os limites mínimos efetivos. Essa mudança de padrão é um fato do catálogo incluído do CLI, não de todas as interfaces – embora a lacuna na nuvem tenha sido fechada desde então: os acessos de 4 e 7 de setembro marcavam o Astra como indisponível para o Codex cloud (e o GPT-5.6 Sol como disponível), enquanto o novo acesso de 15 de setembro mostra a matriz de disponibilidade marcando o Astra também como disponível para o Codex cloud; a página ainda observa: “Atualmente, você não pode alterar o modelo padrão dos chats do Codex cloud.” Ressalva sobre a implementação: a elegibilidade varia conforme a conta e, no CLI 0.153.4+, uma conta fora da implementação gradual tem um padrão incluído que ainda não pode usar – fixe um modelo em config.toml (ou passe -m) para ter uma seleção determinística; desde a v0.156.1, o próprio exemplo da documentação é model = "gpt-6-sol". A cobrança do modo Fast do Astra está documentada, embora a página de modelos não liste um nível Fast: a documentação de velocidade do Codex o define como 2,5x os créditos Standard ao usar o login com ChatGPT (“quando disponível”), e a página de preços da API apresenta tarifas do modo Fast de exatamente 2x as tarifas Standard aplicáveis (US$ 20/US$ 100 por MTok em contexto curto, US$ 40/US$ 150 em contexto longo). A parte “velocidade 2x” do texto do catálogo da v0.153.2 continua sendo apenas texto de exibição do catálogo – a página de velocidade não informa nenhum multiplicador de velocidade para o Astra.^145146147148 Parcialmente superado em 23 de setembro de 2026: a documentação de modelos não descreve mais o Astra como o modelo recomendado do Codex. A seção “Modelos recomendados” agora prioriza o GPT-6 Sol e o Luna, reserva o Astra para “os trabalhos completos mais difíceis”, marca o Astra como indisponível para o Codex cloud e define Light (low) como esforço inicial do Astra, o que corresponde ao catálogo incluído. O Astra continua sendo o padrão incluído do CLI quando nenhum modelo está configurado.¹⁷¹ Superado em 29 de setembro de 2026: a v0.159.1 torna o GPT-6.1 Sol o padrão incluído e move o Astra para a segunda posição no seletor, enquanto a documentação de modelos passa a recomendar o GPT-6.1 Sol para programação complexa e mantém o Astra para os trabalhos completos mais difíceis; os exemplos de configuração da documentação agora usam gpt-6.1-sol.¹⁷⁸

Predefinições Power no Astra (adição à documentação, em 6 de setembro de 2026 ou antes): a passagem sobre o seletor de modelos na documentação de modelos do Codex agora associa as opções Power do seletor aos níveis de raciocínio do GPT-6-Astra – a primeira associação documentada das predefinições Power ao Astra – em um parágrafo ausente no novo acesso de 5 de setembro em ¹⁴⁶ e confirmado como publicado em 7 de setembro. Literalmente: “Para contas Pro, Business (US$ 100) e Enterprise elegíveis, a implementação gradual do Astra atualiza as opções Power para Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium e Astra Extra High. As opções podem variar conforme o plano e a etapa da implementação.” A frase anterior na documentação observa que as ilustrações do seletor ainda mostram os controles do GPT-5.6. Considere isso em conjunto com a tabela de modelos acima: “Power” significava GPT-5.6 Sol com raciocínio medium; em uma conta elegível, a mesma escala de predefinições agora abrange Terra, Sol e Astra em níveis fixos de raciocínio, e as opções continuam dependendo do plano e da etapa de implementação. O parágrafo permanecia literalmente inalterado no novo acesso de 15 de setembro de 2026.¹⁴⁶ Atualizado em 23 de setembro de 2026: após o lançamento do GPT-6 Sol e Luna, a documentação lista as seis predefinições Power como “Luna High, Sol Light (a predefinição inicial), Sol Medium, Astra Light, Astra Medium e Astra Extra High”, observa que alguns planos pagos não incluem Astra Extra High e sugere começar em Medium para Sol, High para Luna e Light (low) para Astra.¹⁷¹

Notas experimentais entre contextos (Astra, publicadas na documentação, por adesão): a página de documentação dos modelos do Codex contém uma seção intitulada “Gerenciamento experimental de contexto”, literalmente: “Nos clientes Codex compatíveis, os usuários que fizeram login com ChatGPT Plus ou Pro podem optar pelo gerenciamento experimental de contexto. O Astra mantém notas entre janelas de contexto e pode pesquisar mensagens anteriores e resultados de ferramentas da mesma tarefa. Esse experimento é desativado por padrão e não está disponível com login de Business, Enterprise ou por chave da API no lançamento.” O mecanismo de adesão, literalmente: “Para participar, defina features.context_management.experimental_mode = true no seu config.toml e inicie uma nova tarefa.” Essa é a mesma interface features.context_management.experimental_mode disponibilizada pela v0.153.0 (consulte Gerenciamento de contexto) – a página da documentação agora a associa nominalmente ao Astra e ao login com Plus e Pro, enquanto as notas de versão da v0.153.0 mencionavam sessões elegíveis Plus, Pro e Pro Lite. A v0.154.0 torna o código mais restritivo: a elegibilidade para o experimento agora é controlada pelos recursos do modelo ativo no início da sessão (#43147). A seção da documentação permanecia literalmente inalterada no novo acesso de 15 de setembro de 2026. O recurso é experimental e desativado por padrão; espere mudanças no comportamento e na elegibilidade.^140146152 v0.157.0: o catálogo de modelos incluído não marca mais o GPT-6-Astra, nem qualquer outro modelo incluído, como compatível com contexto experimental (#47397), e o CLI só ativa o experimento em um modelo marcado dessa forma. Portanto, com o catálogo incluído, a adesão não tem efeito; não há documentação que informe se o catálogo fornecido às contas conectadas é diferente. A documentação de modelos ainda descrevia a adesão em 26 de setembro de 2026.¹⁷⁴ 29 de setembro de 2026: a página de modelos não contém mais essa seção, a referência de configuração descreve features.context_management.experimental_mode como “Configuração experimental de gerenciamento de contexto. O recurso não está disponível no momento”, e o GPT-6.1 Sol também não está marcado como compatível.¹⁷⁸

Fluxograma de seleção de modelo

Is this a quick fix, extraction, or other well-defined repeatable task?
├─ Yes → gpt-6-luna (most efficient; docs suggest starting at High)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Hardest end-to-end work across many steps and tools?
   │     │  ├─ Yes → gpt-6-astra (strongest; most expensive)
   │     │  └─ No → gpt-6.1-sol (near-Astra at lower cost; default since v0.159.1)
   └─ GPT-6.1 Sol not yet available on your account? → gpt-6-sol, then gpt-5.6-sol

Esforço de raciocínio

Controle quanto o modelo “pensa” antes de responder:

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

Detalhes de persistent (v0.151.0): os turnos executados com esforço persistent ativam por padrão o lembrete da hora atual e a ferramenta interrompível clock.sleep (as configurações explícitas de features.current_time_reminder e os requisitos gerenciados são preservados), além de incluírem orientações de proatividade e acompanhamento que os metadados do modelo podem substituir ou desativar por meio de persistent_instructions.¹³⁵

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

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

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

Troca de modelo

Troque de modelo durante a sessão com o slash command /model ou defina o modelo para cada execução usando --model / -m:

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

Quanto custa o Codex?

Consulte também Seleção de modelos para conhecer os recursos e Frameworks de decisão para escolher o modelo certo 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 por licença/mês. Licenças exclusivas para Codex com pagamento conforme o uso agora estão disponíveis para os workspaces Business e Enterprise — sem tarifa fixa por licença, com cobrança baseada no consumo de tokens.⁷⁹ A página de preços agora publica os limites como faixas por modelo (consulte 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 em maio de 2026 (encerrado em 31 de maio de 2026): no plano Plus, o Codex operou com um limite de 5 horas 25× maior (em comparação com o aumento padrão de 20×), e o limite da faixa de US$ 100/mês foi dobrado durante o mesmo período.⁸⁹

Experiência dos limites de uso na TUI (v0.152.0-v0.153.0): atingir um limite não é mais um beco sem saída. A v0.152.0 exibe banners acionáveis de limite de uso acima do campo de composição — para verificar o uso, gerenciar créditos, redefinir limites, notificar o proprietário do workspace e gerenciar planos — filtrados conforme a conta autenticada e o usuário; o uso é atualizado após erros de limite e, quando o banner orienta, o Codex muda para o primeiro modelo alternativo disponível sem alterar configurações não relacionadas da thread.¹³⁸ A v0.153.0 adiciona alertas antecipados para os planos Plus e Team: um alerta é acionado quando resta menos da metade da cota em uma janela de uso de aproximadamente cinco horas, enquanto os demais planos e durações de janela mantêm os limites existentes de 75%, 90% e 95%.¹⁴⁰

Custos em créditos

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

As tarifas correspondem à velocidade Standard, e a página de preços informa que as tarifas do GPT-5.6 Sol, Terra e Luna “permanecem inalteradas” após o lançamento do GPT-6. Na prática, “o uso do GPT-5.6 consome, em média, de 5 a 30 créditos por mensagem” (a página indicava de 5 a 40 no acesso de agosto); o modo Fast custa 2,5x a tarifa de créditos Standard para GPT-6.1 Sol e GPT-6 Astra, Sol e Luna “quando disponível”, e o catálogo incluído torna Fast a faixa padrão para GPT-6 Sol e Luna (mas não para GPT-6.1 Sol) na TUI, a menos que você defina service_tier. Portanto, verifique /fast status caso os créditos estejam acabando mais rápido do que o esperado. A geração de imagens consome os limites incluídos de 3 a 5 vezes mais rápido do que interações equivalentes somente com texto.^162171178

Os planos Enterprise e Edu dimensionam os créditos conforme a alocação contratual. Consulte /status na TUI para ver o uso atual.

Cobrança da API

Ao usar o Codex por meio da API, a OpenAI cobra o uso por token conforme o preço padrão da API da OpenAI para o modelo selecionado (além de eventuais descontos aplicáveis pelo cache de prompts). Tarifas atuais da API por 1 milhão de tokens: GPT-6.1 Sol, US$ 2 pela entrada / US$ 10 pela saída (US$ 0,10 pela entrada em cache); GPT-6 Sol, US$ 2 / US$ 10; GPT-6 Luna, US$ 0,10 / US$ 0,50; GPT-6 Astra, US$ 10 / US$ 50. Para os quatro modelos, prompts acima de 272 mil tokens de entrada custam 2x o preço da entrada e 1,5x o preço da saída para toda a solicitação, e o modo Fast custa 2x.^146171178 Os multiplicadores de créditos do ChatGPT não se aplicam ao login com chave da API. 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-6-luna e model_reasoning_effort = "low" para tarefas rotineiras
2. Reserve o raciocínio avançado: use xhigh apenas para problemas realmente difíceis, pois ele consome de 3 a 5 vezes 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. Processe em lote com o modo exec: codex exec evita a sobrecarga da TUI nos fluxos de automação
6. Monitore o uso: consulte /status na TUI e os painéis de cobrança da sua organização — desde a v0.148.0, /status, as linhas de status e os títulos do terminal exibem a estimativa de créditos ou custos da thread para workspaces qualificados¹¹⁸

Exemplos de custos reais

Custos representativos da API para tarefas comuns (snapshot de preços do gpt-5.3-codex em meados de 2026, com raciocínio médio — as proporções se mantêm entre os modelos):

Os custos variam conforme o esforço de raciocínio, o uso de cache e a duração da conversa. Use gpt-5.6-luna em tarefas rotineiras para reduzir consideravelmente esses gastos. Tokens de entrada em cache recebem desconto na cobrança.

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 na TUI. A contagem de tokens inclui toda a sobrecarga, não apenas suas mensagens visíveis. Se os custos surpreenderem você, verifique quantos servidores da MCP estão conectados — cada um adiciona definições de ferramentas a todas as chamadas da API.

Gerenciamento de custos da equipe

Estratégias para controlar os custos da equipe: - Configure requirements.toml para aplicar limites de modelo e de esforço de raciocínio em toda a organização - Use gpt-5.6-luna para CI/CD — pipelines automatizados raramente precisam do nível máximo de raciocínio - Orçamento baseado em perfis — defina os perfis ci, review e dev com tetos de custo adequados - Monitore via 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 de planejamento 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 e 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 usar?

Associe sua tarefa a um perfil pré-configurado:

Arquivos de perfil (um por predefinição, em ~/.codex/; o layout legado de arquivo único com profile = "default" + [profiles.*] não é lido desde a versão 0.134.0¹²²):

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Alterne o perfil por sessão: codex --profile careful

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

O Codex usa um modelo de segurança em duas camadas que separa o que é tecnicamente possível de quando o Codex solicita aprovação humana. A abordagem é fundamentalmente diferente do sistema de permissões do Claude Code — o Codex impõe 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.

Reforço de segurança na v0.148.0: agora, as restrições do sandbox falham de forma segura — um caminho negado ou ilegível é tratado como bloqueado, em vez de ser silenciosamente permitido — tanto no Linux quanto no Windows.¹¹⁸

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) fornece isolamento em profundidade.⁵ Bubblewrap (bwrap) é incluído no código e compilado como parte da build para Linux (promovido de opcional na v0.100.0)⁷. A v0.117.0 melhorou a confiabilidade do sandbox em distribuições mais antigas com configurações de kernel legadas.⁷⁵ A v0.129.0 reforçou a inicialização do sandbox no Linux e atualizou o Bubblewrap incluído para a versão 0.11.2, com correções de segurança do projeto original; a v0.130.0 adicionou mais reforços à inicialização.⁸⁹⁹¹
• Windows: sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). WSL também é compatível (herda Landlock + seccomp do Linux). A v0.117.0 inclui melhorias no sandbox com tokens restritos para proporcionar um isolamento de processos mais eficaz.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários de runtime do desktop, permitindo que o sandbox do Windows encontre os binários de runtime de forma confiável para usuários do sandbox do workspace.⁹¹

Por que isso importa: 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 escapar. 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): foi corrigida uma vulnerabilidade que permitia que a execução de shell por meio de fork do zsh contornasse as restrições do sandbox.⁶⁰ Se você estiver usando uma versão anterior, atualize imediatamente. - Limite de 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 devcontainers do Docker usa Bubblewrap para executar o sandbox dentro do contêiner. WSL2 é compatível; WSL1 é explicitamente rejeitado (Bubblewrap é incompatível com a camada de compatibilidade de 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 que hooks executados antes ou depois das ferramentas não 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 os ignora — recorra à observabilidade do app-server se precisar de uma trilha de auditoria completa. - Sistema de arquivos /dev no Linux (v0.105.0): comandos executados no sandbox no Linux agora recebem um sistema de arquivos /dev mínimo, melhorando a compatibilidade com ferramentas que esperam nós de dispositivo.⁶¹

Política ReadOnlyAccess (v0.100.0+): uma estrutura de política configurável para controle granular do 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 marca como obsoleto. Prefira on-request para execuções interativas e never para execuções não interativas que já tenham um limite externo de segurança.⁸⁷

Desde a v0.150.0, você pode vincular um atalho de teclado que alterna entre os modos de permissão no compositor — configure-o usando /keymap.¹³²

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 em 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+)

Agora, o fluxo de aprovação aceita permissões adicionais de sandbox e rejeição granular:⁶¹

• Permissões adicionais de sandbox: quando um comando precisa de acesso além do modo de sandbox atual, o Codex pode solicitar permissões adicionais específicas, sem exigir uma mudança completa de modo
• Rejeição granular: rejeite chamadas individuais de ferramentas com feedback para que o Codex possa ajustar a 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 integrada request_permissions 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 ações declaradas como somente leitura por um app sejam executadas sem solicitação, mas ainda pausa para qualquer operação de gravação.¹⁰⁷ Antes disso, as aprovações de apps funcionavam mais no esquema tudo ou nada; writes corresponde ao modelo 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.¹¹⁶ Isso fica entre “aprovar tudo” (a postura que --full-auto incentivava 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-a com os padrões mais seguros de revisão automática da v0.146.1 para modelos com recursos cibernéticos, herdados por essa flag. Trate-a como qualquer delegação de autoridade: é adequada para execuções longas e não supervisionadas, nas quais uma interrupção causaria uma paralisação, mas inadequada para sessões que envolvam credenciais ou o estado de produção, nas quais você deve ser o revisor.

Aprovação para entrada de terminal com privilégios elevados (v0.151.0; habilitada por padrão desde a v0.158.0)

A flag de recurso write_stdin_approval — desabilitada por padrão quando chegou na v0.151.0 e habilitada por padrão desde a v0.158.0 — exige uma nova aprovação antes que uma entrada não vazia seja enviada a um terminal unified-exec com privilégios elevados. Essas revisões passam por hooks, Guardian, app server e TUI como aprovações writeStdin; o ambiente do terminal, o diretório de inicialização e o estado de elevação persistem entre turnos, e a identidade do processo é revalidada após a aprovação, antes que qualquer byte seja gravado. A ação totalmente formatada e o motivo da aprovação devem caber em 8.000 bytes — ações grandes demais ou truncadas são rejeitadas antes que a aprovação seja solicitada ou qualquer conteúdo chegue ao terminal.¹³⁵ A v0.158.0 habilita a flag (#47799) e impede que concessões feitas apenas em tempo de execução, como as usadas por plugins para métricas, acionem uma revisão, enquanto permissões adicionais de agentes, contornos do sandbox e alterações de política posteriores à inicialização continuam acionando revisões (#48073). Para desabilitar: defina write_stdin_approval = false em [features] no config.toml.¹⁷⁶

Perfis de permissão (v0.113.0+, expandidos 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 personalizada [permissions.<name>].⁸⁷ A v0.133.0 promove os perfis a uma superfície gerenciada: APIs de listagem expõem os metadados disponíveis dos perfis, perfis podem herdar de outros, o requirements.toml gerenciado pode declarar requisitos de permissão, 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 e globs confidenciais que devem permanecer ilegíveis mesmo quando a raiz do projeto permitir gravação. Para exceções pontuais de comandos, prefira regras em vez de ampliar o perfil de forma abrangente.⁸⁷

v0.151.0: threads restauradas do app-server mantêm seus perfis de permissão, em vez de serem reduzidas a substituições legadas de sandbox por turno — os perfis persistem durante o roteamento de turnos e mudanças compatíveis de diretório com /cd, e um /cd que não consiga representar com segurança o perfil restaurado como um modo de sandbox legado é rejeitado, em vez de enfraquecer silenciosamente as restrições.¹³⁴

Orientações legadas sobre --full-auto

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

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

Na v0.128.0, as notas de versão marcam --full-auto como obsoleto, e a ajuda atual do CLI deixou de listá-lo para execuções interativas. 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 passe a flag apresenta um erro em vez de ser executado. A migração é mecânica — substitua-a por --sandbox workspace-write (mais uma flag ou um perfil de aprovação, caso a invocação antiga dependesse do comportamento de aprovação de --full-auto). Antes de atualizar, revise qualquer automação que invoque codex exec pelo shell: a falha aparece como um pipeline quebrado, 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 correções de segurança do projeto original. Nenhuma alteração de configuração é necessária. Execute codex update para receber essas melhorias.⁸⁹

Configurações recomendadas

Desenvolvimento diário (padrão seguro):

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

Usuário avançado (acesso total, com supervisão humana):

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

Publicações da comunidade recomendam essa combinação como um “ponto ideal”⁸; entenda o que ela realmente faz antes de repetir a recomendação: as solicitações de aprovação aparecem quando um comando precisa sair do sandbox ou acessar a rede, e danger-full-access remove esses dois limites, portanto on-request quase não tem mais nada para elevar. É a capacidade máxima com o mínimo de perguntas, não a capacidade máxima com verificação humana para cada comando; se você quiser a segunda opção, mantenha workspace-write e deixe o limite do sandbox acionar as solicitações.¹²³

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 solicitações de revisão por meio de um subagente Guardian, em vez de exigir aprovação humana para cada ação. A sessão do Guardian persiste entre aprovações para reutilizar o cache de prompts e evitar o custo de inicialização. Cada revisão recebe um histórico limpo (decisões anteriores não vazam para revisões posteriores).⁷³

Configure o revisor no config.toml:

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

Isso é 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".

Padrões do Guardian v2 invertidos (v0.151.0): agora, o Guardian v2 usa por padrão revisões de uso do computador com imagens. features.guardianv2.review_scope.computer_use_only assume true por padrão — defina-o como false para manter o escopo mais amplo de revisão de ferramentas — e features.guardianv2.transcript.include_images assume true por padrão — defina-o como false para excluir imagens das transcrições do Guardian. Ambos foram lançados na v0.150.0 como superfícies configuráveis e desabilitadas por padrão; foi na v0.151.0 que passaram a ser habilitados por padrão.¹³⁵

O escopo do Guardian acompanha o modo de aprovação (v0.153.0): agora, dois modos ignoram trabalhos do Guardian que não podem mudar o resultado. Em Acesso total (que já combina approvalPolicy: "never" com permissões irrestritas), solicitações somente de confirmação do Guardian e do MCP são aprovadas sem revisão síncrona, pré-aquecimento do sampler ou pontuação em segundo plano — ambientes pendentes, com falha ou restritos não são tratados como Acesso total, e o estado ativo das permissões é reavaliado a cada turno para que uma thread existente possa entrar ou sair do Acesso total com segurança. No Modo de aprovação pelo usuário (approvals_reviewer = "user"), o pré-aquecimento e a pontuação assíncrona do Guardian são ignorados, e confirmações comuns de execução de node_repl.js são aceitas automaticamente, enquanto as verificações de ações confidenciais e as solicitações de entrada do usuário mantêm o comportamento existente.¹⁴⁰ Isso restringe quando o Guardian é executado, não a camada de aprovação humana: o comportamento de solicitação descrito neste guia para danger-full-access com on-request pertence à política de aprovação, que é um mecanismo separado. Além disso, a v0.152.1 permite que a revisão de aprovação do Guardian obtenha sua política do Node REPL nos metadados do modelo (auto_review.node_repl_policy), recorrendo à política incluída quando o campo estiver ausente.¹³⁹

A pontuação de uso do computador do Guardian respeita os requisitos do modelo (v0.153.1): a pontuação do Guardian limitada ao uso do computador e as decisões rápidas de aprovação agora só são executadas quando o modelo ativo define node_repl_auto_review_required em seus metadados, e pontuações anteriores ou em andamento são invalidadas quando uma troca de modelo ignora a pontuação — assim, voltar para um modelo revisado não pode reativar uma decisão de aprovação obsoleta. Esse é o destaque do patch v0.153.1 e não aparece no corpo da versão: #42422 (um cherry-pick de 38ba8cdc) só pode ser comprovado pela comparação rust-v0.153.0…rust-v0.153.1.¹⁴²

A reutilização da compactação da thread principal pelo Guardian é habilitada por padrão (v0.156.0): #46522 promove guardian_reuse_parent_compaction a um recurso estável e o habilita por padrão, permitindo que o Guardian reutilize a compactação criptografada da thread principal ao reiniciar uma sessão de revisão. De acordo com os testes do PR, as sessões de revisão armazenadas em cache continuam sendo invalidadas quando o histórico da thread principal muda. Para restaurar o comportamento anterior: defina guardian_reuse_parent_compaction = false em [features] no config.toml ou execute codex features disable guardian_reuse_parent_compaction.¹⁶⁹¹⁷¹

O contexto da thread do Guardian é habilitado por padrão (v0.157.0): #47275 promove guardianv2.thread_context a estável e o habilita para revisões síncronas e assíncronas do Guardian, fazendo com que as revisões usem o contexto pertencente à thread. Ele é independente da opção enabled do Guardian v2. Na v0.157.0, você podia desabilitá-lo com thread_context = false em [features.guardianv2]; a v0.158.0 removeu essa opção.¹⁷⁴

O contexto da thread do Guardian está sempre habilitado (v0.158.0): #47686 e #47689 tornam incondicional o uso do contexto pertencente à thread para a captura de sessões do Guardian e os forks de histórico dos subagentes. O Codex ignora thread_context em [features.guardianv2], inclusive substituições de perfil e requisitos gerenciados, e exibe um aviso de obsolescência solicitando que você o remova do config.toml. Não há uma opção substituta para desabilitá-lo.¹⁷⁶

O Guardian pode ler mensagens anteriores do usuário (v0.160.0, opcional): a transcrição revisada pelo Guardian pode omitir uma instrução, restrição ou permissão revogada anteriormente. Com guardian_conversation_history_tools = true em [features] e Apps habilitado, o revisor recebe duas ferramentas, user_message.search_messages e user_message.read_messages, fornecidas pela própria conexão e identidade de Apps da sessão principal. Cada chamada verifica novamente a política atual de apps e ferramentas da sessão principal e falha de forma segura quando uma ferramenta está desabilitada ou exige aprovação. Duas chaves de [auto_review] ajustam esse comportamento: conversation_history_max_output_tokens limita cada resposta (uma estimativa de 4.000 tokens por padrão; limites mais rigorosos da sessão principal ainda se aplicam), e experimental_conversation_history_prompt substitui as instruções integradas de recuperação (um valor em branco usa o padrão). Uma segunda flag opcional, guardian_root_handoff_context, restringe as evidências da conversa raiz usadas na revisão de um agente worker às mensagens próximas de cada transferência para ele, mais as três mensagens mais recentes. Ambas as flags estão em desenvolvimento e desabilitadas por padrão; a referência de configuração ainda não as lista.¹⁸²

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

Classificador do PowerShell mais rigoroso (v0.142.2): agora, comandos do PowerShell que contêm regiões executáveis da AST que o classificador de segurança não consegue inspecionar exigem aprovação, em vez de passar pela aprovação automática — isso fecha uma brecha pela qual PowerShell ofuscado ou criado dinamicamente podia evitar a classificação no Windows.¹⁰⁵

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

Habilitando o acesso à rede

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

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

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

Suporte a proxy do WebSocket (v0.104.0+)

Para ambientes corporativos que encaminham o tráfego do WebSocket por um proxy, o Codex agora oferece suporte às variáveis de ambiente WS_PROXY e WSS_PROXY:⁴⁹

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

Elas complementam o suporte existente ao proxy HTTPS_PROXY e a proxies SOCKS5 (v0.93.0+).

A v0.146.0 é a versão que tornou “todas as camadas de transporte” uma afirmação 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 do LM Studio — sete caminhos que o changelog lista como anteriormente incompatíveis com o proxy.¹¹⁴ Se você executava o Codex atrás de um proxy corporativo antes da v0.146.0 e via falhas de login ou de instalação de plugins 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 — assim, 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 para cada shell no 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 para redes corporativas bloqueadas em qualquer um dos sistemas operacionais.¹⁰⁶

Testando o sandbox

Verifique o comportamento do sandbox antes de confiar nele:

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

Se o sandbox estiver funcionando corretamente, ambos os comandos deverão falhar com um erro de permissão negada em um perfil limitado ao workspace. Se qualquer um deles for executado com sucesso, a configuração do sandbox precisará ser investigada.

Como funciona o AGENTS.md?

O AGENTS.md é o sistema de instruções de projeto do Codex — um padrão aberto⁹ agora administrado pela Agentic AI Foundation da Linux Foundation. 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 arquivos 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 não confiáveis ignoram o AGENTS.md do projeto (v0.150.0): o percurso acima pressupõe que o projeto seja confiável. Desde a v0.150.0, “Projetos não confiáveis não fornecem mais instruções do AGENTS.md no nível do projeto, e as regras gerenciadas de negação de leitura continuam em vigor após alterações de permissão” — a descoberta no escopo do projeto é ignorada, enquanto as instruções no nível do usuário em ~/.codex/AGENTS.md são preservadas. Assim, um checkout não confiável não pode injetar um contrato operacional antes de você confiar nele.¹³²

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 e executa a descoberta em relação a 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 busca, leitura e edição de arquivos.” Você escolhe qual pasta é a principal no menu do projeto, em Editar projeto.¹¹³

Essa única configuração controla simultaneamente três dos cinco sistemas principais 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, defina-o como 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 dos projetos no aplicativo para desktop.

O que torna um AGENTS.md excelente

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

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

NÃO FAÇA: - Não inclua guias de estilo completos sem regras de execução - Não use instruções ambíguas (“tenha cuidado”, “otimize”) - Não misture prioridades contraditórias (velocidade + verificação exaustiva + nenhum orçamento de execução) - Nã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 trabalho de captura de snapshots do shell e 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 lugares seguros para exibir credenciais.³⁷⁵⁵⁹⁵

A regra operacional é simples: não exiba segredos para o modelo inspecionar; mantenha as credenciais auxiliares na configuração exigida pelo ambiente; durante 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 repositórios intencionais de segredos; oculte o histórico local quando aparecer 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 dos tokens, os caminhos exatos ou os detalhes internos dos detectores.⁹⁵

O mecanismo de substituição

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

• Congelamentos de versão: “Nenhum recurso novo, apenas correções”
• Modo de incidente: “Todas as alterações devem ser revisadas pelo responsável de plantão”
• Reforço temporário: “Nenhuma atualização de dependência nesta sprint”

Configuração

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

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

Geração 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 nas versões v0.99.0 e v0.100.0 com os nomes legados AfterAgent e AfterToolUse, adicionou um mecanismo experimental de hooks na v0.114.0 com SessionStart e Stop,⁷⁰ e tornou os hooks estáveis na v0.124.0 (23 de abril de 2026).⁸⁵ O mecanismo incluído na rust-v0.150.0 registra doze eventos (HOOK_EVENT_NAMES em codex-rs/hooks/src/lib.rs) — onze na v0.149.1, com Interrupt adicionado como o décimo segundo na v0.150.0¹³² — e os nomes legados foram removidos da superfície configurável: AfterToolUse não aparece mais em nenhum lugar da árvore de código-fonte, e AfterAgent permanece apenas como o nome interno do payload da ponte legada notify.¹²⁴ Os hooks executam scripts ou ferramentas MCP durante o loop agêntico. Todos os hooks correspondentes de vários arquivos são executados, vários hooks de comando correspondentes a um evento são iniciados simultaneamente e todo hook não gerenciado precisa ser revisado e considerado confiável antes da execução.¹²⁴ A v0.148.0 amplia o mecanismo: os hooks podem executar comandos de forma assíncrona e invocar ferramentas MCP — defina async = true em um manipulador de comando para permitir que ele seja executado em segundo plano enquanto o Codex continua, ou use um manipulador mcp_tool para acessar os mesmos servidores MCP usados pelo agente.¹¹⁸¹²⁴

Eventos de hook disponíveis

Ferramentas hospedadas, como WebSearch, não passam pelo fluxo de hooks, e alguns fluxos de ferramentas especializadas podem optar por não usá-lo; nas palavras da própria OpenAI, trata-se de “uma proteção útil, não de um limite completo de aplicação de políticas”.¹²⁴

Configuração de hooks

Os hooks são organizados em três níveis — um evento, um grupo de matchers e um ou mais manipuladores — e ficam no hooks.json (~/.codex/hooks.json, <repo>/.codex/hooks.json ou hooks/hooks.json de um plugin) ou diretamente em config.toml e requirements.toml. Os hooks locais do projeto são carregados apenas quando a camada .codex/ do projeto é confiável.¹²⁴ O formato TOML inline:

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

Campos do manipulador: type (command ou mcp_tool; os manipuladores prompt e agent são analisados, mas ignorados), command, timeout em segundos (600 por padrão; 1 segundo para SessionEnd, até 3), statusMessage, additionalContextLimit (quanto de additionalContext chega ao modelo antes que o Codex salve o texto completo no disco e envie uma prévia), commandWindows (substituição exclusiva para Windows) e async. Os comandos usam o cwd da sessão como diretório de trabalho; portanto, hooks locais do repositório devem resolver os caminhos a partir de git rev-parse --show-toplevel, em vez de usar um caminho relativo .codex/hooks/....¹²⁴

Revisão e confiança. O Codex registra a confiança com base no hash atual de cada hook não gerenciado; hooks novos ou alterados são marcados para revisão e ignorados até serem considerados confiáveis. Execute /hooks para inspecionar as origens dos hooks, revisar, confiar ou desativar hooks individuais; quando há hooks que precisam de revisão na inicialização, o Codex exibe um aviso indicando /hooks. Hooks gerenciados provenientes do sistema, MDM, nuvem ou requirements.toml são considerados confiáveis por política e não podem ser desativados pelo navegador de hooks do usuário. --dangerously-bypass-hook-trust executa os hooks habilitados sem confiança persistente em uma única invocação, para automações que validam as origens dos hooks em outro lugar.¹²⁴

O stdout do hook SessionStart é incorporado ao 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 padrões de hooks do Claude Code

O Codex usa os mesmos nomes de eventos do Claude Code para os eventos que implementa; portanto, você pode portar a maioria das configurações de hooks movendo o JSON para hooks.json e marcando-o como confiável por meio de /hooks:

Dica de especialista: Novos eventos de hook continuam chegando nas versões — a v0.150.0 adicionou o evento Interrupt (¹³²) — portanto, consulte HOOK_EVENT_NAMES em codex-rs/hooks/src/lib.rs e o changelog do Codex para conferir a lista atual.

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. É útil para solucionar problemas com um hook incluído em um plugin que não esteja funcionando corretamente ou para desativar temporariamente um linter PostToolUse durante uma sessão de edição focada.⁸⁹

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

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

Mudanças no MCP na v0.121.0: As ferramentas agora são registradas com um namespace, então os nomes de ferramentas nas listagens aparecem como <server>:<tool> em vez de nomes simples. Atualize scripts ou prompts que fazem grep em nomes de ferramentas não qualificados. Uma nova flag supports_parallel_tool_calls é repassada aos MCPs incluídos e permite execução paralela em servidores que declaram suporte. Os metadados de estado do sandbox agora fluem pelos metadados de ferramentas do MCP, o que permite aos servidores adaptar o comportamento (por exemplo, emitir um aviso ao rodar sob um sandbox read-only). A requisição personalizada codex/sandbox-state foi removida. Use o caminho de metadados no lugar dela. A fase 3 do rollout de MCP Apps chega nesta versão com suporte a chamadas de ferramentas, e chamadas de ferramentas adiadas em formato achatado (flattened) agora funcionam em servidores que usam o padrão de chamada adiada.⁸²

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

Mudanças no MCP na v0.147.0 (7 de agosto de 2026): O Codex adiciona suporte opt-in à revisão 2026-07-28 do protocolo MCP. Ela traz descoberta paginada (catálogos grandes de ferramentas chegam em páginas em vez de uma única listagem enorme), requisições de múltiplas rodadas (um servidor pode manter uma troca de várias etapas dentro de uma única requisição lógica) e inicialização não bloqueante do servidor. As ferramentas MCP em cache ficam expostas antes de o servidor terminar de iniciar, então um servidor lento não trava mais a abertura da sessão. O suporte é opt-in, então servidores na revisão anterior continuam funcionando sem alterações.¹¹⁶

Mudanças no MCP na v0.151.0 (29 de agosto de 2026): Servidores MCP opcionais ganham um período de tolerância de inicialização configurável – mcp_optional_startup_grace_ms (padrão de 1.000 ms) controla quanto tempo a captura do catálogo de ferramentas espera pelos servidores opcionais. O valor 0 desativa a tolerância compartilhada, e os servidores opcionais voltam a usar o startup_timeout_sec configurado. Valores atualizados passam a valer em tempo de execução e nas atualizações de configuração do MCP. As extensões também podem inspecionar ou substituir resultados de ferramentas MCP antes que eles cheguem ao modelo. O ToolLifecycleContributor::on_mcp_tool_result roda antes de a conclusão do MCP ser publicada e antes de o resultado ser preparado para o modelo. Isso vale tanto para resultados bem-sucedidos quanto para erros, inclusive via Code Mode.¹³⁴

Mudanças no MCP na v0.152.0 (1º de setembro de 2026): Três mudanças aditivas. Chegam as requisições de formulário openai/elicitation: o Codex anuncia suporte a formulários quando o cliente declara uma capability form com valor de objeto. Ele também processa requisições openai/elicitation/create e encaminha os metadados e o schema opaco delas pelo app server como openaiForm (preservando as anotações x-openai-*). O tratamento legado de openai/form continua independente, e a TUI recusa automaticamente as requisições de formulário que não consegue renderizar. Limites de saída por ferramenta: cada entrada na configuração tools de um servidor MCP aceita um output_token_limit positivo (por exemplo, [mcp_servers.context7.tools.search] com output_token_limit = 2000). Quando políticas de plugin e de usuário se sobrepõem, o limite mais restritivo prevalece. O orçamento efetivo fica registrado no histórico da conversa, então a saída das ferramentas, as respostas de hooks pós-ferramenta e as sessões retomadas são truncadas no mesmo limite. Esse limite se soma ao tool_output_token_limit global. Nomes de servidor no estilo de pacote: nomes de servidores MCP agora podem conter :, @, / e . (então npm:@modelcontextprotocol/server-sequential.thinking é um nome válido). Esses nomes são preservados em mcp add/get/list/remove, nos namespaces de ferramentas em tempo de execução e na busca de credenciais OAuth. Nomes que não são chaves simples (bare) aparecem entre aspas nas dicas de recuperação geradas para o config.toml.¹³⁸

Configurando servidores MCP

Servidores STDIO (processos locais):

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

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

Servidores HTTP (remotos):

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

Gerenciamento via CLI

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

Dentro da 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 templates de recursos. Ele é útil quando um servidor não carrega ou quando as ferramentas não aparecem onde deveriam. O /mcp simples continua rápido. A partir da v0.144.0, ferramentas MCP podem solicitar autenticação de forma interativa sem opt-in experimental. Um servidor que precisa de autenticação no meio da sessão pede isso pelo fluxo normal, em vez de falhar até que você se autentique previamente com codex mcp login.¹⁰⁷

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

Verificação de usuário no MCP (v0.155.0, Macs compatíveis): sessões locais da TUI em Macs compatíveis podem verificar requisições MCP com Touch ID, assinadas pelo Secure Enclave (#43624, #43712, #43715). A identidade de verificação fica restrita ao workspace em que foi cadastrada (#43524), e a verificação é levada nativamente às continuações de ferramentas MCP (#44346). O recurso foi acompanhado pela primeira vez no checklist de promoção da v2.68, cortado da 0.154.0 junto com o grupo do alpha.7 e lançado na 0.155.0.¹⁵⁶

Executando o Codex COMO servidor MCP

Removido (v0.154.0, 9 de setembro de 2026). O comando codex mcp-server e o binário independente codex-mcp-server foram removidos na versão estável 0.154.0 (#42993), o que conclui a descontinuação anunciada em 24 de agosto de 2026. Segundo o changelog oficial (5 de setembro de 2026): “O comando codex mcp-server e o binário independente codex-mcp-server foram removidos após sua descontinuação em 24 de agosto de 2026. Atualize as integrações que iniciam qualquer um desses comandos antes de atualizar o Codex.” As integrações devem migrar para o protocolo app-server, a interface por trás da extensão do VS Code e do app desktop (autenticação, histórico de conversas, aprovações, eventos de agente em streaming). A própria entrada de remoção classifica esse protocolo como experimental e diz que ele “não tem suporte para cargas de trabalho de produção”. Quem usa o Claude Code tem outra opção, o plugin do Codex para Claude Code: “Use o Codex a partir do Claude Code para revisar código ou delegar tarefas.” Conectar o Codex A servidores MCP externos (codex mcp ..., /mcp) continua funcionando normalmente.^125152153

No CLI 0.153.4 e anteriores, o comando ainda existe. Ele está descontinuado desde 24 de agosto de 2026 e, desde a v0.149.0, imprime warning: `codex mcp-server` is deprecated and will be removed in a future release. no stderr e depois inicia mesmo assim (PR #39657). Se uma integração não puder migrar imediatamente, a solução provisória é fixar a versão com npm install -g @openai/codex@0.153.4:^12125148152

codex mcp-server                        # REMOVED in 0.154.0; works only on 0.153.x and earlier (deprecated, warns)

Na 0.153.x e anteriores, o servidor expõe duas ferramentas: 1. codex(): inicia uma nova sessão com parâmetros de prompt, sandbox, modelo e aprovação 2. codex-reply(): continua uma sessão existente com threadId e prompt

Uso com o Agents SDK (Python) – somente CLI 0.153.4 ou anterior:

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

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

Servidores MCP notáveis

Padrões práticos

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

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

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

Padrão 2a: Saída multimodal de ferramentas (v0.107.0) — Ferramentas personalizadas agora podem retornar saída multimodal (imagens, conteúdo rico) junto com texto. Assim, ferramentas que produzem artefatos visuais, como capturas de tela, diagramas e renderizações de gráficos, podem enviá-los diretamente ao modelo para análise.⁶²

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

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

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

Code Mode [EXPERIMENTAL]

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

Desde a v0.139.0, o Code Mode pode chamar a pesquisa independente na web diretamente — inclusive de chamadas de ferramenta JavaScript aninhadas — e recebe resultados em texto simples. Assim, um fluxo do Code Mode pode buscar informações em tempo real sem sair do contexto de programação em sandbox.¹⁶⁵ A v0.146.0 estende a pesquisa independente na web a provedores de modelos personalizados compatíveis, portanto o recurso não está mais limitado aos modelos hospedados pela OpenAI.¹¹⁴

A v0.146.0 permitiu que o app-server se conectasse a hosts remotos do Code Mode, eliminando a necessidade de o runtime do Code Mode estar na mesma máquina que o cliente — originalmente por WebSocket.¹¹⁴ A v0.151.0 remove o transporte WebSocket (#40692): as conexões --code-mode-host do app server aceitam apenas endpoints gRPC http:// e https://, enquanto o host independente do Code Mode é limitado a listeners stdio e gRPC — na tag rust-v0.151.0, a documentação do listener diz literalmente “Endpoint de transporte: stdio, stdio:// ou grpc://IP:PORT.” O WebSocket permanece apenas como um endpoint opcional que transmite lotes brutos de traces OTLP para rastreamento, não como transporte de sessão.¹³⁵

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

Runtime REPL JavaScript [REMOVIDO]

O Codex v0.100.0 adicionou um runtime REPL JavaScript experimental (js_repl), e a v0.106.0 o promoveu por meio da interface /experimental.⁶⁰ Essas orientações agora são apenas históricas. Na v0.128.0, o changelog da versão inclui “Remover o recurso js_repl”, 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 no repositório, ferramentas MCP ou uma skill do Codex com uma pasta scripts/ quando precisar de lógica executável e reproduzível.

O que são skills?

Skills são pacotes reutilizáveis de recursos específicos para tarefas que o Codex carrega sob demanda. Elas seguem o padrão aberto de agent skills.¹³

Estrutura de uma skill

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

Locais de descoberta

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

Como criar uma skill

Formato de 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 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 a elas, inclusive 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 em muitas skills, fique atento a esse aviso.

Ativar/desativar

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

Skills vs. slash commands

Como depurar skills

Se uma skill não estiver sendo ativada:

1. Verifique a descoberta: /skills deve listá-la na TUI
2. Verifique o caminho: confirme que a pasta da skill está em um local reconhecido (~/.codex/skills/, raiz do projeto ou /etc/codex/skills/)
3. Verifique enabled: skills com enabled = false em config.toml não serão carregadas
4. Verifique a ativação implícita: se você depende da detecção automática, confirme que 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 implantação

Uma skill completa com vários arquivos, mostrando referências e scripts funcionando 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

Os plugins unificam skills, entradas de MCP, hooks e conectores de apps em um único pacote instalável (v0.110.0+).⁶⁵ Desde a v0.117.0, os plugins são recursos de primeira classe: plugins com escopo de produto são sincronizados automaticamente na inicialização, e /plugins oferece um navegador dentro da TUI para descoberta e gerenciamento.⁷⁵ A v0.128.0 ampliou os fluxos de trabalho de plugins com instalação via marketplace, cache de pacotes remotos, APIs de desinstalação remota, hooks incluídos em plugins, estado de ativação dos hooks e importação de configurações de agentes externos.⁸⁶ A v0.129.0 (7 de maio de 2026) adiciona compartilhamento de plugins no workspace (envie um conjunto de plugins aos colegas de equipe sem publicá-lo novamente), controles de acesso ao compartilhamento (ativar/desativar por destinatário, revogar), filtragem por origem (limitar de quais marketplaces um workspace obtém conteúdo) e operações de marketplace que podem ser executadas diretamente no navegador /plugins, em vez de usar a CLI.⁸⁹ A v0.133.0 (21 de maio de 2026) facilita a auditoria da descoberta de plugins: a saída da listagem identifica os marketplaces, as versões instaladas ficam visíveis, as raízes dos marketplaces são listadas e coleções remotas de plugins podem ser exibidas sem precisar adivinhar de qual registro veio cada resultado.⁹⁸ A v0.130.0 (8 de maio de 2026) torna o empacotamento de plugins mais transparente e oferece mais controle sobre o fluxo de compartilhamento:⁹¹

• Hooks incluídos visíveis nos detalhes do plugin. A visualização de detalhes em /plugins agora lista todos os hooks de ciclo de vida incluídos em um plugin (SessionStart, UserPromptSubmit, Stop etc.). Antes de instalar um plugin, você pode ver exatamente quais hooks ele registrará na sua sessão — sem efeitos colaterais inesperados de hooks vindos de um plugin no qual você confiou apenas pelas ferramentas oferecidas.
• Metadados de compartilhamento do plugin em shareContext. Quando um plugin é compartilhado a partir de um workspace, o payload do link de compartilhamento agora expõe metadados do link (criador, escopo e atualidade), permitindo que as sessões destinatárias mostrem a procedência e decidam se devem aceitá-lo.
• Controles de visibilidade nas configurações de compartilhamento. As configurações de compartilhamento oferecem uma opção de visibilidade para que as equipes publiquem plugins em workspaces ou listas de destinatários específicos sem torná-los disponíveis nas listagens gerais da organização.

A v0.143.0 (8 de julho de 2026) ativa os plugins remotos por padrão. Os plugins remotos agora ficam habilitados sem uma flag de adesão, o catálogo /plugins ganha linhas mais detalhadas (com origens de marketplaces npm ao lado de git e locais), e cada entrada mostra tanto a versão remota quanto a instalada localmente, deixando qualquer divergência visível de imediato.¹⁰⁶ Para uma equipe que está padronizando um conjunto compartilhado de plugins, a ativação remota por padrão elimina a etapa de habilitação em cada máquina que antes limitava a distribuição.

Origens dos plugins

Desde a v0.147.0, a busca de plugins abrange catálogos locais, pessoais, do workspace e remotos em uma única consulta — você busca uma funcionalidade, não o catálogo que por acaso a contém. Combinado com os pacotes portáveis Agent Plugin, um plugin criado em um ambiente pode ser instalado sem problemas em outro, em vez de ficar vinculado à máquina ou ao workspace onde foi desenvolvido.¹¹⁶

Descoberta de plugins

O Codex informa ao modelo quais plugins estão habilitados no início da sessão (v0.111.0), melhorando a descoberta de MCPs, apps e skills instalados.⁶⁵ Durante uma sessão, o modelo pode sugerir plugins relevantes com base no contexto da tarefa. Na v0.117.0, os plugins com escopo de produto passaram a ser sincronizados na inicialização, garantindo que o catálogo de plugins mais recente esteja disponível sem intervenção manual.⁷⁵ Desde a v0.142.0, o menu /plugins organiza os plugins remotos nas seções Selecionados pela OpenAI, Workspace e Compartilhados comigo, e interações qualificadas podem recomendar e instalar plugins relevantes diretamente no fluxo.¹⁰⁴ Desde a v0.151.0, plugin/list e plugin/installed carregam a configuração efetiva dos plugins para cada cwd solicitado – os marketplaces locais são combinados na ordem das solicitações, os estados de instalação e ativação são mesclados entre repositórios, e configurações de projeto inválidas são relatadas por meio de marketplaceLoadErrors sem descartar catálogos locais válidos nem catálogos remotos habilitados globalmente.¹³⁴

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 (funcionalidades, ferramentas e 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 oferece uma experiência de descoberta mais completa, com metadados, categorias e avaliações.⁶⁹ As verificações de autenticação durante a instalação confirmam se os plugins que exigem chaves de API ou OAuth têm credenciais válidas antes de serem instalados. 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 das origens de marketplaces em codex plugin marketplace. Isso formaliza a distribuição de plugins de terceiros para além do marketplace próprio da OpenAI e oferece suporte à forma abreviada 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 somente em 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>

Após a adição, os plugins de um marketplace aparecem no navegador /plugins junto aos plugins padrão. Clientes do app server (integrações com IDE/desktop) têm um endpoint paralelo para registrar marketplaces de forma programática.⁸²

Consideração de segurança: marketplaces de terceiros executam código arbitrário de plugins com as suas permissões do Codex. Verifique as origens antes de adicioná-las e prefira a execução em sandbox durante os primeiros usos.

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 de empacotamento aberto e independente de fornecedor, publicado como Agent Plugins 1.0.0 em 6 de agosto de 2026, cujo site oficial o resume como “Um formato de pacote portável para componentes reutilizáveis que estendem agentes de IA”.¹⁶¹ Um plugin é um diretório com um manifesto plugin.json obrigatório (um esquema fechado com exatamente dez campos de nível superior permitidos — $schema, name, version, description, author, homepage, repository, license, keywords, extensions — no qual “Os clientes DEVEM relatar e ignorar cada campo desconhecido”), uma pasta skills/ opcional (cada diretório filho imediato que contém um SKILL.md representa um skill), um arquivo mcp.json opcional que declara servidores stdio, Streamable HTTP ou HTTP+SSE legado, e diretórios opcionais com namespace de cliente em domínio reverso que outros clientes “DEVEM ignorar”. Seu escopo normativo é o empacotamento: a especificação “define a especificação canônica Agent Plugins v1.0.0 para empacotar componentes reutilizáveis que estendem agentes de IA em plugins distribuíveis” — Agent Skills e MCP mantêm suas próprias especificações abaixo dela.¹⁶¹

A governança é o ponto central. 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 passaria a integrar o grupo principal de mantenedores.¹⁶¹ Os clientes de lançamento mencionados incluem ChatGPT, Codex, Cursor, GitHub Copilot, Kiro e VS Code. Uma ausência chama a atenção: Anthropic, responsável pela criação do formato Agent Skills subjacente e do próprio MCP, não está entre os mantenedores — Claude Code mantém seu próprio formato de plugins, e o Codex preenche essa lacuna do seu lado com a origem de marketplace Claude Code (v0.146.0) e /import.¹⁶¹

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

As notas de versão anunciam as interfaces do Codex sem publicar suas chaves de configuração nem a sintaxe da CLI. Este texto registra que o recurso foi lançado e o que o padrão especifica, não como utilizá-lo no Codex — considere o fluxo de criação de manifestos e qualquer uso 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
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

A v0.153.0 amplia a CLI de plugins, passando do gerenciamento de marketplaces para operações no nível dos plugins em marketplaces remotos: codex plugin list inclui entradas de catálogos remotos (com origem, versão, política de instalação e política de autenticação na saída JSON), e plugins remotos podem ser adicionados e removidos pela CLI de plugins já existente. Os catálogos remotos são armazenados em cache por escopo e coleção – resultados recentes do cache têm prioridade, uma solicitação de adição que não encontra um plugin no cache faz uma nova busca uma vez, e o catálogo local selecionado é preservado quando uma listagem remota sem filtro falha (os erros ainda são exibidos para marketplaces remotos selecionados explicitamente).¹⁴⁰

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

Dica para especialistas: os plugins reúnem o que antes exigia configuração separada de MCP, instalação de skills e configuração de conectores de apps. Um único plugin pode incluir os três — acelerando a integração da equipe e tornando a configuração mais portável.

Modo de planejamento e colaboração

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

Modo de planejamento vs ferramenta update_plan (v0.152.0): são duas coisas diferentes, e apenas uma delas vem ativada por padrão. O modo de planejamento — o modo de colaboração descrito nesta seção, no qual o Codex apresenta uma proposta antes de executá-la — vem ativado por padrão desde a v0.94.0 e não mudou. update_plan é uma ferramenta de planejamento que o modelo pode chamar para manter um plano estruturado durante um turno. Ela foi lançada como recurso opt-in na v0.152.0: tools.update_plan.enabled tem false como padrão e, enquanto estiver desativada, o Codex também remove as orientações integradas de update_plan dos prompts de modelo, modo de colaboração, multiagente, compactação, pré-aquecimento e continuação de objetivos (as instruções básicas personalizadas, as instruções do catálogo de modelos, as políticas de colaboração e o texto do objetivo do usuário são preservados mesmo quando mencionam planejamento). Ative-a explicitamente com tools.update_plan.enabled = true no config.toml.¹³⁸

Como entrar no modo de planejamento

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

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

Modo Steer

O modo Steer (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á dois métodos de inserção:

Exemplos práticos:

# Codex is refactoring the auth module...

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

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

O modo Steer está sempre ativo na TUI. Se você preferir esperar o Codex terminar antes de dar 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)

Realce de sintaxe (v0.105.0): agora, a TUI realça a sintaxe de blocos de código delimitados e diffs inline. 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 usando a transcrição de voz. Esse recurso é experimental e pode exigir permissão para acessar o 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ê possa escolher hardwares específicos 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 retomou a voz 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.¹¹² v0.155.0 e v0.156.0: conversas de voz ao vivo. A v0.155.0 (17 de setembro de 2026) adicionou /voice como um recurso experimental opt-in: uma conversa ao vivo com transcrição via streaming e controles de microfone, ativada por /experimental nas builds compatíveis (#43581, #43651, #44331), com um atalho configurável para silenciar o microfone (#43690) e recursos de voz assinados nos pacotes para macOS (#43983). A v0.156.0 (22 de setembro de 2026) tornou o recurso estável e ativado por padrão (#44921), e o changelog da documentação anunciou no mesmo dia: “As conversas de voz são ativadas por padrão, com uma tecla F8 para alternar o recurso, um seletor de /voice settings e runtimes de áudio incluídos para Linux e Windows.” Para desativá-lo, defina realtime_conversation = false em [features] no config.toml. A referência de slash commands CLI ainda não lista /voice, e a página do recurso Voice na documentação aborda o ChatGPT Voice no aplicativo para desktop, uma interface separada.¹⁵⁶¹⁶⁹

Outras melhorias: - Links longos agora continuam clicáveis mesmo quando quebrados em várias linhas da TUI (v0.105.0)⁶¹ - Links de arquivos locais são exibidos com uma formatação melhor (v0.106.0)⁶⁰ - O markdown da TUI mantém links da web clicáveis por meio de metadados OSC 8, e tabelas com pouco espaço são convertidas em registros legíveis de chave/valor sem perder os destinos dos links (v0.136.0)¹⁶⁸ - Links em markdown aparecem como rótulos clicáveis nos terminais compatíveis, enquanto os URLs visíveis são mantidos nos demais (v0.150.0)¹³² - O processamento de Ctrl+C para subagentes 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 em ~/.codex/memory/. O Codex as carrega no início da sessão e as utiliza 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 está em src/core/auth/, não em src/middleware/“
• Preferências de fluxo de trabalho: “Sempre execute o linter antes de me mostrar um diff”

Memória em pipelines

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

Aprimoramentos da memória (v0.101.0–v0.107.0)

• Remoção de dados confidenciais: as memórias são verificadas automaticamente em busca de dados confidenciais antes de serem gravadas no disco
• Consciência 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 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, priorizando memórias acessadas com frequência e que foram 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 se desvia do esperado⁶²
• 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 vez do padrão anterior). O pipeline da fase 2 é executado entre as 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 na TUI (v0.121.0): uma nova interface 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, portanto, a redefinição limpa a superfície de recuperação futura 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

O Codex mantém as sessões em ~/.codex/sessions/, permitindo retomar, bifurcar e usar fluxos de trabalho com várias threads entre o CLI e as interfaces desktop.

A 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, sem obrigar você a fechar uma para acessar outra.¹¹⁴ Na prática, um projeto de longa duração deixa de ser uma lista de registros de data e hora que você precisa reconhecer pela data. A v0.147.0 adiciona seções de conversas: as conversas são organizadas em seções persistentes, ordenadas manualmente, e transcrições longas podem ser navegadas de forma incremental, em vez de serem carregadas por inteiro.¹¹⁶ A v0.148.0 adiciona /export e bifurcação pela linha de comando: /export grava a conversa completa em Markdown (na área de transferência ou em um novo arquivo), codex exec fork bifurca uma sessão de forma não interativa, e o seletor de retomada pode arquivar e restaurar sessões.¹¹⁸ A v0.149.0 adiciona codex queue — envie mensagens para sessões locais ou remotas existentes pela linha de comando — e corrige threads retomadas ou bifurcadas para que restaurem o perfil de permissões ativo.¹²⁰ A v0.150.0 adiciona títulos automáticos: tarefas sem nome no terminal recebem títulos descritivos automaticamente, e /rename sugere um título editável com base na conversa.¹³² A v0.151.0 adiciona /recap: solicite quando quiser um breve resumo do progresso recente e dos próximos passos da conversa; o Codex também gera o mesmo resumo automaticamente para conversas qualificadas que estejam ociosas e fora de foco, adicionando-o à transcrição, com solicitações limitadas e isoladas e novas tentativas apenas em caso de falhas automáticas.¹³⁵ A v0.153.0 torna a parte automática opcional: tui.auto_recap = false cancela as verificações automáticas de resumo agendadas e descarta resultados automáticos pendentes, enquanto o /recap manual continua funcionando.¹⁴⁰

codex agents (v0.149.0) é o painel interativo para todas as sessões de agentes ativas na máquina: pesquise, inicie, abra, renomeie e interrompa tarefas em uma única tela, com atalhos configuráveis. Dentro de uma sessão, /agents alterna entre todas as sessões de agentes ativas, e /subagents alterna entre os subagentes da sessão atual.¹²⁰¹²⁹ A v0.150.0 torna as tarefas endereçáveis a partir da conversa: faça referência a outras tarefas do Codex com menções usando @ e peça aos agentes que leiam, criem ou enviem mensagens para tarefas pelo terminal.¹³²

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 pesquisa.

Histórico de threads paginado (v0.145.0, promovido na v0.151.0): o histórico de threads paginado oferece retomada eficiente, pesquisa em todo o histórico, nomes de threads persistentes, suporte a subagentes 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 faz diferença em diretórios de trabalho de longa duração com centenas de sessões. Introduzido como experimental na v0.145.0; a v0.151.0 retira os APIs da fase experimental (thread/turns/list, thread/items/list e thread/revert não precisam mais do recurso experimental API) e torna o modo paginado o padrão resolvido SOMENTE para threads duráveis cujo armazenamento seja compatível com thread/turns/list e thread/items/list, e apenas quando thread/start omite historyMode. Threads efêmeras e threads apoiadas por armazenamentos sem esses APIs ainda usam o modo legado como padrão, seleções explícitas mantêm seu comportamento, e o enum ThreadHistoryMode no nível do protocolo ainda usa Legacy como padrão na tag rust-v0.151.0 (protocol.rs:755-758) — um padrão resolvido para threads duráveis compatíveis, não uma alteração generalizada.¹¹²¹³⁵

Bifurcar

Crie uma ramificação da conversa para explorar alternativas sem perder o 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. Desde a v0.146.0, o histórico das bifurcações é paginado, e elas podem ser criadas como temporárias — uma bifurcação temporária não aparece nas listagens de threads, mantendo experimentos descartáveis fora da lista de threads que você realmente usa para navegar.¹¹⁴ As alterações em uma bifurcação não afetam a outra. Isso é útil para comparar abordagens (por exemplo, “bifurque e experimente Redis em vez de Memcached”) ou explorar alterações arriscadas com segurança.

Bifurcação de threads em subagentes (v0.107.0): agora, as threads podem ser bifurcadas em subagentes independentes, permitindo que uma conversa crie fluxos de trabalho paralelos executados de forma autônoma. Isso amplia o modelo de bifurcação existente — em vez de apenas criar uma ramificação da conversa, a thread bifurcada se torna um subagente com seu próprio contexto de execução.⁶² Desde a v0.117.0, os subagentes usam endereços baseados em caminhos (por exemplo, /root/agent_a) com mensagens estruturadas entre agentes, tornando a coordenação multiagente mais explícita e fácil de depurar.⁷⁵

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

• Os logs da sua sessão local não contêm mais o texto simples da delegação. Você pode ver que um agente pai criou um subagente e o que retornou, mas não a instrução exata enviada. Se você audita ou depura execuções multiagente pelo histórico da sessão, esse registro não está mais disponível; o issue de regressão aberto que acompanha esse problema não tinha nenhuma correção vinculada até meados de julho de 2026.¹⁰⁹ Eventos do ciclo de vida de extensões (início/interrupção de subagentes, 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 deixar de funcionar. Um endpoint de modelo que não esteja configurado para o uso de ferramentas criptografadas rejeita o schema criptografado de spawn_agent com um erro 400 ("declares encrypted parameters but is not configured for encrypted tool use"). Se a delegação multiagente falhar com esse erro em um provedor personalizado, a causa é a mudança na criptografia, não a sua configuração.¹⁰⁹
• As notificações geradas pelo Codex continuam legíveis. As notificações de conclusão dos agentes filhos são produzidas pelo próprio Codex, então permanecem em texto simples e agora são renderizadas como itens agent_message tipados, 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 do texto cifrado sem informar contra o que ele oferece proteção.

Multiagente v2 estabilizado (v0.145.0, ativação opcional): a experiência multiagente v2, lançada na v0.137.0 e ampliada com delegação criptografada na v0.138.0, agora está estabilizada como um recurso de ativação opcional. A v0.145.0 adiciona modelos configuráveis para subagentes, níveis de raciocínio por subagente, simultaneidade configurável, funções multiagente restauradas e navegação aprimorada entre agentes. Se você decidiu não adotar a v2 durante o período de instabilidade das versões v0.137/v0.138, esta é a versão em que a configuração se estabiliza — as escolhas de modelo e raciocínio dos subagentes agora ficam na configuração, em vez de serem definidas 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 dos diffs.

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 -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
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 bifurcações focada, sem excluir o histórico. Arquive pela TUI com /archive ou pelo shell:¹⁶⁸

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

Uma sessão arquivada fica protegida contra operações de retomada ou bifurcação até que você a desarquive — uma proteção contra continuar acidentalmente 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 é impedido de executar auxiliares do Git fornecidos pelo repositório (uma correção de segurança de comandos). No Windows, um fluxo de provisionamento em fase alfa adiciona codex sandbox setup --elevated para administradores.¹⁶⁸

Saída em linhas JSON

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

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

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

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

Saída estruturada

Imponha o formato da resposta com o 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

Flags principais

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 o seu CI extrai dados da saída de inicialização, o texto do banner agora é mais enxuto; os eventos estruturados de --json não mudaram.⁹¹

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 ambiente de execução do app-server incluído nas interfaces para desktop e IDE.⁹¹ A v0.133.0 aprimora o formato de execução do comando: ele pode funcionar 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 os APIs de paginação do app-server abaixo ao criar UIs que precisam enumerar históricos extensos de threads sem carregar cada turno na memória de uma só vez.

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

Os clientes do app-server agora podem paginar threads extensas por meio de três visualizações distintas dos itens dos turnos:⁹¹

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: os clientes do app-server agora podem enumerar os ambientes disponíveis, listar as threads descendentes de uma thread e bifurcar o histórico a partir de um turno específico — os elementos básicos de que uma UI precisa para ramificar uma execução a partir de um ponto anterior sem reproduzi-la até esse ponto.¹⁰⁶ A v0.151.0 remove os APIs de histórico paginado de threads da fase experimental e faz com que threads duráveis com stores compatíveis usem por padrão o histórico paginado quando thread/start omite historyMode (threads efêmeras e stores incompatíveis continuam no modo legado); o carregamento do histórico completo está obsoleto para threads paginadas (#40676).¹³⁵

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

As threads ativas do app-server agora aplicam alterações em config.toml sem exigir uma reinicialização — edite a configuração, salve e a thread em execução refletirá os novos valores no próximo turno. 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.⁹¹

Configurações dinâmicas no escopo do turno (v0.151.0): as configurações de um turno em execução agora podem ser alteradas durante a execução. O método experimental turn/settings/update do app-server atualiza model, effort, summary e serviceTier nas etapas seguintes de um turno ativo específico sem alterar turnos futuros, informando se a atualização foi aplicada, rejeitada ou se perdeu o alvo; as restrições gerenciadas são revalidadas, e as propriedades de aprovação admitidas do turno e de segurança do Guardian são preservadas antes da publicação de um snapshot atualizado das configurações. turn/start também aceita serviceTierForTurn, permitindo que um novo turno substitua o nível de serviço sem alterar o nível salvo da thread (“default” significa velocidade padrão; quando omitido ou definido como null, herda o nível da thread).¹³⁵

Executores remotos criptografados (v0.141.0)

A partir da 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 de um limite de rede. A mesma versão fez com que a execução remota multiplataforma preservasse o diretório de trabalho e o shell nativos do executor, portanto, quando um controlador em um sistema operacional controla um executor em outro, os caminhos e a semântica do shell não são mais reescritos de forma implícita. O TLS agora também aceita assinaturas de certificado P-521 para compatibilidade com proxies corporativos.¹⁰³

Codex Cloud e tarefas em segundo plano [EXPERIMENTAL]

Suporte ao GitLab (beta, 19 de agosto de 2026): o Codex cloud agora se conecta a projetos do GitLab em todos os planos do ChatGPT — vincule um projeto, crie ambientes, inicie tarefas a partir de issues e merge requests e solicite revisões; o Self-Managed GitLab requer a versão 19.0 ou posterior.¹¹⁹

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.⁴ A partir do CLI v0.150.0, as tarefas também podem ser acessadas em uma conversa no terminal: faça referência a outras tarefas do Codex com menções usando @ e peça aos agentes para ler, criar ou enviar mensagens às tarefas.¹³² Consulte também GitHub Action e CI/CD para integrar o Codex ao seu pipeline de CI.

Credenciais de tarefas na nuvem reforçadas (v0.152.0): as solicitações de tarefas na nuvem podem incluir credenciais salvas do ChatGPT, por isso o destino agora é restringido antes mesmo do carregamento da autenticação — CODEX_CLOUD_TASKS_BASE_URL é validada em relação a origens confiáveis da HTTPS do ChatGPT na porta 443 (URLs que contêm informações de usuário, consultas ou fragmentos são rejeitadas), e os redirecionamentos são desativados no backend de tarefas na nuvem e nos clientes de descoberta de ambientes, garantindo que as credenciais nunca sejam encaminhadas a um destino de redirecionamento.¹³⁸

Como funciona

1. Envie uma tarefa (pelo chatgpt.com/codex, pela integração com o Slack ou pelo 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: sem acesso do agente à internet (padrão)
• Ativado: allowlist opcional de domínios + 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 thread do Slack para iniciar uma tarefa na nuvem.

Pré-requisitos: 1. Plano elegível do ChatGPT (Plus, Pro, Business, Enterprise ou Edu) 2. Conta 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 na nuvem

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

O Codex Desktop App

O Codex Desktop App (macOS e Windows) oferece uma interface gráfica otimizada para 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 nativo do Windows.⁶⁶

Instalação

codex app                      # Auto-downloads and installs on first run

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

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 poderosa, 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 e o texto visível ou fora da tela disponibilizado pelo app, além de armazenar o anexo localmente no histórico da sessão.⁹⁹

Para trabalhos de web e 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 assets e inspeção somente leitura de JavaScript, e permite marcar regiões da página com comentários que o Codex pode atender na próxima interação.⁹⁹ Para sites que exigem login, continue usando a extensão do navegador (Chrome, Edge, Brave, Opera ou Vivaldi; o Opera não oferece chat lateral). Ferramentas do site (WebMCP, 25 de agosto de 2026): no navegador integrado do desktop app, o ChatGPT Work e o Codex podem usar ferramentas disponibilizadas por um site para interagir com a página; use o GPT-5.6 Sol ou o GPT-5.6 Terra na versão mais recente do desktop app, pois as ferramentas do site não estão disponíveis com o GPT-5.6 Luna nem em workspaces Enterprise ou Edu.¹²⁷

Use o Computer Use apenas quando uma integração estruturada ou a visualização no navegador não puder verificar a tarefa. Ele pode inspecionar e operar apps permitidos 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 permanece restrito: o Codex pode acessar temporariamente os apps permitidos durante interações ativas e confiáveis do Computer Use depois que o Mac é bloqueado, com proteções 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 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 final — você escolhe quais alterações serão integradas de volta

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

Configurações de Worktree e propriedade da thread (v0.151.0): o comportamento dos worktrees gerenciados é determinado a partir da configuração [desktop] existente por um parser de configurações dedicado — por padrão, a raiz dos worktrees é $CODEX_HOME/worktrees, a limpeza automática fica ativada e 15 worktrees são mantidos, com validação das raízes configuradas, dos sinalizadores de limpeza e das quantidades de retenção antes do uso. Cada worktree vinculado e gerenciado também pode conter um registro de propriedade codex-thread.json versionado em seus metadados Git, associando-o a uma thread: as gravações são atômicas e não sobrescrevem dados existentes (associações repetidas são idempotentes e proprietários conflitantes são rejeitados), e checkouts primários, aninhados e não gerenciados são rejeitados antes que os metadados de propriedade sejam alterados.¹³⁵

Worktrees gerenciados chegam ao CLI na v0.154.0 (experimental): --worktree na inicialização ou /worktree na TUI cria um checkout isolado para uma sessão nova ou bifurcada, codex exec oferece suporte a worktrees gerenciados para automações, e os comandos de sessão da TUI, junto com um navegador de worktrees, permitem listar, explorar e retomar sessões de worktree (#42196, #42366, #42652, #43069, #43120, #43286). A v0.155.0 adiciona recursos relacionados ao gerenciamento, enquanto os worktrees permanecem desativados por padrão: a visão geral dos agentes pode ocultar, arquivar e excluir sessões de worktree, os detalhes de propriedade ficam visíveis e a exclusão de um worktree gerenciado sem alterações exige confirmação (#43942, #44424, #44433). A ativação por padrão (#44870) foi integrada em 11 de setembro, mas NÃO fazia parte da versão estável 0.155.0, conforme verificado pela ancestralidade em relação à tag rust-v0.155.0.¹⁵²¹⁵⁶

Os worktrees gerenciados passam a ser o padrão na v0.156.0: a #44870 promove worktrees a um recurso estável, ativa-o por padrão e o remove de /experimental. Também são lançados: sessões de worktree podem se conectar a um daemon local existente em vez de iniciar um próprio (#46498), e sessões de worktree podem ser criadas diretamente na visão geral dos agentes (#45276), que também recebe abas de filtro por status (#46839). Se você tiver scripts ou configurações criados com base na premissa de que os worktrees ficam desativados quando não são solicitados, a versão 0.156.0 altera esse comportamento. Para desativá-los: defina worktrees = false em [features] no config.toml (por execução: --disable worktrees). Daemons locais mais antigos: se a criação de um worktree ou o uso de /cd for bloqueado com a mensagem “The local Codex service cannot check background terminals”, execute codex app-server daemon update e reinicie o Codex.¹⁶⁹¹⁷¹

Ferramentas de worktree para o modelo (v0.162.0): em um projeto local confiável com o recurso ativado, o próprio modelo pode criar e listar worktrees gerenciados por meio de novas ferramentas (#50148), e os prompts de nova conversa e bifurcação explicam as opções de worktree (#50416).¹⁸⁷

Automações

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

• Em repositórios Git, as automações usam worktrees dedicados em segundo plano (isolados do diretório de trabalho)
• Em projetos que não usam Git, as execuções ocorrem diretamente no diretório do projeto
• As automações usam as configurações padrão do seu 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: classifique 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 no Windows em 4 de março de 2026 (App v26.304), com suporte nativo ao PowerShell, sandbox nativo do Windows e paridade total de recursos, incluindo skills, automações e worktrees, sem exigir o 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 posteriores.

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 workflows do Codex.

SDK do Codex

O SDK da TypeScript incorpora os recursos de agente do Codex a aplicativos personalizados.¹⁹

Instalação

npm install @openai/codex-sdk

Uso básico

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

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

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

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

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

Recursos avançados do SDK

• runStreamed(...): Stream assíncrono de eventos para atualizações intermediárias
• Autenticação do SDK da Python (v0.132.0+): login com chave da API, fluxos do navegador/código do dispositivo do ChatGPT, inspeção da conta e logout são caminhos nativos do SDK.⁹⁷
• Praticidade para turnos somente de texto (v0.132.0+): as APIs de turno da Python aceitam strings simples e retornam metadados mais completos de TurnResult, incluindo itens coletados, duração e uso.⁹⁷
• outputSchema: Impõe uma saída final no formato JSON
• Entrada multimodal: Envia texto + imagens locais ({ type: "local_image", path: "..." })
• Workflows de imagem (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas e o histórico de imagens é preservado ao retomar uma 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 + diretório de trabalho por turno e refinadas na v0.125.0 com ambientes persistentes), view_image agora resolve os caminhos dos arquivos 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 mantidas em ~/.codex/sessions.

Runtime: Node.js 18+.

Otimização de desempenho

Gerenciamento de contexto

As janelas de contexto variam conforme o modelo. A família GPT-5.6 atual (Sol, Terra, Luna) opera com uma janela de 272K; o GPT-5.5, modelo principal da geração anterior, oferece 400K no Codex (1M na API); o GPT-5.4 / GPT-5.4-mini (que serão descontinuados no 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). Todas elas se esgotam mais rápido do que você imagina — gerencie-as de forma proativa:

1. Use /compact regularmente: resume o histórico da conversa para liberar tokens
2. Forneça documentação local: um AGENTS.md bem elaborado e uma documentação local de qualidade reduzem o trabalho de exploração (que consome contexto)
3. Use @ para anexar arquivos específicos: referencie os arquivos diretamente em vez de pedir ao Codex que os encontre
4. Mantenha os prompts focados: prompts bem delimitados e com os arquivos exatos consomem menos contexto do que explorações em aberto

Gerenciamento de contexto experimental (v0.153.0, desativado por padrão): features.context_management.experimental_mode ativa uma pilha de contexto coordenada — contexto com orçamento de tokens, notas do histórico e uma ferramenta new_context — para sessões qualificadas do ChatGPT Plus, Pro e Pro Lite que usam o backend do Codex. Sessões com chave da API, provedores personalizados, endpoints que não sejam do Codex e threads estruturadas temporárias ficam de fora, e a flag está explicitamente em desenvolvimento: trate-a como uma prévia do futuro do gerenciamento de contexto, não como algo no qual basear workflows.¹⁴⁰ A v0.154.0 adiciona uma verificação de capacidade: a qualificação é determinada com base nos recursos do modelo ativo na inicialização da sessão (#43147) — a mesma interface que a documentação dos modelos do Codex associa nominalmente ao Astra para login no Plus e no Pro (consulte a observação de contexto cruzado em Qual modelo devo escolher?).¹⁴⁶¹⁵² Na v0.157.0, nenhum modelo do catálogo incluído está marcado como compatível com esse recurso (#47397), portanto, com esse catálogo, a configuração não produz efeito.¹⁷⁴ O GPT-6.1 Sol, adicionado na v0.159.1, também não está marcado, e a referência de configuração agora descreve a chave como “indisponível no momento”.¹⁷⁸