Codex on Windows: Native PowerShell vs WSL, Sandbox, and Path Failures

On Windows, Codex usually fails because of the environment: the binary lives in Windows or WSL, the repo sits on a different filesystem, Git uses another credential store, the terminal inherited a different PATH, and the sandbox will not write where you expected.

Native PowerShell and WSL can both work. Do not mix two copies of Node, Git, Python, and paths in one session.

This is a verified rewrite of KnightLi’s Codex Windows troubleshooting guide. Check install commands against current OpenAI Codex docs. The package is @openai/codex; unscoped codex on npm is a different project.

Pick one lane

Native PowerShell fits: code already on C:\Work, Visual Studio / MSBuild / Windows SDK, tests that must call Windows binaries, team scripts in PowerShell.

WSL fits: Linux in production, Bash / GNU tools / Docker Linux workflows, code sensitive to case, permission bits, or symlinks, READMEs written as Linux commands.

Keep Codex on the same side as the project’s main toolchain.

Inventory both environments

PowerShell:

Get-Command codex, node, git -ErrorAction SilentlyContinue
codex --version
node --version
git --version
(Get-Command codex).Source
npm config get prefix

Then WSL:

wsl --status
wsl --list --verbose
command -v codex node git
which node npm codex
file "$(which codex)"

Different versions are normal. The bug is upgrading one copy and running the other. If WSL which codex points at a .cmd, Windows npm leaked into PATH—install a Linux build inside WSL. Do not call /mnt/c/Program Files/nodejs/npm.cmd and call it a Linux install.

Native install and login

$PSVersionTable
[Environment]::Is64BitProcess
npm install -g @openai/codex
Get-Command codex
codex --version
codex login

Log in as the same Windows user that will run Codex. Admin PowerShell and a normal user do not share credential directories. Temporary keys stay in the process:

$env:OPENAI_API_KEY = '<temporary-key>'

Do not put keys in a profile, a repo script, or shell history. New environment variables only appear in a new window.

Open the repo with a literal path:

Set-Location -LiteralPath 'C:\Work\my-project'
git rev-parse --show-toplevel
git status --short
codex

Spaces and non-ASCII names are why -LiteralPath exists. Ask Codex for a read-only report of cwd and branch first; it must match git rev-parse --show-toplevel.

WSL: /home or /mnt/c

Linux toolchains belong on the WSL filesystem (~/src). /mnt/c/... is convenient for Visual Studio, but small-file I/O, permission bits, symlinks, watchers, and case folding all differ.

If both sides must touch the tree, measure npm install time, Git fileMode noise, watcher misses, symlink creation, and case-sensitive tests. Do not run two formatters from Windows and WSL on the same worktree.

Convert paths with wslpath, not string replace. Do not pass C:\... to Linux binaries or /home/... to ordinary Windows programs. Paths in Codex tool calls must belong to the environment that launched it.

Git, line endings, quoting

PowerShell Git often uses Git Credential Manager; WSL Git may use ssh-agent, a Linux helper, or nothing. One side can pull and the other cannot without Codex being involved. Do not paste a PAT into the remote URL.

Windows defaults to CRLF, Linux to LF. Without .gitattributes, crossing environments makes Git think the whole tree changed:

* text=auto
*.sh text eol=lf
*.ps1 text eol=crlf

Match the team. If Codex starts and sees hundreds of dirty files, stop—separate line endings, fileMode, and generated files. Mass permission flips on /mnt/c are usually core.fileMode, not a feature.

PowerShell single quotes do not expand; double quotes do. JSON, $ in regex, paths with spaces, and backticks in commit messages all break easily. In Windows PowerShell 5.1, curl may be an alias for Invoke-WebRequest. Say “run this in PowerShell 7,” not “a Windows command.” Bash export, VAR=value cmd, and piping into bash do not paste into PowerShell.

Sandbox is not UAC

The Codex sandbox decides what this agent session may read, write, or execute. UAC and NTFS ACLs are the OS. Running as admin does not lift the sandbox; a sandbox allow does not pierce NTFS.

Layer an Access denied: sandbox scope, NTFS ACL, read-only bit, antivirus, file lock, long paths, WSL mount mapping. Do not enable the highest privilege mode to skip one prompt, and do not grant Everyone Full Control on a whole volume.

External programs: $LASTEXITCODE. Cmdlets like Copy-Item: terminating errors. Do not mix them.

Other traps

Multiple Node/Python: winget, nvm-windows, Volta, and WSL nvm can all exist. Read packageManager, lockfiles, .nvmrc before letting the agent install. Competing lockfiles mean look at history, not guess.

Docker: PowerShell and WSL may both talk to Docker Desktop with different contexts and bind-mount path rules. Windows paths, WSL paths, and named volumes in Compose are not interchangeable. Access to the Docker daemon is usually host-level privilege.

Proxy: A browser login does not imply npm, Git, or the CLI can reach the network. WSL env vars do not auto-sync from Windows. Disabling TLS checks is not a strategy.

Execution policy: running scripts is disabled is PowerShell policy. Running codex itself usually needs no change; .ps1 files may need RemoteSigned or a one-shot Bypass.

Before a task: git status, current branch, repo root. After: git diff and project tests. “Codex said it finished” is not a review.

A stable pairing

• Windows / .NET / PowerShell: code on NTFS, native Codex, Windows Git, PowerShell 7 (pwsh.exe, not built-in 5.1).
• Linux services / Node / Python: code in WSL ~/src, WSL Codex, Linux Git, Bash.
• Must cross both: one Git writer, the other side only runs specific tools, .gitattributes pins line endings.

The better route is not the fancier one. It is the one where commands, filesystem, credentials, and tests live in a single explainable environment.