Codex Windows 安装与排错：原生 PowerShell、WSL、沙箱权限和路径问题

Codex 在 Windows 上最常见的问题往往不是模型能力，而是运行环境：命令到底装在 Windows 还是 WSL、仓库路径属于哪个文件系统、Git 使用哪套凭据、终端继承了哪些环境变量，以及沙箱允许写入哪里。原生 PowerShell 和 WSL 都能成为可用入口，但不要在同一个任务中随意混用两套 Node、Git、Python 和路径。本文先帮助你选择路线，再分别完成安装、登录、仓库验证和故障定位。 Codex 的安装方式、模型和具体审批界面可能继续更新。文中的诊断原则可以长期复用，安装命令则应与 OpenAI Codex 官方文档当前页面核对。

先选原生 Windows 还是 WSL

原生 PowerShell 更适合：

项目本来就在 C:\Work 等 Windows 目录；
依赖 Visual Studio、MSBuild、PowerShell 或 Windows SDK；
测试必须调用 Windows 程序；
团队命令和部署脚本以 PowerShell 为主。 WSL 更适合：
项目生产环境是 Linux；
依赖 Bash、GNU 工具、Docker Linux 工作流；
包含对大小写、权限位或符号链接敏感的代码；
团队 README 主要提供 Linux 命令。选择原则很简单：让 Codex 与项目主要工具链处在同一环境。不要因为某条命令在 WSL 更短，就把 Windows 仓库、Windows Node 和 WSL Git 混在一次任务里。

盘点电脑上已有的两套环境

在 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

再进入 WSL：

1
2
3


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

在 WSL 内运行：

1
2
3
4
5
6


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

两边输出不同并不是错误，它们本来就是独立环境。问题出在用户以为升级了一个，实际运行的却是另一个。

原生 PowerShell 安装前的准备

先确认 64 位 PowerShell 和 Node 可用：

1
2
3
4


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

如果使用 npm 安装 Codex，执行官方当前安装命令。常见形式是：

1

npm install -g @openai/codex

安装后：

1
2
3


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

如果官方已经提供 Windows 安装器或其他推荐方式，优先采用官方最新说明。不要同时用 npm、独立二进制和多个包管理器安装三份 Codex。查看命令解析到的真实路径：

1
2


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

原生登录与凭据

启动登录：

1

codex login

浏览器登录完成后，回到同一 Windows 用户的终端验证。不要用管理员 PowerShell 登录，再用普通用户运行；两者的用户目录和凭据可能不同。如果使用 API Key，按官方支持方式设置。临时环境变量只在当前进程及其子进程生效：

1
2


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

不要把真实 Key写进 PowerShell Profile、仓库脚本或命令历史。测试结束后关闭终端，必要时撤销该 Key。登录失败时先确认系统时间、浏览器回调、防火墙和代理，不要反复删除整个配置目录。

在原生 Windows 打开仓库

使用绝对路径：

1
2
3
4


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

路径包含空格时，-LiteralPath 比手工转义更稳妥。启动后先让 Codex 执行只读检查：

1

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

它回报的路径必须与 git rev-parse --show-toplevel 一致。若错误，退出会话，在正确目录重新启动。

WSL 安装的正确位置

在 PowerShell 进入指定发行版：

1

wsl -d Ubuntu

在 WSL 中安装 Node 和 Codex。不要调用 /mnt/c/Program Files/nodejs/npm.cmd 来假装完成 Linux 安装。验证全部命令来自 Linux 路径：

1
2
3
4


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

再执行官方安装命令和登录：

1
2


npm install -g @openai/codex
codex login

WSL 的登录状态通常与 Windows 原生状态分开。即使同一浏览器账户完成授权，也要在目标环境单独验证。

WSL 仓库放在 /home 还是 /mnt/c

Linux 工具链项目优先放在 WSL 自己的文件系统，例如：

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 便于 Windows 程序直接访问，但大量小文件、权限位、符号链接、文件监听和大小写行为可能不同。如果项目必须同时被 Visual Studio 和 WSL 使用，可以留在 Windows 盘，但应测试：

npm/pnpm 安装速度；
Git 文件权限变化；
Watcher 是否漏事件；
符号链接是否创建成功；
测试是否依赖大小写；
Docker bind mount 性能。不要从 Windows 和 WSL 同时运行两个格式化器修改同一工作树。

Windows 路径与 WSL 路径互换

PowerShell 路径：

1

C:\Work\my-project

在 WSL 中通常对应：

1

/mnt/c/Work/my-project

使用 wslpath 转换比字符串替换可靠：

1
2


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

不要把 C:\... 路径直接传给 Linux 原生命令，也不要把 /home/... 传给普通 Windows 程序并期待它自动识别。 Codex 工具调用中的路径必须属于启动它的环境。

Git 凭据为何一边能拉取、一边不能

PowerShell 的 Git 可能使用 Git Credential Manager；WSL Git 可能使用 SSH Agent、Linux Credential Store 或没有配置任何 Helper。 Windows 检查：

1
2


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

WSL 检查：

1
2
3


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

不要为了修复 WSL 拉取失败而把 Personal Access Token写进 Remote URL。它会出现在 .git/config、日志和进程参数中。更稳妥的方法是在选定环境配置 GitHub CLI、SSH Key 或受支持的 Credential Helper。

