开发工具

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

比较 Codex CLI 在 Windows 原生 PowerShell 与 WSL 中的使用方式，覆盖安装登录、Git 凭据、工作目录、CRLF、环境变量、沙箱审批和常见权限错误。

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' }

再判断是：

  1. Codex 沙箱范围；
  2. Windows 文件权限；
  3. 文件只读属性；
  4. 防病毒软件拦截；
  5. 文件锁；
  6. 路径过长或字符问题；
  7. 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。若不是任务所需，拒绝并让它改用仓库内临时目录。

推荐的稳定组合

Windows/.NET/PowerShell 项目：代码放在 NTFS，使用原生 Codex、Windows Git 和 PowerShell 7。 Linux 服务/Node/Python 项目：代码放在 WSL ~/src，使用 WSL Codex、Linux Git 和 Bash。 必须跨两边的项目：明确唯一的 Git 写入环境，另一边只运行特定工具，并用 .gitattributes 固定换行策略。 最重要的不是哪条路线“更高级”，而是命令、文件系统、凭据和测试是否处于同一个可解释环境。环境一旦稳定，Codex 的排错成本会明显下降。

Windows 与 WSL 延伸文档

Codex 在 PowerShell 中的逐项报错排查

在 Windows PowerShell 里运行 Codex 报错，很多时候不是 Codex 本身坏了，而是 PowerShell、Node、路径、执行策略、网络代理或命令传参方式出了问题。

尤其是从 macOS、Linux 教程复制命令到 Windows 时，很容易把 Bash 写法原样贴进 PowerShell。结果看起来像 Codex 报错，实际是命令根本没有按预期执行。

这篇按排查型思路整理：先确认环境，再处理安装、登录、路径、执行策略、参数转义、中文编码和网络问题。

快速排查清单

遇到 Windows PowerShell 运行 Codex 报错，可以先跑下面几条：

1
2
3
4
5

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

如果 codex --version 能正常输出，说明 Codex 命令至少已经能被系统找到。接下来再看是登录、项目目录、权限还是网络问题。

如果第一步就报错，优先按这个顺序查：

  1. Node.js 是否安装。
  2. npm 全局 bin 目录是否在 PATH 里。
  3. codex 命令是否存在。
  4. 当前 PowerShell 是 Windows PowerShell 5.1 还是 PowerShell 7。
  5. 是否把 Bash 命令直接复制到了 PowerShell。

报错一：codex 不是内部或外部命令

常见提示类似：

1

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

这通常表示系统找不到 codex 可执行文件。

先检查：

1
2
3
4

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

如果 Node 或 npm 不存在，先安装 Node.js LTS。装完后关闭当前 PowerShell，重新打开一个新窗口，再检查版本。

如果 npm 存在，但 codex 不存在，通常需要重新安装 Codex CLI：

1

npm install -g @openai/codex

安装完成后再运行：

1
2

where.exe codex
codex --version

如果安装成功但仍然找不到命令，多半是 npm 全局目录没有进入 PATH。可以查看：

1
2

npm config get prefix
npm bin -g

然后确认对应目录是否在环境变量 Path 中。改完环境变量后，需要重新打开终端。

报错二：npm install -g 失败

安装 Codex 时，Windows 上常见失败原因有三个：

  • Node.js 版本太旧；
  • npm 全局目录权限不够；
  • 公司网络、代理或证书拦截。

先确认版本：

1
2

node -v
npm -v

如果 Node 版本明显过旧，建议升级到当前 LTS 版本，再重新安装。

如果是权限问题，不要第一反应就用管理员终端硬装。更稳妥的做法是让 npm 全局包安装到用户目录，或者使用 Node 版本管理工具。临时用管理员 PowerShell 可以解决一部分问题，但也容易造成后续权限混乱。

如果是网络问题，npm 通常会出现超时、证书、代理相关提示。可以先测试：

1
2
3
4

npm ping
npm config get proxy
npm config get https-proxy
npm config get registry

公司网络下，如果需要代理，要按公司的代理规则配置 npm；如果是证书拦截，不要随便关闭 SSL 校验，先找内部开发环境说明。

报错三：运行脚本被 ExecutionPolicy 拦截

有些教程会让你运行 .ps1 脚本，PowerShell 可能提示：

1

running scripts is disabled on this system

这是 PowerShell 执行策略拦截，不是 Codex 的模型问题。

如果你确认脚本来源可信，可以对当前用户放宽策略：

1

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

也可以只针对这一次运行：

1

powershell -ExecutionPolicy Bypass -File .\script.ps1

但不要把 -ExecutionPolicy Bypass 当万能前缀到处加。它只应该用于你明确知道脚本来源、内容和风险的场景。

如果只是运行 codex 命令，通常不需要改执行策略。

报错四：路径里有空格或中文导致命令失败

Windows 路径常见这种形式：

1

C:\Users\Your Name\Documents\My Project

如果把命令拼成一整串，很容易把路径拆坏。PowerShell 里更稳的做法是：路径单独放进变量，用 & 调用程序，用数组传参。

不要这样写：

1

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

建议这样写：

1
2
3

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

如果要调用一个路径里的可执行文件：

1
2
3
4
5
6

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

& $exe @args

关键点是：不要手工拼接一条很长的命令字符串。每个参数应该作为独立项传给 PowerShell。

报错五：从 Bash 教程复制命令到 PowerShell

