Como corrigir a instalação do Codex CLI: PATH, login e WSL

Se a instalação terminar, mas o shell exibir codex: command not found, o problema não é a autenticação: o terminal não consegue localizar o executável. Se o Codex abrir e travar durante o login pelo navegador, a instalação já foi concluída. Trate as duas situações como falhas distintas.

Confirme a instalação com um único comando

Abra um novo terminal e execute:

codex --version

Um número de versão confirma que esse shell consegue encontrar e executar o Codex. Pule para a seção de login se a autenticação for o único problema restante. Se o comando estiver ausente, verifique se você instalou o Codex no mesmo ambiente que está usando agora. Um erro comum é instalar no PowerShell e depois procurar o comando no WSL, ou o contrário.

Verifique qual terminal executou o instalador

Em macOS, Linux ou WSL, execute o script oficial dentro desse shell:

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

Para Windows nativo, abra o PowerShell — não uma janela do WSL — e execute:

irm https://chatgpt.com/codex/install.ps1 | iex

Se Node.js e npm já estiverem instalados, o pacote npm é outra opção compatível:

npm install --global @openai/codex

Depois de concluir qualquer um dos métodos, feche todos os terminais, abra um novo e execute codex --version. Use apenas um método de instalação. Se houver várias cópias, um executável antigo pode aparecer antes no PATH e dificultar a identificação da versão em uso.

O instalador autônomo coloca o executável em ~/.local/bin no macOS e no Linux, e em %LOCALAPPDATA%\Programs\OpenAI\Codex\bin no Windows.

Se o arquivo existir, mas o comando não, compare o diretório de instalação com o PATH.

Em macOS, Linux ou WSL:

ls -l ~/.local/bin/codex
printf '%s\n' "$PATH" | tr ':' '\n'

Se ~/.local/bin estiver ausente, execute export PATH="$HOME/.local/bin:$PATH" no shell atual e teste novamente. Assim que funcionar, adicione a mesma linha em ~/.zshrc ou ~/.bashrc.

No PowerShell do Windows:

Test-Path "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin\codex.exe"
$env:Path -split ';'

Se o executável existir, mas o diretório estiver ausente, adicione %LOCALAPPDATA%\Programs\OpenAI\Codex\bin à variável de ambiente do usuário do Windows Path, e reabra o PowerShell.

Mantenha as instalações do Windows e do WSL separadas

PowerShell e WSL são ambientes de execução separados. Por padrão, o WSL adiciona os diretórios do Windows ao $PATH, então pode ser capaz de iniciar um programa do Windows, como codex.exe. Isso não significa que o executável do Linux codex esteja instalado no WSL. Se você trabalhar dentro do WSL, instale a versão Linux lá.

Para configurar o WSL2, execute o comando abaixo em um PowerShell com privilégios de administrador ou no Windows Terminal:

wsl --install

Reinicie o Windows se solicitado. Conclua a configuração inicial do usuário Linux, em seguida, entre no WSL:

wsl

Dentro do shell Linux, instale o Codex com o script Linux:

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

Abra um novo shell do WSL e confirme com codex --version. A documentação atual do Codex é voltada ao WSL2; o WSL1 deixou de ser compatível a partir do Codex 0.115. Manter os projetos no diretório pessoal do WSL, como ~/code/..., em vez de /mnt/c/..., também evita muitos problemas de sistema de arquivos e permissões.

Se você permanecer no PowerShell, mantenha apenas a instalação do Windows. Se usar o WSL, mantenha a instalação, a execução e os arquivos do projeto dentro desse ambiente.

Se o login no navegador nunca voltar ao terminal

Quando o Codex inicia, mas a autenticação não termina, reinicie o fluxo de login padrão:

codex login

Depois do login no ChatGPT pelo navegador, as credenciais devem ser devolvidas ao Codex. Verifique o estado atual de autenticação com:

codex login status

Em uma máquina remota ou sem interface gráfica — ou em uma rede corporativa que bloqueie o callback local — o navegador pode concluir a autenticação enquanto o terminal continua aguardando. Nesse caso, use o fluxo beta de código do dispositivo. Em contas pessoais, a autorização por código do dispositivo precisa ser ativada primeiro nas configurações de segurança do ChatGPT; em workspaces gerenciados, um administrador precisa liberar o recurso.

codex login --device-auth

Para trocar de conta ou limpar um cache de autenticação suspeito, encerre a sessão e inicie outra. codex logout remove as credenciais armazenadas; portanto, use-o apenas quando estiver pronto para fazer login novamente.

codex logout
codex login

Um espaço de trabalho gerenciado no ChatGPT pode restringir o método de login permitido ou o próprio espaço de trabalho. Se o Codex continuar rejeitando uma conta pessoal, verifique a política da organização antes de reinstalar.

Se a instalação e o login parecem saudáveis

Quando a versão e o status de autenticação estão corretos, mas o Codex ainda não inicia, execute o resumo de diagnóstico:

codex doctor --summary

O comando verifica a instalação local, a configuração, as credenciais e o ambiente de execução. Ao pedir ajuda, informe o sistema operacional, o shell, a saída de codex --version, o método de instalação e o item do diagnóstico que falhou. Nunca cole um token de acesso nem o conteúdo de ~/.codex/auth.json.