Instalar e atualizar o Codex CLI: Mac, Linux, Windows

Instalar a CLI do OpenAI Codex é um comando por plataforma – curl -fsSL https://chatgpt.com/codex/install.sh | sh no macOS e no Linux, powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" no Windows – com npm e Homebrew como alternativas suportadas, e atualizar é codex update, que reconhece instalações por script, npm e Homebrew e executa o upgrade daquele canal.¹⁴¹¹ A parte que a maioria das páginas pula vem depois do primeiro comando: qual das cinco rotas de instalação escolher, como fixar uma versão quando um lançamento quebra algo, por que o pacote do winget está sete versões menores atrás do npm e o que uma desinstalação deixa em ~/.codex. Esta página é essa referência, uma tabela por tarefa, atualizada até a v0.153.4 (4 de setembro de 2026).⁹

TL;DR

• O instalador independente é a rota que a OpenAI coloca em primeiro lugar, tanto no README quanto na documentação da CLI, com npm e Homebrew apresentados como alternativas (“you can also install” na documentação da CLI, “can also be installed via” no README): o script install.sh no macOS e no Linux, o script install.ps1 no Windows. Ele baixa o binário compilado, então não precisa de Node.¹¹¹
• npm e Homebrew são alternativas suportadas. npm install -g @openai/codex fixa versão com uma especificação de pacote comum (@<version>); brew install --cask codex estava, no momento da escrita, na mesma 0.153.4 do npm.¹²¹⁰
• Evite o winget para instalar o próprio Codex. A OpenAI publica o pacote OpenAI.Codex, mas os pull requests de manifesto para 0.147.0 a 0.152.0 estão parados sem merge em microsoft/winget-pkgs desde 7 de agosto de 2026, então a versão instalável mais recente no dia da escrita é a 0.146.1, contra 0.153.4 no npm.³¹⁰
• codex update cobre instalações por script, npm e Homebrew (v0.128.0 em diante): ele reutiliza a detecção de canal de instalação que a TUI já tem e executa o upgrade correspondente. Uma instalação por winget não é um canal que ele reconheça; essa você atualiza com winget upgrade OpenAI.Codex. Os equivalentes manuais para o resto são executar o instalador de novo, npm install -g @openai/codex@latest ou brew upgrade --cask codex.⁴¹¹
• Fixe versão com --release <version> no install.sh, $env:CODEX_RELEASE antes da linha do install.ps1 ou @<version> no npm. O cask do Homebrew acompanha uma única versão atual e não consegue fixar.²¹²
• Desinstalar o pacote não remove seu estado, mas em uma instalação por script, rm -rf ~/.codex remove também a própria CLI, porque o instalador guarda as versões em ~/.codex/packages/standalone.¹²

Como instalo o Codex CLI?

Quatro rotas, na ordem em que a própria documentação da OpenAI as apresenta,¹¹¹ mais o winget no Windows, que a OpenAI não documenta:³

# Standalone installer, no Node required (macOS, Linux, WSL) -- the route OpenAI lists first
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

# npm (needs Node.js 16+; pins with a plain @version spec)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows; lags npm, see the platform section)
winget install OpenAI.Codex

Depois confirme que a instalação chegou e faça login:

codex --version      # codex-cli 0.153.4
codex login          # ChatGPT account (recommended) or an API key

Em uma primeira instalação por script, o bloco do perfil só vale em shells novos. Se codex não for encontrado no terminal de onde você instalou, execute ali export PATH="$HOME/.local/bin:$PATH" ou abra um novo; o instalador imprime as mesmas duas linhas ao terminar (“Current terminal” e “Future terminals”).¹²

Prefere um binário puro? Todo lançamento no GitHub traz tarballs por plataforma (codex-aarch64-apple-darwin.tar.gz, codex-x86_64-apple-darwin.tar.gz, codex-x86_64-unknown-linux-musl.tar.gz, codex-aarch64-unknown-linux-musl.tar.gz), e desde a v0.106.0 o mesmo install.sh é anexado a cada lançamento como asset. Cada arquivo contém uma única entrada com a plataforma no nome; renomeie-a para codex depois de extrair.¹⁵

