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, aplica patches em arquivos e delega tarefas à nuvem. Domine cinco sistemas – config.toml, o modelo de sandbox/aprovação, AGENTS.md, MCP e skills – e ele se tornará um multiplicador de produtividade. Qual modelo usar: a documentação de modelos da OpenAI agora recomenda o GPT-6 Sol (gpt-6-sol, disponível no seletor do CLI desde a v0.156.1) para tarefas cotidianas e complexas de programação, o GPT-6-Astra para os trabalhos completos mais difíceis (ainda é o padrão integrado do CLI quando nenhum modelo é definido) e o GPT-6 Luna para tarefas específicas e de alto volume. A disponibilidade depende do plano, das configurações do workspace e da implementação gradual, e os modelos GPT-5.6 continuam disponíveis enquanto isso; o GPT-5.5 deixará de estar disponível no Codex para login com o ChatGPT em 14 de outubro de 2026.¹⁴⁶¹⁷¹ 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.157.1 (26 de setembro de 2026); os Destaques das versões começam com um resumo do estado atual (o que vem ativado por padrão e o que ainda é experimental) e depois abordam cada versão, enquanto o Changelog lista todas as atualizações do guia.¹¹⁶¹⁷⁴

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, aplica patches em arquivos, conecta-se a serviços externos por meio do MCP e delega tarefas demoradas à nuvem. Ele roda localmente, mas pensa globalmente; a mesma inteligência alimenta cinco interfaces distintas, dependendo de como você trabalha, 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 de forma casual ou eficaz se resume a cinco sistemas principais. Domine-os e o Codex se tornará um multiplicador de produtividade:

1. Sistema de configuração: controla o comportamento por meio do config.toml
2. Modelo de sandbox e aprovação: controla o que o Codex pode fazer
3. AGENTS.md: define os 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 conhecimentos especializados reutilizáveis

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 em equipe. 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 pegam até usuários experientes de surpresa.

Principais conclusões

• Cinco interfaces, um só cérebro: CLI, aplicativo para desktop, extensão para IDE, tarefas na nuvem e extensão para navegador (Chrome, Edge, Brave, Opera e Vivaldi) compartilham a mesma família de modelos, então escolha a interface que melhor se adapta 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 entre diferentes 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 profiles 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 integrado do Codex oferece ao GPT-6 Astra, Sol e Luna e à família GPT-5.6 uma janela de contexto de 272 mil tokens (o API informa 1,05 milhão para o GPT-6 Sol e Luna); o GPT-5.5 oferece 400 mil no Codex até ser descontinuado nessa plataforma em 14 de outubro de 2026. Use /compact, prompts específicos e referências a @file para gerenciar os limites de tokens de forma proativa.⁸³¹¹²

Como usar este guia

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

O Cartão de referência rápida no final oferece 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, da mais recente para a mais antiga, 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 conferências da documentação) estão nas notas de rodapé.

Estado atual

Codex CLI em 26 de setembro de 2026

• Estável: v0.157.1, publicada em 26 de setembro (npm latest), uma correção para Windows sobre a v0.157.0 (25 de setembro).
• Alpha: a versão npm alpha é a 0.159.0-alpha.4. A linha 0.158 não gerou uma versão estável.
• Ativados por padrão desde a v0.157.0: a transcrição em tela cheia, a inicialização automática do servidor em segundo plano e o contexto de thread do Guardian. Para desativar um deles, defina fullscreen_transcript = false em [tui], daemon_auto_start = false em [features] (ou inicie com --no-daemon) ou thread_context = false em [features.guardianv2].
• Ativados por padrão desde a v0.156.0: /voice, worktrees gerenciadas e reutilização da compactação da thread principal pelo Guardian (chaves realtime_conversation, worktrees e guardian_reuse_parent_compaction em [features]).
• Ainda opcionais ou experimentais: gerenciamento experimental de contexto, Codex Cloud e modo de código.
• Modelos: GPT-6 Sol (gpt-6-sol) para programação cotidiana e complexa, GPT-6-Astra para os trabalhos completos mais difíceis (ainda é o padrão incluído no CLI quando nenhum modelo é definido) e GPT-6 Luna para tarefas de alto volume. O GPT-5.5 deixa o Codex para logins com o ChatGPT em 14 de outubro de 2026.
• Fixação da versão: npm install -g @openai/codex@0.157.1; depois, confirme com codex --version.¹⁷⁴¹⁷⁵

v0.157.1 (26 de setembro de 2026)

Uma correção para Windows composta por quatro ajustes retroportados da branch principal. O Codex não abre mais uma janela do console ao iniciar o host do modo de código ou um servidor MCP stdio local. O servidor em segundo plano agora pode ser iniciado quando o Windows mantém o processo dentro de um objeto de job externo, e um servidor em segundo plano desvinculado não mantém mais abertos os pipes de saída do inicializador, algo que podia deixar o comando de chamada aguardando mesmo após o encerramento do inicializador. As notas da versão do 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ê usa 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 ativa mais três padrões.

• A transcrição em tela cheia está ativada por padrão. A interface em tela cheia oferecida pela v0.156.0 por meio de /tui agora é aquela em que uma sessão é aberta, 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" continuam tendo precedência. Agora, clicar enquanto pressiona Shift amplia uma seleção da transcrição.
• O servidor em segundo plano é iniciado automaticamente em execuções interativas qualificadas, e a opção sai de /experimental. Execuções com --no-daemon, --oss, --profile ou a maioria das substituições com -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 (a opção padrão). Para desativar a inicialização automática, defina daemon_auto_start = false em [features].
• O contexto de thread do Guardian está ativado por padrão para revisões síncronas e assíncronas, independentemente da opção 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, restando o Fast. O catálogo incluído não indica mais que o GPT-6-Astra é compatível com o gerenciamento experimental de contexto (consulte Gerenciamento de contexto).

Outras novidades: o atalho f cria uma ramificação 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 transitórias com um timeout de cinco minutos e aplicam restrições de rede durante redirecionamentos e conexões HTTP e WebSocket abertas. No Windows, o acesso a objetos do sandbox fica limitado à sessão de login do executor.¹⁷⁴

v0.156.1 (23 de setembro de 2026)

Uma correção com uma única mudança que leva o GPT-6 Sol e o GPT-6 Luna ao CLI estável. 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 nenhum modelo é definido em config.toml. O seletor passa a classificar 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, o prompt de troca agora sugere gpt-6-luna em vez de gpt-5.6-luna.

Se a sua configuração especifica um modelo antigo, espere um prompt de migração exibido uma única vez: seleções salvas de gpt-5.6-sol, gpt-5.6-terra, gpt-5.5 e gpt-5.4 passam a apontar para o GPT-6 Sol, enquanto gpt-5.6-luna e gpt-5.4-mini passam a apontar 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 o Fast (priority) como nível de serviço padrão do GPT-6 Sol e do Luna, portanto uma sessão da TUI sem service_tier definido pode iniciar no modo Fast, que no login com o ChatGPT cobra 2,5 vezes os créditos do Standard. Confira com /fast status; /fast off muda para o 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 implantação; administradores Enterprise precisam habilitar os novos modelos primeiro.¹⁷¹

v0.156.0 (22 de setembro de 2026)

A versão que ativa 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 precisar acessar /experimental. Também são novidades: um atalho F8 configurável, um seletor /voice settings para a voz usada em conversas futuras, runtimes de voz incluídos para Linux e Windows e suporte à redução de movimento.
• As worktrees gerenciadas estão ativadas 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 sobre o Guardian.

