Codex CLI no Windows sem confusão

Instalar o Codex CLI, receber uma resposta da API e salvar um arquivo são verificações diferentes. Este roteiro separa essas etapas ao conectar o cliente ao Crazyrouter. O procedimento inclui o começo no Windows, os comandos de PowerShell, o payload de uma chamada curta e a configuração do cliente. A intenção é deixar um caminho que outra pessoa consiga repetir e discutir, inclusive quando parar antes do resultado final.

1. Qual afirmação queremos conseguir sustentar?

Evidência obtida	Afirmação razoável	Salto que devemos evitar
Saída de versão	O executável foi iniciado	A API está pronta
Catálogo retornado	A operação de listagem respondeu	Todo modelo pode gerar
Resposta curta concluída	Uma geração específica funcionou	Todo o fluxo do agente é compatível
Diálogo na CLI	O cliente conseguiu responder nessa sessão	O projeto pode ser modificado
Arquivo com comportamento conferido	A tarefa local definida foi atendida	Qualquer tarefa futura dará certo

Para quem está começando, vale uma definição rápida: CLI é um programa usado pelo terminal; provider é a configuração que aponta esse programa para um serviço; modelo é a identificação enviada naquela solicitação. O serviço remoto não se confunde com a instalação local do agente.

Usaremos Crazyrouter como implementação concreta do provider. Isso permite discutir endereço, autenticação e protocolo com valores específicos, mas não dispensa confirmar a conta e o modelo. Uma assinatura ChatGPT, um acesso OpenAI API e um token de outro serviço não são a mesma autorização.

2. Preparar um ambiente que outra pessoa consiga descrever

Se Node, npm e Codex já estão acessíveis, consulte as versões e preserve o ambiente existente. Para quem ainda não tem essas ferramentas, segue o caminho completo pelo Windows, incluindo os detalhes de entrada no PowerShell.

Abra o PowerShell e confira o ambiente

No menu Iniciar, procure PowerShell; no Windows Terminal, selecione esse perfil. Comece numa janela comum. Copie apenas os comandos, sem o prompt PS C:\...> e sem a saída dos exemplos. Execute uma linha por vez; blocos com if devem ser copiados inteiros.

Cole com Ctrl + V. Se aparecer >>, pode faltar uma aspa ou chave: cancele com Ctrl + C e copie novamente. Usaremos npm.cmd e codex.cmd para evitar que o PowerShell selecione um iniciador .ps1 bloqueado pela política de scripts.

node --version
npm.cmd --version

Se ambos retornarem versões, siga para a instalação da CLI. Se node não for encontrado, falta instalar o ambiente ou atualizar o PATH da janela.

Instale Node.js, se necessário

No download oficial do Node.js, escolha LTS, Windows e o instalador .msi. Confira a arquitetura nas configurações do Windows, em Sistema → Sobre: x64 e ARM64 usam pacotes diferentes. Não copie as instruções de Docker para esta instalação nativa.

No assistente, mantenha npm e a inclusão no PATH. Ferramentas extras de compilação não são necessárias para este exercício. Depois, feche o terminal e abra outro; se estiver dentro de um editor, reinicie-o quando necessário. Execute novamente os dois comandos de versão.

As capturas estão em chinês; use-as para reconhecer o erro e a saída de versão. Não é preciso instalar o mesmo número mostrado. Se a falha continuar, confira a instalação e seu diretório no PATH antes de mexer em API ou modelo.

Instale e localize o Codex

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

codex.cmd --version
codex.cmd --help

Espere a instalação terminar antes de consultar versão e ajuda. -g instala um utilitário global do npm; não significa liberar todo o computador para o agente. Leia o conteúdo de WARN e notice, e investigue npm ERR! ou falhas de download. O comando de versão é a verificação local.

Se codex.cmd continuar ausente numa janela nova:

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

O segundo comando mostra a pasta global. Procure codex.cmd nela. Se existir, adicione essa pasta ao Path do usuário, sem apagar os itens existentes; salve e reabra o terminal. Se não existir, confira o log da instalação. Não acrescente o nome do arquivo ao Path.

Registre os números realmente mostrados na sua máquina. Na preparação deste material, foram observados Node.js v24.21.0, npm 11.19.0 e Codex CLI 0.158.0; isso descreve um ambiente, não uma exigência para procurar precisamente essas versões.

