Codex CLI: a referência técnica definitiva

TL;DR: O Codex é um agente de programação que atua em várias interfaces: ele lê sua base de código, executa comandos em um sandbox no nível do sistema operacional, modifica arquivos e delega tarefas à nuvem. Domine cinco sistemas – config.toml, o modelo de sandbox e aprovação, AGENTS.md, MCP e skills – e ele multiplica sua capacidade de trabalho. Qual modelo usar: a documentação de modelos da OpenAI agora recomenda o GPT-6.1 Sol (gpt-6.1-sol, o modelo padrão incluído no CLI desde a v0.159.1) para programação complexa e trabalho com agentes, o GPT-6-Astra para os trabalhos mais difíceis de ponta a ponta e o GPT-6 Luna para tarefas específicas e repetíveis. A disponibilidade depende do plano, do cliente e das configurações do workspace; o GPT-6 Sol e os modelos GPT-5.6 continuam no seletor, e o GPT-5.5 deixa de estar disponível no Codex para quem faz login pelo ChatGPT em 14 de outubro de 2026.^146171178 Está começando? Vá direto para Instalação e Início rápido. Está acompanhando os lançamentos? A versão estável mais recente é a v0.164.0 (23 de outubro de 2026): dez espaços em /presets para prompts reutilizáveis, argumentos diretamente em /model e /permissions, prévias de imagens na transcrição em tela cheia, login no MCP gerenciado pela empresa e assistente de configuração do Bedrock ativado por padrão; Destaques dos lançamentos começa com um resumo do estado atual (o que está ativado por padrão e o que ainda é experimental) e depois aborda cada versão, e o Histórico de alterações lista todas as atualizações do guia.^116178182183

O Codex funciona como um agente de programação que atua em várias interfaces, não como um chatbot que escreve código. O CLI lê sua base de código, executa comandos em um sandbox, modifica arquivos, conecta-se a serviços externos via MCP e delega tarefas demoradas à nuvem. Ele roda localmente, mas pensa globalmente; a mesma inteligência alimenta cinco interfaces distintas, conforme sua forma de trabalhar, incluindo a extensão de navegador (Chrome, Edge, Brave, Opera e Vivaldi), que executa o Codex no seu navegador sem assumir o controle dele.⁹⁰¹²⁷

A diferença entre usar o Codex casualmente e usá-lo com eficácia está em cinco sistemas fundamentais. Domine esses sistemas e o Codex multiplica sua capacidade de trabalho:

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

Passei meses usando o Codex junto com o Claude Code em bases de código de produção, pipelines de CI/CD e fluxos de trabalho em equipe. Este guia reúne essa experiência na referência completa que eu gostaria de ter encontrado quando comecei. Cada recurso inclui a sintaxe usada na prática, exemplos reais de configuração e os casos especiais que pegam até usuários experientes.

Principais conclusões

• Cinco interfaces, uma só inteligência: 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. Por isso, escolha a interface mais adequada ao seu fluxo de trabalho.⁹⁰
• Sandbox no nível do sistema operacional: o Codex aplica restrições ao sistema de arquivos e à rede no nível do kernel (Seatbelt no macOS, bubblewrap + seccomp no Linux), não dentro de contêineres.
• AGENTS.md funciona em várias ferramentas: as instruções do seu projeto funcionam no Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed e em mais de 60.000 projetos de código aberto. Escreva uma vez e use em qualquer lugar.
• Perfis reduzem o custo das trocas 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.1 Sol, GPT-6 Astra, Sol e Luna e à família GPT-5.6 uma janela de contexto de 272K (o API informa 1,05M para GPT-6.1 Sol, GPT-6 Sol e Luna); o GPT-5.5 oferece 400K no Codex até ser descontinuado na plataforma em 14 de outubro de 2026. Use /compact, prompts específicos e referências @file para gerenciar os limites de tokens de forma proativa.^83112178

Como usar este guia

Esta é uma referência com mais de 3.300 linhas — comece pela seção 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 das versões: o que mudou recentemente

O histórico de cada versão, da mais recente para a mais antiga, para quem acompanha os lançamentos do Codex. Chegou agora? Vá direto para o Início rápido; nada abaixo é necessário para começar a produzir. Os detalhes de verificação (comparações, listas de commits e conferências na documentação) estão nas notas de rodapé.

Estado atual

Codex CLI em 23 de outubro de 2026

• Estável: v0.164.0 (23 de outubro, npm latest), gerada a partir da 0.164.0-alpha.11 mais um commit de lançamento (a alpha.12 incluía nove commits ausentes na versão estável) e 330 commits à frente da v0.163.0: dez posições numeradas em /presets para prompts reutilizáveis e slash commands, /model [model] --reasoning <level> --speed <tier> e /permissions <profile-id> diretamente na linha de comando, prévias de imagens na transcrição em tela cheia em terminais Kitty ou Sixel, autorização gerenciada pela empresa para conexões MCP, mascaramento de credenciais para comandos Bash remotos compatíveis (controlado pela flag credential_masking) e o assistente de configuração do Amazon Bedrock ativado por padrão. Antes dela: v0.163.0 (15 de outubro), que adicionou o painel /config com busca, a tecla líder e o Daybreak ativado por padrão.
• Alpha: npm alpha está na 0.165.0-alpha.1 (23 de outubro, horas após a versão estável). Nessa tag, reasoning_effort_override é estável e está ativada, e guardianv3, guardian_recorded_items e tui_multi_backend são novas e estão desativadas. A série 0.164 foi da alpha.1 (16 de outubro) à alpha.12 (22 de outubro), com builds fora da sequência 0.163.0-alpha.11.1 e 11.2 (21–22 de outubro) e 0.164.0-alpha.11.1 (23 de outubro) em paralelo.
• Modelo padrão desde a v0.159.1: GPT-6.1 Sol, substituindo o GPT-6-Astra, inclusive no Amazon Bedrock. Defina model em config.toml para manter outro modelo. O catálogo incluído na v0.164.0 é idêntico byte a byte ao das versões v0.162.1 e v0.163.0 e lista os mesmos modelos da v0.159.1.
• Ativados por padrão desde a v0.164.0: o assistente de configuração do Amazon Bedrock (bedrock_setup_wizard, estável; bedrock_setup_wizard = false em [features] o desativa), atualizações incrementais de ferramentas (incremental_tools, estável) e coordenação da renovação de OAuth do MCP (mcp_oauth_refresh_coordination, estável). Os worktrees gerenciados e a conversa em tempo real são permanentes: suas flags estão marcadas como removidas, com os recursos mantidos ativos.
• Ativados por padrão desde a v0.163.0: Daybreak (cli_daybreak, agora estável; cli_daybreak = false em [features] oculta os controles) e interrupção do modo de código (code_mode_interrupt, estável), de modo que uma nova mensagem também interrompe uma célula do Code Mode em execução; sessões com chave de API recebem programas de acesso Cyber por padrão (api_key_cyber_access_programs). Removidas: shell_zsh_fork e unified_exec_zsh_fork, ignoradas com um aviso de migração.
• Ativado por padrão desde a v0.162.0: instant_interrupt, que faz uma nova entrada interromper a resposta do modelo (instant_interrupt = false em [features] o desativa); a flag continua marcada como em desenvolvimento.
• Ativada por padrão desde a v0.161.0: descoberta de modelos com chave de API (api_key_model_discovery = false em [features] a desativa).
• Ativados por padrão desde a v0.158.0: aprovação para envio de entrada a terminais com privilégios elevados (write_stdin_approval = false em [features] a desativa), além de copiar ao selecionar e colar com o botão direito na TUI em tela cheia (copy_on_select = "never", right_click_paste = "off" em [tui]). O contexto da conversa do Guardian está sempre ativo; thread_context é ignorada.
• Ativados por padrão desde a v0.157.0: a transcrição em tela cheia (fullscreen_transcript = false em [tui]) e a inicialização automática do servidor em segundo plano (daemon_auto_start = false em [features], ou --no-daemon).
• Ativados por padrão desde a v0.156.0: /voice, worktrees gerenciados e reutilização da compactação da conversa principal pelo Guardian.
• De ativação opcional ou experimentais: Codex Cloud, modo de código e sua busca de ferramentas por relevância (code_mode_tool_search, v0.162.0), recuperação do histórico pelo Guardian (guardian_conversation_history_tools, v0.160.0) e as flags em desenvolvimento que vêm desativadas na v0.164.0 (desde a v0.163.0: async_compaction, credential_masking, output_token_replay, retain_client_tool_outputs, subagent_default_context_limits, code_mode_host_grpc, code_mode_tool_description_first, guardian_trust_orchestrator_connectors; novas na v0.164.0: app_server_websocket_compression, executor_capability_discovery_v2, mcp_tool_list_changed, multi_env_copy_file, runtime_agent_instances, subagent_thread_environments, wake_on_agent_messages). O gerenciamento experimental de contexto não está disponível no momento.
• Modelos: GPT-6.1 Sol para programação complexa, GPT-6-Astra para os trabalhos mais difíceis, GPT-6 Luna para tarefas repetíveis. GPT-6 Sol e Luna iniciam em Fast (2,5x créditos); GPT-6.1 Sol não. O GPT-5.5 sai do Codex em 14 de outubro de 2026.
• Fixar a versão: npm install -g @openai/codex@0.164.0, depois codex --version.^{176178186187188189192193194195}

v0.164.0 (23 de outubro de 2026)

A série 0.164 chega à versão estável a partir de sua própria alpha. A v0.164.0 foi publicada em 23 de outubro (04:48 UTC; npm latest às 04:52 UTC), gerada a partir da 0.164.0-alpha.11 mais um commit de lançamento; a alpha.12 (22 de outubro) estava nove commits à frente desse ponto, e a 0.164.0-alpha.11.1, publicada fora da sequência (23 de outubro, 01:58 UTC), adicionou quatro commits à base da alpha.11. A comparação com a v0.163.0 contabiliza 330 commits. Três flags passam a vir ativadas e são marcadas como estáveis: bedrock_setup_wizard (o assistente de configuração do Amazon Bedrock, com a entrada de chave de API agrupada aos outros métodos de login da AWS quando credenciais são detectadas), incremental_tools e mcp_oauth_refresh_coordination. As flags worktrees e realtime_conversation são marcadas como removidas, com seus recursos mantidos ativos, portanto os worktrees gerenciados e a conversa em tempo real não podem mais ser desativados; stable_environment_tools e transcript_v2 também foram removidas. Sete flags em desenvolvimento são novas e vêm desativadas. O catálogo de modelos incluído é o mesmo blob distribuído na v0.162.1.¹⁹⁴¹⁹⁵

