Codex Windows installation and troubleshooting: native PowerShell, WSL, sandbox permissions and path issues

The most common problems with Codex on Windows are often not model capabilities, but the running environment: whether the command is installed in Windows or WSL, which file system the repository path belongs to, which set of credentials Git uses, which environment variables are inherited by the terminal, and where the sandbox allows writing. Both native PowerShell and WSL can be used as entry points, but do not mix two sets of Node, Git, Python and paths in the same task. This article first helps you choose a route, and then completes installation, login, repository verification and fault location. Codex’s installation method, model and specific approval interface may continue to be updated. The diagnostic principles in this article can be reused for a long time, and the installation commands should be checked with the current page of the OpenAI Codex official document.

Choose native Windows or WSL first

Native PowerShell is more suitable:

• The project is originally in a Windows directory such as C:\Work;
• Depends on Visual Studio, MSBuild, PowerShell or Windows SDK;
• Testing must call Windows programs;
• Team commands and deployment scripts are mainly PowerShell. WSL is more suitable for:
• The project production environment is Linux;
• Depends on Bash, GNU tools, Docker Linux workflow;
• Contains code that is sensitive to case, permission bits or symbolic links;
• Team README Mainly provides Linux commands. The selection principle is simple: keep Codex in the same environment as the main tool chain of the project. Don’t mix Windows Repository, Windows Node, and WSL Git in one task just because a certain command is shorter in WSL.

Inventory of the two existing environments on the computer

Check in PowerShell:

1
2
3
4
5
6

Get-Command codex -ErrorAction SilentlyContinue
Get-Command node -ErrorAction SilentlyContinue
Get-Command git -ErrorAction SilentlyContinue
codex --version
node --version
git --version

Enter WSL:

1
2
3

wsl --status
wsl --list --verbose
wsl

Run within WSL:

1
2
3
4
5
6

command -v codex
command -v node
command -v git
codex --version
node --version
git --version

It is not an error if the output of the two sides is different, they are inherently independent environments. The problem is that users think one is upgraded, but the other is actually running.

Preparation before native PowerShell installation

First confirm that 64-bit PowerShell and Node are available:

1
2
3
4

$PSVersionTable
[Environment]::Is64BitProcess
node --version
npm --version

If you use npm to install Codex, execute the official current installation command. The common form is:

1

npm install -g @openai/codex

After installation:

1
2
3

Get-Command codex
codex --version
codex --help

If the official Windows installer or other recommended methods have been provided, the latest official instructions will be used first. Don’t install three copies of Codex at the same time using npm, standalone binaries, and multiple package managers. View the real path resolved by the command:

1
2

(Get-Command codex).Source
npm config get prefix

Native login and credentials

Start login:

1

codex login

After the browser login is completed, return to the terminal verification of the same Windows user. Do not log in with an administrator PowerShell and then run it as a normal user; the user directories and credentials may be different. If using API Key, set it according to the official support method. Temporary environment variables only take effect in the current process and its sub-processes:

1
2

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

Do not write the real Key into the PowerShell Profile, repository script or command history. After the test is completed, close the terminal and revoke the Key if necessary. When login fails, first confirm the system time, browser callback, firewall and proxy, and do not delete the entire configuration directory repeatedly.

Open the repository in native Windows

Use absolute path:

1
2
3
4

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

When the path contains spaces, -LiteralPath is more reliable than manual escaping. After starting, let Codex perform a read-only check:

1

报告当前工作目录、Git 分支和未提交文件，不要修改文件。

The path it reports must be consistent with git rev-parse --show-toplevel. If an error occurs, exit the session and restart in the correct directory.

Correct location for WSL installation

Enter the specified distribution in PowerShell:

1

wsl -d Ubuntu

Install Node and Codex in WSL. Do not call /mnt/c/Program Files/nodejs/npm.cmd to pretend to complete the Linux installation. Verify that all commands come from the Linux path:

1
2
3
4

which node
which npm
which codex
file "$(which codex)"

Execute the official installation command and log in:

1
2

npm install -g @openai/codex
codex login

WSL’s login state is usually separate from the Windows native state. Even if authorization is completed with the same browser account, it must be verified separately in the target environment.