3. Fixar o que pode mudar durante o experimento

Antes de conectar, escolha um diretório pequeno e saiba de onde a CLI será iniciada:

$projectDir = Join-Path $env:USERPROFILE 'CodexProjects\crazyrouter-demo'
New-Item -ItemType Directory -Path $projectDir -Force | Out-Null
Set-Location -LiteralPath $projectDir
Get-Location

O último comando confirma a posição atual. O nome da pasta não configura o serviço; serve para identificar o exercício. Se já houver arquivos ali, veja o que pode ser alterado antes de pedir qualquer gravação. Uma página antiga pode passar em um teste manual e mascarar uma tentativa nova que não salvou nada.

Mantenha o mesmo PowerShell durante o roteiro. Variáveis comuns, como $projectDir, pertencem à sessão. O token também será colocado apenas no ambiente desse processo. Mudar de janela sem refazer a preparação acrescenta uma diferença que não tem relação com o modelo.

4. Consultar o catálogo com uma credencial própria

Crie um token no acesso Crazyrouter que você tem autorização para usar. A documentação de início orienta a localização da administração de tokens. Não use uma chave encontrada num exemplo público.

$crazySecret = Read-Host 'Crazyrouter API Key' -AsSecureString
$env:CRAZYROUTER_API_KEY = [System.Net.NetworkCredential]::new('', $crazySecret).Password
$crazySecret.Dispose()
Remove-Variable crazySecret
[bool]$env:CRAZYROUTER_API_KEY

A entrada protegida evita inserir o segredo como texto explícito da linha de comando. O True final informa somente que existe valor no processo. Não consulta o serviço e não diz se a chave expirou, se possui créditos ou se permite um modelo.

$crazyBase = 'https://api.crazyrouter.com/v1'
$crazyHeaders = @{ Authorization = "Bearer $env:CRAZYROUTER_API_KEY" }
$crazyModels = Invoke-RestMethod -Method Get -Uri "$crazyBase/models" -Headers $crazyHeaders
$crazyModels.data | Select-Object -ExpandProperty id

$crazyModel = Read-Host 'Model ID'

A resposta do catálogo fornece os identificadores para a escolha. Em Model ID, indique exatamente uma opção com permissão e comportamento apropriado ao uso de Responses pelo Codex. Não confunda o rótulo apresentado numa página com o campo id da API.

Guarde a identificação escolhida e preserve a URL usada na consulta. Se mudar o token depois, refaça também a criação de $crazyHeaders: esse objeto guarda o valor usado quando foi montado, não uma referência que se atualiza sozinha a cada alteração do ambiente.

5. Separar transporte HTTP de conclusão da geração

Antes de envolver a configuração interna da CLI, envie uma chamada pequena. Ela consome recursos reais da conta conforme as regras do serviço:

$crazyPayload = @{
    model = $crazyModel
    input = 'Reply with OK.'
    stream = $false
} | ConvertTo-Json -Depth 6

$crazyResponse = Invoke-RestMethod -Method Post -Uri "$crazyBase/responses" -Headers $crazyHeaders -ContentType 'application/json' -Body $crazyPayload
$crazyResponse | Select-Object id, status, error
$crazyResponse.output | ConvertTo-Json -Depth 8

O payload tem três escolhas explícitas: o modelo de $crazyModel, uma entrada curta e a resposta sem streaming. A rota é /v1/responses. A base já contém /v1, então não acrescente esse trecho novamente.

Observe o identificador, o estado, o erro e o conteúdo efetivo de output. Um retorno HTTP sem exceção pode conter uma falha de negócio. Também pode haver diferenças no envelope da resposta que precisam ser interpretadas pela documentação atual, em vez de tratadas como sucesso por falta de uma mensagem vermelha.

O teste tem uma limitação deliberada: stream = false não verifica o caminho de streaming do agente. Também não aciona ferramentas. Ele reduz o problema para uma geração simples, permitindo observar uma parte antes de montar o restante. Depois, a CLI ainda precisa ser exercitada.

6. Fazer a CLI usar a mesma combinação de parâmetros

Agora levamos a configuração testada para o cliente. O risco aqui é comparar duas coisas que parecem iguais, mas usam endereços ou modelos diferentes.