O instalador baixa da infraestrutura de lançamento hospedada pela OpenAI: chatgpt.com/codex/install.sh redireciona para releases.openai.com, uma mudança que chegou na v0.146.0, com o GitHub Releases como host de reserva.⁶ Em uma rede que bloqueia ou limita o host de artefatos da OpenAI mas permite o GitHub, pegue o script do asset do lançamento e diga a ele para buscar o binário também no GitHub:¹¹²

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

A variável fica do lado do sh do pipe. A forma VAR=value curl ... | sh aplica a variável só ao curl, então o script nunca a vê e fica silenciosamente no padrão. No PowerShell, defina $env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM = 'false' antes de executar a linha de instalação.

Qual rota você deve escolher?

Quais plataformas o Codex suporta?

No Windows, o Codex roda nativamente no PowerShell com um sandbox do Windows, e há dois modos de sandbox. elevated é o preferido: usa usuários de sandbox dedicados com privilégios reduzidos, limites de permissão no sistema de arquivos, regras de firewall e mudanças de política local, e exige uma configuração aprovada por administrador. unelevated é a reserva: executa comandos com um token restrito do Windows derivado do seu usuário e limites de sistema de arquivos baseados em ACL.⁸ O modo é escolhido no config.toml:

[windows]
sandbox = "elevated"   # or "unelevated"

A orientação da OpenAI é usar o sandbox nativo por padrão e escolher o WSL quando você precisar de ferramentas nativas do Linux, quando seu fluxo de trabalho já viver no WSL2 ou quando nenhum dos modos de sandbox nativos do Windows atender aos seus requisitos.⁸ Uma distinção que vale guardar: a configuração do Windows pressupõe que o winget está na máquina para os seus próprios passos de configuração; isso é diferente de instalar o Codex via winget. A OpenAI publica esse pacote, o fluxo de lançamento tem um job winget que abre um pull request de manifesto em microsoft/winget-pkgs para lançamentos estáveis, mas esses envios estão parados sem merge desde que o manifesto da 0.146.1 foi mesclado em 7 de agosto de 2026; os pedidos para 0.147.0 a 0.152.0 estavam todos abertos no momento da escrita, e para 0.153.0 a 0.153.4 não existe nenhum. Nada está quebrado na CLI; o índice do pacote é que está atrasado.³⁸

O Node.js só é pré-requisito para a rota do npm. Os scripts de instalação baixam o binário compilado, e o cask do Homebrew não declara dependências.¹²

Como atualizo o Codex CLI?

O Codex não se atualiza sozinho. A TUI percebe um lançamento mais novo e oferece o comando do seu canal de instalação; executá-lo é com você, e o comando embutido cobre instalações por script, npm e Homebrew.⁴ A verificação na inicialização é, ela mesma, uma chave de configuração: check_for_update_on_startup = false no config.toml, que a referência descreve como “Check for Codex updates on startup (set to false only when updates are centrally managed)”; frotas que gerenciam atualizações centralmente definem features.in_app_updates = false no requirements.toml.¹⁶

codex --version                      # what you run now
npm view @openai/codex version       # newest published

codex update                         # built-in, v0.128.0+; detects your install channel

codex update chegou com a v0.128.0 em 30 de abril de 2026; o pull request que o adicionou reutilizou a detecção de canal de instalação e o executor de atualização que a TUI já tinha para os avisos de atualização. O mapa de canais cobre npm (mais as variantes bun, pnpm e Vite+), Homebrew e o instalador independente no Unix e no Windows; uma instalação por winget não está nele, então um Codex instalado via winget só é atualizado por winget upgrade OpenAI.Codex.⁴ Os equivalentes manuais, se você preferir ou estiver preparando a imagem de uma máquina:

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # standalone: re-run the installer
npm install -g @openai/codex@latest                    # npm
brew upgrade --cask codex                              # Homebrew
winget upgrade OpenAI.Codex                            # winget (to whatever winget has)

irm https://chatgpt.com/codex/install.ps1 | iex           # standalone on Windows: re-run the installer

Os lançamentos saem em uma linha estável rápida – da 0.150.0 à 0.153.4 chegaram entre 26 de agosto e 4 de setembro de 2026 – então a distância entre “o que eu uso” e “a mais recente” costuma ser uma semana, não um trimestre.⁹

Como instalo uma versão específica?

npm e o script de instalação fixam ambos por versão; o Homebrew não:²¹²

