Development Tools

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

Compares how the Codex CLI is used with Windows native PowerShell versus WSL, covering installation logins, Git credentials, working directories, CRLF, environment variables, sandbox approvals, and common permission errors.

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.

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