CLI do OpenAI Codex: instalação, comandos, config.toml e codex exec

A CLI do OpenAI Codex é um agente de programação sob licença Apache-2.0 criado pela OpenAI que roda localmente no seu terminal. Use codex de forma interativa para analisar repositórios, editar arquivos, acionar ferramentas locais e revisar códigos, ou use codex exec de forma não interativa em scripts e esteiras de integração contínua (CI). Ele lê as configurações de ~/.codex/config.toml e .codex/config.toml do projeto, carrega diretrizes de AGENTS.md e estabelece limites por meio de sandboxes e políticas de aprovação.

Como a CLI do Codex se posiciona junto às demais ferramentas da OpenAI

A OpenAI disponibiliza o Codex em diferentes formatos:

• Codex CLI (codex): agente de programação local e leve que opera direto no seu terminal junto ao seu repositório e ferramentas locais.
• Extensões de IDE: com suporte para VS Code, Cursor e Windsurf. A CLI e as extensões compartilham os mesmos níveis de configuração.
• Aplicativo para computador (codex app): rode codex app ou acesse a página do Codex App no chatgpt.com.
• Codex Web (chatgpt.com/codex): agente na nuvem. O comando codex cloud consulta chats na nuvem, envia tarefas para ambientes configurados e reflete os resultados na sua máquina.

Instalação e atualização da CLI do OpenAI Codex

Instale a CLI do Codex pelo script instalador independente, via gerenciador de pacotes ou pelos binários oficiais no GitHub Releases.

Instaladores independentes no macOS, Linux e Windows

No macOS ou Linux, instale ou atualize pelo terminal:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

No Windows, execute o comando abaixo no PowerShell para instalar ou atualizar:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Os instaladores baixam os arquivos diretamente de https://releases.openai.com/codex e usam o GitHub Releases como alternativa se o download principal falhar. Para forçar o download pelo GitHub Releases, defina CODEX_INSTALLER_USE_RELEASES_OPENAI_COM como false (valores 0 ou no também funcionam):

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

Gerenciadores de pacotes e binários do GitHub Releases

• npm: use npm install -g @openai/codex para instalar.
• Homebrew: use brew install --cask codex para instalar.
• GitHub Releases: faça o download de codex-aarch64-apple-darwin.tar.gz ou codex-x86_64-apple-darwin.tar.gz (macOS), ou codex-x86_64-unknown-linux-musl.tar.gz ou codex-aarch64-unknown-linux-musl.tar.gz (Linux). Descompacte o arquivo executável e mude o nome para codex.

Fazer login e iniciar uma tarefa

Abra o comando codex dentro de um repositório Git. Na primeira execução, selecione Sign in with ChatGPT (planos Plus, Pro, Business, Edu ou Enterprise) ou informe uma chave de API. Crie pontos de restauração com Git antes e depois das execuções para desfazer alterações de forma segura se necessário.

Comandos interativos da CLI e fluxos no terminal

Gerencie contexto, revisões, ferramentas e permissões direto pelo shell ou em uma sessão interativa:

Dois fluxos prontos ajudam em mudanças maiores no código:

• Revisão de código local: analisa alterações pendentes, um commit ou uma branch base e lista apontamentos priorizados sem modificar sua árvore de arquivos.
• Subagentes: transfere investigações pontuais para subagentes dedicados e retorna as descobertas para a sessão principal.

Como configurar o Codex com o config.toml

O Codex guarda configurações pessoais em ~/.codex/config.toml e configurações específicas de cada projeto em .codex/config.toml (também acessíveis na extensão de IDE clicando na engrenagem em Codex Settings > Open config.toml).

O Codex carrega as camadas de projeto .codex/ (configurações, hooks e regras) exclusivamente em repositórios marcados como confiáveis; em pastas não confiáveis, aplicam-se apenas as configurações de usuário e de sistema.

Ordem de prioridade das configurações

