Guia completo para instalar o Codex CLI no Windows: Node.js, npm.ps1 e variáveis de ambiente

A instalação do Codex CLI no Windows envolve principalmente Node.js, npm, PowerShell e variáveis de ambiente. Este artigo organiza as etapas na ordem em que são executadas e explica como resolver alguns erros comuns.

O artigo aborda apenas a instalação e o uso básico do Codex CLI.

1. Verificações antes da instalação

Abra o PowerShell e execute separadamente:

node --version
npm --version

Se os dois comandos exibirem números de versão, avance diretamente para “Instalar o Codex CLI”.

Se node ou npm não for reconhecido, normalmente há duas possibilidades:

• O Node.js ainda não está instalado no computador.
• O Node.js está instalado, mas o terminal atual ainda não carregou as novas variáveis de ambiente.

2. Instalar o Node.js

Acesse o site oficial do Node.js:

https://nodejs.org/

Baixe a versão LTS para Windows e siga o assistente de instalação. Em geral, basta manter as opções padrão.

Depois de instalar, feche a janela anterior do PowerShell, abra uma nova e verifique novamente:

node --version
npm --version

Se os números de versão aparecerem, o Node.js e o npm estão disponíveis.

3. Resolver o bloqueio de execução de npm.ps1

Em alguns computadores Windows, executar npm no PowerShell gera uma mensagem semelhante a esta:

O arquivo npm.ps1 não pode ser carregado porque a execução de scripts está desabilitada neste sistema.

Isso normalmente não significa que a instalação do npm esteja danificada. A política de execução de scripts do PowerShell está bloqueando npm.ps1.

Sem alterar essa política, você pode chamar diretamente o arquivo de comando do npm para Windows:

npm.cmd --version

Se esse comando exibir a versão, você também poderá usar npm.cmd para instalar o Codex CLI.

Em um computador pessoal, depois de confirmar que a origem do script é confiável, também é possível definir RemoteSigned apenas para o usuário atual:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Reabra o PowerShell após a alteração. Computadores gerenciados por uma empresa ou instituição de ensino podem estar sujeitos a políticas da organização; nesse caso, procure o administrador.

4. Instalar o Codex CLI

Execute no PowerShell:

npm.cmd install -g @openai/codex@latest

Após a instalação, confira a versão:

codex.cmd --version

Se aparecerem codex-cli e um número de versão, a ferramenta de linha de comando foi instalada com sucesso. Usar codex.cmd evita que o PowerShell bloqueie o script correspondente, codex.ps1.

Quando precisar atualizar, execute novamente:

npm.cmd install -g @openai/codex@latest
codex.cmd --version

5. O comando codex não é encontrado após a instalação

Se a instalação terminou sem erros, mas o sistema não reconhece codex, primeiro feche o PowerShell atual e abra uma nova janela.

Em seguida, execute:

Get-Command codex.cmd -ErrorAction SilentlyContinue
npm.cmd config get prefix

O primeiro comando verifica se o sistema consegue localizar o Codex. O segundo mostra o local de instalação global do npm.

Se Get-Command não retornar nada, verifique se o diretório global do npm está na variável de ambiente Path do usuário atual. Depois de modificar as variáveis de ambiente, reabra o terminal para aplicar as mudanças.

6. Iniciar o Codex no diretório de um projeto

Crie primeiro um diretório separado para praticar. Evite iniciar uma ferramenta de programação diretamente em toda a pasta do usuário ou em um diretório com muitos arquivos privados.

New-Item -ItemType Directory -Path "$env:USERPROFILE\CodexProjects\demo" -Force
Set-Location "$env:USERPROFILE\CodexProjects\demo"
codex.cmd

Na primeira execução, faça a autenticação usando as opções de login exibidas no terminal. Elas podem variar conforme a versão e o estado da conta; siga a interface atual e as instruções oficiais.

Se não conseguir concluir o processo na página de login, evite modificar repetidamente configurações desconhecidas ou usar scripts de origem duvidosa. Verifique nesta ordem:

1. Confirme se a hora e o fuso horário do sistema estão corretos.
2. Confirme se o navegador abre a página de login normalmente.
3. Feche o terminal antigo e execute codex.cmd novamente.
4. Verifique o estado da conta e a disponibilidade do serviço.
5. Consulte as instruções de login mais recentes na documentação oficial do Codex.

Documentação oficial do Codex:

https://developers.openai.com/codex/cli/

7. Escolher as opções de confiança no diretório e sandbox

O Codex pode pedir confirmação de confiança no diretório atual. Continue apenas se a ferramenta puder ler e modificar os arquivos desse diretório.

Adote os seguintes cuidados durante o uso:

• Execute a ferramenta em um diretório de projeto separado.
• Confira o comando e o caminho de destino antes da execução.
• Use controle de versão ou faça backup antes de modificar arquivos importantes.
• Não divulgue senhas, tokens ou outras credenciais em prompts, código ou capturas de tela.
• Não desative todas as proteções de segurança por conveniência.

Para apenas ler e analisar código, prefira permissões mais restritas. Autorize a gravação de arquivos ou a execução de comandos conforme a necessidade real da tarefa.

8. Perguntas frequentes

1. O comando node não é reconhecido

Confirme se o Node.js está instalado e se você reabriu o PowerShell após a instalação. Se ainda não funcionar, verifique se o diretório de instalação do Node.js está em Path.

2. Não é possível executar npm.ps1

Use npm.cmd no lugar de npm. Altere a política de execução do PowerShell do usuário atual somente depois de confirmar que você administra o dispositivo e que a origem do script é confiável.

3. A instalação apresenta um erro de permissão

Primeiro, verifique se o diretório global de instalação do npm pertence ao usuário atual. Sem entender a causa, não desative os recursos de segurança do sistema nem execute scripts desconhecidos de elevação de privilégios.

4. codex.cmd --version funciona, mas o login falha ao iniciar

Isso normalmente indica que o CLI já está instalado. O problema provavelmente está na autenticação, no navegador, no estado da conta, no ambiente de rede ou na disponibilidade do serviço. Investigue cada possibilidade com base na mensagem de erro original do terminal.

5. Como confirmar qual Codex está sendo usado?

Execute:

Get-Command codex.cmd | Format-List Name,Source,Version
codex.cmd --version

Esses dois comandos ajudam a identificar o caminho do comando e a versão atual.

9. Checklist de instalação

• node --version exibe a versão normalmente.
• npm.cmd --version exibe a versão normalmente.
• codex.cmd --version exibe a versão normalmente.
• O PowerShell foi reaberto para carregar as variáveis de ambiente.
• O Codex inicia em um diretório de projeto separado.
• O login usa a entrada oficial fornecida pela versão atual.
• Nenhuma senha, token ou URL com parâmetros sensíveis foi divulgada.
• Os arquivos importantes estão em backup ou sob controle de versão.

Verificar Node.js, npm, Codex CLI, login e diretório do projeto nessa ordem costuma facilitar o diagnóstico, em comparação com alterar várias configurações ao mesmo tempo. As versões e as telas de login podem mudar; siga a interface atual do Codex e a documentação oficial para as opções específicas.