CRLF 与“所有文件都被修改”

Windows 常用 CRLF，Linux 常用 LF。如果 .gitattributes 不明确，跨环境切换可能让 Git认为大量文件变化。先看：

1
2
3


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

仓库应通过 .gitattributes 声明策略，例如：

1
2
3


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

实际规则要与团队一致。不要在有用户未提交改动时运行批量重新规范化命令。如果 Codex 刚启动就看到几百个变化，先停止写入，确认是换行、权限位还是生成文件，而不是让 Agent继续“修复”。

PowerShell 引号与 Bash 引号不同

PowerShell 中单引号不展开变量，双引号会展开：

1
2
3


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

Bash 的规则相似但并不完全相同，管道对象模型也不同。容易出错的内容包括：

JSON 中的双引号；
正则表达式中的 $；
Git 提交信息中的反引号；
带空格的路径；
原生命令参数与 PowerShell 参数绑定；
curl 在旧 PowerShell 中可能是别名。让 Codex 编写命令时明确说明目标 Shell，例如“在 PowerShell 7 中运行”，不要只说“Windows 命令”。

沙箱与审批不是 Windows UAC

Codex 的沙箱决定本次 Agent 可以读取、写入或执行哪些内容；Windows UAC 和 NTFS ACL 决定操作系统层面权限。两者是不同层次。即使程序以管理员身份运行，Codex 仍可能按沙箱策略拒绝某些写入。相反，沙箱允许执行的命令也不能突破 NTFS 权限。启动任务前确认：

工作区根目录是否正确；
是否只允许写入仓库；
网络访问是否必要；
命令执行是否需要审批；
用户配置目录是否在范围外；
是否会触碰其他挂载盘。不要为了省去一次提示就永久使用最高权限模式。高权限应对应清晰任务和可验证目标。

“Access denied” 的分层排查

先取得完整错误路径，不要只看最后一句。检查文件属性与 ACL：

1
2


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

检查是否被其他进程占用：

1

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

再判断是：

Codex 沙箱范围；
Windows 文件权限；
文件只读属性；
防病毒软件拦截；
文件锁；
路径过长或字符问题；
WSL 挂载权限映射。不要直接关闭 Defender 或给整个磁盘 Everyone Full Control。

Node、Python 和包管理器冲突

Windows 可能同时存在 winget Node、nvm-windows、Volta 和项目内工具；WSL 又有一套 nvm 或系统 Node。记录真实解析路径：

1

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

WSL：

1

type -a node pnpm python3 pip3

在让 Codex 安装依赖前，阅读仓库的 packageManager、锁文件、.nvmrc、.python-version 或工具配置。同时出现 package-lock.json、pnpm-lock.yaml 和 yarn.lock 时，不要让 Agent猜测包管理器，应先查项目文档和 Git 历史。

Docker Desktop 与 WSL

原生 PowerShell 和 WSL 都可能调用 Docker Desktop，但上下文和路径挂载方式不同。检查：

1
2
3


docker context show
docker version
docker compose version

WSL 中也运行相同命令，确认连接到预期引擎。 Compose 文件中的 Windows 路径、WSL 路径和 named volume 不可随意互换。遇到权限问题时先运行 docker compose config 查看解析结果。不要把 Docker Socket 暴露给不可信容器或 Agent。能访问 Docker Daemon 通常意味着可以获得宿主机高权限。

代理和 TLS 错误

企业网络中，浏览器能登录不代表 npm、Git 和 Codex CLI 都能访问外网。 PowerShell 查看代理变量：

1

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

Git 查看代理：

1

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

WSL 环境变量与 Windows 不自动同步。分别配置，并让 NO_PROXY 包含确实需要直连的本地地址。不要使用关闭 TLS 验证作为长期解决方案。应安装企业 CA 或让网络管理员提供正确代理配置。

任务开始前保存基线

无论使用哪种环境，都先运行：

1
2
3


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

告诉 Codex哪些改动属于用户、哪些文件可以修改、必须运行什么测试。完成后至少检查：

1
2
3


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

高风险任务还应运行项目测试和构建。不要用“Codex说完成了”代替 Git diff 与测试结果。

常见症状速查

PowerShell 找不到 codex

重启终端，检查 npm config get prefix 和 Get-Command codex，确认没有只安装在 WSL。

WSL 中 codex 指向 .cmd

说明 PATH 混入 Windows npm 全局目录。清理 PATH，并在 WSL 内安装 Linux 版本。

登录成功后仍提示未认证

确认运行用户和环境与登录时相同。管理员终端、普通终端、Windows 和 WSL 各自可能有独立配置。

Git 显示权限位全部变化

检查 core.fileMode、仓库位置和 WSL 挂载行为。先理解变化，不要直接提交。

测试在 PowerShell 失败、WSL 成功

检查 Shell 脚本、路径分隔符、环境变量语法和依赖二进制。根据生产目标选择主环境，而不是维护两套偶然可用流程。

Codex 请求访问工作区外目录

判断该目录是否确实是构建缓存或 SDK。若不是任务所需，拒绝并让它改用仓库内临时目录。