Outras novidades: uma TUI opcional em tela cheia, 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 sua própria opção; um menu /daemon e uma flag --no-daemon; e resumos de raciocínio desativados por padrão para novas threads da TUI. Correções de segurança eliminam falhas no sandbox do Windows relacionadas a tráfego de entrada, sockets privilegiados e handles de arquivos somente leitura, e codex doctor não repete mais valores de configuração nas mensagens de erro. As correções de bugs preservam respostas transmitidas após turnos interrompidos ou com falha, corrigem o encaminhamento da área de transferência no tmux e no SSH, restauram o modo Plan ao retomar uma sessão e permitem que o login se recupere 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 completamente a solicitação. A versão 0.155.1 restaura none como fallback, portanto uma chave não definida não solicita resumos. 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 aplicada à 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 falhavam com um provedor que não fosse da OpenAI ou que fosse auto-hospedado, atualize. Se quiser resumos, defina explicitamente a chave (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 abria uma conversa ao vivo com transcrição em tempo real e controles de microfone, habilitada por /experimental em builds compatíveis, com um atalho configurável para silenciar e recursos de voz assinados nos pacotes do macOS. Cinco dias depois, a v0.156.0 o ativou por padrão. As worktrees gerenciadas permaneceram desativadas 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 ao 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 de agentes, consulte detalhes de propriedade e confirme antes de excluir uma worktree gerenciada sem alterações.
• Resumos de raciocínio ao vivo são transmitidos na linha de status da TUI, com horários de conclusão nos 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 AWS do Amazon Bedrock e publicação de Python SDK alinhada aos lançamentos estáveis do CLI.

As correções de segurança eliminam escapes pela interoperabilidade com o 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 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 gerenciadas 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 inline 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, detectados pelo app-server e selecionáveis por nome na TUI.
• Modo de substituição R do Vim, status em tempo real da compactação do contexto e gerenciamento experimental de contexto condicionado à capacidade do modelo na inicialização da sessão.

Segurança: auxiliares do PATH não são mais executados antes que a confiança no workspace seja estabelecida, e o sandbox do macOS foi reforçado contra injeção de entrada no terminal. As conexões do MCP coordenam atualizações dos tokens do OAuth, a retomada e a ramificação remotas preservam as permissões salvas, e retomar uma conversa aberta em outro app mostra 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)

Correções lançadas no mesmo dia que levaram o lançamento do GPT-6-Astra ao CLI. A v0.153.3 adicionou o Astra aos catálogos do Amazon Bedrock (o GPT-5.6 Sol permaneceu como padrão do Bedrock) e corrigiu as orientações do Astra sobre esclarecimentos assíncronos. A v0.153.4 adicionou o Astra ao seletor de modelos, tornou-o o padrão incluído quando nenhum modelo é 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 a sua conta não tiver acesso ao modelo selecionado pelo padrão incluído, defina model explicitamente em 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 de uso do computador e as decisões rápidas de aprovação só são executadas quando os metadados do modelo ativo definem node_repl_auto_review_required, e uma troca para um modelo que ignora a pontuação invalida pontuações anteriores ou em andamento, portanto voltar ao modelo anterior não pode reativar uma aprovação obsoleta. O texto da versão lista apenas uma entrada retroportada do catálogo do GPT-6-Astra, 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 “2x de velocidade, maior uso” (apenas o 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 de mapeamento de teclas configurável.
• Marketplaces remotos de plugins: o CLI de plugins pode listar, instalar e remover plugins remotos, e codex plugin list mostra a origem, a versão, a política de instalação e a política de autenticação.
• tui.auto_recap = false desativa recapitulações automáticas; o comando manual /recap 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/95%.
• O escopo do Guardian acompanha o modo de aprovação: Full Access ignora revisões do Guardian para ações que exigem apenas confirmação, e o modo de aprovação User ignora a pontuação em segundo plano e o pré-aquecimento.
• 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 Plus, Pro e Pro Lite qualificadas no backend do Codex.
• tui.disable_paste_burst substitui a chave de nível superior, que ainda funciona como fallback.

Correções: 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 sobrevive à compactação, às reinicializações e às ramificações, 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 como padrão e, enquanto estiver desativado, as orientações incluídas de update_plan são removidas dos prompts de modelo, modo de colaboração, multi-agent, compactação, pré-aquecimento e continuação de objetivos (consulte Modo Plan e colaboração). Outras novidades: pesquisa no Vim com / e ?, além de n/N, combinável com operadores, com novos rascunhos iniciados no modo Insert; banners acionáveis de limite de uso; progresso da atualização de credenciais, incluindo a reautenticação do 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; timeouts configuráveis para thread/shellCommand; e orçamento de tokens ativado por padrão por meio dos metadados do modelo. A v0.152.1 permite que a revisão de aprovações do Guardian obtenha sua política do Node REPL nos metadados do modelo.¹³⁸¹³⁹

v0.151.0 (29 de agosto de 2026)

• /recap resume a conversa quando solicitado, e o Codex recapitula automaticamente conversas qualificadas que estejam ociosas e fora de foco.
• Hosts do modo de código deixam de usar o transporte WebSocket (apenas stdio e gRPC).
• Threads duráveis usam por padrão um histórico paginado quando o armazenamento oferece suporte.
• O nível de raciocínio persistent chega com ferramentas de relógio e orientações de proatividade incluídas.
• O Guardian v2 usa por padrão revisões de uso do computador com imagens.
• O Vim recebe os movimentos de busca f/F/t/T, além de gg/G.
• Entradas em terminais escalados podem 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 extensões podem inspecionar ou substituir resultados de 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 mudanças de permissão. O texto da versão lista 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 recebem 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 ser endereçáveis com menções @, os agentes podem ler, criar e enviar mensagens para tarefas, e /rename sugere um título editável. Links Markdown são renderizados como rótulos clicáveis, atalhos podem alternar entre modos de permissão, o Vim recebe 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 e desativadas por padrão. A v0.150.1 contabiliza imagens preservadas 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 especificam 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 endpoints, falhas de rede e proxy, estado do app para desktop e conectividade de atualização) e níveis de raciocínio max/ultra nos SDKs. Threads retomadas e ramificadas restauram seus perfis de permissão. 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 o preço do GPT-5.6 Sol em mais de 20% por três meses a partir de 21 de agosto (pelo menos até 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 pesquisa entre catálogos, o protocolo opcional MCP 2026-07-28 e seções de conversa. A v0.148.0 adiciona /export para Markdown, codex exec fork, estimativa de créditos ou custo em /status, Amazon Bedrock Runtime como provedor integrado, hooks assíncronos capazes de invocar o MCP e restrições do sandbox que bloqueiam o acesso em caso de caminhos negados ou 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; manifests de Agent Plugins, além dos marketplaces do Amazon Bedrock e do Claude Code; nomeação de sessões com fixação de threads; skills fornecidas pelo executor; padrões reforçados de revisão automática para modelos com capacidades cibernéticas.¹¹⁴¹¹⁵
• v0.145.0 (21 de julho): /import do Cursor e também do Claude Code; o recurso de voz retorna como conversas V3 em tempo real com streaming; a experiência opcional multi-agent v2 é estabilizada; histórico paginado experimental de threads e login no Amazon Bedrock; 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 como 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 do API no Amazon Bedrock e armazenamento local criptografado para credenciais do OAuth do CLI e do MCP; os antigos controles de voz /realtime foram removidos.¹⁰²
• v0.139.0 (9 de junho): o modo de código pode chamar diretamente a pesquisa na web, os schemas das ferramentas preservam oneOf/allOf, codex doctor informa detalhes do editor e do paginador, e as origens dos marketplaces aparecem na saída do JSON.¹⁶⁵
• v0.138.0 (8 de junho): /app transfere uma sessão do CLI para o app para desktop, e o texto de tarefas da thread principal para subagentes é criptografado no multi-agent v2.¹⁶⁶¹⁰⁸
• v0.137.0 (4 de junho): multi-agent 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): pesquisa no histórico local de conversas, --profile como seletor principal de perfil, objetivos ativados por padrão, herança de perfis de permissão e requirements.toml gerenciado, início e interrupção com codex remote-control, codex doctor e /status mais completos, objetos de texto do Vim, perfis de permissão nomeados em /permissions, autenticação do Python SDK e predefinições de Sandbox, além de codex exec resume --output-schema. A atualização do app em 21 de maio adicionou Appshots, disponibilidade geral do modo Goal e Computer Use bloqueado opcional.^{96979899100101176}