Da maior prioridade para a menor:

• Parâmetros da CLI e substituições com --config (-c)
• Arquivos .codex/config.toml do projeto, da raiz até o diretório atual (o mais próximo prevalece, somente em projetos confiáveis)
• Arquivos de perfil indicados por --profile profile-name (~/.codex/profile-name.config.toml)
• Configuração de usuário (~/.codex/config.toml)
• Padrões de config.toml gerenciados na nuvem para o workspace
• Configurações do sistema (/etc/codex/config.toml no Unix)
• Padrões embutidos do sistema

Em máquinas corporativas, as empresas também podem definir restrições pelo arquivo requirements.toml, proibindo por exemplo opções como approval_policy = "never" ou sandbox_mode = "danger-full-access".

Opções comuns do config.toml e sinalizadores de recursos

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "none"

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

[features]
prefer_mxc = true

Principais opções do config.toml:

• Modelo e raciocínio: model define o modelo padrão da CLI e IDE; model_reasoning_effort ajusta o nível de raciocínio.
• Aprovações e isolamento: approval_policy estabelece quando pedir aprovação de comandos (valores como "on-request" ou "never"; o valor "untrusted" foi descontinuado). O parâmetro sandbox_mode define permissões de rede e sistema de arquivos (como "workspace-write"). Perfis nativos (:read-only, :workspace, :danger-full-access) e tabelas personalizadas [permissions.<name>] também são aceitos.
• Busca na web: web_search usa como padrão "cached" (cache da OpenAI, diminuindo risco de injeção em prompts). Use "indexed" para canalizar pelo índice de busca, "live" para páginas em tempo real (igual a --search, e padrão em sandboxes de acesso total como --yolo), ou "disabled".
• Tom de conversa: personality = "none" descarta a seção de instruções Personality mantendo orientações customizadas (friendly, pragmatic e /personality foram aposentados).
• Atalhos da TUI e registros de log: [tui.keymap.global], [tui.keymap.composer] e [tui.keymap.chat] configuram os atalhos (uma lista vazia desativa a tecla). log_dir indica o caminho dos logs e ativa o arquivo de texto codex-tui.log.
• Ambiente de shell: em [shell_environment_policy], ignore_default_excludes vem como true por padrão. Defina como false para ocultar variáveis com KEY, SECRET ou TOKEN, ou configure filtros em [shell_environment_policy.filters].
• Sinalizadores de recursos: a seção [features] ativa apps, goals, hooks, fast_mode, memories (desativado por padrão), multi_agent, remote_plugin, shell_snapshot, shell_tool e unified_exec, ou pelo parâmetro codex --enable feature_name.

Camadas de instruções com o AGENTS.md

O Codex compila a cadeia de instruções do AGENTS.md uma única vez no início da sessão:

• Instruções globais: em ~/.codex (ou CODEX_HOME), o Codex lê primeiro o AGENTS.override.md, usando o AGENTS.md como alternativa.
• Instruções do projeto e subdiretórios: subindo da raiz do projeto (geralmente raiz do Git) até a pasta atual, o Codex carrega no máximo um arquivo por diretório: AGENTS.override.md, depois AGENTS.md, e por fim os nomes listados em project_doc_fallback_filenames.
• Ordem de mesclagem e limite de tamanho: os arquivos são unidos da raiz para baixo, permitindo que regras mais específicas prevaleçam, respeitando o teto de project_doc_max_bytes (32 KiB padrão no config.toml).

Para auditar os arquivos carregados, rode codex -c log_dir=./.codex-log e verifique ./.codex-log/codex-tui.log.

Rodar scripts e esteiras de CI com o codex exec

Execute tarefas não interativas com o codex exec:

codex exec "summarise the repository structure and list the top 5 risky areas"

Comportamentos fundamentais do codex exec:

• Stdout e stderr: atualizações de progresso saem no stderr e somente a resposta final vai para o stdout, facilitando o direcionamento para pipes ou gravação via -o <path> (--output-last-message <path>). Use --ephemeral para evitar gravação de arquivos de sessão no disco.
• Entrada via stdin: dados enviados por pipe servem como contexto adicional quando combinados com um comando, ou como o prompt integral ao omitir o argumento ou usar codex exec -.
• Opções de sandbox: por padrão opera em modo de leitura. Use --sandbox workspace-write para editar arquivos, ou --sandbox danger-full-access exclusivamente em ambientes controlados. (--full-auto foi descontinuado; use --sandbox workspace-write, ou --approve-for-me para autorização automática com workspace-write.)
• Execução isolada: --ignore-user-config ignora $CODEX_HOME/config.toml, --ignore-rules ignora arquivos .rules e --skip-git-repo-check dispensa a obrigatoriedade de repositório Git. Se um servidor MCP com required = true não inicializar, o codex exec encerra com erro.
• Saída estruturada: --json transmite eventos JSON Lines em tempo real (thread.started, turn.started, item.*, turn.completed, turn.failed, error). O parâmetro --output-schema ./schema.json exige conformidade com um JSON Schema.
• Retomar execuções: rode codex exec resume --last "<prompt>" ou codex exec resume <SESSION_ID> "<prompt>".
• Autenticação em CI: defina CODEX_API_KEY=<api-key> codex exec ... diretamente no comando em vez de salvar como segredo global em fluxos que rodam código de terceiros, ou use openai/codex-action@v1 no GitHub Actions, que inicia um proxy seguro para a chave de API.

Sandboxes no Windows: mxc, elevated e unelevated

No Windows, o Codex pode rodar diretamente no PowerShell usando um sandbox nativo do Windows, sem precisar de WSL ou máquinas virtuais. O Windows 11 é o sistema recomendado. O Windows 10 possui suporte secundário e exige versão 1809 ou superior para o ConPTY. O utilitário winget deve estar instalado.

No Codex CLI 0.162.0 ou posterior, teste o suporte ao mxc sem alterar suas configurações:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK

Monitore sessões da CLI do Codex em um keypad ou no celular com o Orbtile

Ao executar múltiplos terminais com codex, rotinas com codex exec e chats no aplicativo para computador, o Orbtile exibe cada sessão no Logitech MX Creative Keypad, um iPhone ou celular Android (Android 8.0 ou superior com o Orbtile Mobile), conectado a um computador com macOS 14.0 Sonoma ou superior (Apple silicon) ou Windows 11 (x64).

• Detecção sem necessidade de instalação: o Orbtile lê os arquivos de sessão do próprio Codex e seus sinais em tempo real. Sessões de terminal codex, rotinas do codex exec e chats do aplicativo ganham blocos individuais com seu estado, ferramentas em uso, alertas e o texto mais recente.
• Cores e níveis de urgência: sessões em andamento aparecem em azul sereno e brilham em magenta-violeta quando entram em espera. Sessões aguardando sobem para a frente sozinhas, e a tecla 9 pula direto para a primeira delas.
• Aprovações pelo teclado: para chats compatíveis do aplicativo para computador, toque em Deny ou segure Allow (0,6 s) para aprovar comandos e responder a perguntas de múltipla escolha. No terminal, sessões codex oferecem Allow nas teclas (para recusar, responda no terminal). Execuções de codex exec não solicitam aprovação de comando (Codex 0.159.0), e outras esperas mostram Answer on computer.
• Hooks opcionais e SSH: para compactar o estado e obter avisos mais ágeis, instale os hooks opcionais em Settings > Agents > Codex e autorize-os no Codex em Settings > Hooks. O Orbtile também monitora sessões remotas da CLI do Codex via SSH ao lado de Claude Code e ZCode. Consulte Saiba quando uma tarefa do Codex está aguardando você e Watch Claude Code and Codex running on a remote server over SSH.