Whether the WSL repository is placed in /home or /mnt/c

Linux tool chain projects are prioritized in WSL’s own file system, for example:

1
2
3
4
5

mkdir -p ~/src
cd ~/src
git clone https://github.com/example/project.git
cd project
codex

/mnt/c/Work/project is convenient for Windows Programs access directly, but a large number of small files, permission bits, symbolic links, file listening, and case behavior may differ. If the project must be used by both Visual Studio and WSL, you can stay on the Windows disk, but you should test:

• npm/pnpm installation speed;
• Git file permission changes;
• Watcher leaks events;
• Whether the symbolic link is created successfully;
• Test whether it depends on case;
• Docker bind mount performance. Do not run two formatters simultaneously from Windows and WSL to modify the same working tree.

Windows path and WSL path interchange

PowerShell path:

1

C:\Work\my-project

Usually corresponds in WSL:

1

/mnt/c/Work/my-project

Use wslpath conversion is more reliable than string replacement:

1
2

wslpath 'C:\Work\my-project'
wslpath -w /home/user/src/project

Don’t put Pass the C:\... path directly to the Linux native command. Do not pass /home/... to a normal Windows program and expect it to recognize it automatically. The path in the Codex tool call must belong to the environment in which it is launched.

Why can the Git credentials be pulled on one side but not on the other?

PowerShell’s Git may use Git Credential Manager; WSL Git may use SSH Agent, Linux Credential Store or no Helper is configured. Windows check:

1
2

git config --show-origin --get-all credential.helper
git remote -v

WSL check:

1
2
3

git config --show-origin --get-all credential.helper
git remote -v
ssh -T [email protected]

Do not write the Personal Access Token into the Remote URL to fix WSL pull failure. It will appear in .git/config, logs, and process parameters. A more secure approach is to configure GitHub CLI, SSH Key, or a supported Credential Helper in your selected environment.

CRLF and “All files have been modified”

CRLF is commonly used in Windows and LF is commonly used in Linux. If .gitattributes is unclear, switching across environments may make Git think a large number of files have changed. Look first:

1
2
3

git status --short
git diff --numstat
git config --show-origin --get core.autocrlf

The repository should declare the policy through .gitattributes, for example:

1
2
3

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

The actual rules should be consistent with the team. Do not run bulk renormalization commands when any user has not committed changes. If you see hundreds of changes as soon as Codex is started, stop writing first and confirm whether it is a newline, permission bit or generated file, rather than letting the Agent continue to “repair”.

PowerShell quotes are different from Bash quotes

Single quotes in PowerShell do not expand variables, double quotes do:

1
2
3

$name = 'demo'
Write-Output '$name'
Write-Output "$name"

Bash’s rules are similar but not identical, and the pipeline object model is different. Error-prone content includes:

• Double quotes in JSON;
• $ in regular expressions;
• Backticks in Git commit messages;
• Path with spaces;
• Native command parameters bound to PowerShell parameters;
• curl may be an alias in old PowerShell. Have Codex specify the target shell when writing commands, such as “Run in PowerShell 7”, don’t just say “Windows command”.

Sandbox and approval are not Windows UAC

Codex’s sandbox determines what the Agent can read, write or execute this time; Windows UAC and NTFS ACL determine operating system level permissions. The two are at different levels. Even if the program is run as administrator, Codex may still deny certain writes due to sandbox policy. Conversely, the sandbox allows commands to be executed that cannot breach NTFS permissions. Confirm before starting the task:

• Whether the workspace root directory is correct;
• Whether only writing to the repository is allowed;
• Whether network access is necessary;
• Whether command execution requires approval;
• Whether the user configuration directory is outside the scope;
• Whether it will touch other mounting disks. Don’t use highest privilege mode permanently just to avoid a prompt. High authority should correspond to clear tasks and verifiable goals.

Layered troubleshooting of “Access denied”

Get the complete error path first, don’t just read the last sentence. Check file attributes and ACL:

1
2

Get-Item -LiteralPath '.\target-file'
Get-Acl -LiteralPath '.\target-file' | Format-List

Check whether it is occupied by other processes:

1