O legado --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, sandbox e políticas de aprovação, config.toml, AGENTS.md, skills, hooks, plugins, ferramentas multi-agent, objetivos, perfis de permissão, /voice e worktrees gerenciadas (padrão desde a v0.156.0), além da transcrição em tela cheia e da inicialização automática do servidor em segundo plano (padrão desde a v0.157.0). 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, gerenciamento experimental de contexto, Memory v2, o quadro local de mensagens dos agentes e qualquer item marcado como [EXPERIMENTAL] neste guia ou listado em /experimental; esses itens podem mudar entre versões. Removidos: --full-auto (v0.147.0), a política de aprovação untrusted (v0.149.0), codex mcp-server (v0.154.0) e js_repl.

Canal alpha: builds alpha são lançadas várias vezes ao dia, os textos das versões nas linhas alpha são placeholders, e builds lançadas fora do ciclo com base em versões mais antigas aparecem regularmente (as mais recentes: 0.155.0-alpha.16.4, 0.157.0-alpha.11.1, 0.158.0-alpha.15.1 e 0.158.0-alpha.2.1). Pelo menos duas vezes, a tag npm alpha apontou para uma delas, portanto @alpha instalou uma build mais antiga que latest. A linha 0.158 foi da 0.158.0-alpha.2 (23 de setembro) à alpha.15 (25 de setembro) sem uma versão estável; em 25 de setembro, a tag alpha passou para a linha 0.159, que está na 0.159.0-alpha.4. Se você acompanha versões alpha, confira npm view @openai/codex dist-tags e instale uma versão exata em vez de @alpha.¹⁷²¹⁷⁵ Um histórico com datas de como as linhas alpha recentes resultaram em versões estáveis está em ¹⁷³.

Como o Codex funciona: o modelo mental