$codexConfigDir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
$codexConfigFile = Join-Path $codexConfigDir 'config.toml'
if (Test-Path -LiteralPath $codexConfigFile) {
    $backupFile = $codexConfigFile + '.' + (Get-Date -Format 'yyyyMMdd-HHmmss') + '.bak'
    Copy-Item -LiteralPath $codexConfigFile -Destination $backupFile
}
notepad.exe $codexConfigFile

O script usa CODEX_HOME quando existe e, na ausência dele, a pasta .codex do usuário. Antes de editar um arquivo existente, cria uma cópia com horário. Integre as opções ao arquivo atual sem remover preferências que não fazem parte da conexão.

model = "MODEL_ID_FROM_YOUR_ACCOUNT"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "CRAZYROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Troque MODEL_ID_FROM_YOUR_ACCOUNT pelo identificador selecionado. A variável do script e o campo no arquivo não são sincronizados. O mesmo vale para $crazyBase e base_url: confira os dois pares antes de comparar resultados.

Parte do arquivo	Decisão que representa
model	Identidade do modelo chamado
model_provider	Tabela de conexão selecionada
name	Nome de apresentação, sem poder de roteamento
base_url	Prefixo real da API
env_key	Nome da variável de onde vem o segredo
wire_api	Forma de comunicação escolhida
requires_openai_auth	Se o cliente deve usar autenticação OpenAI

Para o método de variável próprio deste roteiro, a última opção é false. Com true, a autenticação OpenAI é usada e env_key é ignorado. Misturar exemplos de duas estratégias pode criar uma configuração aparentemente completa que lê a credencial errada.

As duas primeiras linhas são de nível superior. Coloque-as antes das tabelas entre colchetes; depois de uma tabela, um campo pode passar a pertencer a ela. Altere chaves que já existem em vez de duplicar o nome ou repetir a mesma tabela de provider.

Salve a extensão correta, config.toml, e confira que não virou um documento .txt. Não use a homepage no lugar da API nem coloque UTM no endpoint. Autenticação e provider pertencem ao escopo do usuário; um arquivo local no projeto não substitui indiscriminadamente essas decisões.

7. Observar o comportamento do cliente, não só do script

Set-Location -LiteralPath $projectDir
codex.cmd

Peça uma explicação de HTML em uma frase, sem uso de arquivos ou comandos. Veja se a sessão usa o provider e o modelo esperados. Uma sessão antiga pode carregar escolhas anteriores; depois de mudar a configuração, encerre e abra novamente a partir do PowerShell preparado.

A captura está em chinês. Use-a para identificar o tipo de decisão, não a posição de uma opção ou a disponibilidade do modelo mostrado.

Confiança no diretório e sandbox são controles locais. Eles não são uma segunda cobrança de autenticação pela API. O caminho informado deve corresponder à pasta de exercício; caso contrário, ajuste o local antes de aceitar operações.

8. Usar as falhas como informação, sem inventar uma causa

Um diagnóstico começa pela diferença entre o que esperávamos e o que vimos. O código HTTP é uma pista, mas o corpo da resposta e a operação que o gerou continuam necessários.

Resultado observado	Pergunta seguinte	Conclusão que ainda não cabe
Variável ausente	O processo de origem tinha o valor?	A chave foi recusada pelo serviço
401	A credencial é válida para esse destino?	Todo o serviço está fora do ar
403	Qual motivo de recusa foi informado?	Alterar uma linha resolverá qualquer caso
404	A rota e o modelo estão corretos?	Reinstalar Node reparará a API
429	Foi indicada frequência ou cota?	Basta repetir mais rápido
Texto recebido, escrita bloqueada	Qual limite local impediu a ação?	A geração remota falhou

9. Produzir um arquivo que forneça uma evidência independente

Após uma resposta normal pela CLI, peça uma página local de acompanhamento do exercício. Ela não será um monitor da API; seus controles servem para verificar a interação gerada.

