Errores de Codex en Windows PowerShell: instalación, login, rutas y argumentos

Cuando Codex falla en Windows PowerShell, muchas veces el problema no es Codex. Puede ser Node.js, npm, PATH, política de ejecución, comillas, variables de entorno, proxy o la forma en que PowerShell pasa argumentos.

Checklist rápido

1
2
3
4
5

$PSVersionTable.PSVersion
node -v
npm -v
where.exe codex
codex --version

Si codex --version funciona, Codex está disponible. Luego revisa login, ruta del proyecto, permisos o red.

Error 1: codex no se reconoce

Mensaje típico:

1

codex : The term 'codex' is not recognized as the name of a cmdlet...

Revisa:

1
2
3
4

node -v
npm -v
where.exe npm
where.exe codex

Si falta Node o npm, instala Node.js LTS. Si falta Codex:

1

npm install -g @openai/codex

Luego:

1
2

where.exe codex
codex --version

Si sigue sin aparecer, probablemente el bin global de npm no está en PATH.

Error 2: npm install -g falla

Causas comunes:

• Node.js antiguo;
• permisos del directorio global de npm;
• proxy o certificados corporativos.

1
2
3
4
5
6

node -v
npm -v
npm ping
npm config get proxy
npm config get https-proxy
npm config get registry

No desactives SSL sin entender el entorno corporativo.

Error 3: ExecutionPolicy bloquea scripts

1

running scripts is disabled on this system

Para scripts confiables:

1

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Una sola ejecución:

1

powershell -ExecutionPolicy Bypass -File .\script.ps1

No uses Bypass como prefijo universal.

Error 4: rutas con espacios o caracteres no ASCII

Evita construir una sola cadena larga.

Mal:

1

codex --cd C:\Users\Your Name\Documents\My Project

Mejor:

1
2
3

$project = 'C:\Users\Your Name\Documents\My Project'
Set-Location -LiteralPath $project
codex

Ejecutable con ruta:

1
2
3
4
5
6

$exe = 'C:\Program Files\nodejs\npx.cmd'
$args = @(
    '--version'
)

& $exe @args

Cada argumento debe ser un elemento del array.

Error 5: copiar comandos Bash en PowerShell

1
2
3

export OPENAI_API_KEY=sk-...
curl -fsSL https://example.com/install.sh | bash
VAR=value codex

En PowerShell:

1

$env:OPENAI_API_KEY = 'sk-...'

Persistente:

1

[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User')

Abre una terminal nueva.

Error 6: comillas, barras o JSON se rompen

Evita JSON escapado a mano:

1

codex --config "{\"foo\":\"bar\"}"

Usa objetos o archivos:

1
2
3
4

@{
    foo = 'bar'
    mode = 'review'
} | ConvertTo-Json | Set-Content -Encoding UTF8 .\config.json

Argumentos como array:

1
2
3
4
5
6
7
8

$args = @(
    '--model'
    'gpt-5-codex'
    '--reasoning-effort'
    'high'
)

codex @args

Error 7: texto corrupto o mojibake

La consola puede mostrar mal aunque el archivo esté bien. Verifica con UTF-8:

1

python -c "from pathlib import Path; print(Path('README.md').read_text(encoding='utf-8')[:200])"

Para Markdown en chino o japonés, guarda en UTF-8 y verifica leyendo el archivo.

Error 8: login o API key no funcionan

Define primero el modo:

• Codex app / CLI login;
• API key;
• plugin que usa Codex local;
• otra herramienta llamando Codex.

1

$env:OPENAI_API_KEY

Si cambiaste variables del sistema, abre una nueva ventana.

Error 9: proxy, certificados o firewall

1
2

Resolve-DnsName api.openai.com
Test-NetConnection api.openai.com -Port 443

Si DNS o 443 fallan, arregla red antes de tocar Codex.

Error 10: se interpreta mal éxito o fallo

Programas nativos usan $LASTEXITCODE:

1
2
3
4

npm test
if ($LASTEXITCODE -ne 0) {
    throw "npm test failed with exit code $LASTEXITCODE"
}

Cmdlets usan errores terminantes:

1
2

$ErrorActionPreference = 'Stop'
Copy-Item -LiteralPath '.\a.txt' -Destination '.\backup\a.txt'

Preferir PowerShell 7

powershell.exe suele ser Windows PowerShell 5.1. PowerShell 7 es:

1

pwsh.exe

1

$PSVersionTable.PSVersion

Instalar PowerShell 7 no reemplaza powershell.exe.

Plantilla estable para iniciar Codex

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ErrorActionPreference = 'Stop'

$project = 'C:\Work\my-project'
Set-Location -LiteralPath $project

where.exe codex | Out-Null
if ($LASTEXITCODE -ne 0) {
    throw 'codex command was not found in PATH'
}

codex --version
codex

Con argumentos:

1
2
3
4
5
6

$args = @(
    '--model'
    'gpt-5-codex'
)

codex @args

Orden recomendado

1. node -v y npm -v.
2. where.exe codex.
3. codex --version.
4. PowerShell 5.1 o 7.
5. Rutas con espacios o caracteres no ASCII.
6. Sintaxis Bash pegada por error.
7. ExecutionPolicy.
8. Login o API key en la sesión actual.
9. Proxy y certificados.
10. Diferenciar exit codes de programas y errores de cmdlets.

Resumen

Los errores de Codex en Windows PowerShell suelen ser de instalación, sintaxis de shell, rutas/encoding o red/autenticación. Usa arrays de argumentos, -LiteralPath, verificación UTF-8 y manejo explícito de errores para hacerlo más estable.