Antes de se aprofundar nos recursos, 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 principal: A família de modelos GPT é a base de tudo. Em 23 de setembro de 2026, a geração atual é a GPT-6: gpt-6-sol para tarefas de programação cotidianas e complexas, gpt-6-astra para os trabalhos completos mais difíceis (e o padrão incluído no CLI quando nenhum modelo está configurado) e gpt-6-luna para tarefas específicas e de alto volume. Os modelos GPT-5.6 (Sol, Terra, Luna) continuam disponíveis durante a implementação gradual; o gpt-5.5 (contexto de 400 mil no Codex e de 1 milhão 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.^{83117146148149171} Essa camada lê arquivos, cria 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 aplica restrições no nível do kernel. No Linux, Landlock + seccomp filtram o acesso ao sistema de arquivos e às chamadas de sistema. O sandbox opera no nível do kernel, não dentro de contêineres. Em seguida, a política de aprovação decide quando solicitar confirmação humana.

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

Camada de interfaces: CLI para usuários avançados do terminal e automação. O aplicativo para desktop serve para o gerenciamento de projetos em várias threads. A extensão para IDE atende aos ciclos de edição, compilação e teste. O Cloud executa tarefas assíncronas de forma independente.

A principal conclusão: 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 para IDE em ciclos rápidos de programação, aplicativo para desktop no planejamento e na coordenação e extensão de navegador em fluxos de trabalho que exigem login no navegador.

Sumário

1. Como instalo 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ão
8. Como funcionam o sandbox e o sistema de aprovação?
9. Como funciona o AGENTS.md?
10. Hooks
11. O que é MCP (Model Context Protocol)?
12. Code Mode
13. Runtime REPL 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 para desktop
22. GitHub Action e CI/CD
23. Codex SDK
24. Otimização de desempenho
25. Como depuro problemas? — incluindo codex doctor
26. Implantação empresarial
27. Práticas recomendadas e antipadrões
28. Receitas de fluxos de trabalho
29. Guia de migração
30. Cartão de referência rápida
31. Registro 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 lançamento, os metadados dos canais e os aliases do instalador são fornecidos pela infraestrutura de lançamentos hospedada pela OpenAI, com GitHub como alternativa.¹¹⁴ Se a lista de permissões da sua rede inclui GitHub para instalações e atualizações do Codex, adicione também o host de lançamentos da OpenAI — a alternativa faz com que a ausência na lista de permissões cause uma degradação silenciosa, em vez de uma falha explícita.

# Check what you are running
codex --version                          # -> codex-cli 0.157.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 um lançamento causa problemas. O Codex segue uma linha estável com atualizações frequentes, portanto instalar uma versão exata é a maneira mais rápida de reverter – registre o problema, fixe a versão e siga em frente. Confirme a reversão com codex --version, pois uma segunda instalação ocultada no seu PATH continuará fornecendo silenciosamente o binário antigo (codex doctor sinaliza exatamente isso em Environment).

Desinstalar o pacote não remove seus dados. 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 somente se quiser realmente começar do zero – rm -rf ~/.codex também descarta config.toml, auth.json e todas as sessões armazenadas.

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

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

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

O script detecta automaticamente sua plataforma e arquitetura, faz o download do 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 Lançamentos 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 nativa com tokens restritos (promovida 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 opções 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, inclusive tarefas na nuvem.
2. Chave de API: configure pela variável de ambiente CODEX_API_KEY ou por codex login --with-api-key. Alguns recursos (threads na nuvem) podem não estar disponíveis.

Dica para especialistas: o armazenamento de credenciais pode ser configurado por meio de cli_auth_credentials_store no config.toml. Opções: file (padrão), keyring (chaveiro do sistema operacional) ou auto (usa o chaveiro, se disponível, e recorre ao arquivo como alternativa).

Login no Amazon Bedrock (v0.145.0, experimental): equipes cujo acesso a modelos ocorre pelo Amazon Bedrock contam com uma opção experimental de login com suporte a endpoint e autenticação personalizados, além da autenticação gerenciada existente por chave de API (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 multiagente dos modelos do Amazon Bedrock.¹³² A v0.151.0 adiciona uma opção do Amazon Bedrock, controlada por feature flag, aos fluxos de login qualificados da TUI: a integração inicial detecta perfis existentes da AWS e credenciais de ambiente, oferece configuração manual para perfis, chaves de acesso, variáveis de ambiente e chaves de API do Bedrock, solicita a região da AWS, oculta os segredos durante a inserçã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, inclusive durante a reautenticação de sessões do Amazon Bedrock, com o suporte das notificações estáveis modelProvider/authRecoveryStarted e modelProvider/authRecoveryCompleted do app-server, que incluem a thread, o turno, o provedor e uma mensagem destinada ao usuário.¹³⁸

Preenchimento automático do shell

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

Verificar a instalação

codex --version
# codex-cli 0.157.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ê pede uma mudança, e a sandbox e a política de aprovação determinam quando ele precisa solicitar sua autorização primeiro.

5. Faça uma alteração:

> Add input validation to the login endpoint

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

6. Use um slash command:

> /plan Refactor the database layer to use connection pooling

O Codex cria um plano sem executá-lo. Revise o plano e aprove-o para iniciar a execução.

7. Confira seu 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 baseadas na 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 shell com o prefixo !
• Painel de saída: Respostas do modelo em streaming, chamadas de ferramentas e saída de comandos
• Barra de status: Modelo, uso de tokens, branch do git e modo sandbox

Principais atalhos da TUI:

Alteração 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 janela de contexto está preenchido. Se você usa scripts ou hooks para analisar a linha de status, verifique essa mudança de formato.⁸² O Codex também exibirá um anúncio de atualização da CLI quando uma nova versão estiver disponível.

Slash commands disponíveis na TUI:

Redesign do seletor de fluxos de trabalho (v0.129.0): Retomar e criar derivações agora está mais acessível em um seletor reformulado, e um novo modo de scrollback bruto permite percorrer a transcrição sem renderização quando você precisa copiar comandos ou a saída do modelo exatamente como aparecem. Útil ao fazer a triagem de 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 tem:

• Multitarefa: Execute vários agents em paralelo e em projetos diferentes simultaneamente
• Isolamento por worktree do Git: Cada thread trabalha em uma cópia isolada do seu repositório
• Revisão de diff integrada: Adicione mudanças ao stage, reverta-as e faça commits sem sair do aplicativo
• Terminal integrado: Terminal por thread para executar comandos
• Derivação 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 e 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 ao aplicativo: Visualize páginas locais ou públicas, deixe comentários em elementos ou áreas e permita que o Codex resolva feedback visual específico
• Computer Use: Permita que o Codex opere aplicativos autorizados do Mac para trabalhos de GUI com escopo definido; o uso com o Mac bloqueado é opcional em turnos remotos qualificados do Mac Computer Use

ChatGPT Voice, com tecnologia GPT-Live (desktop 26.715, 23 de julho de 2026): O aplicativo para desktop agora pode ser controlado 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 descrevê-lo. Disponível nos planos Plus, Pro, Business, Edu e Enterprise, no aplicativo para desktop e pelo 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 com a 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 no 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 que você revise o conteúdo compartilhado, pois ainda pode haver informações confidenciais. Veja ou revogue links nos controles de dados do ChatGPT, em Shared links.¹²⁸

Quando usar o aplicativo ou a CLI: Use o aplicativo para desktop ao coordenar vários fluxos de trabalho ou quando precisar revisar diffs visualmente. Use a CLI quando quiser combinar recursos do terminal, criar scripts ou integrar com CI/CD.

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

A extensão Codex para IDE é integrada diretamente ao seu editor:

• Modo agent por padrão: Lê arquivos, faz edições e executa comandos
• Edições inline: 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:

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

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

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

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

O Codex está disponível como 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 ChatGPT para desktop. Todos os cinco são compatíveis com menções de abas e controle do navegador; o Opera não oferece suporte a chat lateral, portanto inicie as tarefas dele pelo aplicativo para desktop. A extensão foi projetada para acompanhar sua navegação normal, sem assumi-la: o Codex trabalha em paralelo nas abas em segundo plano, e 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, ele não tem acesso a nenhum.
• O navegador como bancada de trabalho: A extensão é mais indicada para trabalhos em 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 quando há conflitos.

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

1. Substituições da sessão (mais alta): flags da CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) e substituições com -c key=value
2. Configuração do projeto (.codex/config.toml, descoberta a partir do CWD, subindo até a raiz do projeto; o diretório mais próximo prevalece)
3. Configuração do usuário ($CODEX_HOME/config.toml, com o padrão ~/.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 para desktop do ChatGPT agora pode abranger várias pastas relacionadas, com uma delas definida 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 pesquisar, ler e editar 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. Isso se refere ao escopo de projetos do aplicativo para desktop, e não a uma alteração nas regras de precedência acima — a CLI ainda resolve a configuração do projeto subindo na árvore de diretórios a partir do diretório de trabalho atual.¹¹³

Referência completa de configuração

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6-sol"                    # Docs' example default; unset = bundled default (gpt-6-astra)
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"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # 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)

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

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

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 as chaves dela 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-sol"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Um arquivo de perfil é uma camada acima da sua configuração básica de usuário e abaixo das configurações do projeto e da CLI, portanto ele precisa conter apenas os valores que diferem da sua 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 em cada 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"

Aviso: A API de comunicação chat/completions (wire_api = "chat") foi descontinuada para modelos hospedados pela OpenAI, que 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)

O 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; no API da OpenAI em 24 de abril. Janela de contexto: 400K no Codex, 1M no API — o Codex limita a janela a 400K para equilibrar a capacidade de processamento e o custo entre os níveis de assinatura; o 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 informa um aumento efetivo de cerca de 20% após melhorias na eficiência de tokens). Benchmarks: 82,7% no Terminal-Bench 2.0 (SOTA atual entre os modelos disponíveis publicamente), 84,9% no GDPval (44 profissões), 78,7% no OSWorld-Verified, 98,0% no Tau2-bench Telecom (sem ajuste de prompt). A OpenAI usou GPT-5.5 + Codex internamente para reescrever a infraestrutura de processamento antes do lançamento, gerando um aumento de 20% na velocidade de geração de tokens.⁸³

O GPT-5.5 será descontinuado no Codex com login pelo ChatGPT em 14 de outubro de 2026 — a documentação dos modelos restringe a descontinuaçã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 ao API da OpenAI.¹⁵⁵ A orientação para 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, cada um “quando disponível”. Substitua gpt-5.5 nos padrões do workspace, nas configurações salvas de modelo, nas configurações gerenciadas, nos agentes personalizados, nas tarefas agendadas e nos scripts.¹⁷¹

O GPT-5.4 e o GPT-5.4 mini foram descontinuados no Codex com login pelo ChatGPT em 31 de agosto de 2026.¹¹⁷ A documentação dos modelos agora indica gpt-6-sol e gpt-6-luna como substitutos (no Enterprise e Edu, um administrador precisa primeiro habilitar o Luna); o uso por chave do API não foi afetado.⁶⁴¹⁷¹ A lista exata de modelos varia de acordo com a conta e a implementação gradual. Verifique o cache local: ~/.codex/models_cache.json.

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

Nota sobre o nível gratuito (5 de maio de 2026): o GPT-5.5 Instant foi disponibilizado gradualmente 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 qualificada ou uma chave do API.⁹²

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

Bedrock GPT-5.6 (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 compatibilidade com o nível de esforço de raciocínio max. Para equipes cujo acesso aos modelos passa por um provedor Bedrock, elas podem ser selecionadas da mesma maneira que outros modelos de provedores personalizados (consulte Provedores de modelos personalizados); o nível de esforço max é voltado aos trabalhos mais difíceis de raciocínio e com agentes.¹⁰⁶ 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 de modelos 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): a cronologia, com datas explícitas: a v0.153.1 preparou uma entrada de catálogo exclusiva do 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 no seletor e alterou o padrão incluído no CLI em 4 de setembro. O anúncio descreve uma implementação gradual que começa com um conjunto limitado de organizações (primeiro, parceiros do programa de segurança cibernética) e se estende ao ChatGPT Plus, Pro, Business e Enterprise “nos próximos dias”, além do API da OpenAI e da AWS — as informações sobre a implementação foram divulgadas pela imprensa (CNBC, Axios, Forbes, Al Jazeera, 9to5Mac).¹⁴⁵ Substituído 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 Codex” e “ativo no API”, com Plus e Business previstos para os dias seguintes, e Tibo Sottiaux, líder do Codex, complementou na mesma noite: “O Astra agora também foi disponibilizado a todos os usuários Plus e Business.” Na prática, o acesso continua irregular — relatos da comunidade em 5 de setembro mostram contas Plus ainda vendo apenas modelos GPT-5.6 no Codex — e a linha de disponibilidade da documentação dos modelos citada abaixo permanece inalterada, portanto continua sendo a declaração oficial vigente.¹⁴⁹ A documentação oficial está disponível: a página do modelo no API lista o gpt-6-astra como modelo principal, “Nosso modelo mais avançado, desenvolvido 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 de tokens com entrada máxima de 922.000 tokens, saída máxima de 128K e limite de conhecimento em 30 de abril de 2026 — com um nível documentado para contexto longo: prompts acima de 272K tokens de entrada são cobrados a 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 Luna (econômico). A documentação do Codex indica 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. A escala de raciocínio documentada do Astra no Codex é: 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 na 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. A escala permanece inalterada no novo acesso de 15 de setembro, agora com descrições de cada nível no seletor (Ultra, literalmente: “Raciocínio máximo com delegação automática de tarefas”), e os níveis Max e Ultra contam com 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 pelo 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 o padrão incluído quando nenhum modelo está configurado explicitamente 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 no CLI, não algo aplicável a 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 (com o GPT-5.6 Sol disponível nele), enquanto o novo acesso de 15 de setembro mostra a matriz de disponibilidade marcando o Astra como disponível também para o Codex cloud; a página ainda informa: “Atualmente, você não pode alterar o modelo padrão dos chats do Codex cloud.” Ressalva sobre a implementação: o acesso varia conforme a conta e, no CLI 0.153.4+, uma conta fora da implementação gradual carrega um padrão incluído que ainda não consegue executar — fixe um modelo no config.toml (ou passe -m) para garantir uma seleção determinística; desde a v0.156.1, o exemplo da própria documentação é model = "gpt-6-sol". A cobrança do modo Fast do Astra está documentada, embora a página dos modelos não indique um nível Fast: a documentação de velocidade do Codex o coloca em 2,5x os créditos do Standard com login pelo ChatGPT (“quando disponível”), e a página de preços do API apresenta tarifas do modo Fast exatamente 2x maiores que 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 exibido no catálogo — a página de velocidade não informa nenhum multiplicador de velocidade para o Astra.^145146147148 Parcialmente substituído em 23 de setembro de 2026: a documentação dos modelos não descreve mais o Astra como o modelo recomendado do Codex. A seção “Modelos recomendados” agora começa com GPT-6 Sol e 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 seu esforço inicial, o que corresponde ao catálogo incluído. O Astra continua sendo o padrão incluído no CLI quando nenhum modelo está configurado.¹⁷¹

Predefinições Power com o Astra (adição à documentação, em 6 de setembro de 2026 ou antes): o trecho 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 ativo em 7 de setembro. Literalmente: “Para contas Pro, Business (US$ 100) e Enterprise qualificadas, a implementação 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 da documentação observa que as ilustrações do seletor ainda mostram os controles do GPT-5.6. Leia isso em conjunto com a tabela de modelos acima: “Power” significava GPT-5.6 Sol com raciocínio medium; em uma conta qualificada, 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 da 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 o Sol, High para o Luna e Light (low) para o Astra.¹⁷¹

Notas experimentais entre contextos (Astra, publicadas na documentação, mediante ativaçã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 conectados com ChatGPT Plus ou Pro podem ativar o gerenciamento experimental de contexto. O Astra mantém notas entre janelas de contexto e pode pesquisar mensagens e resultados de ferramentas anteriores da mesma tarefa. Este experimento fica desativado por padrão e, no lançamento, não está disponível com login pelo Business, Enterprise ou por chave do API.” O mecanismo de ativação, literalmente: “Para ativá-lo, 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 de documentação agora a associa nominalmente ao Astra e ao login pelos planos Plus e Pro, enquanto as notas da versão v0.153.0 mencionavam sessões qualificadas Plus, Pro e Pro Lite. A v0.154.0 torna o comportamento do código mais restrito: a qualificação para o experimento agora é controlada pelos recursos do modelo ativo ao iniciar a 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 fica desativado por padrão; espere mudanças no comportamento e na qualificação.^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 o contexto experimental (#47397), e o CLI só ativa o experimento para um modelo marcado dessa forma. Portanto, com o catálogo incluído, a ativação não tem efeito; não está documentado se o catálogo fornecido às contas conectadas é diferente. A documentação dos modelos ainda descreve a ativação em 26 de setembro de 2026.¹⁷⁴

Fluxograma de seleção de modelos

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; bundled default when no model is set)
   │     │  └─ No → gpt-6-sol (everyday and complex coding; start at Medium)
   └─ GPT-6 not yet available on your account? → gpt-5.6-sol

Esforço de raciocínio

Controle quanto o modelo “pensa” antes de responder:

Os níveis compatíveis dependem do modelo. minimal está disponível apenas nos modelos GPT-5. Nem todos os modelos são compatíveis com 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 desabilitar 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+. aumenta em um nível — útil quando um problema difícil no meio da sessão justifica uma progressão temporária de medium → high → xhigh sem /effort nem -c. Quando você aceita um upgrade de modelo durante a 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 uma sessão com o slash command /model ou defina-o 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 Estruturas 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 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 em faixas por modelo (consulte a tabela acima), em vez dos multiplicadores promocionais de 2x do lançamento do Codex Desktop App em fevereiro de 2026.¹⁶¹⁶²

Aumento dos limites de uso em maio de 2026 (encerrado em 31 de maio de 2026): o Codex no plano Plus operou com um limite de 5 horas 25 vezes maior (em vez do aumento padrão de 20 vezes), e o limite do plano 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 texto — verificar o uso, gerenciar créditos, redefinir limites, notificar o proprietário do workspace e gerenciar planos — filtrados de acordo com a conta autenticada e o usuário; os dados de uso são atualizados após erros de limite e, quando indicado pelo banner, 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 é disparado quando resta menos da metade da franquia em uma janela de uso de aproximadamente cinco horas, enquanto outros 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 são para a 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 informava de 5 a 40 quando o acesso foi lançado em agosto); o modo Fast custa 2,5 vezes a tarifa de créditos Standard para GPT-6 Astra, Sol e Luna “quando disponível”, e o catálogo incluído torna Fast a categoria padrão para GPT-6 Sol e Luna na TUI, a menos que você defina service_tier. Portanto, verifique /fast status se os créditos estiverem 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.¹⁶²¹⁷¹

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

Cobrança da API

Ao usar o Codex pela API, a OpenAI cobra o uso por token de acordo com os preços padrão da API da OpenAI para o modelo selecionado (além de eventuais descontos aplicáveis por cache de prompts). Tarifas atuais da API por 1 milhão de tokens: GPT-6 Sol, US$ 2 para entrada / US$ 10 para saída; GPT-6 Luna, US$ 0,10 / US$ 0,50; GPT-6 Astra, US$ 10 / US$ 50. Para os três, prompts com mais de 272 mil tokens de entrada custam 2 vezes mais na entrada e 1,5 vez mais na saída para a solicitação inteira, e o modo Fast custa 2 vezes mais.¹⁴⁶¹⁷¹ 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 conferir as tarifas atuais.²⁰

Estratégias para otimizar 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 elevado: use xhigh somente 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. Reduza os resumos de raciocínio: defina model_reasoning_summary = "none" quando não precisar de explicações
5. Agrupe tarefas com o modo exec: codex exec evita a sobrecarga da TUI em 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 uma estimativa dos créditos ou do custo da thread para workspaces qualificados¹¹⁸

Exemplos de custos reais

Custos representativos da API para tarefas comuns (com base em um retrato dos preços do gpt-5.3-codex em meados de 2026, com raciocínio médio — as proporções relativas são semelhantes entre os modelos):

Os custos variam conforme o nível de raciocínio, o uso de cache e a duração da conversa. Use gpt-5.6-luna para tarefas rotineiras e reduza 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 com /status na TUI. A contagem de tokens inclui toda a sobrecarga, não apenas as mensagens visíveis. Se os custos surpreenderem você, verifique quantos servidores 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: - Defina requirements.toml para impor limites de modelo e de nível de raciocínio em toda a organização - Use gpt-5.6-luna em 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 limites de custo adequados - Monitore com OpenTelemetry — implantações Enterprise podem exportar a telemetria de uso para as plataformas de observabilidade existentes

Estruturas de decisão

Quando usar cada interface

Quando usar cada modo de sandbox

Quando usar cada nível de raciocínio

Modo Plan vs execução direta

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

Modo Steer: Enter vs Tab

Regra geral: Enter = “pare e preste atenção nisto 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?

Escolha um perfil pré-configurado de acordo com sua tarefa:

Arquivos de perfil (um por predefinição, em ~/.codex/; o layout antigo 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 aplica restrições no nível do kernel do sistema operacional.⁵ Consulte também Implantação empresarial para conhecer as restrições de requirements.toml que os administradores aplicam em toda a organização.

Reforço de segurança na v0.148.0: agora, as restrições do sandbox bloqueiam por padrão em caso de falha — um caminho negado ou ilegível é tratado como bloqueado em vez de ser permitido silenciosamente — 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 Unix sockets específicos em uma lista de permissões (por exemplo, docker.sock e sockets IPC de editores), e a resolução de DNS privado não é mais bloqueada por padrão.⁸²
• Linux: Landlock para restrições do sistema de arquivos + seccomp para filtragem de chamadas de sistema. Um processo auxiliar independente (codex-linux-sandbox) fornece isolamento em profundidade.⁵ O Bubblewrap (bwrap) é incluído no código-fonte e compilado como parte da build para Linux (deixou de ser opcional na v0.100.0)⁷. A v0.117.0 melhorou a confiabilidade do sandbox em distribuições mais antigas com configurações legadas de kernel.⁷⁵ A v0.129.0 reforçou a inicialização do sandbox no Linux e atualizou o Bubblewrap incluído para a versão 0.11.2, com correções de segurança do projeto original; a v0.130.0 adicionou outros reforços à inicialização.⁸⁹⁹¹
• Windows: sandbox nativo com tokens restritos (deixou de ser experimental na v0.100.0). O WSL também é compatível (herda Landlock + seccomp do Linux). A v0.117.0 inclui melhorias no sandbox com tokens restritos para aumentar o isolamento de processos.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários do runtime do desktop, permitindo que o sandbox do Windows localize binários de runtime com confiabilidade 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 burlar. O kernel aplica as restrições antes mesmo que o Codex veja a chamada de sistema.

Correções de segurança: - Desvio do sandbox por zsh-fork (v0.106.0): foi corrigida uma vulnerabilidade em que a execução do shell por meio de fork do zsh podia contornar as restrições do sandbox.⁶⁰ Se você 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 na entrada para evitar travamentos causados por payloads grandes demais.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): um novo perfil reforçado para clientes que usam devcontainers do Docker utiliza Bubblewrap para executar o sandbox dentro do contêiner. O WSL2 é compatível; o WSL1 é explicitamente rejeitado (o 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 impedir que hooks executados antes ou depois das ferramentas interfiram nas decisões do subagente Guardian.⁸² Se você depende de hooks para registros ou validação, saiba que uma revisão do Guardian os ignora — use a observabilidade do app server como alternativa caso precise 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 solicitar)

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

Desde a v0.150.0, você pode associar um atalho de teclado para alternar entre os modos de permissão no compositor — configure-o por meio de /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 de uma sequência não aprova automaticamente os comandos seguintes na mesma invocação do shell.⁴⁹

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

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

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

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

Agora, o Codex inclui uma ferramenta 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.) por meio do fluxo de aprovação da TUI, em vez de falhar silenciosamente ou exigir que o usuário reinicie com flags diferentes.

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

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

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