npm install -g @openai/[email protected]                                          # npm: exact version
curl -fsSL https://chatgpt.com/codex/install.sh | sh -s -- --release 0.152.1  # script: --release flag
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_RELEASE=0.152.1 sh    # script: env var, on the sh side
winget install OpenAI.Codex --version 0.146.1                                 # winget: only what it has
codex --version                                                               # verify the rollback took

Repare na posição na forma com variável de ambiente: CODEX_RELEASE=0.152.1 precisa vir antes do sh, depois do pipe. Escrita antes do curl, a variável só se aplica ao curl e o script instala latest enquanto você acha que fixou a versão.¹² No Windows, o script do PowerShell declara $Release = $env:CODEX_RELEASE como seu único parâmetro e recorre a latest quando ele está vazio, então fixar a versão é essa variável, definida na mesma sessão:¹⁷

$env:CODEX_RELEASE = '0.152.1'; irm https://chatgpt.com/codex/install.ps1 | iex

Fixar versão é a atitude certa quando um lançamento trava você: relate o problema, fixe a última versão boa, siga em frente. Verifique com codex --version depois de cada fixação, porque uma segunda instalação em outro ponto do seu PATH vai continuar servindo silenciosamente o próprio binário. O script de instalação verifica exatamente isso: quando encontra um codex gerenciado por Homebrew, npm ou bun já no seu PATH, ele avisa “Multiple managed Codex installs can be ambiguous because PATH order decides which one runs” e se oferece para executar por você a desinstalação correspondente.¹² codex doctor relata o mesmo estado depois do fato em Environment.⁷

Como desinstalo o Codex CLI?

Remova pela rota que o instalou:

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

Uma instalação por script não tem gerenciador de pacotes a quem perguntar. O instalador coloca um link simbólico codex em ~/.local/bin (substituível com CODEX_INSTALL_DIR) que aponta para o binário dentro de ~/.codex/packages/standalone/current (current/bin/codex nos lançamentos atuais); current é, por sua vez, um link simbólico para ~/.codex/packages/standalone/releases/, onde cada versão baixada fica. No macOS, o instalador adiciona um segundo link simbólico ao lado do primeiro, codex-code-mode-host.¹² Remova tudo:

rm -f ~/.local/bin/codex ~/.local/bin/codex-code-mode-host   # the second link exists on macOS installs only
rm -rf ~/.codex/packages/standalone

Se ~/.local/bin não estava no seu PATH na instalação, ou se o instalador encontrou uma instalação concorrente do Homebrew, npm ou bun e reescreveu a entrada, o script também acrescentou um bloco marcado ao seu perfil de shell: de # >>> Codex installer >>> até # <<< Codex installer <<< em ~/.zprofile (zsh no macOS), ~/.bash_profile, ~/.zshrc, ~/.bashrc ou ~/.profile. Apague essas três linhas para terminar.¹²

No Windows, o install.ps1 mantém o mesmo arranjo em %USERPROFILE%\.codex\packages\standalone (ou %CODEX_HOME%\packages\standalone, se você definiu essa variável): versões baixadas em releases\, uma junção current apontando para a que está em uso. Ele expõe o codex.exe por %LOCALAPPDATA%\Programs\OpenAI\Codex\bin (substituível com CODEX_INSTALL_DIR), que é por sua vez uma junção para current\bin, e em vez de um bloco de perfil ele grava esse caminho bin no seu PATH de usuário para futuras sessões do PowerShell. Remova primeiro o diretório standalone, depois a junção bin que agora ficou pendurada, e então tire a entrada da variável Path de usuário em Variáveis de Ambiente:¹⁷

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\packages\standalone"   # releases plus the current junction
cmd /c rmdir "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin"                  # the bin junction; rmdir removes the link, not a target

As desinstalações por gerenciador de pacotes acima não tocam em ~/.codex/. O --zap do Homebrew também não, na prática: a única diretiva zap do cask é rmdir: "~/.codex", e o Homebrew só aplica rmdir: a diretórios que já estão vazios.² Esse diretório guarda o config.toml, suas credenciais salvas e cada sessão, e é por isso que uma reinstalação retoma o login e o histórico de onde você parou. Apague-o só se quiser mesmo começar do zero, e sabendo o que isso significa em uma instalação por script:

rm -rf ~/.codex   # discards config.toml, credentials, all sessions -- AND the CLI itself on a script install