Novidades na TUI. /presets salva prompts reutilizáveis e slash commands em dez posições numeradas, com um menu operado pelo teclado; uma predefinição pode ser criada a partir do texto no campo de composição ou do modelo, esforço de raciocínio e velocidade atuais, e as predefinições ficam salvas em tui.presets na configuração ativa do usuário (#54380, #54381). /model [model] --reasoning <level> --speed <tier> aplica modelo, raciocínio e velocidade à sessão atual sem alterar os padrões salvos, aceitando valores de flags separados por espaço ou =; omitir o modelo aplica as configurações ao modelo atual, e /model sem argumentos continua abrindo o seletor (#54378). /permissions <profile-id> seleciona diretamente um perfil de permissões integrado ou personalizado, como /permissions :read-only, com :ask-for-approval e :approve-for-me como aliases (#54383). Em terminais compatíveis com gráficos Kitty ou Sixel, a transcrição em tela cheia exibe prévias das imagens visualizadas e geradas como miniaturas com dimensões limitadas; espaços de trabalho remotos, terminais incompatíveis e imagens grandes demais mantêm a entrada apenas em texto (#54216).¹⁹⁴

Conexões e credenciais. Servidores MCP configurados diretamente podem se autenticar com autorizações empresariais vinculadas à conta, armazenadas no chaveiro de credenciais, ou por um login dedicado, incluindo clientes OAuth que exigem segredos; a extensão de autorização gerenciada pela empresa é negociada com o protocolo 2026-07-28, e a autorização é revogada quando o proprietário da conta muda ou um login empresarial substitui a autorização concedida (#55334, #55859, #56001). O mascaramento de credenciais passa a abranger comandos Bash remotos compatíveis e sessões com snapshots do zsh, incluindo credenciais de provedores personalizados: o comando vê marcadores de substituição, e o proxy local ao executor injeta as credenciais reais nos destinos correspondentes, recorrendo à execução sem mascaramento com um aviso quando o mascaramento não está disponível; a flag credential_masking ainda vem desativada nessa tag (#54309, #54432, #56049).¹⁹⁴¹⁹⁵

Correções e manutenção. Uma compactação malsucedida não deixa mais resumos parciais no histórico da conversa, e uma falha na compactação em segundo plano recorre a uma alternativa sem provocar um panic (#53932, #55581). Ao retomar uma sessão, o sistema encontra históricos comprimidos e restaura as configurações salvas da conversa, em vez de substituí-las pelos padrões globais (#54008, #55923). No Windows, conexões HTTPS e WebSocket respondem aos desafios de autenticação do proxy com as credenciais Negotiate ou NTLM do usuário conectado (#55994, #56000). -c ou --config fornecidos em vários níveis de subcomandos preservam todas as substituições de configuração (#56022); prompts na fila aguardam a conclusão de uma seleção de permissões pendente (#55682); e o sandbox verifica caminhos de metadados com variações de maiúsculas e minúsculas no macOS e links simbólicos substituíveis usados para localizar executáveis (#54273, #55384). O uso de disco diminui: instalações não utilizadas são removidas (as seleções atual e anterior do daemon são mantidas), checkouts abandonados do marketplace são limpos e os logs do daemon têm tamanho limitado (#53827, #55149, #55689, #55690, #55856); o runtime JavaScript integrado ganha verificações de segurança para a versão otimizada de Array.sort (#54519).¹⁹⁴ O que fazer: atualize. Nenhuma mudança nos padrões será perceptível, a menos que você faça a configuração inicial no Bedrock, onde o assistente agora é executado automaticamente (bedrock_setup_wizard = false em [features] desativa esse comportamento); se você havia definido worktrees ou realtime_conversation em [features], essas chaves agora são ignoradas.¹⁹⁴¹⁹⁵

v0.163.0 (15 de outubro de 2026)

A linha 0.163 chega à versão estável a partir da branch paralela. A v0.163.0 foi publicada em 15 de outubro (21:30 UTC; latest no npm às 21:37 UTC), derivada da 0.163.0-alpha.10.2, uma build paralela baseada na alpha.10, mais um commit de release; a alpha.11 da linha principal (14 de outubro) incluía 23 commits ausentes na versão estável, repetindo o padrão da 0.158. A comparação com a v0.162.1 contabiliza 232 commits. Duas flags de recursos passam a ficar ativadas, ambas marcadas como estáveis: cli_daybreak (controles do Daybreak, alternância via /daybreak e encaminhamento automático pelo programa de acesso Cyber para contas OpenAI elegíveis; codex exec pode selecioná-lo com uma chave API da OpenAI quando o servidor oferece acesso) e code_mode_interrupt (interromper um turno também encerra as células ativas do Code Mode e suas chamadas de ferramentas aninhadas). api_key_cyber_access_programs, já estável, passa a ficar ativada. instant_interrupt continua ativada e ainda em desenvolvimento.¹⁹²¹⁹³

Novidades na TUI. /config abre um painel de preferências com busca, organizado nas abas Aparência, Notificações, Entrada, Sessões e Seleção de texto; as alterações compatíveis são aplicadas imediatamente, o painel indica quais exigem reinicialização, e as edições são salvas no arquivo de configuração local selecionado (#52990, #53429). /keymap configura uma tecla líder: tui.keymap.global.leader usa ctrl-x por padrão, combinações como leader c vêm na sequência, as dicas de atalhos permanecem abertas até você escolher ou cancelar, e o atalho para silenciar a voz muda de Ctrl+X para F9 (#52273). /daemon pode reiniciar um servidor gerenciado em segundo plano, avisando sobre tarefas que a reinicialização pode interromper e reconectando depois (#53173). O Codex executa ferramentas independentes de somente leitura em paralelo: consultas a skills, memória e histórico de conversas, listagens de plugins e agentes, horário atual, contexto restante e get_goal (#52245). Uma mensagem adicional enviada enquanto o Codex está respondendo o redireciona imediatamente (#51812, #51835).¹⁹²

Correções e plataforma. Retomar uma conversa salva restaura suas permissões e aprovações de rede, respeitando substituições explícitas e a política gerenciada (#53150, #53419, #53424). O proxy de rede verifica a permissão antes de uma consulta DNS, rejeita cabeçalhos Host duplicados e impede que aliases de credenciais contornem os hooks de inspeção (#51650, #52661, #53506). /side retorna a uma conversa lateral existente após a troca de conversa, e as respostas a solicitações pendentes voltam para a conversa que as fez (#52184, #53436). No Windows, Ctrl+V e Shift+Insert colam texto e imagens; no WSL, colagens repetidas reutilizam o leitor da área de transferência, e tentativas de cópia atingem o tempo limite em vez de travar (#53224, #52967, #53453). Comandos locais terminam prontamente quando um processo filho mantém um pipe de saída aberto, comandos remotos preservam a saída tardia para a consulta final, e codex exec deixa de repetir o diff de um arquivo após um comando sem relação com ele (#52652, #53331, #53622, #53444).¹⁹²

O zsh modificado foi removido. O Codex usa seu executor de shell padrão e não inclui mais um zsh modificado; o codex-execve-wrapper e a crate shell-escalation também foram removidos, shell_zsh_fork e unified_exec_zsh_fork são ignoradas com um aviso de migração, e requisitos gerenciados que ainda as mencionam geram um alerta (#52160, #52213). Os pacotes para Linux e macOS ficaram menores, com a remoção de símbolos dos binários distribuídos (#52178). Os nomes e o README da crate de sandbox do Linux agora descrevem o que o sandbox já fazia: bubblewrap para isolamento do sistema de arquivos e de namespaces, seccomp para filtragem de chamadas de sistema, com a implementação de Landlock mantida como legada; a aplicação das restrições não mudou (#52610). As orientações do OpenAI Docs incluídas no pacote abrangem migrações para a família GPT-6 (#51768).¹⁹²¹⁹³

O que fazer: atualize. Se um config.toml ou requirements.toml mencionar shell_zsh_fork ou unified_exec_zsh_fork, remova a entrada; se você havia ativado o Daybreak manualmente, a flag não é mais necessária; e, se você usava Ctrl+X para silenciar /voice, agora o atalho é F9.¹⁹²

v0.162.1 (9 de outubro de 2026)

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

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

v0.162.0 (8 de outubro de 2026)

instant_interrupt passa a ficar ativada por padrão. A flag lançada na v0.159.0 com ativação opcional, que permite que uma nova entrada interrompa uma resposta do modelo ou faça uma chamada demorada do modo de código devolver o controle, fica ativada para todos a partir desta versão (PR #51812, incorporado em 7 de outubro); ela continua marcada como em desenvolvimento. Defina instant_interrupt = false em [features] para restaurar o comportamento anterior, em que a entrada digitada aguarda o término da resposta.

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

Provedores e modelos: um provedor personalizado compatível com Responses pode declarar external_web_access e remote_compaction em [model_providers.<name>.capabilities] (#50459). O recurso ultrafast_mode vem ativado, permitindo que um catálogo de modelos que anuncie um nível Ultra Fast (modelos Astra do Amazon Bedrock, #50472) o ofereça independentemente do modo Fast; o catálogo incluído nesta tag não lista esse nível. O modo de código ganha funções auxiliares de JavaScript para transmitir resultados de promises e uma busca de ferramentas ordenada por relevância, com ativação opcional (code_mode_tool_search). apply_patch sempre preserva as terminações de linha CRLF existentes, e a flag apply_patch_preserve_line_endings é removida. Falhas de Responses e WebSocket que permitem nova tentativa respeitam a orientação Retry-After do servidor.

Sandbox e plataforma: foi corrigida a inicialização do sandbox no Linux quando há vários arquivos com acesso negado, executáveis usados na construção do sandbox que permitem gravação são rejeitados, e a configuração do ripgrep não pode mais enfraquecer as máscaras glob de bloqueio; o Windows 10 recupera o acesso normal a arquivos por letras de unidade, as permissões temporárias do sandbox correspondem às do processo filho, a verificação de checksum de arquivos compactados funciona com os caminhos de módulos do PowerShell 7, e as versões para Windows incluem um instalador PowerShell assinado.

O que fazer: atualize; se você costumava digitar a próxima entrada sem interromper o modelo, defina instant_interrupt = false.¹⁸⁷¹⁸⁹

v0.161.0 (7 de outubro de 2026)

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

Novidades: /mcp login <name> faz login em um servidor MCP a partir de uma sessão de terminal em execução (#49290). Seleção de dispositivos de voz: escolha seu microfone, alto-falante e canais de entrada do microfone para conversas com /voice, com as preferências salvas localmente (#49437, #49836). A descoberta de modelos por chave API fica ativada por padrão (api_key_model_discovery, promovida a estável, #49807): ao fazer login com uma chave API da OpenAI em um endpoint compatível, o Codex atualiza o catálogo de modelos pela API, em vez de depender apenas da lista incluída no pacote; api_key_model_discovery = false em [features] desativa o recurso, e a alteração entra em vigor em uma nova sessão. O Amazon Bedrock oferece suporte a multiagente V2 e raciocínio Ultra em modelos compatíveis, e o Bedrock Mantle aceita regiões AWS GovCloud (#49345, #49813). Daybreak (ativação opcional). Uma nova flag cli_daybreak, desativada por padrão e em desenvolvimento, adiciona controles do Daybreak à CLI: um comando /daybreak para ativar e desativar, indicadores e roteamento automático do programa de acesso Cyber, para logins com ChatGPT no provedor OpenAI cuja conta e catálogo de modelos indiquem suporte. Ative com --enable cli_daybreak ou cli_daybreak = true em [features]; uma preferência daybreak = true salva, sozinha, não faz nada. Independentemente disso, codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red> (e o cyberAccessProgram da SDK de TypeScript) solicita um programa de acesso Cyber para um único turno, com ou sem a flag, e mantém a escolha salva inalterada (#49856 a #49861, #49939, #51207). O catálogo incluído já contém as entradas ocultas gpt-daybreak-blue-latest e gpt-daybreak-red-latest. Ativado por padrão e marcado como estável desde a v0.163.0.¹⁹³

Correções: uma elevação aprovada de permissões do sistema de arquivos pode conceder acesso mais amplo de escrita, mantendo os bloqueios de leitura e as restrições de rede, e tarefas em segundo plano mantêm as permissões do turno que as originou; permissões explícitas de inicialização persistem após reconexões do terminal; sessões de terminal do Windows com privilégios elevados podem iniciar com um servidor integrado; Enter envia a entrada acumulada após o período de detecção de colagem expirar, inclusive no modo de inserção do Vim; a retomada de conversas inclui o histórico confirmado mais recente, e a inicialização detecta mais cedo corrupções recuperáveis do SQLite, mantendo os bancos de dados danificados como backups; novas tentativas de Responses e o fallback de WebSocket para HTTP respeitam as orientações do servidor para novas tentativas. A documentação de autenticação agora informa que as credenciais podem ficar no chaveiro, em vez de sempre em auth.json.

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

v0.160.1 (5 de outubro de 2026)

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

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

v0.160.0 (1 de outubro de 2026)

A versão estável da série 0.160, criada a partir da 0.160.0-alpha.6.1 mais um backport. Nenhuma alteração nos padrões. O catálogo de modelos incluído na tag é idêntico, byte a byte, ao das versões v0.159.1 e v0.159.2, então GPT-6.1 Sol continua sendo o padrão, e as duas novas flags de recursos vêm desativadas. O backport (#49763) atualizou a versão candidata congelada da 0.160, cuja branch foi criada antes da v0.159.1, com as mudanças da série de manutenção 0.159: GPT-6.1 Sol no catálogo incluído e nos catálogos do Amazon Bedrock, além dos lembretes de segurança da conta da v0.159.3. Sem ele, a 0.160 teria sido lançada sem GPT-6.1 Sol.

Adições opcionais ao Guardian (ambas em desenvolvimento e desativadas por padrão):

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

Sempre ativo: mensagens criptografadas dos agentes agora aparecem nos registros do Guardian, em ordem, em vez de serem descartadas.

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

Provedores e conexões: a TUI mantém as configurações de provedor, resumo de raciocínio e verbosidade de um servidor de aplicativos, mostra as sessões corretas no histórico de retomada e bifurcação e oculta as configurações de resumo de raciocínio em /status para conexões com servidores. Um provedor com um catálogo de modelos explícito (model_catalog_url) agora recebe apenas esse catálogo: nenhum modelo incluído é mesclado, os metadados correspondem ao ID exato do modelo, uma falha na atualização descarta as entradas em cache em vez de reutilizá-las, e uma inicialização sem modelo disponível informa um erro de configuração, a menos que model esteja definido. Quando um filtro de conteúdo interrompe uma resposta, a nova tentativa instrui o modelo a explicar a limitação, oferecer uma alternativa permitida e continuar os outros trabalhos.

Correções: fallbacks do PowerShell no sandbox do Windows, reparo de ACL para caminhos longos do ambiente de execução e ausência de janelas de console abertas por processos auxiliares em segundo plano; subagentes mantêm ambientes que ainda estão iniciando; o SQLite não trava mais na configuração da conexão e informa erros de inicialização em vez de erros de tempo limite. O banco de dados de logs recupera espaço não utilizado em segundo plano, e o carregamento de plugins armazena em cache os manifestos já processados e reutiliza conexões HTTP. A documentação dos provedores agora informa que as credenciais de requires_openai_auth usam o backend escolhido por cli_auth_credentials_store, e que env_key indica o nome da variável de ambiente que contém a chave de API.

O que fazer: atualize. Se um provedor personalizado define model_catalog_url, confirme que o catálogo lista todos os modelos que você seleciona.¹⁸²

v0.159.3 (30 de setembro de 2026)

Lembretes opcionais de segurança da conta. Sessões locais da TUI autenticadas com ChatGPT no provedor OpenAI podem mostrar um banner que pode ser dispensado, pedindo que você conclua a configuração de segurança da conta, com um botão que abre chatgpt.com. O servidor decide quem o vê; a CLI busca o aviso em segundo plano sem bloquear um turno, não mostra nada quando o estado é desconhecido, ignora espaços de trabalho remotos e contas FedRAMP e lembra quando o aviso foi dispensado entre conversas e reconexões. Banners de uso têm prioridade. Essa é a única alteração da versão, e a v0.160.0 contém o mesmo código.

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

v0.159.2 (29 de setembro de 2026)

Uma correção no Windows para janelas de console que piscam na tela. No Windows, o Codex não abre mais uma janela de console toda vez que inicia um processo em segundo plano. Isso abrange comandos da ferramenta de shell, hooks, chamadas ao Git e ao npm, renovações de credenciais do Amazon Bedrock executadas sem terminal, verificações de diagnóstico, atualizações da configuração do sandbox e comandos no sandbox legado do Windows. Comandos que precisam do seu terminal continuam herdando o console dele. A versão contém um único backport de duas correções da branch main, publicado cerca de três horas e meia após a v0.159.1. Ela não altera padrões, chaves de configuração nem modelos, e o novo auxiliar de inicialização mantém o comportamento anterior no macOS e no Linux.

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

v0.159.1 (29 de setembro de 2026)

GPT-6.1 Sol se torna o modelo padrão. Quando config.toml não define um modelo, a CLI agora inicia com GPT-6.1 Sol (gpt-6.1-sol) em vez de GPT-6-Astra, e GPT-6.1 Sol substitui GPT-6 Sol como padrão nos catálogos Mantle e Runtime do Amazon Bedrock. O seletor /model o lista primeiro, como “Modelo versátil mais recente para programação e trabalho cotidiano”, seguido por GPT-6-Astra, GPT-6 Sol (agora “Modelo versátil da geração anterior”), GPT-6 Luna e os modelos mais antigos. Escolhas salvas não são migradas: uma configuração que especifica gpt-6-sol ou gpt-6-astra mantém esse modelo, e os avisos de migração para seleções antigas de GPT-5 continuam indicando GPT-6 Sol ou GPT-6 Luna. A documentação da OpenAI adicionou o modelo no mesmo dia e agora o recomenda para programação complexa e fluxos de trabalho com agentes: “desempenho próximo ao Astra em tarefas complexas, com custo menor que o Astra.” Ele custa 50 créditos por 1 milhão de tokens de entrada (2,5 para tokens em cache, 250 para saída), e a faixa do Plus é de 15 a 160 mensagens. Dois detalhes do catálogo diferem do GPT-6 Sol: ele não tem um nível de serviço padrão, então a sessão começa na velocidade Standard em vez de Fast, e seu esforço de raciocínio padrão é low em vez de medium. A disponibilização inicial abrange Plus, Pro, Business, Enterprise e Edu; no Enterprise e no Edu, ele permanece desativado até que um administrador o habilite, e Free e Go não estão incluídos no lançamento.

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

v0.159.0 (29 de setembro de 2026)

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

Novidades desta versão:

• instant_interrupt (ativação opcional, em desenvolvimento): uma nova entrada interrompe a resposta do modelo ou faz uma chamada demorada de code-mode ceder o controle. Defina instant_interrupt = true em [features] para experimentar. Ativado por padrão desde a v0.162.0.
• O visualizador de avisos descarta os avisos que você já viu ao ser fechado; pressione k para guardar um deles para depois.
• Você pode rolar a transcrição enquanto decide se deseja implementar um plano.
• A renderização de Mermaid aceita mais conexões de fluxogramas, rótulos e grupos de nós.
• Sessões vazias mantêm seus rascunhos quando você troca de tarefa, e as conversas podem ser arquivadas antes do primeiro turno.
• /status é exibido sem bordas e quebra valores longos em várias linhas.
• Clientes do app-server podem paginar o histórico de uma conversa a partir de um item específico.

Mudanças no sandbox: comandos aprovados mantêm as proibições explícitas de acesso ao sistema de arquivos, diretórios .aws dentro das raízes com permissão de escrita são protegidos por padrão (regras explícitas ainda prevalecem), sandboxes do macOS com acesso à rede permitem a avaliação de confiança TLS, e ambientes de execução que exigem um proxy agora recebem um. A skill plugin-creator incluída na distribuição foi removida.

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

v0.158.0 (28 de setembro de 2026)

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

Mudanças nos padrões:

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

Modelos e planos: o GPT-5.4 sai dos catálogos incluídos na distribuição e do Bedrock, e seleções salvas do GPT-5.4 continuam recebendo o aviso de migração para o GPT-6 Sol. O Codex reconhece o plano Pro Max e identifica os níveis Pro como “Pro”, “Pro (More)” e “Pro (Max)”. Os atalhos de raciocínio podem chegar ao Max.

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

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

v0.157.1 (26 de setembro de 2026)

Um patch para Windows com quatro correções trazidas da main por backport. O Codex não abre mais uma janela de console ao iniciar o host de code-mode ou um servidor MCP stdio local. O servidor em segundo plano consegue iniciar quando o Windows mantém o processo dentro de um objeto de trabalho externo, e um servidor em segundo plano desacoplado não mantém mais abertos os pipes de saída do inicializador, o que podia deixar o comando que o chamou aguardando após o encerramento do inicializador. As notas da versão no GitHub e a entrada no 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 altera mais três padrões.

• A transcrição em tela cheia está ativada por padrão. A interface em tela cheia que a v0.156.0 oferecia pelo /tui agora é a interface inicial das sessões, inclusive quando a configuração não tem uma seção [tui]. Para manter o histórico de rolagem do terminal, escolha Scrollback em /tui ou defina fullscreen_transcript = false em [tui]; --no-alt-screen e tui.alternate_screen = "never" continuam tendo precedência. Clicar com Shift agora estende a seleção na transcrição.
• O servidor em segundo plano inicia automaticamente nas inicializações interativas elegíveis, e a opção sai de /experimental. Inicializações com --no-daemon, --oss, --profile ou a maioria das substituições via -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 executar sem ele, reiniciá-lo com as configurações necessárias ou cancelar (o padrão). Para desativar a inicialização automática, defina daemon_auto_start = false em [features].
• O contexto da conversa no Guardian está ativado por padrão para revisões síncronas e assíncronas, independentemente da opção enabled do Guardian v2. Para desativar, 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 Fast. O catálogo incluído na distribuição não marca mais o GPT-6-Astra como 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 aplicativo, mantendo rascunhos e prompts na fila; /import funciona em sessões remotas e com servidor em segundo plano; e o terminal renderiza marcadores Unicode, caixas de seleção e equações alinhadas. As correções mantêm conversas por voz em andamento quando você troca de conversa, recuperam respostas não enviadas quando um turno termina, respeitam as configurações de mouse do tmux, encaminham conexões em tempo real e buscas independentes na web pelos proxies configurados, repetem uploads de arquivos com falhas transitórias com um tempo limite de cinco minutos e aplicam restrições de rede a redirecionamentos e conexões HTTP e WebSocket abertas. No Windows, o acesso a objetos do sandbox é limitado à sessão de logon do executor.¹⁷⁴

v0.156.1 (23 de setembro de 2026)

Um patch com uma única mudança que traz GPT-6 Sol e GPT-6 Luna para o CLI estável. Ambos agora aparecem no seletor /model abaixo do GPT-6-Astra, que continua em primeiro lugar e permanece como padrão da distribuição quando nenhum modelo está definido em config.toml. O seletor passa a identificar a família GPT-5.6 como modelos mais antigos (o GPT-5.6 Sol aparece como “Modelo de programação mais antigo para tarefas complexas”) e o GPT-5.5 como um “Modelo legado de programação”. Quando você se aproxima de um limite de uso, o aviso de troca agora sugere gpt-6-luna em vez de gpt-5.6-luna.

Se sua configuração especifica um modelo mais antigo, espere um aviso 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 apontam para o GPT-6 Sol, e gpt-5.6-luna e gpt-5.4-mini apontam para o GPT-6 Luna. Os catálogos do Amazon Bedrock não mudam nesta versão: eles não incluem GPT-6 Sol nem 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 na distribuição define Fast (priority) como nível de serviço padrão para GPT-6 Sol e Luna, então uma sessão da TUI sem service_tier definido pode começar no modo Fast, que, com login pelo ChatGPT, consome 2,5 vezes os créditos do Standard. Confira com /fast status; /fast off muda para Standard. O que fazer: atualize e experimente codex -m gpt-6-sol em uma tarefa conhecida. A disponibilidade depende do seu plano, das configurações do workspace e da liberação gradual; administradores Enterprise precisam habilitar os novos modelos primeiro.¹⁷¹

v0.156.0 (22 de setembro de 2026)

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

• A voz vem ativada por padrão. /voice inicia uma conversa ao vivo nas builds compatíveis sem precisar acessar /experimental. Outras novidades: um atalho F8 configurável para ativar e desativar a voz, um seletor /voice settings para escolher a voz usada em conversas futuras, runtimes de voz incluídos para Linux e Windows e suporte à redução de movimento.
• Os worktrees gerenciados vêm ativados por padrão. --worktree e /worktree não precisam mais de uma flag de recurso. Sessões de worktree podem se conectar a um daemon local existente e podem ser criadas na visão geral dos agentes.
• A reutilização da compactação da conversa principal pelo Guardian vem ativada por padrão: quando o Guardian reinicia uma sessão de revisão, ele pode reutilizar a compactação criptografada da conversa principal.

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

Outras novidades: uma TUI em tela cheia opcional, selecionada com /tui, com busca 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 matemáticas TeX renderizados no terminal, cada um com seu próprio controle de ativação; um menu /daemon e uma flag --no-daemon; e resumos de raciocínio desativados por padrão em novas conversas da TUI. Correções de segurança eliminam brechas no sandbox do Windows relacionadas a tráfego de entrada, sockets privilegiados e handles de arquivos somente leitura, e codex doctor não exibe mais valores de configuração nas mensagens de erro. Correções de bugs preservam respostas transmitidas em streaming após turnos com falha ou interrompidos, corrigem o encaminhamento da área de transferência no tmux e no SSH, restauram o modo Plan ao retomar uma sessão e permitem recuperar o login 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 conversa local da TUI sem model_reasoning_summary na configuração solicitava resumos detailed, e os provedores sem suporte a resumos de raciocínio rejeitavam a solicitação imediatamente. A versão 0.155.1 restaura none como valor padrão quando a chave não está definida, de modo que nenhum resumo é solicitado nesse caso. As configurações explícitas auto, concise e detailed sempre foram respeitadas e continuam sendo. A mesma alteração de uma linha também foi incorporada à branch main e incluída na versão 0.156.0.

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

v0.155.0 (17 de setembro de 2026)

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

Também na versão 0.155.0:

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

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

v0.154.0 (9 de setembro de 2026)

Esta versão foi fechada aproximadamente no ponto da 0.154.0-alpha.6, então 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 esforço de raciocínio) ficou para a 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 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ção do Guardian também foram removidos, e as aprovações agora são rejeitadas quando novas instruções do usuário as invalidam.

Novidades:

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

Segurança: os utilitários auxiliares do PATH não são mais executados antes de o workspace ser considerado confiável, e o sandbox do macOS recebeu proteção adicional contra injeção de entrada no terminal. As conexões MCP coordenam as renovações de tokens OAuth, a retomada remota e a criação de ramificações preservam as permissões salvas, e retomar uma conversa aberta em outro app exibe uma transcrição somente leitura. A voz foi incluída apenas como infraestrutura de runtime, e as primeiras referências ao Daybreak no código chegaram sem documentação pública.¹⁵²¹⁵³

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

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

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; não há uma versão mínima do CLI documentada, então considere essas as versões mínimas. Se 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 versão v0.153.1 faz a avaliação de uso do computador pelo Guardian respeitar os requisitos do modelo: a avaliaçã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 dispensa a avaliação invalida avaliações anteriores ou em andamento, de modo que voltar ao modelo anterior não possa reativar uma aprovação desatualizada. A descrição da versão lista apenas uma entrada de catálogo do GPT-6-Astra portada para essa versão, configurável por meio do API; o seletor e o padrão só mudaram na v0.153.4. A versão v0.153.2 corrige a descrição do nível Fast do Astra de “1,5x” para “velocidade 2x maior, uso aumentado” (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 campo de mensagem, incluindo conteúdo colado e imagens anexadas; vim_normal.redo é uma ação configurável do mapa de teclas.
• Marketplaces remotos de plugins: o CLI de plugins pode listar, instalar e remover plugins remotos, e codex plugin list mostra origem, versão, política de instalação e política de autenticação.
• tui.auto_recap = false desativa as recapitulações automáticas; 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 dispensa revisões do Guardian para ações que exigem apenas confirmação, e o modo de aprovação User dispensa a avaliação em segundo plano e a preparação antecipada.
• features.context_management.experimental_mode (desativado por padrão) habilita contexto com orçamento de tokens, notas de histórico e a ferramenta new_context para sessões elegíveis dos planos Plus, Pro e Pro Lite no backend do Codex.
• tui.disable_paste_burst substitui a chave de nível superior, que continua funcionando como alternativa.

Correções: as sessões da TUI se reconectam após uma queda do app-server com os rascunhos intactos, o histórico de revisão do Guardian é preservado após compactação, reinicializações e ramificações, e as aprovações salvas do MCP ficam restritas à conta selecionada.¹⁴⁰

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

update_plan passou a exigir ativação explícita: tools.update_plan.enabled tem false como padrão e, enquanto está desativado, as orientações incluídas para update_plan são removidas dos prompts de modelo, modo de colaboração, múltiplos agentes, compactação, pré-aquecimento e continuação de metas (veja Modo de planejamento e colaboração). Outras novidades: busca no Vim com / e ?, além de n/N, combinável com operadores, com novos rascunhos começando no modo de inserção; banners de limite de uso com ações disponíveis; progresso da renovação de credenciais, incluindo reautenticação no Amazon Bedrock; nomes de servidores MCP no formato de pacotes (:, @, / e . são permitidos); solicitações de formulário MCP openai/elicitation; um output_token_limit do MCP por ferramenta; credenciais de tarefas na nuvem restritas a origens confiáveis; tempos limite configuráveis para thread/shellCommand; e controle do 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ção do Guardian obtenha sua política do Node REPL dos metadados do modelo.¹³⁸¹³⁹

v0.151.0 (29 de agosto de 2026)

• /recap resume a conversa sob demanda, e o Codex recapitula automaticamente conversas elegíveis que estejam inativas e sem foco.
• Os hosts do modo de código deixam de usar o transporte WebSocket (apenas stdio e gRPC).
• As threads persistentes passam a usar histórico paginado por padrão quando o armazenamento oferece suporte.
• O nível de esforço de raciocínio persistent chega com ferramentas de relógio e orientações de proatividade incluídas.
• O Guardian v2 passa a usar por padrão revisões de uso do computador com imagens.
• O Vim ganha movimentos de busca e deslocamento até caracteres com f/F/t/T, além de gg/G.
• O envio de dados a terminais com permissões elevadas pode exigir uma nova aprovação (write_stdin_approval, desativado por padrão).
• Um período de tolerância configurável para servidores MCP opcionais (mcp_optional_startup_grace_ms, padrão de 1.000 ms), e extensões podem inspecionar ou substituir resultados de ferramentas MCP.

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

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

Os hooks ganham um evento Interrupt que é executado quando um turno ativo de nível superior é interrompido (tempo limite padrão de 1 segundo, máximo 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 referenciáveis por menções com @, os agentes podem ler, criar e enviar mensagens para tarefas, e /rename sugere um título editável. Os links Markdown são renderizados como rótulos clicáveis, atalhos podem alternar entre os modos de permissão, o Vim ganha repetição com ., e projetos não confiáveis deixam de fornecer instruções de AGENTS.md no nível do projeto. features.network_proxy.credential_broker e review_scope.computer_use_only do Guardian v2 chegam como opções configuráveis, desativadas por padrão. A v0.150.1 contabiliza as imagens mantidas no orçamento de tokens da compactação remota.¹³²¹³³

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

A política de aprovação untrusted foi descontinuada; altere as configurações que a usam 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 no Vim, um codex doctor mais abrangente (proteção de endpoints, falhas de rede e proxy, estado do aplicativo desktop, conectividade para atualizações) e níveis de esforço de raciocínio max/ultra nas SDKs. As threads retomadas e derivadas restauram seu perfil de permissões. A v0.149.1 adiciona codex exec --thread-source <SOURCE> (user, subagent, memory_consolidation ou o nome de um recurso; threadSource na SDK do TypeScript).

Preços no mesmo período: a OpenAI reduziu os preços do GPT-5.6 Sol em mais de 20% por três meses a partir de 21 de agosto (até pelo menos 21 de novembro de 2026), e a tarifa 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–18 de agosto de 2026)

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

Versões anteriores (maio–julho de 2026)

• v0.146.0 e v0.146.1 (29 de julho, 5 de agosto): os proxies configurados abrangem todos os transportes; manifestos de Agent Plugins e os marketplaces do Amazon Bedrock e do Claude Code; nomeação de sessões com fixação de threads; skills fornecidas pelo executor; padrões mais restritivos de revisão automática para modelos com capacidades de cibersegurança.¹¹⁴¹¹⁵
• v0.145.0 (21 de julho): /import do Cursor, além do Claude Code; a voz retorna como conversas V3 em tempo real por streaming; a experiência opcional de múltiplos agentes 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 em 272.000 tokens.¹¹¹¹¹²
• v0.140.0 (15 de junho): /usage, codex delete e /delete, /import do Claude Code, o menu unificado de menções com @, autenticação do Amazon Bedrock por chave de API e armazenamento local criptografado para credenciais de CLI e de OAuth do MCP; os antigos controles de voz /realtime foram removidos.¹⁰²
• v0.139.0 (9 de junho): o modo de código pode chamar a busca na web diretamente, os esquemas das ferramentas preservam oneOf/allOf, codex doctor informa detalhes do editor e do paginador, e as fontes dos marketplaces aparecem na saída de JSON.¹⁶⁵
• v0.138.0 (8 de junho): /app transfere uma sessão do CLI para o aplicativo desktop, e o texto das tarefas enviado do agente principal ao subagente é criptografado no modo de múltiplos agentes v2.¹⁶⁶¹⁰⁸
• v0.137.0 (4 de junho): múltiplos agentes v2, atalhos de teclado F13-F24 na TUI e uma extensão de skills v1.¹⁶⁷
• v0.132.0 a v0.135.0 (20–28 de maio): busca no histórico local de conversas, --profile como seletor principal de perfil, metas ativadas por padrão, herança de perfis de permissões e requirements.toml gerenciado, início e parada de codex remote-control, mais informações em codex doctor e /status, objetos de texto do Vim, perfis de permissões nomeados em /permissions, autenticação na SDK do Python e predefinições de Sandbox, além de codex exec resume --output-schema. A atualização do aplicativo de 21 de maio adicionou Appshots, disponibilidade geral do modo de metas e Computer Use bloqueado com ativação opcional.^{96979899100101196}

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

Nota sobre estabilidade: Interfaces e recursos estáveis e documentados: o CLI principal e a TUI, o isolamento em sandbox e as políticas de aprovação, config.toml, AGENTS.md, skills, hooks, plugins, ferramentas multiagente, metas, perfis de permissão, /voice e worktrees gerenciadas (padrão desde a v0.156.0), a transcrição em tela cheia e a inicialização automática do servidor em segundo plano (padrão desde a v0.157.0), a aprovação de entrada no terminal, a cópia ao selecionar e a colagem com o botão direito (padrão desde a v0.158.0), a interrupção instantânea (padrão desde a v0.162.0, ainda marcada como em desenvolvimento), o Daybreak e a interrupção do modo de código (cli_daybreak, code_mode_interrupt; estáveis e ativados desde a v0.163.0), além do assistente de configuração do Bedrock, das atualizações incrementais de ferramentas e da coordenação da atualização de MCP OAuth (estáveis e ativados desde a v0.164.0). As worktrees gerenciadas e a conversa em tempo real são permanentes desde a v0.164.0: suas flags estão marcadas como removidas, e os recursos continuam ativados. Browser, Computer Use e Appshots são recursos documentados voltados ao usuário cuja disponibilidade depende da plataforma e do plano. Experimentais ou em desenvolvimento: Codex Cloud, modo de código e busca de ferramentas no modo de código, Memory v2, o mural local de mensagens dos agentes, as flags de histórico e de contexto de transferência do Guardian (v0.160.0) e tudo o que estiver marcado como [EXPERIMENTAL] neste guia ou listado em /experimental; esses recursos podem mudar entre versões. O gerenciamento experimental de contexto, segundo a referência de configuração, “não está disponível no momento”. Removidos: --full-auto (v0.147.0), a política de aprovação untrusted (v0.149.0), codex mcp-server (v0.154.0), a opção de desativar thread_context do Guardian (v0.158.0), as flags shell_zsh_fork e unified_exec_zsh_fork, junto com o próprio zsh modificado (v0.163.0), e js_repl.

Canal alpha: builds alpha são lançadas várias vezes ao dia, as descrições dos lançamentos nas séries alpha são esboços, e builds fora do ciclo normal, derivadas de bases mais antigas, aparecem regularmente. Pelo menos duas vezes, a tag alpha do npm apontou para uma delas, fazendo com que @alpha instalasse uma build mais antiga que latest. A série 0.158 foi da 0.158.0-alpha.2 (23 de setembro) à alpha.15 (25 de setembro); sua versão estável, v0.158.0 (28 de setembro), foi gerada a partir da build fora do ciclo normal 0.158.0-alpha.15.4, composta pela alpha.15 mais dezesseis backports, e permaneceu como latest no npm até a publicação da v0.159.0, 27 horas depois. A série 0.159 foi da alpha.1 (25 de setembro) à alpha.13 (28 de setembro) e foi lançada como v0.159.0 a partir da alpha.13. A série 0.160 chegou à 0.160.0-alpha.6 (29 de setembro) e ficou congelada nesse ponto; a 0.161.0-alpha.1 é a alpha.6 apenas com o número da versão alterado. Em 30 de setembro, a 0.160.0-alpha.6.1 acrescentou à alpha.6 a única correção do console do Windows da v0.159.2 que faltava. No mesmo dia, a série 0.159 recebeu mais uma versão de correção, a v0.159.3. A série 0.160 foi então lançada como estável na v0.160.0 (1º de outubro), gerada a partir da alpha.6.1 mais um backport, e na v0.160.1 (5 de outubro). A série 0.161 produziu alphas e backports fora do ciclo normal, sendo a mais recente a 0.161.0-alpha.13.1 (6 de outubro), mas nenhuma versão estável; ela não é considerada pulada, porque nenhuma versão superior foi lançada como estável. Agora, alpha aponta para a 0.162.0-alpha.16. Se você acompanha as alphas, confira npm view @openai/codex dist-tags e instale uma versão exata em vez de usar @alpha.^176179181185 Um histórico com datas de como as séries alpha recentes se tornaram versões estáveis está em ¹⁷³. A série 0.161 foi lançada como v0.161.0 em 7 de outubro a partir da 0.161.0-alpha.13.1 (com um commit de lançamento adicional); a v0.162.0 veio em seguida, em 8 de outubro, a partir da 0.162.0-alpha.18.1, enquanto a 0.162.0-alpha.20 estava 52 commits à frente da base usada para essa versão estável; a v0.162.1 acrescentou três commits em 9 de outubro; alpha era a 0.163.0-alpha.5 em 10 de outubro, passou pelas alpha.8, alpha.9 e alpha.10 em 13 de outubro e estava na 0.163.0-alpha.11 em 14 de outubro. A série 0.163 chegou à versão estável em 15 de outubro: a v0.163.0 foi gerada a partir da 0.163.0-alpha.10.2, lançada fora do ciclo normal (com um commit de lançamento adicional), enquanto a alpha.11 estava 23 commits à frente dessa base. A série 0.164 começou em 16 de outubro com a alpha.1 e a alpha.2, chegou à 0.164.0-alpha.3 em 17 de outubro e à alpha.12 em 22 de outubro, acompanhada pelas builds fora do ciclo normal 0.163.0-alpha.11.1 e 11.2 (21 e 22 de outubro) e 0.164.0-alpha.11.1 (23 de outubro). A série 0.164 foi lançada como estável em 23 de outubro, na v0.164.0, gerada a partir da alpha.11 mais um commit de lançamento (a alpha.12 estava nove commits à frente dessa base), e alpha passou para a 0.165.0-alpha.1 no mesmo dia.^{189190191193195}

Como o Codex funciona: o modelo mental

Antes de explorar os recursos, entenda como a arquitetura do Codex molda tudo o que você faz com ele. O sistema opera em cinco 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 / bubblewrap / 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 29 de setembro de 2026, a geração atual é a GPT-6: gpt-6.1-sol para programação complexa e trabalho com agentes (o padrão incluído do CLI quando nenhum modelo está configurado, desde a v0.159.1), gpt-6-astra para os trabalhos completos mais difíceis, gpt-6-luna para tarefas específicas e de alto volume e o modelo da geração anterior gpt-6-sol. Os modelos GPT-5.6 (Sol, Terra, Luna) continuam disponíveis durante a implantação; o gpt-5.5 (contexto de 400K no Codex e 1M no API) deixará de estar disponível no Codex para login com o ChatGPT em 14 de outubro de 2026, e o gpt-5.4 deixou de estar disponível no Codex em 31 de agosto de 2026.^{83117146148149171178} Ele lê arquivos, escreve patches, executa comandos do shell e raciocina sobre sua base de código. Quando o contexto fica cheio, o Codex compacta a conversa para liberar espaço. Essa camada consome tokens.

Camada de segurança: todos os comandos executados pelo Codex passam por um sandbox no nível do sistema operacional. No macOS, o framework Seatbelt da Apple aplica restrições no nível do kernel. No Linux, o Bubblewrap isola o sistema de arquivos e os namespaces, enquanto o seccomp filtra as chamadas de sistema; a implementação anterior com Landlock é mantida como opção legada. O sandbox opera no nível do kernel, não dentro de contêineres. Em seguida, a política de aprovação determina quando solicitar confirmação humana.

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

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

O principal insight: a maioria dos usuários utiliza apenas uma interface. Usuários avançados usam as cinco: Cloud para tarefas de longa duração, CLI para operações determinísticas no repositório, extensão de IDE para ciclos rápidos de programação, aplicativo para desktop para planejamento e coordenação e extensão do navegador para fluxos de trabalho no navegador com login ativo.

Sumário

1. Como instalar o Codex?
2. Início rápido: sua primeira sessão
3. Principais interfaces de interação
4. Análise detalhada do sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Codex?
7. Estruturas para tomada de decisões
8. Como 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 depurar problemas? — incluindo codex doctor
26. Implantação empresarial
27. Boas práticas e antipadrões
28. Receitas de fluxos de trabalho
29. Guia de migração
30. Cartão de referência rápida
31. 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, voltar a uma versão anterior ou desinstalar o Codex CLI?

O Codex inclui um comando de autoatualização desde a v0.128.0; todas as outras operações usam o gerenciador de pacotes que fez a instalação.⁸⁶ A partir da v0.146.0, os artefatos de lançamento, os metadados dos canais e os aliases do instalador são distribuídos pela infraestrutura de lançamentos hospedada pela OpenAI, com GitHub como alternativa de fallback.¹¹⁴ Se sua rede permite acesso ao GitHub para instalar e atualizar o Codex, adicione também o host de lançamentos da OpenAI — por causa do fallback, a ausência desse host na lista de permissões prejudica o funcionamento silenciosamente, sem gerar um erro explícito.

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

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

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

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

Fixar uma versão é a melhor opção quando uma atualização causa problemas. O Codex mantém um ritmo rápido de lançamentos estáveis, então instalar uma versão exata é a forma mais rápida de reverter – registre o problema, fixe a versão e siga em frente. Confirme que a reversão funcionou com codex --version, pois uma segunda instalação com precedência no seu PATH continuará fornecendo o binário antigo silenciosamente (codex doctor sinaliza exatamente isso em Ambiente).

Desinstalar o pacote não remove seus dados. A autenticação, as configurações e o histórico de sessões ficam em ~/.codex/. Mantenha essa pasta para preservar os logins e o histórico ao reinstalar; exclua-a apenas se quiser 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 no GitHub:⁶⁰

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

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

Download de binários

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

Requisitos do sistema

• macOS: Apple Silicon ou Intel (suporte completo a sandbox via Seatbelt)
• Linux: x86_64 ou arm64 (sandbox via bubblewrap + seccomp)
• Windows: Sandbox nativo com tokens restritos (deixou de ser experimental na v0.100.0). Também há suporte a WSL²

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

Duas formas de autenticação:

1. Conta ChatGPT (recomendado): Faça login com sua assinatura atual Plus, Pro, Team, Business, Edu ou Enterprise. Acesso completo aos recursos, incluindo 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 (conversas na nuvem) podem ficar indisponíveis.

Dica avançada: Você pode configurar o armazenamento de credenciais por meio de cli_auth_credentials_store em config.toml. Opções: file (padrão), keyring (chaveiro do sistema operacional) ou auto (keyring, se disponível; arquivo como fallback).

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

Autocompletar no shell

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

Verificar a instalação

codex --version
# codex-cli 0.164.0

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

Comece do zero e seja produtivo em 5 minutos.

1. Instale e autentique:

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

2. Acesse a pasta de um projeto:

cd ~/my-project                  # Any git repo works

3. Inicie o Codex:

codex

Você verá a TUI interativa. O Codex lê a estrutura do seu projeto automaticamente.

4. Faça uma pergunta:

> What does this project do? Summarize the architecture.

O Codex lê os principais arquivos e explica a base de código. Uma pergunta como essa não gera alterações — o Codex só modifica arquivos quando você pede uma mudança, e o sandbox e a política de aprovação determinam quando ele precisa pedir permissão antes.

5. Faça uma alteração:

> Add input validation to the login endpoint

O Codex propõe edições na forma de 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 para iniciar a execução.

7. Confira seu trabalho:

> /diff

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

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

Interfaces principais de interação

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

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:

• Campo de entrada: Digite prompts, anexe arquivos com @, execute comandos de shell com o prefixo !
• Painel de saída: Respostas do modelo em tempo real, chamadas de ferramentas e saída de comandos
• Barra de status: Modelo, uso de tokens, branch do git, modo de sandbox

Principais atalhos da TUI:

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

Slash commands disponíveis na TUI:

Redesenho do seletor de fluxo de trabalho (v0.129.0): As opções de retomar e criar ramificações agora estão mais acessíveis em um seletor redesenhado, e um novo modo de histórico de rolagem bruto permite navegar pela transcrição não renderizada quando você precisa copiar comandos ou a saída do modelo literalmente. Útil para analisar uma sessão longa de depuração ou encaminhar a saída para outra ferramenta.⁸⁹

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

2. Codex Desktop App (macOS + Windows)

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

O aplicativo desktop adiciona recursos que a CLI não tem:

• Multitarefa: Execute vários agentes em paralelo em diferentes projetos simultaneamente
• Isolamento com worktrees do Git: Cada conversa trabalha em uma cópia isolada do seu repositório
• Revisão de diffs na própria interface: Prepare, reverta e faça commit de alterações sem sair do aplicativo
• Terminal integrado: Terminal por conversa para executar comandos
• Ramificação de conversas: Crie ramificações de conversas para explorar alternativas
• Janelas flutuantes destacáveis: Destaque conversas em janelas que você pode mover
• Automações: Agende tarefas recorrentes (triagem de issues, monitoramento de CI, resposta a alertas)
• Appshots: Anexe a uma conversa a janela do aplicativo Mac em primeiro plano, com uma captura de tela e o texto disponível
• Comentários no navegador integrado: Visualize páginas locais ou públicas, deixe comentários sobre elementos ou áreas e permita que o Codex atenda a feedback visual preciso
• Computer Use: Permita que o Codex opere aplicativos Mac autorizados em tarefas com escopo definido na interface gráfica; o uso com a tela bloqueada é opcional para turnos remotos elegíveis de Computer Use no Mac

ChatGPT Voice, com tecnologia GPT-Live (desktop 26.715, 23 de julho de 2026): Agora você pode controlar o aplicativo desktop por voz — converse sobre o trabalho e coordene tarefas entre Chat, Work e Codex sem digitar. No macOS, ativar o Contexto da tela compartilha com a conversa um appshot da janela em primeiro plano, para que você possa perguntar sobre o que está vendo em vez de descrever. Disponível nos planos Plus, Pro, Business, Edu e Enterprise, no aplicativo desktop e pelo Remote no iOS. Esse é o recurso de voz da interface desktop. A CLI tem seus próprios recursos de voz, separados: conversas ao vivo com /voice na TUI (ativadas por padrão desde a v0.156.0) e ditado pela barra de espaço (adicionado experimentalmente na v0.105.0).¹¹³¹⁶⁹

Retratos compartilhados de conversas (20 de agosto de 2026): Em todos os planos do Codex, o aplicativo desktop para macOS pode compartilhar um retrato somente para leitura de uma conversa local do Codex. O retrato não é atualizado quando a conversa original muda; links de contas pessoais abrem para qualquer pessoa com o link, enquanto links de contas de espaços de trabalho abrem apenas para membros do espaço de trabalho de origem. O Codex oculta padrões conhecidos de segredos antes do compartilhamento, mas a OpenAI orienta você a revisar o conteúdo compartilhado porque informações sensíveis podem permanecer. Visualize ou revogue links nos controles de dados do ChatGPT, em Links compartilhados.¹²⁸

Quando usar o aplicativo ou a CLI: Use o aplicativo desktop quando estiver coordenando várias frentes de trabalho ou precisar de revisão visual de diffs. Use a CLI quando quiser combinar ferramentas no terminal, criar scripts ou integrar com CI/CD.

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

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

• Modo de agente por padrão: Lê arquivos, faz edições, executa comandos
• Edições no próprio código: Sugestões que levam em conta o contexto dos 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 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 deixe executar: Coloque na fila tarefas que são executadas independentemente da sua máquina local
• Execução paralela: Execute várias tarefas na nuvem simultaneamente
• Criação de PRs: O Codex cria pull requests a partir do trabalho concluído
• Aplicação local: Traga os resultados da nuvem para seu repositório local com codex apply <TASK_ID>

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

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

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

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

• 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 quais sites o Codex pode acessar; por padrão, ele não tem acesso a nenhum.
• Navegador como ambiente de trabalho: A extensão é mais indicada para trabalhar com aplicativos e sites em que a página é a fonte de verdade — consoles de administração, painéis internos, interfaces de gerenciamento de conteúdo, sistemas de chamados — e não substitui a CLI em repositórios locais.
• Mesma inteligência: a extensão de navegador usa a mesma inteligência GPT-5.x-Codex das outras interfaces, então uma configuração de AGENTS.md ou skills que funciona na CLI leva as mesmas convenções para o trabalho feito pelo navegador.

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

Análise detalhada do sistema de configuração

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

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

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

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

Locais dos arquivos de configuração

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

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

Referência completa de configuração

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-6-sol"             # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # on-request|never (untrusted retired in v0.149.0)

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

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

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output (global; per-tool MCP overrides in v0.152.0)
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

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

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Browser-extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

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

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

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

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

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

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

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

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

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

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

Perfis

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

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

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

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

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

Ative um perfil:

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

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

Provedores de modelos personalizados

Conecte-se ao Azure, AWS Bedrock, a modelos locais ou a serviços de proxy:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

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

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

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

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

Aviso: o API de comunicação chat/completions (wire_api = "chat") foi descontinuado para modelos hospedados pela OpenAI, e a OpenAI anunciou sua remoção em fevereiro de 2026.³⁴ Provedores locais (Ollama, LM Studio) ainda podem aceitar esse formato. Para endpoints da OpenAI, use wire_api = "responses".

Use modelos locais com a flag --oss:

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

Ou defina na configuração:

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

Substituições de configuração inline

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

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Qual modelo devo escolher?

Modelos disponíveis (setembro de 2026)

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

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

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

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

Nota sobre o nível gratuito (5 de maio de 2026): o GPT-5.5 Instant foi disponibilizado no nível gratuito do ChatGPT em 5 de maio de 2026. Isso amplia o público da família GPT-5.5 para além dos planos pagos, embora o acesso ao Codex CLI continue exigindo uma assinatura Plus / Pro / Business / Enterprise / Edu / Go elegível ou uma chave da API.⁹²

GPT-5.4 mini (17 de março de 2026): uma variante menor e mais rápida do GPT-5.4, com contexto de 400K por US$ 0,75/US$ 4,50 por MTok — usa apenas 30% da cota do GPT-5.4. Ideal para delegação a subagentes: deixe o GPT-5.4 cuidar do planejamento e da coordenação, enquanto subagentes GPT-5.4 mini executam subtarefas mais específicas (pesquisa na base de código, revisão de arquivos e processamento de documentos) em paralelo.⁷⁶

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

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

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

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

Fluxograma de seleção de modelo

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

Esforço de raciocínio

Controle quanto o modelo “pensa” antes de responder:

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

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

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

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

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

Troca de modelo

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

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

Quanto custa o Codex?

Consulte também Seleção de modelos para conhecer os recursos e Frameworks de decisão para escolher o modelo certo para cada tarefa.

Acesso pelos planos do ChatGPT

A disponibilidade do Codex depende do seu plano do ChatGPT e das configurações da organização:⁵¹

Atualização de preços de abril de 2026: o preço anual do Business caiu de US$ 25 para US$ 20 por licença/mês. Licenças exclusivas para Codex com pagamento conforme o uso agora estão disponíveis para os workspaces Business e Enterprise — sem tarifa fixa por licença, com cobrança baseada no consumo de tokens.⁷⁹ A página de preços agora publica os limites como faixas por modelo (consulte a tabela acima), em vez dos multiplicadores promocionais de 2x do lançamento do Desktop App em fevereiro de 2026.¹⁶¹⁶²

Aumento do limite de uso em maio de 2026 (encerrado em 31 de maio de 2026): no plano Plus, o Codex operou com um limite de 5 horas 25× maior (em comparação com o aumento padrão de 20×), e o limite da faixa de US$ 100/mês foi dobrado durante o mesmo período.⁸⁹

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

Custos em créditos

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

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

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

Cobrança da API

Ao usar o Codex por meio da API, a OpenAI cobra o uso por token conforme o preço padrão da API da OpenAI para o modelo selecionado (além de eventuais descontos aplicáveis pelo cache de prompts). Tarifas atuais da API por 1 milhão de tokens: GPT-6.1 Sol, US$ 2 pela entrada / US$ 10 pela saída (US$ 0,10 pela entrada em cache); GPT-6 Sol, US$ 2 / US$ 10; GPT-6 Luna, US$ 0,10 / US$ 0,50; GPT-6 Astra, US$ 10 / US$ 50. Para os quatro modelos, prompts acima de 272 mil tokens de entrada custam 2x o preço da entrada e 1,5x o preço da saída para toda a solicitação, e o modo Fast custa 2x.^146171178 Os multiplicadores de créditos do ChatGPT não se aplicam ao login com chave da API. Consulte a página oficial de preços da API para ver as tarifas atuais.²⁰

Estratégias de otimização de custos

1. Use perfis: crie um perfil fast com gpt-6-luna e model_reasoning_effort = "low" para tarefas rotineiras
2. Reserve o raciocínio avançado: use xhigh apenas para problemas realmente difíceis, pois ele consome de 3 a 5 vezes mais tokens
3. Use --ephemeral: ignore a persistência da sessão em CI/CD para reduzir a sobrecarga
4. Minimize os resumos de raciocínio: defina model_reasoning_summary = "none" quando não precisar de explicações
5. Processe em lote com o modo exec: codex exec evita a sobrecarga da TUI nos fluxos de automação
6. Monitore o uso: consulte /status na TUI e os painéis de cobrança da sua organização — desde a v0.148.0, /status, as linhas de status e os títulos do terminal exibem a estimativa de créditos ou custos da thread para workspaces qualificados¹¹⁸

Exemplos de custos reais

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

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

Sobrecarga oculta de tokens

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

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

Gerenciamento de custos da equipe

Estratégias para controlar os custos da equipe: - Configure requirements.toml para aplicar limites de modelo e de esforço de raciocínio em toda a organização - Use gpt-5.6-luna para CI/CD — pipelines automatizados raramente precisam do nível máximo de raciocínio - Orçamento baseado em perfis — defina os perfis ci, review e dev com tetos de custo adequados - Monitore via OpenTelemetry — implantações Enterprise podem exportar a telemetria de uso para as stacks de observabilidade existentes

Estruturas de decisão

Quando usar cada interface

Quando usar cada modo de sandbox

Quando usar cada nível de raciocínio

Modo de planejamento vs execução direta

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

Modo Steer: Enter vs Tab

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

Desktop App vs CLI

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

Qual perfil usar?

Associe sua tarefa a um perfil pré-configurado:

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

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

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

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

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

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

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

O Codex usa um modelo de segurança de 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 ver as restrições de requirements.toml que os administradores aplicam em toda a organização.

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

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

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

Aplicação específica por plataforma:

• macOS: framework Seatbelt da Apple via sandbox-exec, com perfis específicos para cada modo compilados em tempo de execução e aplicados pelo kernel⁶. Desde a v0.121.0, os perfis de sandbox do macOS podem permitir sockets Unix específicos (por exemplo, docker.sock e sockets IPC do editor), e a resolução de DNS privado deixou de ser bloqueada por padrão.⁸²
• Linux: bubblewrap (bwrap) para isolamento do sistema de arquivos e de namespaces + seccomp para filtragem de syscalls, executados por meio de um processo auxiliar independente (codex-linux-sandbox); a implementação Landlock foi mantida como legado, e a v0.163.0 renomeou o tipo de comando e o módulo de syscalls do crate que faziam referência ao Landlock, sem alterar a aplicação das restrições.⁵¹⁹³ O Codex prefere o primeiro bwrap no PATH que esteja fora do diretório de trabalho e, se necessário, usa o codex-resources/bwrap incluído (distribuído desde a v0.100.0)⁷, exibindo um aviso na inicialização quando o bwrap não está disponível ou não consegue criar namespaces de usuário. A v0.117.0 melhorou a confiabilidade do sandbox em distribuições mais antigas com configurações legadas do kernel.⁷⁵ A v0.129.0 reforçou a inicialização do sandbox no Linux e atualizou o Bubblewrap incluído para a versão 0.11.2, com correções de segurança upstream; a v0.130.0 adicionou outros reforços à inicialização.⁸⁹⁹¹
• Windows: sandbox nativo com tokens restritos (promovido de experimental na v0.100.0). Também há suporte ao WSL (que herda o bubblewrap + seccomp do Linux). A v0.117.0 inclui melhorias no sandbox com tokens restritos para oferecer melhor isolamento de processos.⁷⁵ A v0.130.0 concede aos usuários do sandbox acesso ao cache de binários do runtime do desktop para que o sandbox do Windows consiga localizar esses binários de forma confiável para usuários do sandbox do workspace.⁹¹

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

Correções de segurança: - Contorno do sandbox por fork do zsh (v0.106.0): corrigida uma vulnerabilidade em que a execução do shell por meio de fork do zsh podia contornar as restrições do sandbox.⁶⁰ Se você estiver usando uma versão anterior, atualize imediatamente. - Limite de tamanho da entrada (v0.106.0): agora, o Codex aplica um limite de entrada de aproximadamente 1 milhão de caracteres para evitar travamentos causados por payloads excessivamente grandes.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): um novo perfil reforçado para clientes que usam devcontainers do Docker utiliza Bubblewrap para executar o sandbox dentro do contêiner. Há suporte ao WSL2; o WSL1 é explicitamente recusado (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 que hooks executados antes ou depois de ferramentas não interfiram nas decisões do subagente Guardian.⁸² Se você depende de hooks para registro ou validação, lembre-se de que uma revisão do Guardian os ignora — recorra à observabilidade do app-server caso precise de uma trilha de auditoria completa. - Sistema de arquivos /dev no Linux (v0.105.0): agora, os comandos executados no sandbox no Linux recebem um sistema de arquivos /dev mínimo, o que melhora a compatibilidade com ferramentas que esperam nós de dispositivos.⁶¹

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

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

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

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

on-failure ainda aparece em alguns exemplos antigos e caminhos de compatibilidade, mas a documentação atual de configuração da OpenAI o identifica como obsoleto. 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 vincular um atalho de teclado para alternar entre os modos de permissão no composer — 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 flexíveis de aprovação (v0.105.0+)

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

• Permissões adicionais do sandbox: quando um comando precisa de acesso além do permitido pelo modo atual do sandbox, o Codex pode solicitar permissões adicionais específicas, sem exigir uma mudança completa de modo
• Rejeição granular: rejeite chamadas individuais de ferramentas com 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.) pelo fluxo de aprovação da TUI, em vez de falhar silenciosamente ou exigir que o usuário reinicie com flags diferentes.

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

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

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

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

Aprovação para entrada elevada no terminal (v0.151.0; habilitada por padrão desde a v0.158.0)

A flag de recurso write_stdin_approval — desabilitada por padrão quando chegou na v0.151.0 e habilitada por padrão desde a v0.158.0 — exige uma nova aprovação antes que uma entrada não vazia seja enviada a um terminal unified-exec elevado. Essas revisões passam por hooks, Guardian, app server e TUI como aprovações writeStdin; o ambiente do terminal, o diretório de inicialização e o estado de elevação persistem entre turnos, e a identidade do processo é revalidada após a aprovação, antes da gravação de qualquer byte. 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.¹³⁵ A v0.158.0 ativa a flag (#47799) e impede que concessões exclusivas do runtime, como as usadas por plugins para métricas, acionem uma revisão, enquanto permissões adicionais do agente, contornos do sandbox e alterações de política desde a inicialização ainda acionam (#48073). Para desativar: defina write_stdin_approval = false em [features] no config.toml.¹⁷⁶

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

Os perfis de permissão 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 promove os perfis a uma superfície gerenciada: APIs de listagem 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 passa a usar o perfil resolvido em vez de uma política ad hoc separada.⁹⁸

default_permissions = "project-safe"

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

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

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

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

Use none para arquivos confidenciais e globs que devam permanecer ilegíveis mesmo quando a raiz do projeto permitir gravação. Para exceções pontuais de comandos, prefira regras em vez de ampliar um perfil de forma abrangente.⁸⁷

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

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

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

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

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

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

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

Configurações recomendadas

Desenvolvimento diário (padrão seguro):

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

Usuário avançado (acesso completo, 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 a recomendação: as solicitações de aprovação são acionadas quando um comando precisa sair do sandbox ou acessar a rede, e danger-full-access remove esses dois limites, portanto on-request quase não tem mais o que elevar. Essa configuração oferece capacidade máxima com o mínimo de perguntas, não capacidade máxima com verificação humana de cada comando; se você quiser a segunda opção, mantenha workspace-write e deixe o limite do sandbox acionar as solicitações.¹²³

Automação de CI/CD:

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

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

As aprovações inteligentes podem encaminhar solicitações de revisão a 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 vazam para revisões posteriores).⁷³

Configure o revisor no 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 usar approval_policy = "never" para tudo.

Padrões do Guardian v2 invertidos (v0.151.0): agora, o Guardian v2 usa por padrão revisões de uso do computador com imagens. features.guardianv2.review_scope.computer_use_only usa 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 usa true como padrão — defina-o como false para não incluir imagens nas transcrições do Guardian. Ambos foram lançados na v0.150.0 como opções configuráveis e desabilitadas por padrão; foi na v0.151.0 que passaram a ser habilitados por padrão.¹³⁵

O escopo do Guardian acompanha o modo de aprovação (v0.153.0): agora, dois modos ignoram operações 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 falha ou restritos não são tratados como Full Access, e o estado ativo das permissões é 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 e a pontuação assíncrona do Guardian são ignorados, e as confirmações comuns de execução de node_repl.js são aceitas automaticamente, enquanto as verificações de ações confidenciais e as solicitações de entrada do usuário mantêm o comportamento atual.¹⁴⁰ Isso restringe quando o Guardian é executado, não a camada de aprovação humana: o comportamento de solicitação descrito neste guia para danger-full-access com on-request pertence à política de aprovação, que é um mecanismo separado. Além disso, a v0.152.1 permite que a revisão de aprovação do Guardian obtenha sua política do Node REPL a partir dos 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 pelo Guardian respeita os requisitos do modelo (v0.153.1): agora, a pontuação exclusiva de uso do computador pelo Guardian e as decisões rápidas de aprovação só são executadas quando o modelo ativo define node_repl_auto_review_required nos próprios metadados, e pontuações anteriores ou em andamento são invalidadas quando uma troca de modelo ignora a pontuação — assim, voltar para um modelo revisado não pode reativar uma decisão de aprovação obsoleta. Essa é a principal mudança do patch v0.153.1 e não está descrita no corpo 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 do agente principal pelo Guardian é habilitada 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 quando reinicia uma sessão de revisão. De acordo com os testes do PR, as sessões de revisão em cache ainda são invalidadas quando o histórico principal muda. Para restaurar o comportamento anterior: defina guardian_reuse_parent_compaction = false em [features] no config.toml ou execute codex features disable guardian_reuse_parent_compaction.¹⁶⁹¹⁷¹

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

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

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

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

Classificação mais rigorosa do 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 despercebidos pela aprovação automática — fechando uma brecha pela qual código PowerShell ofuscado ou criado dinamicamente podia escapar da classificação no Windows.¹⁰⁵

Detecção ampliada de comandos perigosos (v0.144.5): agora, a detecção reconhece mais formas de execução forçada de rm, e comandos rejeitados retornam motivos de rejeição mais claros, em vez de uma recusa opaca — algo útil ao ajustar políticas de aprovação e precisar entender por que um comando foi bloqueado.¹¹⁰

Habilitando o acesso à rede

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

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

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

Suporte a proxy do WebSocket (v0.104.0+)

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

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

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

A v0.146.0 foi a versão que tornou verdadeira, de fato, a afirmação “todas as camadas de transporte”. Agora, os proxies configurados são respeitados na autenticação, nos downloads de plugins, na autorização do MCP, na execução remota, nas conexões do WebSocket, nos redirecionamentos HTTP e nas conexões do LM Studio — sete caminhos que, segundo o changelog, anteriormente ignoravam o proxy.¹¹⁴ Se você executava o Codex por trás de um proxy corporativo antes da v0.146.0 e via falhas de login ou instalação de plugins enquanto chamadas comuns ao modelo funcionavam, essa lacuna provavelmente era a causa.

Proxy do sistema no macOS (v0.142.2+): com respect_system_proxy habilitado, os clientes de autenticação do macOS respeitam as configurações de proxy, PAC e WPAD do sistema — portanto, Macs corporativos que recebem configurações de proxy por meio de perfis não precisam mais de variáveis de ambiente de proxy específicas por 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 no macOS ou no Windows, incluindo a configuração automática por 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, ambos os comandos deverão falhar com um erro de permissão negada em um perfil limitado ao workspace. Se algum dos comandos for executado com sucesso, será necessário investigar a configuração do sandbox.

Como funciona o AGENTS.md?

O AGENTS.md é o sistema de instruções de projeto do Codex — um padrão aberto⁹ agora administrado pela Agentic AI Foundation da Linux Foundation. Compatível com Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode e mais de 60.000 projetos de código aberto. Ele define como o Codex se comporta em um repositório ou diretório específico. Consulte Skills para conhecer pacotes reutilizáveis de conhecimento especializado que complementam o AGENTS.md.

Hierarquia de descoberta

O Codex cria uma cadeia de instruções no início da sessão percorrendo a árvore de diretórios:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Projeto (da raiz do git até o diretório atual): em cada nível, verifica AGENTS.override.md > AGENTS.md > nomes de arquivos alternativos
3. Mesclagem: os arquivos são concatenados da raiz para baixo; arquivos mais próximos aparecem depois no prompt e substituem orientações anteriores

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Projetos não confiáveis ignoram o AGENTS.md do projeto (v0.150.0): o percurso acima pressupõe que o projeto seja confiável. Desde a v0.150.0, “Projetos não confiáveis não fornecem mais instruções do AGENTS.md no nível do projeto, e as regras gerenciadas de negação de leitura continuam em vigor após alterações de permissão” — a descoberta no escopo do projeto é ignorada, enquanto as instruções no nível do usuário em ~/.codex/AGENTS.md são preservadas. Assim, um checkout não confiável não pode injetar um contrato operacional antes de você confiar nele.¹³²

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

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

O que torna um AGENTS.md excelente

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

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

NÃO FAÇA: - Não inclua guias de estilo completos sem regras de execução - Não use instruções ambíguas (“tenha cuidado”, “otimize”) - Não misture prioridades contraditórias (velocidade + verificação exaustiva + nenhum orçamento de execução) - Não escreva documentação em prosa (AGENTS.md é uma política operacional, não um README)

Exemplo: AGENTS.md de produção

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Tratamento de segredos em sessões de agentes

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

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

O mecanismo de substituição

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

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

Configuração

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

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

Geração da estrutura inicial

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Ou verifique sua cadeia de instruções:

codex --ask-for-approval never "Summarize your current instructions"

Hooks

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

Eventos de hook disponíveis

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

Configuração de hooks

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

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

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

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

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

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

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

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

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

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

Como reproduzir padrões de hooks do Claude Code

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

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

Navegador de hooks na TUI (v0.129.0): Execute /hooks na TUI para descobrir os hooks disponíveis, ver quais estão ativos no momento e ativar ou desativar hooks individuais sem editar config.toml. É útil para solucionar problemas com um hook incluído em um plugin que não esteja funcionando corretamente ou para desativar temporariamente um linter PostToolUse durante uma sessão de edição focada.⁸⁹

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

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

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

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

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

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

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

Configurando servidores MCP

Servidores STDIO (processos locais):

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

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

Servidores HTTP (remotos):

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

Gerenciamento via CLI

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

Dentro da sessão, /mcp mostra os servidores ativos e as ferramentas disponíveis. /mcp verbose (v0.123.0+)⁸⁴ retorna diagnósticos completos do servidor, recursos e templates de recursos. Ele é útil quando um servidor não carrega ou quando as ferramentas não aparecem onde deveriam. O /mcp simples continua rápido. A partir da v0.144.0, ferramentas MCP podem solicitar autenticação de forma interativa sem opt-in experimental. Um servidor que precisa de autenticação no meio da sessão pede isso pelo fluxo normal, em vez de falhar até que você se autentique previamente com codex mcp login.¹⁰⁷

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

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

Executando o Codex COMO servidor MCP

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

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

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

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

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

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

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

Servidores MCP notáveis

Padrões práticos

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

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

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

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

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

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

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

Code Mode [EXPERIMENTAL]

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

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

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

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

Runtime REPL JavaScript [REMOVIDO]

O Codex v0.100.0 adicionou um runtime REPL JavaScript experimental (js_repl), e a v0.106.0 o promoveu por meio da interface /experimental.⁶⁰ Essas orientações agora são apenas históricas. Na v0.128.0, o changelog da versão inclui “Remover o recurso js_repl”, e a lista atual de recursos marca tanto js_repl quanto js_repl_tools_only como removidos.⁸⁶

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

O que são skills?

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

Estrutura de uma skill

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

Locais de descoberta

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

Como criar uma skill

Formato de SKILL.md:

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

## Security Audit Procedure

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

Metadados (agents/openai.yaml):

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

policy:
  allow_implicit_invocation: false    # Require explicit $skill

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

Como invocar skills

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

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

Ativar/desativar

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

Skills vs. slash commands

Como depurar skills

Se uma skill não estiver sendo ativada:

1. Verifique a descoberta: /skills deve listá-la na TUI
2. Verifique o caminho: confirme que a pasta da skill está em um local reconhecido (~/.codex/skills/, raiz do projeto ou /etc/codex/skills/)
3. Verifique enabled: skills com enabled = false em config.toml não serão carregadas
4. Verifique a ativação implícita: se você depende da detecção automática, confirme que allow_implicit_invocation: true está definido em agents/openai.yaml
5. Use palavras-chave: inclua no prompt termos presentes na description da skill para melhorar a correspondência implícita

Exemplo de produção: skill de implantação

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

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

SKILL.md:

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

## Deployment Procedure

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

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

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

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

Plugins

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

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

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

Origens dos plugins

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

Descoberta de plugins

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

Menções a @plugin (v0.112.0+)

Faça referência a qualquer plugin instalado diretamente no chat com @plugin-name.⁶⁸ Quando você menciona um plugin, o contexto dele (funcionalidades, ferramentas e configuração) é incluído automaticamente na janela de contexto do modelo — não é necessário descrever o que o plugin faz.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

Isso funciona com qualquer plugin instalado, incluindo skills personalizados, servidores MCP e conectores de apps.

Marketplace de plugins (v0.113.0+)

O marketplace de plugins agora oferece uma experiência de descoberta mais completa, com metadados, categorias e avaliações.⁶⁹ As verificações de autenticação durante a instalação confirmam se os plugins que exigem chaves de API ou OAuth têm credenciais válidas antes de serem instalados. Um endpoint de desinstalação remove corretamente os plugins e suas configurações associadas.

Adição de marketplaces de terceiros (v0.121.0+)

A documentação atual do OpenAI Codex mantém o gerenciamento das origens de marketplaces em codex plugin marketplace. Isso formaliza a distribuição de plugins de terceiros para além do marketplace próprio da OpenAI e oferece suporte à forma abreviada de repositórios GitHub, URLs Git HTTP(S), URLs SSH e diretórios raiz de marketplaces locais; use --ref para fixar uma referência Git e repita --sparse PATH somente em repositórios de marketplace baseados em Git.⁹³

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

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

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

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

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

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

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

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

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

A governança é o ponto central. A Vercel iniciou a proposta e desenvolveu a especificação 1.0 com Amazon, Anysphere (Cursor), GitHub, Microsoft e OpenAI; a lista de mantenedores do repositório da especificação abrange Amazon, Cursor, Microsoft, OpenAI e Vercel, e o Google anunciou no dia do lançamento que passaria a integrar o grupo principal de mantenedores.¹⁶¹ Os clientes de lançamento mencionados incluem ChatGPT, Codex, Cursor, GitHub Copilot, Kiro e VS Code. Uma ausência chama a atenção: Anthropic, responsável pela criação do formato Agent Skills subjacente e do próprio MCP, não está entre os mantenedores — Claude Code mantém seu próprio formato de plugins, e o Codex preenche essa lacuna do seu lado com a origem de marketplace Claude Code (v0.146.0) e /import.¹⁶¹

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

As notas de versão anunciam as interfaces do Codex sem publicar suas chaves de configuração nem a sintaxe da CLI. Este texto registra que o recurso foi lançado e o que o padrão especifica, não como utilizá-lo no Codex — considere o fluxo de criação de manifestos e qualquer uso de codex plugin publish como não verificados até que a documentação da OpenAI os aborde.

Gerenciamento de plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

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

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

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

Modo de planejamento e colaboração

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

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

Como entrar no modo de planejamento

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

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

Modo Steer

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

Há dois métodos de inserção:

Exemplos práticos:

# Codex is refactoring the auth module...

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

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

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

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

Realce de sintaxe (v0.105.0): agora, a TUI realça a sintaxe de blocos de código delimitados e diffs inline. Use /theme para escolher um esquema de cores.⁶¹

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

Transcrição de voz (v0.105.0, experimental): pressione a barra de espaço para ditar prompts usando a transcrição de voz. Esse recurso é experimental e pode exigir permissão para acessar o microfone.⁶¹ Desde a v0.107.0, sessões de voz em tempo real permitem selecionar os dispositivos de microfone e alto-falante, para que você possa escolher hardwares específicos de entrada e saída de áudio.⁶² Removido na v0.140.0 e retomado na v0.145.0: os controles experimentais de voz /realtime e suas dependências de áudio foram removidos da TUI na v0.140.0 (a transcrição de voz pela barra de espaço não foi afetada).¹⁰² A v0.145.0 retomou a voz em um novo formato: entradas de áudio e saídas de ferramentas de áudio em formatos locais comuns, além de conversas V3 em tempo real via streaming.¹¹² v0.155.0 e v0.156.0: conversas de voz ao vivo. A v0.155.0 (17 de setembro de 2026) adicionou /voice como um recurso experimental opt-in: uma conversa ao vivo com transcrição via streaming e controles de microfone, ativada por /experimental nas builds compatíveis (#43581, #43651, #44331), com um atalho configurável para silenciar o microfone (#43690) e recursos de voz assinados nos pacotes para macOS (#43983). A v0.156.0 (22 de setembro de 2026) tornou o recurso estável e ativado por padrão (#44921), e o changelog da documentação anunciou no mesmo dia: “As conversas de voz são ativadas por padrão, com uma tecla F8 para alternar o recurso, um seletor de /voice settings e runtimes de áudio incluídos para Linux e Windows.” Para desativá-lo, defina realtime_conversation = false em [features] no config.toml. A referência de slash commands CLI ainda não lista /voice, e a página do recurso Voice na documentação aborda o ChatGPT Voice no aplicativo para desktop, uma interface separada.¹⁵⁶¹⁶⁹

Outras melhorias: - Links longos agora continuam clicáveis mesmo quando quebrados em várias linhas da TUI (v0.105.0)⁶¹ - Links de arquivos locais são exibidos com uma formatação melhor (v0.106.0)⁶⁰ - O markdown da TUI mantém links da web clicáveis por meio de metadados OSC 8, e tabelas com pouco espaço são convertidas em registros legíveis de chave/valor sem perder os destinos dos links (v0.136.0)¹⁶⁸ - Links em markdown aparecem como rótulos clicáveis nos terminais compatíveis, enquanto os URLs visíveis são mantidos nos demais (v0.150.0)¹³² - O processamento de Ctrl+C para subagentes foi corrigido para encerrar corretamente os processos filhos (v0.106.0)⁶⁰

Sistema de memória

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

Comandos de memória

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

O que armazenar

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

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

Memória em pipelines

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

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

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

Memória vs AGENTS.md

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

Gerenciamento de sessões

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

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

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

Retomar

Continue de onde parou:

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

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

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

Bifurcar

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

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

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

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

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

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

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

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

Listagem de threads

Veja e gerencie sessões ativas:

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

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

Ciclo de vida da sessão

As sessões são sincronizadas entre o CLI e o aplicativo desktop — comece em um e continue no outro.

Modo não interativo (codex exec)

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

Uso básico

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
codex exec --json "triage open bugs" -o result.txt

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

Arquivamento de sessões (v0.136.0)

As sessões podem ser arquivadas para manter a lista de retomadas e bifurcações focada, sem excluir o histórico. Arquive pela TUI com /archive ou pelo shell:¹⁶⁸

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

Uma sessão arquivada fica protegida contra operações de retomada ou bifurcação até que você a desarquive — uma proteção contra continuar acidentalmente uma sessão que pretendia encerrar. Na mesma versão, codex app-server --stdio inicia o app-server no modo stdio para integrações com editores e hosts, e /diff agora é impedido de executar auxiliares do Git fornecidos pelo repositório (uma correção de segurança de comandos). No Windows, um fluxo de provisionamento em fase alfa adiciona codex sandbox setup --elevated para administradores.¹⁶⁸

Saída em linhas JSON

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

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

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

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

Saída estruturada

Imponha o formato da resposta com o Schema JSON:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message grava a mensagem final em um arquivo.

Retomada e revisão de sessões

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Flags principais

Autenticação em CI

codex exec oferece suporte a CODEX_API_KEY para autenticação não interativa em ambientes de automação.

Banner de inicialização do codex exec (v0.130.0). O banner de inicialização do codex exec não exibe mais o antigo texto “research preview”. Se o seu CI extrai dados da saída de inicialização, o texto do banner agora é mais enxuto; os eventos estruturados de --json não mudaram.⁹¹

codex remote-control (v0.130.0+)

codex remote-control é um comando de nível superior que inicia um app-server headless projetado para ser controlado por outro processo — extensões de IDE, orquestradores personalizados ou planos de controle remoto. Ele substitui a invocação de codex app-server com várias flags que muitos integradores montavam manualmente e oferece a ferramentas de terceiros um ponto de entrada único e estável para o mesmo ambiente de execução do app-server incluído nas interfaces para desktop e IDE.⁹¹ A v0.133.0 aprimora o formato de execução do comando: ele pode funcionar como um comando em primeiro plano, aguardar até estar pronto, informar o status da máquina e ainda oferecer os comandos explícitos start / stop, no estilo daemon, para configurações de controladores de longa duração.⁹⁸ A v0.143.0 adiciona codex remote-control pair, que gera um código de pareamento manual a partir de um daemon em execução para que um controlador possa se conectar sem o handshake de descoberta automática — útil quando o processo controlador está em um host ou segmento de rede diferente do daemon.¹⁰⁶

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

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

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

Combine codex remote-control com os APIs de paginação do app-server abaixo ao criar UIs que precisam enumerar históricos extensos de threads sem carregar cada turno na memória de uma só vez.

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

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

Combine a paginação com a interface ThreadStore introduzida na v0.121.0 para percorrer threads de longa duração com eficiência, especialmente em implantações de remote-control nas quais o orquestrador pode estar em uma máquina diferente dos arquivos de rollout.⁸² A v0.143.0 amplia o que um controlador pode inspecionar: os clientes do app-server agora podem enumerar os ambientes disponíveis, listar as threads descendentes de uma thread e bifurcar o histórico a partir de um turno específico — os elementos básicos de que uma UI precisa para ramificar uma execução a partir de um ponto anterior sem reproduzi-la até esse ponto.¹⁰⁶ A v0.151.0 remove os APIs de histórico paginado de threads da fase experimental e faz com que threads duráveis com stores compatíveis usem por padrão o histórico paginado quando thread/start omite historyMode (threads efêmeras e stores incompatíveis continuam no modo legado); o carregamento do histórico completo está obsoleto para threads paginadas (#40676).¹³⁵

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

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

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

Executores remotos criptografados (v0.141.0)

A partir da v0.141.0 (estável, 18 de junho de 2026), os executores remotos se conectam por canais Noise-relay autenticados e criptografados de ponta a ponta — o plano de controle e o executor não precisam mais confiar no relay entre eles, o que é importante sempre que o seu orquestrador controla um app-server através de um limite de rede. A mesma versão fez com que a execução remota multiplataforma preservasse o diretório de trabalho e o shell nativos do executor, portanto, quando um controlador em um sistema operacional controla um executor em outro, os caminhos e a semântica do shell não são mais reescritos de forma implícita. O TLS agora também aceita assinaturas de certificado P-521 para compatibilidade com proxies corporativos.¹⁰³

Codex Cloud e tarefas em segundo plano [EXPERIMENTAL]

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

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

O Codex Cloud executa tarefas de forma assíncrona em ambientes gerenciados pela OpenAI.⁴ A partir do CLI v0.150.0, as tarefas também podem ser acessadas em uma conversa no terminal: faça referência a outras tarefas do Codex com menções usando @ e peça aos agentes para ler, criar ou enviar mensagens às tarefas.¹³² Consulte também GitHub Action e CI/CD para integrar o Codex ao seu pipeline de CI.

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

Como funciona

1. Envie uma tarefa (pelo chatgpt.com/codex, pela integração com o Slack ou pelo CLI)
2. O Codex clona seu repositório em um sandbox isolado na nuvem
3. O agente trabalha de forma independente: lê o código, executa testes e faz alterações
4. Ao terminar, o Codex cria um PR ou fornece um diff para revisão
5. Aplique os resultados localmente com codex apply <TASK_ID>

Acesso à internet na nuvem

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

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

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

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

Integração com o Slack

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

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

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

CLI na nuvem

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

O Codex Desktop App

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

Instalação

codex app                      # Auto-downloads and installs on first run

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

Principais recursos

Appshots, comentários no navegador e Computer Use

As atualizações do app de 21 de maio tornam o desktop app uma superfície de contexto mais poderosa, em vez de apenas um gerenciador de threads. Use os Appshots quando o Codex precisar conhecer o estado de outro app do Mac antes de agir: o Codex captura a janela em primeiro plano e o texto visível ou fora da tela disponibilizado pelo app, além de armazenar o anexo localmente no histórico da sessão.⁹⁹

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

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

Modos de thread

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

Mecânica de isolamento do Worktree:

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

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

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

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

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

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

Automações

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

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

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

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

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

Suporte ao Windows

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

GitHub Action e CI/CD

A GitHub Action oficial integra o Codex ao seu pipeline de CI/CD.¹⁸

Uso básico

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Opções de configuração

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

Estratégias de segurança

Controles de acesso

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

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

SDK do Codex

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

Instalação

npm install @openai/codex-sdk

Uso básico

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

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

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

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

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