A nova flag --approve-for-me do CLI transforma 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 costumava incentivar e que agora foi removida) e “interromper para tudo” — as solicitações continuam existindo como pontos de decisão, mas um revisor responde a elas. Combine-a com os padrões de revisão automática mais seguros 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 sem supervisão, nas quais uma interrupção causa uma paralisação, mas inadequada para sessões que lidam com credenciais ou estado de produção, nas quais você deve ser o revisor.

Aprovação de entrada elevada no terminal (v0.151.0)

A feature flag write_stdin_approval — desabilitada por padrão — exige uma nova aprovação antes que uma entrada não vazia seja enviada a um terminal unified-exec elevado. Essas revisões são encaminhadas por hooks, Guardian, app server e TUI como aprovações writeStdin; o ambiente, o diretório de inicialização e o estado de elevação do terminal persistem entre os turnos, e a identidade do processo é validada novamente 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 que qualquer conteúdo chegue ao terminal.¹³⁵

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

Os perfis de permissão separam 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 eleva os perfis a uma interface gerenciada: listas de APIs expõem os metadados dos perfis disponíveis, os perfis podem herdar uns dos outros, o requirements.toml gerenciado pode declarar requisitos de permissão, os perfis ativos são atualizados em tempo de execução e a configuração do sandbox do Windows agora usa o perfil resolvido em vez de uma política improvisada 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 confidenciais e globs que não devem ser legíveis, mesmo quando a raiz do projeto permite gravação. Para exceções pontuais de comandos, prefira regras em vez de ampliar excessivamente um perfil.⁸⁷

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

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

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

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

