Um comando instala. Um nome de pacote errado desperdiça vinte minutos. A falha de instalação mais comum do Codex CLI não é uma dependência faltando ou um problema de plataforma — é rodar npm i -g codex em vez de npm i -g @openai/codex. O pacote codex sem escopo é um projeto de 2012 sem nenhuma relação com a OpenAI; ele instala silenciosamente e depois não faz nada útil.
Passada essa etapa, a instalação em si é direta. Este guia cobre macOS, Windows e Linux com os comandos que funcionam em 2026, o requisito de versão do Node.js que pega muita gente de surpresa, e correções pros erros que aparecem depois de uma instalação limpa.
Verificado com a documentação oficial do Codex CLI e o pacote npm, maio de 2026.
O Que É o Codex CLI
O Codex CLI é o agente de código de terminal open-source da OpenAI. Ele roda localmente, lê seu repositório, edita arquivos e executa comandos — tudo direto do seu terminal. Você dá uma tarefa; ele propõe mudanças; você aprova ou rejeita.
Como ele difere do app desktop do Codex
O app desktop do Codex é uma aplicação GUI completa, com computer use, um marketplace de plugins e uma interface visual. O Codex CLI é a versão de terminal: sem GUI, sem mouse, sem computer use. É mais rápido de configurar, scriptável, e se integra a workflows de terminal existentes. Se você quer rodar agentes em pipelines de CI/CD, escrever shell scripts que chamam o Codex, ou simplesmente prefere ficar no terminal, o CLI é a escolha certa.
Onde o Codex CLI se encaixa nas ferramentas da OpenAI
Existem quatro superfícies do Codex: o CLI de terminal (este guia), o app desktop (codex app), as extensões de IDE pro VS Code/JetBrains, e o Codex Web (baseado em nuvem, em chatgpt.com/codex). Este guia cobre só a instalação do CLI.
Pré-requisitos Antes de Instalar
Requisito de versão do Node.js
O caminho de instalação via npm exige Node.js 22 ou mais recente. Versões anteriores vão falhar ou produzir comportamento inesperado.
Confira sua versão atual:
node --versionSe você estiver abaixo da 22, instale ou atualize:
Usando o nvm (recomendado pra gerenciar versões do Node):
nvm install 22
nvm use 22
#Ou baixe direto do nodejs.orgSe você não quer instalar o Node.js de jeito nenhum, use o caminho do binário pré-compilado — descrito em cada seção de plataforma abaixo.
Conta OpenAI e tier de plano
O Codex CLI está incluído nos planos ChatGPT Plus, Pro, Business, Edu e Enterprise. Não existe compra separada do Codex CLI. Os limites de uso variam por tier de plano. Se você está numa conta ChatGPT gratuita, vai precisar fazer upgrade antes do Codex CLI conseguir autenticar.
Autenticação por API key também é suportada, principalmente pra pipelines de CI/CD e ambientes headless.
Considerações de rede e proxy
O Codex CLI faz requisições HTTPS de saída pras APIs da OpenAI. Se seu ambiente usa um proxy HTTP, defina a variável de ambiente HTTPS_PROXY ou https_proxy antes de rodar. Firewalls corporativos que fazem inspeção TLS podem interferir no fluxo de login OAuth; nesses ambientes, a autenticação por API key é mais confiável.
Instalar no macOS
Comando oficial de instalação
Três caminhos de instalação estão disponíveis. Escolha um:
# Opção 1: npm (requer Node.js 22+)
npm install -g @openai/codex
# Opção 2: Homebrew
brew install --cask codex
# Opção 3: Binário pré-compilado (sem necessidade de Node.js)
# Baixe em https://github.com/openai/codex/releases
# Escolha: codex-aarch64-apple-darwin.tar.gz (Apple Silicon)
# ou codex-x86_64-apple-darwin.tar.gz (Intel)
tar -xzf codex-aarch64-apple-darwin.tar.gz
mv codex /usr/local/bin/codex
chmod +x /usr/local/bin/codexO caminho do npm e o caminho do Homebrew acabam com o mesmo binário do CLI. Use o que combinar com seu workflow de gerenciamento de pacotes já existente.
Verifique com codex --version
codex --versionSe um número de versão aparecer, o binário está instalado e no seu PATH. Se você receber command not found, o diretório de bin global do seu npm não está no seu PATH — correção abaixo.
Problemas específicos do macOS
command not found depois do npm install:
# Descubra onde o npm instala os binários globais:
npm bin -g
# Adicione ao seu shell profile (~/.zshrc ou ~/.bash_profile):
export PATH="PATH:PATH: PATH:(npm bin -g)"
source ~/.zshrcO Gatekeeper bloqueia a execução (Apple Silicon, binário baixado):
Se o macOS bloquear o binário com "cannot be opened because the developer cannot be verified":
xattr -d com.apple.quarantine /usr/local/bin/codexOu vá em System Settings → Privacy & Security e clique em "Allow Anyway" depois do primeiro bloqueio.
Problemas com o caminho do Homebrew: Se o brew install --cask codex instalou o app desktop em vez do CLI, use o caminho do npm especificamente pro CLI.
Instalar no Windows
Configuração do PowerShell
O caminho nativo recomendado pro Windows em 2026 é PowerShell com npm:
# Instale o Node.js 22 primeiro se precisar (use nvm-windows ou baixe direto)
# Depois:
npm install -g @openai/codex
# Verifique:
codex --versionImportante: o nome do pacote é @openai/codex, não codex. O pacote codex sem escopo no npm é um projeto de 2012 sem relação nenhuma. Instalar o errado produz erros confusos sem causa óbvia.
Sandbox do Windows: o Codex CLI no Windows nativo usa um sandbox baseado em AppContainer que restringe escritas no sistema de arquivos e limita o acesso à rede por padrão. A OpenAI ainda classifica o suporte ao sandbox do Windows como experimental — veja o guia oficial de configuração do Windows pros detalhes atuais.
WSL2 vs. instalação nativa
Dois caminhos funcionam no Windows:
PowerShell nativo — instale via npm e rode direto no PowerShell ou no Windows Terminal. Funciona pra maioria dos workflows. Use isso se seu projeto está no sistema de arquivos do Windows e você não precisa de ferramentas específicas do Linux.
WSL2 — instale o Linux dentro do WSL2, e então instale o Codex CLI lá. Use isso quando:
Seu projeto já está no sistema de arquivos do WSL
Você precisa do comportamento de sandbox nativo do Linux
Sua toolchain de build exige Linux
Dentro do WSL2:
npm install -g @openai/codex
codex --versionNão tente rodar o binário do Codex CLI do WSL2 direto do PowerShell — chame ele de dentro do terminal do WSL.
Problemas específicos do Windows
Erros de permissão do npm no PowerShell:
# Rode o PowerShell como Administrador e depois:
npm install -g @openai/codex
# Ou configure o npm pra instalar num diretório de usuário:
npm config set prefix "$env:APPDATA\npm"
# Adicione %APPDATA%\npm ao seu PATH de usuário em System Settingscodex not found depois do npm install:
Verifique se o bin global do npm está no PATH:
npm bin -g
# Adicione o caminho impresso ao seu PATH de usuário via System Settings → Environment VariablesA janela do navegador de login não abre: Se o fluxo de navegador do OAuth não abrir, use autenticação por API key em vez disso (veja a seção Primeiro Login).
Instalar no Linux
Ubuntu e Debian
# Instale o Node.js 22 via NodeSource:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Instale o Codex CLI:
npm install -g @openai/codex
# Verifique:
codex --versionSem pacote deb: o Codex CLI não distribui um pacote .deb ou .rpm. O npm e o binário pré-compilado do GitHub Releases são os caminhos suportados no Linux.
Sandbox com Bubblewrap: a versão Linux usa o Bubblewrap (bwrap) pra sandboxing. Releases recentes já vêm com um fallback standalone do bwrap pras instalações via npm e DotSlash, então instalar o Bubblewrap manualmente não é mais necessário na maioria dos sistemas.
Instalar no Linux Fedora e RHEL
# Instale o Node.js 22:
sudo dnf install nodejs npm # ou use o nvm
# Instale o Codex CLI:
npm install -g @openai/codexArch Linux
# Node.js:
sudo pacman -S nodejs npm
# Codex CLI:
npm install -g @openai/codexBinário pré-compilado (todas as distros Linux, sem necessidade de Node.js)
# Baixe do GitHub Releases — escolha sua arquitetura:
# x86_64: codex-x86_64-unknown-linux-musl.tar.gz
# ARM64: codex-aarch64-unknown-linux-musl.tar.gz
curl -L -o codex.tar.gz \
"https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz"
tar -xzf codex.tar.gz
mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
chmod +x /usr/local/bin/codex
codex --versionO binário musl é linkado estaticamente — ele roda em qualquer distribuição Linux sem dependências de runtime adicionais.
Problemas específicos do Linux
Erros de permissão do npm:
# Configure o npm pra instalar num diretório de usuário (sem sudo):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codexBubblewrap faltando em distros mais antigas:
# Ubuntu/Debian:
sudo apt-get install bubblewrap
# Fedora:
sudo dnf install bubblewrapPrimeiro Login e Autenticação
Fluxo com conta ChatGPT (recomendado)
Na primeira vez que você roda o codex, ele pede pra você fazer login:
codexSelecione Sign in with ChatGPT. Seu navegador abre numa página OAuth. Faça login com a conta ChatGPT que tem sua assinatura Plus/Pro/Business. Quando a autenticação terminar, volte pro terminal — a sessão está ativa.
Esse fluxo vincula o Codex CLI à sua assinatura ChatGPT. Nenhum gerenciamento de API key necessário.
Fluxo com API key (pra CI/CD e ambientes headless)
export OPENAI_API_KEY="sk-..."
codexOu adicione ao seu shell profile pra persistência. Com uma API key, o Codex usa seus créditos de API em vez da sua cota de assinatura do ChatGPT. Confira a página de preços pras taxas de token atuais.
Onde as credenciais ficam armazenadas
As credenciais OAuth do ChatGPT ficam guardadas no keychain do sistema (macOS Keychain, Windows Credential Manager, Linux Secret Service). A credencial não fica salva num arquivo de configuração em texto plano. Pra fazer logout: rode codex auth logout ou remova a entrada direto do keychain do seu sistema.
Seu Primeiro Comando no Codex CLI
# Primeiro, navegue até o diretório do projeto:
cd your-project
# Inicie uma sessão interativa:
codexPrimeira tarefa mínima
Depois que a TUI abrir, tente uma tarefa somente leitura pra verificar se tudo está funcionando:
Resuma o que esse projeto faz com base no README e nos arquivos de nível superior
O Codex vai ler os arquivos do repositório e devolver um resumo. Nenhuma modificação de arquivo. Se isso funcionar, tanto a autenticação quanto o acesso às ferramentas estão funcionando corretamente.
Como fica quando dá certo
Você vai ver uma interface de terminal dividida: a conversa de um lado, a saída de arquivo/comando do outro. Pra tarefas que modificam arquivos, o Codex vai te mostrar um diff e pedir aprovação antes de aplicar as mudanças. Aprove com y, pule com n, ou revise mais com e.
Erros Comuns de Instalação e Correções
| Erro | Causa | Correção |
|---|---|---|
| command not found: codex | O bin global do npm não está no PATH | Rode npm bin -g, adicione esse caminho ao seu shell profile |
| npm ERR! code EACCES | O npm não tem permissão pro diretório global | Configure o npm pra usar um diretório de usuário (veja as seções de cada plataforma) |
| Instalou o pacote errado | Usou npm i -g codex em vez de @openai/codex | npm uninstall -g codex && npm install -g @openai/codex |
| Erro de versão do Node.js | Node < 22 instalado | Instale o Node.js 22+ via nvm ounodejs.org |
| A janela do navegador do OAuth não abre | Ambiente headless ou proxy | Use export OPENAI_API_KEY e pule o OAuth |
| bwrap: No such file or directory (Linux) | Bubblewrap faltando | Instale o bubblewrap via seu gerenciador de pacotes |
| O login continua falhando | Conta não está num plano pago | Faça upgrade pro Plus ou use uma API key |
FAQ
Qual versão do Node.js é realmente necessária pro Codex CLI?
O Node.js 22 ou mais recente é exigido pro caminho de instalação via npm. O binário pré-compilado do GitHub Releases não exige Node.js nenhum — é um binário Rust compilado estaticamente que roda de forma independente. Se você gerencia várias versões do Node entre projetos, use o nvm (macOS/Linux) ou o nvm-windows pra instalar a 22 sem afetar outros projetos.
Como eu instalo o Codex CLI no Windows sem usar o WSL?
Instale o Node.js 22 pelo nodejs.org, depois rode npm install -g @openai/codex no PowerShell. O Codex CLI roda nativamente no PowerShell com um sandbox baseado em AppContainer. O WSL2 é opcional — use ele se seu projeto está no sistema de arquivos do WSL ou se você precisa especificamente do comportamento nativo do Linux. O caminho nativo do Windows funciona pra maioria dos workflows de código.
Por que o login do Codex CLI continua falhando?
As causas mais comuns: (1) sua conta ChatGPT está no plano gratuito — o Codex exige Plus, Pro, Business, Edu ou Enterprise; (2) seu proxy corporativo está interceptando TLS e o fluxo de navegador do OAuth não consegue completar — use autenticação por API key em vez disso; (3) a janela do navegador abriu, mas você fez login com uma conta diferente do seu plano pago. Tente codex auth logout pra limpar a sessão e autenticar de novo do zero.
Como eu atualizo ou desinstalo completamente o Codex CLI?
# Atualizar:
npm update -g @openai/codex
# ou:
npm install -g @openai/codex@latest
# Desinstalar:
npm uninstall -g @openai/codex
# Remova a configuração e as credenciais:
rm -rf ~/.codex
codex auth logout # limpa a entrada do keychain do sistemaPra instalações via Homebrew: brew uninstall --cask codex. Pra instalações via binário: remova o binário de onde você colocou ele (por exemplo, rm /usr/local/bin/codex).