Uma reinstalação limpa que preserva seu estado é uma linha no npm: npm uninstall -g @openai/codex && npm install -g @openai/codex@latest. Na rota do script, executar o instalador de novo substitui a versão em ~/.codex/packages/standalone e deixa sua configuração em paz.¹²

O ciclo de vida inteiro em uma tabela

O que o codex doctor verifica?

codex doctor é o comando a executar antes de relatar um bug ou depurar uma instalação que “funcionava ontem”. Na 0.153.4, ele reúne sete seções em um único relatório – Notes, Environment (consistência de runtime e instalação), Configuration (estado de carregamento do config.toml, autenticação, MCP, política de sandbox), Desktop App (adicionada na v0.149.0), Updates, Connectivity e Background Server – com --summary para uma visão compacta, --json para uma forma legível por máquina e com dados sensíveis ocultados, --all para expandir listas truncadas e --no-color para logs; codex doctor --help também lista --ascii na 0.153.4.⁷¹³¹⁵ A maioria dos relatos de “o Codex quebrou” se resolve em algo que ele nomeia na primeira tela: um modo de autenticação obsoleto, um config.toml que não pôde ser interpretado ou uma segunda instalação escondendo a que está no seu PATH. O detalhamento completo, seção por seção, está no guia.

O que muda depois de instalar

A primeira coisa em que uma instalação nova tropeça não é o binário. Desde a v0.149.0, a CLI se recusa a iniciar com approval_policy = "untrusted", então um config.toml copiado de uma máquina mais antiga precisa de uma mudança.¹³ Vindo do Claude Code? O post de migração coloca as duas configurações lado a lado, e o post sobre hooks explica o que o Codex executa ao redor do modelo. O guia do Codex CLI é a referência completa: modos de sandbox e aprovação, AGENTS.md, MCP, skills e tarefas na nuvem. E se você usa as duas ferramentas, a página de instalação do Claude Code é a gêmea desta.

Perguntas frequentes

Como atualizo o Codex CLI para a versão mais recente?

Execute codex update (v0.128.0 em diante); ele detecta se você instalou pelo script, npm ou Homebrew e executa o upgrade daquele canal. Os equivalentes manuais são executar o script de instalação de novo, npm install -g @openai/codex@latest ou brew upgrade --cask codex. Uma instalação por winget não é um canal que o codex update reconheça; para essa, use winget upgrade OpenAI.Codex.

O Codex CLI se atualiza automaticamente?

Não. A TUI verifica se há um lançamento mais novo e oferece o comando de atualização que corresponde ao seu canal de instalação, e codex update (v0.128.0 em diante) o executa; nada é baixado ou aplicado até você fazer isso.

Como desinstalo o Codex CLI?

Use a rota que o instalou: npm uninstall -g @openai/codex, brew uninstall --cask codex ou winget uninstall OpenAI.Codex. Em uma instalação por script, remova o link simbólico ~/.local/bin/codex (e ~/.local/bin/codex-code-mode-host no macOS) junto com o diretório ~/.codex/packages/standalone. No Windows, a instalação por script é %USERPROFILE%\.codex\packages\standalone, a junção %LOCALAPPDATA%\Programs\OpenAI\Codex\bin e uma entrada no seu PATH de usuário; remova as três. Sua configuração, credenciais e sessões permanecem em ~/.codex/ até você mesmo remover o resto desse diretório.

Como instalo o Codex CLI no Windows?

Execute powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". A CLI roda nativamente no PowerShell com um sandbox do Windows (elevated de preferência, unelevated como reserva); o WSL2 é uma opção se você precisar de ferramentas do Linux ou se nenhum dos modos de sandbox servir, não um pré-requisito. O Windows 11 é a base recomendada. winget install OpenAI.Codex também funciona, mas fica atrás da linha estável.

Preciso do Node.js para instalar o Codex?

Só para a rota do npm, e o pacote exige Node 16 ou mais recente. O script de instalação, o script do PowerShell e o cask do Homebrew entregam todos o binário codex compilado, então uma máquina sem Node consegue executar o Codex.

Como verifico qual versão do Codex eu tenho?

codex --version imprime a versão (por exemplo, codex-cli 0.153.4). npm view @openai/codex version mostra a versão publicada mais recente, e codex doctor relata o caminho de instalação e se outra cópia no seu PATH está escondendo essa.