Nas notas da versão v0.128.0, --full-auto aparece como obsoleto, e a ajuda atual do CLI não o lista mais para execuções interativas. Em vez dele, 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 essa flag retorna um erro em vez de ser executado. A migração é mecânica — substitua-a por --sandbox workspace-write (e adicione uma flag de aprovação ou um perfil caso a invocação antiga dependesse do comportamento de aprovação de --full-auto). Antes de atualizar, revise qualquer automação que invoque codex exec pelo shell: a falha aparece como um pipeline quebrado, não como um aviso de descontinuação.¹¹⁶

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ários travamentos em casos extremos durante execuções prolongadas; e o Bubblewrap incluído é 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

Artigos da comunidade recomendam essa combinação como um “ponto ideal”⁸; entenda o que ela realmente faz antes de repetir o conselho: as solicitações de aprovação aparecem quando um comando precisa sair do sandbox ou acessar a rede, enquanto danger-full-access remove esses dois limites, portanto on-request quase não tem mais o que elevar. É a capacidade máxima com o mínimo de solicitações, não a capacidade máxima com verificação humana de cada comando; se você quiser esta última opção, mantenha workspace-write e deixe que o limite do sandbox acione 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 do prompt e evitar a sobrecarga de inicialização. Cada revisão recebe um histórico limpo (as decisões anteriores não afetam as revisões seguintes).⁷³

Configure o revisor em config.toml:

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

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

Os padrões do Guardian v2 foram 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 tem true como padrão — defina-o como false para manter o escopo mais amplo de revisão de ferramentas — e features.guardianv2.transcript.include_images tem true como padrão — defina-o como false para excluir imagens das transcrições do Guardian. As duas opções foram lançadas na v0.150.0 como interfaces configuráveis e desativadas por padrão; foi na v0.151.0 que passaram a ser ativadas 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 alterar o resultado. Em Full Access (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 falhas ou restritos não são tratados como Full Access, e o estado de permissão ativo é reavaliado a cada turno para que uma thread existente possa entrar ou sair do Full Access com segurança. No modo de aprovação do usuário (approvals_reviewer = "user"), o pré-aquecimento do Guardian e a pontuação assíncrona são ignorados, enquanto as confirmações comuns de execução do node_repl.js são aceitas automaticamente; 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 que este guia descreve 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), usando a política incluída como fallback quando o campo não estiver presente.¹³⁹

