Windows PowerShell Codex errors: install, login, paths, and argument troubleshooting

When Codex fails in Windows PowerShell, the root cause is often not Codex itself. It may be Node.js, npm, PATH, execution policy, quoting, environment variables, proxy settings, or PowerShell argument passing.

This guide walks through the most common errors and the order to debug them.

Quick Checklist

Start here:

1
2
3
4
5

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

If codex --version works, Codex is available. Then look at login, project path, permissions, or network issues. If it fails, check Node, npm global paths, and the installed Codex CLI first.

Error 1: codex Is Not Recognized

Common message:

1

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

Check:

1
2
3
4

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

If Node.js or npm is missing, install the Node.js LTS version, then open a new PowerShell window. If npm exists but codex does not, reinstall:

1

npm install -g @openai/codex

Then:

1
2

where.exe codex
codex --version

If the command is still missing, the npm global bin directory is probably not in PATH.

Error 2: npm install -g Fails

Common causes:

• old Node.js version;
• npm global directory permission issue;
• company proxy or certificate interception.

Check:

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

Do not disable SSL verification casually. On managed company devices, follow the internal development environment guide.

Error 3: ExecutionPolicy Blocks Scripts

If PowerShell says scripts are disabled:

1

running scripts is disabled on this system

For trusted scripts, you can set the current user policy:

1

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Or run a trusted script once:

1

powershell -ExecutionPolicy Bypass -File .\script.ps1

Do not add -ExecutionPolicy Bypass everywhere. It is only for trusted scripts you understand.

Error 4: Paths With Spaces or Chinese Characters

Avoid building one long command string.

Instead of:

1

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

Use:

1
2
3

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

When calling an executable path:

1
2
3
4
5
6

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

& $exe @args

Each argument should be its own array item.

Error 5: Copying Bash Commands Into PowerShell

Bash examples such as:

1
2
3

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

are not PowerShell commands.

PowerShell environment variable syntax:

1

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

To persist it for the user:

1

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

Open a new terminal afterward.

Error 6: Quotes, Backslashes, or JSON Arguments Break

Do not hand-escape complex JSON in a one-line command:

1

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

Prefer files or structured objects:

1
2
3
4

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

For native commands, use arrays:

1
2
3
4
5
6
7
8

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

codex @args

Error 7: Chinese Text Looks Garbled or Files Are Corrupted

PowerShell console mojibake does not always mean the file is broken. Verify with UTF-8 reads:

1

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

When Codex or scripts modify Chinese Markdown, ask them to write UTF-8 explicitly and verify after writing. Do not treat terminal display alone as proof of corruption.

Error 8: Codex Login or API Key Does Not Work

First identify the intended auth mode:

• Codex app or CLI login;
• API key;
• plugin using local Codex;
• another tool calling Codex.

Check whether the current session sees the variable:

1

$env:OPENAI_API_KEY

If you just changed system environment variables, open a new PowerShell window.

Error 9: Proxy, Certificates, or Firewall

If Codex starts but requests fail, test the network:

1
2

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

If DNS or port 443 fails, fix network access first. If the browser works but PowerShell fails, check terminal proxy settings and company certificate policy.

Error 10: Success and Failure Are Judged Incorrectly

Native programs use $LASTEXITCODE:

1
2
3
4

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

PowerShell cmdlets use terminating errors:

1
2

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

Do not use $LASTEXITCODE to check Copy-Item, Move-Item, or Remove-Item.

Prefer PowerShell 7

powershell.exe is usually Windows PowerShell 5.1. PowerShell 7 is:

1

pwsh.exe

Check:

1

$PSVersionTable.PSVersion

Installing PowerShell 7 does not replace powershell.exe. Check your Windows Terminal, VS Code, and task settings.

A Safer Codex Startup Template

 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

With arguments:

1
2
3
4
5
6

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

codex @args

Suggested Debug Order

1. Check node -v and npm -v.
2. Check where.exe codex.
3. Run codex --version.
4. Confirm PowerShell 5.1 or 7.
5. Check paths with spaces or non-ASCII characters.
6. Check whether you copied Bash syntax.
7. Check execution policy.
8. Check login or API key in the current session.
9. Check proxy and certificate settings.
10. Separate native program exit codes from PowerShell cmdlet errors.

Summary

Most Windows PowerShell Codex errors fall into four buckets: installation, shell syntax, paths/encoding, and network/authentication. Debug them in order before reinstalling everything. Use argument arrays, -LiteralPath, UTF-8 verification, and explicit error handling to make Codex on Windows much more stable.