很多 Codex、Agent、CLI 工具教程默认写给 macOS 或 Linux。常见 Bash 写法包括：

1
2
3

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

这些不能直接照搬到 PowerShell。

PowerShell 设置环境变量应该写：

1

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

只对当前窗口有效。想长期保存，可以用系统环境变量界面，或者用：

1

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

保存后重新打开 PowerShell。

如果教程里是 .sh 安装脚本，Windows PowerShell 不能直接运行。你需要找项目是否提供 Windows 安装方式，或者在 WSL、Git Bash、PowerShell 7 中按对应说明处理。

报错六：引号、反斜杠和 JSON 参数被 PowerShell 改坏

PowerShell 不是 Bash。它的引号、反引号、变量展开和数组传参规则都不同。

如果命令里包含 JSON、正则、多层引号或很长提示词，不建议写成一行：

1

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

更稳的做法是把复杂内容放进文件：

1
2
3
4

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

然后让工具读取文件，或者用更简单的参数形式。

如果要在 PowerShell 里调用原生命令，优先使用数组：

1
2
3
4
5
6
7
8

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

codex @args

这样比手写转义更少出错。

报错七：中文乱码或文件被写坏

Windows 上最容易让人误判的是编码问题。PowerShell 终端显示乱码，不一定代表文件真的坏了；但如果用错误方式写入中文文件，确实可能把内容写成问号或乱码。

排查时可以用 Python 读取文件：

1

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

如果只是终端显示问题，文件本身可能没事。

如果需要让 Codex 或脚本修改中文 Markdown，建议明确告诉它：

  • 不要用 Set-Content、Out-File 随手写中文；
  • 写文件时指定 UTF-8；
  • 修改后用 UTF-8 读取验证；
  • 不要把 PowerShell 控制台乱码当成文件损坏证据。

这类问题在 Hugo、Markdown、中文路径和多语言文章里尤其常见。

报错八：Codex 登录或 API Key 不生效

Codex 的认证方式可能和你当前使用入口有关。有的场景使用 ChatGPT 登录，有的场景使用 API key，有的插件会沿用本机 Codex 配置。

排查时先确认你到底想用哪种方式：

  • Codex App / CLI 登录；
  • API key；
  • 插件调用本机 Codex；
  • 通过其他工具间接调用 Codex。

如果你设置了环境变量，先检查当前窗口是否能读到：

1

$env:OPENAI_API_KEY

如果为空，说明当前 PowerShell 没拿到这个变量。重新设置，或者关闭终端后重开。

如果你刚刚修改了系统环境变量，但旧窗口里仍然没有变化，这是正常的。PowerShell 进程启动时才读取环境变量，新值不会自动注入已经打开的窗口。

报错九：网络代理、证书或公司防火墙拦截

如果 Codex 能启动，但请求一直失败，常见原因是网络：

  • 公司代理；
  • TLS 证书检查；
  • DNS 解析；
  • 安全软件拦截；
  • 终端没有继承系统代理；
  • npm 和 Codex 使用的代理配置不一致。

可以先做基础网络检查：

1
2

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

如果 DNS 或 443 端口都不通，先处理网络，不要继续改 Codex 配置。

如果浏览器能访问，但 PowerShell 不行，通常要检查代理配置。公司设备上不要随便绕过代理或关闭证书校验，优先看组织提供的开发环境设置。

报错十：Codex 调用命令后判断成功失败不准

如果你让 Codex 在 PowerShell 里跑命令，它可能会混淆两类错误：

  • 原生命令的退出码；
  • PowerShell cmdlet 的异常。

外部程序要看 $LASTEXITCODE：

1
2
3
4

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

PowerShell cmdlet 则应该使用终止错误：

1
2

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

不要用 $LASTEXITCODE 判断 Copy-Item、Move-Item、Remove-Item 这类 cmdlet 是否成功。

建议优先使用 PowerShell 7

Windows 自带的 powershell.exe 通常是 Windows PowerShell 5.1。PowerShell 7 的命令是：

1

pwsh.exe

两者不是一回事。

检查当前版本：

1

$PSVersionTable.PSVersion

如果你经常在 Windows 上运行 Codex、Node、Git、Python、Hugo、npm 等开发工具，建议安装并使用 PowerShell 7。它对现代命令行工具更友好，原生命令传参也更接近开发者预期。

但注意：安装 PowerShell 7 不会自动替换 powershell.exe。你的 VS Code、Windows Terminal、脚本和任务配置里，可能仍然在调用 5.1。

一份更稳的 Codex 启动模板

如果你经常在固定项目里运行 Codex，可以写一个简单的启动脚本，例如 start-codex.ps1：

 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

如果要传参数，用数组：

1
2
3
4
5
6

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

codex @args

这样做的好处是：路径、参数、错误处理都更清楚。后面出问题，也更容易定位是哪一步失败。

排查顺序建议

最后给一个实用顺序：

  1. node -v 和 npm -v 是否正常。
  2. where.exe codex 是否能找到 Codex。
  3. codex --version 是否能运行。
  4. 当前 PowerShell 是 5.1 还是 7。
  5. 项目路径是否包含空格、中文或特殊符号。
  6. 是否复制了 Bash 命令。
  7. 是否存在执行策略拦截。
  8. 登录方式或 API key 是否在当前窗口生效。
  9. 网络、代理和证书是否正常。
  10. 是否把 PowerShell cmdlet 和外部程序的错误判断混在一起。