A pontuação de uso do computador do Guardian respeita os requisitos do modelo (v0.153.1): agora, a pontuação do Guardian limitada ao uso do computador e as decisões rápidas de aprovação 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 desatualizada. Esse é o principal destaque do patch v0.153.1 e não aparece no corpo das notas da versão: a #42422 (um cherry-pick de 38ba8cdc) só pode ser comprovada pela comparação rust-v0.153.0…rust-v0.153.1.¹⁴²

A reutilização da compactação da thread principal pelo Guardian é ativada por padrão (v0.156.0): a #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 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 é ativado por padrão (v0.157.0): a #47275 promove guardianv2.thread_context a um recurso 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, e configurações explícitas e substituições de perfil são preservadas. Para desativá-lo: defina thread_context = false em [features.guardianv2] no config.toml.¹⁷⁴

Classificação mais rigorosa no PowerShell (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 passarem pela aprovação automática — isso corrige uma falha que permitia que PowerShell ofuscado ou construído dinamicamente evitasse 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 recusa obscura — algo útil ao ajustar políticas de aprovação e precisar 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

Compatibilidade com proxy para WebSocket (v0.104.0+)

Para ambientes corporativos que encaminham o tráfego de WebSocket por um proxy, agora o Codex aceita as variáveis de ambiente WS_PROXY e WSS_PROXY:⁴⁹

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

Elas complementam a compatibilidade existente com HTTPS_PROXY e proxies SOCKS5 (v0.93.0+).

A v0.146.0 é a versão que tornou “todas as camadas de transporte” uma realidade. 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 de WebSocket, nos redirecionamentos HTTP e nas conexões do LM Studio — sete caminhos que, segundo o changelog, antes ignoravam o proxy.¹¹⁴ Se você executava o Codex atrás de um proxy corporativo antes da v0.146.0 e encontrava falhas no login ou na instalação de plugins enquanto as chamadas comuns ao modelo funcionavam, essa lacuna é a explicação mais 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 em cada shell para o tráfego de autenticação.¹⁰⁵ Desde a v0.143.0, isso também se aplica ao Windows e ao tráfego de API do Responses: o Codex encaminha tanto a autenticação quanto as chamadas de API do Responses pelo proxy do sistema do macOS ou do Windows, incluindo a configuração automática de PAC e WPAD, eliminando a última lacuna em redes corporativas restritas nos dois 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, os dois comandos deverão falhar com um erro de permissão negada em um perfil limitado ao workspace. Se qualquer um dos comandos for bem-sucedido, 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.

Plan Mode e colaboração

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

Plan mode vs a ferramenta update_plan (v0.152.0): são duas coisas diferentes, e apenas uma delas vem ativada por padrão. O Plan mode — o modo de colaboração descrito nesta seção, no qual o Codex apresenta uma proposta antes de executá-la — está 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 dentro de um turno. Ela foi lançada como recurso opt-in na v0.152.0: tools.update_plan.enabled usa 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, multi-agent, compactação, prewarm e continuidade de objetivos (instruções básicas personalizadas, instruções do catálogo de modelos, 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 Plan mode

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

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

Steer mode

O Steer mode (ativado por padrão desde a v0.98.0) permite que você insira 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 Steer mode está sempre ativo na TUI. Se preferir esperar o Codex terminar antes de dar instruções, basta digitar normalmente após a conclusão do turno — não é necessário nenhum modo especial.

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

Destaque de sintaxe (v0.105.0): agora, a TUI destaca a sintaxe de blocos de código delimitados e diffs 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 por 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ê escolha um hardware específico de entrada e saída de áudio.⁶² Removido na v0.140.0 e retomado na v0.145.0: os controles experimentais de voz /realtime e suas dependências de áudio foram removidos da TUI na v0.140.0 (a transcrição de voz pela barra de espaço não foi afetada).¹⁰² A v0.145.0 trouxe a voz de volta em um novo formato: entradas de áudio e saídas de ferramentas de áudio em formatos locais comuns, além de conversas V3 em tempo real via streaming.¹¹² 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 e 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 vêm ativadas por padrão, com alternância pela tecla F8, um seletor de configurações /voice settings e runtimes de áudio integrados para Linux e Windows.” Para desativá-las, defina realtime_conversation = false em [features] no config.toml. A referência de slash commands CLI ainda não inclui /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 entre linhas da TUI (v0.105.0)⁶¹ - Links para arquivos locais são exibidos com uma formatação aprimorada (v0.106.0)⁶⁰ - O markdown da TUI mantém os links da web clicáveis por meio de metadados OSC 8, e tabelas sem espaço suficiente passam a ser exibidas como registros legíveis de chave/valor sem perder os destinos dos links (v0.136.0)¹⁶⁸ - Links em markdown aparecem como rótulos clicáveis em terminais compatíveis, enquanto os URLs permanecem visíveis nos demais (v0.150.0)¹³² - O tratamento de Ctrl+C para sub-agents foi corrigido para encerrar corretamente os processos filhos (v0.106.0)⁶⁰

Sistema de memória

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

Comandos de memória

As memórias são armazenadas em arquivos markdown dentro de ~/.codex/memory/. O Codex as carrega no início da sessão e as 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 fica em src/core/auth/, não em src/middleware/“
• Preferências de fluxo de trabalho: “Sempre execute o linter antes de me mostrar um diff”

Memória em pipelines

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

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

• Sanitização de segredos: as memórias são verificadas automaticamente em busca de segredos antes de serem gravadas no disco
• Reconhecimento do CWD: agora, os arquivos de memória incluem o contexto do diretório de trabalho para recuperar informações específicas do projeto
• Exclusão de mensagens do desenvolvedor: mensagens de desenvolvedor/sistema são excluídas da entrada de memória da fase 1, melhorando a qualidade da memória ao manter o foco nas interações do usuário
• Esquecimento baseado em diff (v0.106.0): agora, a memória usa esquecimento baseado em diff para remover fatos desatualizados, mantendo o armazenamento de memória 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 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 desviar 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 sessões para condensar as transcrições da fase 1 em fatos duradouros; a mudança de modelo melhora a qualidade da recuperação com o mesmo custo de tokens.⁸²
• Menu de memórias da TUI (v0.121.0): uma nova interface disponível durante a sessão permite acessar o modo de memória, excluir memórias específicas e usar um botão de redefinição. Agora, redefinir a memória preserva rollouts anteriores em vez de invalidá-los, portanto a redefinição limpa a superfície de recuperação futura sem comprometer a reprodução da sessão.⁸²

Memória vs AGENTS.md

Dica: use /m_update para fatos que devem persistir indefinidamente. 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 interface de contexto mais completa, em vez de apenas um gerenciador de threads. Use 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 e armazena 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 prévia renderizada compartilhada, permite ações no navegador, como cliques, capturas de tela, downloads de recursos e inspeção somente leitura JavaScript, e permite marcar regiões da página com comentários que o Codex pode processar no próximo turno.⁹⁹ 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 de sites (WebMCP, 25 de agosto de 2026): no navegador integrado do Desktop App, o ChatGPT Work e o Codex podem usar ferramentas fornecidas por um site para interagir com a página; use GPT-5.6 Sol ou GPT-5.6 Terra na versão mais recente do Desktop App, pois as ferramentas de sites não estão disponíveis com GPT-5.6 Luna nem em workspaces Enterprise ou Edu.¹²⁷

Use o Computer Use somente quando uma integração estruturada ou a prévia do navegador não puder verificar a tarefa. Ele pode inspecionar e operar apps autorizados do Mac, mas segue as aprovações e as regras de sandbox do Codex para edições de arquivos e comandos de shell. O uso com a tela bloqueada permanece restrito: o Codex pode acessar temporariamente os apps autorizados durante turnos ativos e confiáveis do Computer Use após o bloqueio do Mac, com proteções de bloqueio automático e detecção de entrada local.⁹⁹

Modos de thread

Cada thread é executada em um dos três modos, selecionado durante sua 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 terminar — você escolhe quais alterações deseja incorporar

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

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

Os 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ção, 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 continuam desativados por padrão: a visão geral dos agentes permite 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 mudança para ativação por padrão (#44870) foi incorporada 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 recurso estável, ativa-o por padrão e o remove de /experimental. Lançados junto com essa mudança: as sessões de worktree podem se conectar a um daemon local existente, em vez de iniciar um próprio (#46498), e podem ser criadas diretamente pela visão geral dos agentes (#45276), que também recebe abas de filtro por status (#46839). Se você tem scripts ou configurações que pressupõem que os worktrees ficam desativados até serem solicitados, a 0.156.0 é a versão que altera esse comportamento. Para desativar: defina worktrees = false em [features] no config.toml (por execução: --disable worktrees). Daemons locais mais antigos: se a criação de worktrees ou /cd for bloqueada com “The local Codex service cannot check background terminals”, execute codex app-server daemon update e reinicie o Codex.¹⁶⁹¹⁷¹

Automações

As automações são executadas localmente no app, portanto o app precisa estar aberto e o projeto 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 sem Git, as execuções acontecem diretamente no diretório do projeto
• As automações usam suas configurações padrão de sandbox

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

Exemplos de uso: - Triagem de issues: categorize e priorize automaticamente novas issues - Monitoramento de CI: acompanhe falhas de build e sugira correções - Resposta a alertas: reaja a alertas de monitoramento com análises de diagnóstico - Atualizações de dependências: verifique e aplique patches de segurança

Os resultados aparecem em uma fila de revisão para aprovação humana.

Suporte ao Windows

O Codex Desktop App foi lançado para Windows em 4 de março de 2026 (App v26.304), com suporte nativo ao PowerShell, sandbox nativo do Windows e todos os recursos da versão para macOS, incluindo skills, automações e worktrees, sem exigir WSL.⁶⁶

Action do GitHub e CI/CD

A Action oficial do GitHub 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 aplicações personalizadas.¹⁹

Instalação

npm install @openai/codex-sdk

Uso básico

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

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

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

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

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

Recursos avançados do SDK

• runStreamed(...): Stream assíncrono de eventos para atualizações intermediárias
• Autenticação do SDK da Python (v0.132.0+): login com chave da API, fluxos de navegador/código de dispositivo do ChatGPT, inspeção de 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, com itens coletados, duração e uso.⁹⁷
• outputSchema: Impõe uma saída final no formato JSON
• Entrada multimodal: Passe texto + imagens locais ({ type: "local_image", path: "..." })
• Workflows de imagem (v0.117.0): view_image retorna URLs, imagens geradas podem ser reabertas e o histórico de imagens é 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 + pasta 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 é obtida em relação à pasta de trabalho desse ambiente, não ao host que executa o SDK.⁹¹

Configuração de threads e do 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 ficam armazenadas em ~/.codex/sessions.

Ambiente de execução: Node.js 18+.

Otimização de desempenho

Gerenciamento de contexto

As janelas de contexto variam de acordo com o modelo. A família GPT-5.6 atual (Sol, Terra, Luna) usa uma janela de 272K; o GPT-5.5, modelo principal da geração anterior, oferece 400K no Codex (1M na API); GPT-5.4 / GPT-5.4-mini (que deixarão o Codex em 31 de agosto de 2026) oferecem 1M / 400K; a família legada GPT-5.3-Codex usava 272K de entrada + 128K de saída (orçamento total de 400K). Todas elas ficam cheias 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 de alta qualidade e uma boa documentação local reduzem o trabalho de exploração (que consome contexto)
3. Use @ para anexar arquivos específicos: Referencie os arquivos diretamente em vez de pedir que o Codex os encontre
4. Mantenha os prompts focados: Prompts com escopo definido e arquivos exatos consomem menos contexto do que uma exploração aberta

Gerenciamento experimental de contexto (v0.153.0, desativado por padrão): features.context_management.experimental_mode ativa uma pilha coordenada de contexto — contexto com orçamento de tokens, notas de 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 são do Codex e threads estruturadas temporárias são excluídos. Além disso, a flag está explicitamente em desenvolvimento: considere-a uma prévia dos rumos do gerenciamento de contexto, não algo sobre o qual criar workflows.¹⁴⁰ A v0.154.0 adiciona uma verificação de capacidade: a qualificação é determinada com base nos recursos do modelo ativo durante a inicialização da sessão (#43147) — a mesma área que a documentação dos modelos do Codex associa nominalmente ao Astra para login no Plus e Pro (consulte a observação sobre contextos na seção Qual modelo devo escolher?).¹⁴⁶¹⁵² Desde a 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.¹⁷⁴

Eficiência de tokens

Otimização de velocidade

1. gpt-5.3-codex-spark: Variante de menor latência para colaboração interativa
2. --profile fast: gpt-5.6-luna pré-configurado com baixo nível de raciocínio
3. Execução paralela de ferramentas: O Codex executa leituras/verificações independentes simultaneamente; portanto, estruture os prompts para permitir isso
4. Loops orientados a resultados: Peça para “implementar, testar, corrigir e parar quando tudo estiver funcionando” em vez de fornecer instruções passo a passo

Como depuro problemas?

Problemas comuns e soluções

Referência de mensagens de erro

O que codex doctor faz?

codex doctor é o único comando que você deve executar antes de relatar um bug ou depurar uma instalação com problemas. Ele reúne o ambiente de execução local, a configuração, a autenticação, o terminal, a rede e o estado em um único relatório, e o próprio modelo de issue do projeto solicita que você cole a saída dele.¹⁶³

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

O relatório é organizado em seções estáveis, para que você possa ir direto à que precisa:¹⁶³

Cada verificação inclui um indicador de status — ✓ ok, ✗ falha, ⚠ aviso, ○ inativo — acompanhado de uma linha de resumo. --json identifica cada verificação com um identificador estável, permitindo o uso em CI ou em um script de suporte, em vez de servir apenas para inspeção visual.¹⁶³

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

Use-o primeiro, não por último. A maioria dos relatos de que “o Codex não está funcionando” se deve a algo que o doctor já identifica: um modo de autenticação obsoleto, um config.toml cuja análise falhou ou uma segunda instalação ocultando aquela presente no seu PATH.

Ferramentas de diagnóstico

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

Diagnósticos da TUI durante a sessão:

/status                                # Token/session overview
/debug-config                          # Show config layers and requirement sources
/compact                               # Summarize history to reclaim context

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

Reinstalação limpa

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

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

Modo de depuração

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

Como relatar problemas

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

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

Codex Security [PRÉVIA]

O Codex Security entrou em prévia de pesquisa em 6 de março de 2026, trazendo a análise de segurança de aplicações com reconhecimento de contexto para a plataforma Codex.⁷⁷ Ele está disponível para clientes ChatGPT Pro, Enterprise, Business e Edu pelo Codex web.

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

Desempenho: durante a prévia de pesquisa, o Codex Security analisou 1,2 milhão de commits e identificou 10.561 vulnerabilidades de alta gravidade. A precisão melhorou ao longo do tempo — reduzindo o ruído em 84%, diminuindo em mais de 90% os casos de gravidade superestimada e cortando pela metade a taxa de falsos positivos. O sistema encontrou vulnerabilidades reais no OpenSSH, GnuTLS e Chromium, com 14 CVEs atribuídas.⁷⁷

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

Implantação empresarial

Controles administrativos (requirements.toml)

Os administradores aplicam as políticas empresariais por meio do requirements.toml, um arquivo de configuração imposto pelo administrador que restringe configurações críticas de segurança que os usuários não podem substituir:²¹

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

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["on-request", "never"]   # `untrusted` retired in v0.149.0

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"