Como Instalar a OpenAI Codex CLI (Windows, macOS, Linux)

- Os comandos e caminhos de documentação foram conferidos com a documentação oficial na data de escrita (08/2026); o domínio da documentação do Codex já mudou uma vez (developers.openai.com → learn.chatgpt.com), então confira a documentação atual antes de rodar isto se esta página estiver antiga.

Antes de instalar a Codex CLI

Antes de instalar o OpenAI Codex, deixe estes itens prontos:

• Um plano ChatGPT compatível com o Codex. Segundo a página de preços na data de escrita, o acesso à CLI é mais claro a partir do Plus (Plus, Pro, Business, Enterprise) ou por pagamento conforme o uso via chave de API; Free/Go podem não incluí-lo - confira os preços do Codex antes de instalar, em vez de chutar.
• Um sistema operacional: Windows, macOS ou Linux - a Codex CLI roda nativamente nos três, sem exigir WSL2 no Windows e sem precisar pensar em builds separados para Apple Silicon ou Intel (o instalador escolhe o binário certo para você).
• Uma conexão funcionando com o chatgpt.com para baixar o instalador e fazer login - um proxy corporativo cativo ou uma rede muito restrita pode bloquear o download mesmo que o resto da sua internet funcione bem.
• Node.js apenas se você escolher o caminho de instalação via npm - os outros dois métodos (script de instalação, Homebrew) não encostam no Node.

Com esses quatro itens prontos, a instalação em si é um comando mais uma curta espera de download - a parte que costuma demorar mais é escolher a conta ChatGPT certa para fazer login, especialmente se você tem tanto uma conta pessoal quanto uma fornecida pela empresa (Business/workspace). As duas podem ter permissões de CLI diferentes, então, se uma tela de login parecer estranha ou a CLI informar um plano que você não esperava, verifique com qual conta você está realmente autenticada antes de presumir que algo quebrou.

Instalar a Codex CLI no macOS e no Linux

O caminho mais rápido é o script de instalação oficial, rodado direto no terminal - ele baixa um binário nativo, sem precisar de outro runtime:

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