Crie apenas index.html na pasta atual, em português brasileiro.
Use o título “Meu teste local” e três caixas de seleção inicialmente desmarcadas.
Os rótulos são “Página aberta”, “Controles conferidos” e “Repetição feita”.
Mostre quantas caixas estão marcadas, atualizando o número ao marcar ou desmarcar.
Esclareça na página que essas marcações são manuais, não testes automáticos de API.
Inclua CSS e JavaScript no mesmo arquivo, sem dependências externas ou instalação.
Não faça chamadas de rede nem altere outros arquivos.
Informe o caminho efetivamente salvo; se a escrita for recusada, reporte a limitação.

Saia do diálogo usando /quit ou a opção disponível. Confira o arquivo e, somente depois de True, abra-o:

Test-Path .\index.html

Start-Process .\index.html

Marque uma caixa, depois outra, desmarque a primeira e observe se a contagem acompanha o estado real. Ao recarregar, as caixas devem voltar ao estado inicial, já que não foi solicitada persistência. Compare também os textos e a existência do aviso sobre marcação manual.

Se houver erro, reproduza a sequência e peça a correção nesse arquivo. Não basta o agente afirmar que testou: abra a versão salva e repita. Caso haja arquivos homônimos, confira a URL local no navegador para não avaliar uma cópia antiga.

10. Dúvidas práticas ao repetir em outra máquina

A instalação precisa usar a mesma versão da captura?

Não por causa da captura. Confira os requisitos atuais e registre a versão usada. A imagem documenta um formato de tela, não impõe um número que permanecerá obrigatório.

É preciso mudar a política de scripts?

Comece pelos iniciadores .cmd apresentados. Se houver necessidade adicional de scripts, trate a política especificamente, respeitando a administração da máquina. Não é uma etapa geral de liberação irrestrita.

Qual registry está sendo usado no download?

npm.cmd config get registry

Leia o resultado antes de alterar uma origem que pode ser intencional. O download do pacote é independente da URL que receberá a geração. Não desligue a validação de certificados como correção genérica.

A chave foi salva no TOML?

[bool]$env:CRAZYROUTER_API_KEY

Não: env_key contém o nome, e a consulta acima mostra apenas a presença do valor no processo. Preparar outra janela ou fechar a original muda essa condição.

Posso colar comandos de CMD no mesmo lugar?

Não assuma equivalência. Aqui usamos $env:USERPROFILE e Set-Location. A expansão por %USERPROFILE% e cd /d pertencem a outra sintaxe. Preserve também as aspas em caminhos com espaços.

Como atualizar e identificar duas instalações?

npm.cmd install -g @openai/codex@latest
codex.cmd --version
Get-Command codex* -All

Consulte as localizações retornadas. Uma atualização pode atingir um prefixo enquanto o Windows encontra primeiro outro iniciador. Resolver isso exige saber qual arquivo está rodando.

Um endpoint Chat Completions já comprova uso no Codex?

Não. Protocolo, streaming e ferramentas fazem parte do comportamento necessário. Este roteiro usa Responses e depois uma tarefa na CLI justamente para não substituir o segundo teste pelo primeiro.

Quanto do erro posso compartilhar?

O suficiente para reproduzir a operação: comando, versão, modelo, horário, resposta sem segredos e último resultado confirmado. Evite tokens, códigos de dispositivo e dados particulares do projeto. Uma identificação de resposta costuma ser mais útil do que o diretório inteiro de configuração.

11. Registrar o resultado e os limites

Na preparação do material, a instalação local foi verificada, mas não havia uma credencial Crazyrouter válida para concluir a integração. Portanto, este roteiro não apresenta um response ID, um modelo confirmado ou uma tarefa remota bem-sucedida. Os testes de API e de criação da página acima são etapas para executar com sua conta, não resultados já obtidos.

Ao reproduzir, anote versão, model ID, método e endpoint, horário, status HTTP, response ID e estado final quando disponíveis. Registre também o texto retornado e se o arquivo foi realmente salvo e conferido. O HTTP 200 sozinho não comprova conclusão; omita credenciais do registro. Se catálogo e geração tiverem resultados diferentes, relate cada um separadamente.

Para repetir após uma mudança, recupere a anotação de versão e seleção. Se o modelo mudou, confira seu ID e refaça a chamada pequena. Se a URL mudou, mantenha script e configuração consistentes. Se só mudou de projeto, revise a pasta e suas permissões, sem reinstalar tudo por reflexo.

Consulte também a documentação do Codex para as opções da versão em uso.