Get-Process | Where-Object { $_.ProcessName -match 'node|python|dotnet|code' }

Then judge:

1. Codex sandbox scope;
2. Windows file permissions;
3. File read-only attribute;
4. Anti-virus software interception;
5. File lock;
6. The path is too long or character problem;
7. WSL mount permission mapping. Do not turn off Defender directly or give Everyone Full Control to the entire disk.

Node, Python and package manager conflicts

Windows may have winget Node, nvm-windows, Volta and in-project tools at the same time; WSL also has a set of nvm or system Node. Record the real parsing path:

1

Get-Command node,pnpm,python,pip | Select-Object Name,Source

WSL:

1

type -a node pnpm python3 pip3

Before letting Codex install dependencies, read the packageManager, lock file, .nvmrc, .python-version or tool configuration of the repository. When package-lock.json, pnpm-lock.yaml and yarn.lock appear at the same time, do not let the Agent guess the package manager. You should check the project documentation and Git history first.

Docker Desktop and WSL

Both native PowerShell and WSL may call Docker Desktop, but the context and path mounting methods are different. Check:

1
2
3

docker context show
docker version
docker compose version

Run the same command in WSL to confirm connection to the expected engine. Windows paths, WSL paths, and named volumes in Compose files are not interchangeable. When encountering permission problems, first run docker compose config to view the parsing results. Do not expose Docker Socket to untrusted containers or agents. Having access to the Docker Daemon usually means gaining high privileges on the host machine.

Proxy and TLS errors

In the corporate network, just because the browser can log in does not mean that npm, Git and Codex CLI can access the external network. PowerShell View Agent Variables:

1

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY -ErrorAction SilentlyContinue

Git View Agent:

1

git config --show-origin --get-regexp 'http\..*proxy'

WSL environment variables are not automatically synchronized with Windows. Configure them separately, and let NO_PROXY contain the local address that really needs a direct connection. Do not use turning off TLS verification as a long-term solution. An enterprise CA should be installed or the network administrator should provide the correct proxy configuration.

Save the baseline before starting the task

No matter which environment you use, run first:

1
2
3

git status --short
git branch --show-current
git rev-parse --show-toplevel

Tell Codex which changes belong to the user, which files can be modified, and what tests must be run. After completion check at least:

1
2
3

git status --short
git diff --stat
git diff --check

High risk tasks should also run project tests and builds. Don’t use “Codex says it’s done” instead of Git diff and test results.

Common symptom quick check

PowerShell cannot find codex

Restart the terminal and check npm config get prefix and Get-Command codex to confirm that they are not installed only in WSL.

The codex in WSL points to .cmd

Description PATH is mixed into the Windows npm global directory. Clear PATH and install the Linux version within WSL.

After successful login, it still prompts that it is not authenticated

Confirm that the running user and environment are the same as when you logged in. Administrator terminal, normal terminal, Windows and WSL may each have independent configurations.

Git shows all permission bit changes

Check core.fileMode, repository location and WSL mount behavior. Understand the changes first, don’t commit directly.

Test fails in PowerShell, succeeds in WSL

Check shell scripts, path separators, environment variable syntax and dependent binaries. Choose your primary environment based on your production goals, rather than maintaining two sets of processes that are occasionally available.

Codex requests access to a directory outside the workspace

Determine whether the directory is indeed the build cache or SDK. If it is not required by the task, reject it and let it use the temporary directory in the repository instead.

Recommended stable combination

Windows/.NET/PowerShell project: code in NTFS, using native Codex, Windows Git and PowerShell 7. Linux Service/Node/Python Project: Code is placed in WSL ~/src, using WSL Codex, Linux Git and Bash. Must span projects on both sides: specify a unique Git writing environment, run only specific tools on the other side, and fix the newline strategy with .gitattributes. The most important thing is not which route is “more advanced”, but whether the command, file system, credentials and tests are in the same interpretable environment. Once the environment is stable, Codex’s troubleshooting costs will decrease significantly.

Windows and WSL further reading

• OpenAI Codex official document
• Microsoft WSL file system description
• Git Property document

Step-by-Step Codex Error Troubleshooting in PowerShell

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.