Passar o curl direto para o sh deixa algumas pessoas desconfortáveis, e esse instinto é razoável em geral - você está confiando no que a URL retornar naquele momento. Se preferir não rodar às cegas um script que não leu, baixe-o antes (curl -fsSL https://chatgpt.com/codex/install.sh -o install.sh), leia e então rode sh install.sh. Para uma instalação única no domínio oficial de um fornecedor conhecido, a maioria dos desenvolvedores aceita o risco; para uma máquina restrita ou compartilhada, vale o minuto extra de baixar e ler.

Duas alternativas caso você prefira gerenciar por um gerenciador de pacotes:

brew install --cask codex

npm install -g @openai/codex

A armadilha mais comum: o nome do pacote npm é @openai/codex, não apenas codex - rodar npm install -g codex instala o pacote errado (ou dá 404). Dois dos guias em inglês que li apontam exatamente esse erro. Se optar pelo caminho do npm, use uma versão LTS atual do Node.js; as fontes secundárias que cruzei não concordam sobre a versão mínima exata, então, se o npm reclamar da versão, atualize o Node para a última LTS primeiro, ou contorne toda a questão com o script de instalação ou o Homebrew acima. Confira o README oficial no GitHub se precisar tirar a dúvida.

Qual escolher? Se for uma instalação única e você não se importar com atualizações manuais, use o script de instalação - é o mais rápido. Se a sua máquina já depende do Homebrew para todas as outras CLIs, mantenha esse hábito (um brew upgrade depois também atualiza o Codex). O caminho do npm só faz sentido se você já tiver o Node.js instalado para outra coisa - não instale o Node só para usar essa opção.

Instalar a Codex CLI no Windows

No Windows, abra o PowerShell e rode exatamente este comando - eu mesma rodei isto ao vivo na minha própria máquina Windows enquanto escrevia:

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

1. Abra o PowerShell (direitos de administrador não são necessários na maioria das máquinas).
2. Cole o comando completo acima e pressione Enter.
3. A flag -ExecutionPolicy ByPass vale apenas para esta execução - ela não muda a política da sua máquina - só permite que este script de instalação não assinado rode desta única vez.
4. Feche o terminal antigo e abra um novo para que o PATH atualizado entre em vigor.
5. Rode codex --version para confirmar.

Prefira o Windows Terminal à antiga janela do cmd.exe se você o tiver instalado - não é obrigatório, mas o prompt do PowerShell e qualquer saída colorida que o Codex imprima aparecem de forma mais confiável ali, e foi o que usei na execução ao vivo acima.

A Codex CLI roda nativamente no Windows - o WSL2 não é necessário. Se o seu time já padronizou no WSL2 (por exemplo, para compartilhar scripts com um pipeline de CI Linux), você ainda pode instalar o Codex dentro do WSL2 usando o mesmo comando curl da seção de macOS/Linux acima; não existe um comando WSL2 específico para Windows.

Se a sua máquina Windows for gerenciada pela empresa (um dispositivo sob política de grupo), o -ExecutionPolicy ByPass ainda pode ser bloqueado na camada de política da organização, não só na do usuário - nesse caso, a TI precisa afrouxá-lo, e não há solução alternativa do lado do usuário. O Windows Defender SmartScreen também pode pedir confirmação na primeira vez que você roda um instalador recém-baixado - é um aviso normal para um arquivo novo, não um sinal de que algo quebrou.

Verificar a instalação

Rode codex --version. Um número de versão impresso de volta significa que você terminou. Se o terminal disser que codex não é reconhecido, quase sempre é um PATH desatualizado - feche o terminal por completo (inclusive o integrado de uma IDE) e abra uma janela nova antes de suspeitar de qualquer outra coisa. Se você tentou mais de um método de instalação (digamos, o npm e depois o script de instalação) e o codex --version mostra uma versão inesperada, provavelmente há duas cópias no PATH - veja qual realmente roda com where codex (Windows) ou which codex (macOS/Linux) e remova a que sobra.

Fazer login no Codex

Rode codex no seu terminal para iniciar a CLI e escolha a opção de login pelo ChatGPT quando for solicitado (o texto exato na tela pode mudar entre versões - siga o que a CLI mostrar no momento). O fluxo geralmente abre uma aba do navegador para você confirmar o login e depois devolve a sessão ao terminal automaticamente - sem colar token na mão. O seu plano ChatGPT determina qual modelo e quais limites de uso você recebe; veja os preços do Codex por plano para os detalhes, em vez de chutar números aqui. Se o login falhar em silêncio (a aba do navegador fecha, mas o terminal nunca confirma), a causa mais comum é uma camada de SSO ou proxy corporativo interceptando o redirecionamento - tente de novo numa rede sem restrições antes de presumir que a própria CLI está com defeito.

Rodar o seu primeiro comando do Codex

Entre com cd em uma pasta de projeto de verdade (não uma vazia - o Codex precisa de código real para ler e trabalhar) e então rode:

codex

Tente algo concreto, como: "Leia o README e liste 3 formas de rodar os testes neste repositório." Ou algo menor para aquecer: "Liste os 5 maiores arquivos deste repositório por número de linhas." Se o Codex precisar rodar um comando ou editar um arquivo, ele vai pausar e pedir aprovação primeiro (dependendo do seu approval_policy) e mostrar o comando ou o diff exato que quer executar, para você aprovar ou rejeitar - isso é o fluxo normal de aprovação, não um erro; a seção de configuração abaixo explica por que ele para e como afrouxar ou apertar isso. Uma primeira execução bem-sucedida costuma terminar com o Codex imprimindo um resumo curto do que leu ou mudou, além de alguma sugestão de próximo passo - se, em vez disso, você levar um erro imediato antes de ele fazer qualquer coisa, isso quase sempre aponta de volta para a etapa de login acima, não para esta.

Noções básicas do ~/.codex/config.toml

A sua configuração de usuário fica em ~/.codex/config.toml; um projeto pode sobrescrevê-la com um .codex/config.toml na raiz do repositório. Precedência (da mais alta para a mais baixa, segundo a documentação oficial de configuração): flags da CLI > .codex/config.toml do projeto > perfil (--profile) > ~/.codex/config.toml do usuário. Na prática, isso significa: se o seu ~/.codex/config.toml pessoal define approval_policy = "on-request" como um padrão global sensato, mas o .codex/config.toml de um repositório específico define approval_policy = "untrusted" para um fluxo mais rígido, o arquivo do projeto vence sempre que você estiver trabalhando dentro daquele repositório - e uma flag pontual --approval-policy na CLI ganha de ambos, para uma única execução.

Esses três são os que mais vale ajustar primeiro: model equilibra qualidade, velocidade e custo; sandbox_mode decide o que o Codex pode de fato tocar (há também uma opção mais segura read-only e uma danger-full-access que você não deveria rodar como padrão); approval_policy decide com que frequência você precisa aprovar manualmente. Coloque os três em um único ~/.codex/config.toml e fica assim:

model = "gpt-5.6"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Essa é só a camada básica. A próxima camada - ensinar ao Codex as convenções do seu próprio projeto (comandos de teste/build, regras que não podem quebrar) - fica no AGENTS.md para o Codex.

Erros comuns de instalação e correções

A maioria dos problemas de instalação remete a uma de quatro coisas: um nome de pacote digitado errado, um PATH desatualizado, a política padrão de scripts do Windows ou uma pasta cujas permissões o Codex não consegue resolver de forma limpa. Aqui está cada uma, com a correção de verdade em vez de um genérico "reinstale e torça":

Atenção: dois comandos de instalação "curl ... | sh" diferentes

Se mais adiante você topar com instruções para curl -fsSL https://agentkit.best/install.sh | sh, isso é uma ferramenta totalmente diferente - o AgentKit (a CLI ak), um kit pago instalado por cima do Codex ou do Claude Code, e não parte do próprio Codex. Os dois comandos são quase idênticos (mesmo formato curl -fsSL <domain>/install.sh | sh), então, se você salvar qualquer um deles em notas ou no histórico do shell para depois, rotule-o com o domínio - não copie e cole um script achando que é o outro.

Mais um hábito que vale criar cedo: a Codex CLI evolui rápido, e tanto o domínio de instalação quanto algumas flags da CLI já mudaram uma vez desde o lançamento. Rodar o comando de instalação de tempos em tempos (ou o caminho de atualização do método que você usou) é um seguro barato contra continuar rodando, sem perceber, um build antigo.

Perguntas frequentes

A Codex CLI é gratuita para instalar?

A CLI em si é open source e gratuita para instalar, e o binário não expira nem fica te incomodando. Para fazer login e realmente usá-la, você precisa de um plano ChatGPT compatível com o Codex (mais claro a partir do Plus, segundo a página de preços na data de escrita) ou de uma chave de API cobrada por uso.

Preciso de uma chave de API?

Não, se você fizer login com um plano ChatGPT compatível com o Codex - esse é o caminho padrão para a maioria dos desenvolvedores individuais. Uma chave de API só é necessária se você quiser pagar por token (útil para automação/CI, onde fazer login de forma interativa não é prático) em vez de usar um plano ChatGPT.

Dá para instalar sem Node.js?

Sim. O script de instalação oficial (curl ... | sh no macOS/Linux, PowerShell no Windows) e o Homebrew não exigem Node.js nenhum. Só o caminho npm install -g @openai/codex precisa do Node, já que o próprio npm vem com o Node.js.

Precisa de WSL no Windows?

Não. A Codex CLI roda nativamente no Windows, com o próprio instalador e o próprio binário. O WSL2 só é útil se você quiser especificamente compartilhar um pipeline Linux existente ou scripts de shell com o seu time.

Como faço para atualizá-la?

Rode de novo o mesmo método de instalação que você usou originalmente (o script de instalação, brew upgrade ou npm install -g @openai/codex) e ele sobrescreve a versão antiga com a mais recente - não é preciso um passo de desinstalação separado antes.

Adicionar o AgentKit depois de instalar o Codex?

A Codex CLI em si é gratuita (ela pega carona no plano ChatGPT que você já tem). O AgentKit é uma camada separada e paga que você instala por cima do Codex para ter skills/subagents/workflows prontos em vez de montar os seus: ak kit init engineer --target codex --global, confirme a tela de preview, abra uma nova sessão do Codex e então rode $ak:cook ... para começar. Nada disso muda o comando base codex que você acabou de instalar - só dá a esse comando coisas mais estruturadas para executar. Essa é a mesma configuração de gate que eu de fato uso tanto no Claude Code quanto no Codex, não um jabá descartável - os detalhes estão em AgentKit in Codex. Se hoje você só está tateando o Codex, pule esta etapa inteira e volte quando realmente sentir o atrito de reexplicar o seu fluxo de trabalho a cada sessão - é nesse ponto que um kit pronto começa a se pagar.