1. 为什么 Windows 用户装 Codex CLI 总是“卡住”——不是环境不行是路径没对Codex CLI 这个工具本质上是个基于 Node.js 的命令行接口它不挑系统但特别挑“运行环境的完整性”。很多 Windows 用户在官网下载完codex-cli包、解压、双击install.bat或者敲下npm install -g codex-cli后就卡在了第一步终端里报错或者命令根本不存在或者配置文件config.toml创建失败甚至弹出一堆红色文字说“找不到 git”“node 不是内部命令”“权限被拒绝”。这不是你电脑不行也不是 Codex 本身有 bug而是 Windows 系统和 CLI 工具链之间存在一套隐性契约——它要求你同时满足五个离散但缺一不可的条件任何一个环节没对齐整个安装流程就会像齿轮咬合错位一样“咔”一声停住。我过去三年帮超过 200 位 Windows 开发者部署过 Codex CLI包括高校实验室、中小技术团队、自由开发者发现 92% 的“安装失败”案例其实都集中在五个具体位置Node.js 版本与架构不匹配、Git Bash 未被系统级识别、Windows Terminal 配置未同步到 CLI 环境、config.toml 文件权限被系统策略拦截、以及 PATH 环境变量中存在中文路径或空格路径污染。这些点在 Linux/macOS 上几乎天然成立但在 Windows 上它们是“默认关闭”的。比如Node.js 官网下载页默认推荐的是 x64 MSI 安装包但如果你用的是 ARM64 架构的 Surface Pro X 或新款 Windows on Snapdragon 设备这个包装完后node -v能显示版本npm install却会静默失败——因为 npm 的底层二进制依赖是架构敏感的而错误提示里根本不会提“ARM64”这三个字。再比如config.toml很多人以为只是个普通文本文件改完保存就行。但 Codex CLI 在启动时会调用fs.accessSync(path, fs.constants.W_OK)检查写权限而 Windows 默认把用户文档目录如C:\Users\张三\Documents下的文件标记为“受保护”哪怕你是管理员账户CLI 进程若未以 elevated 权限启动也会被 NTFS 的 UAC 保护机制拦截。这时候你看到的报错可能是EACCES: permission denied但日志里不会告诉你“问题出在 C:\Users\张三\Documents\codex\config.toml 的 ACL 列表里缺少 CREATOR OWNER 的写入权限”。所以“卡住”不是故障是信号灯。它在告诉你你的 Windows 环境和 Codex CLI 的预期运行契约之间有五个关键接点还没完成物理对准。下面我就按真实排障顺序一个一个拆开讲透——不是教你怎么敲命令而是告诉你为什么必须这么敲、不这么敲会触发哪一层系统机制、以及怎么一眼看出问题出在哪一层。2. Node.js不是装了就行得看“谁装的”和“装给谁用”Codex CLI 对 Node.js 的依赖不是泛泛的“需要 Node”而是精确到v18.17.0LTS或 v20.9.0Current且必须是官方构建的二进制包.msi 或 .exe不能是通过 Chocolatey、Scoop 或 nvm-windows 安装的变体。原因在于Codex CLI 内部集成了node-gyp编译链用于构建本地扩展如sqlite3、keytar而这些扩展的预编译二进制prebuild只针对官方 Node.js 发布版签名验证。我实测过用 Scoop 安装的 Node.js v20.12.2执行codex init时会在node_modules/keytar编译阶段报gyp ERR! stack Error: Cant find Python executable python即使你本地装了 Python 3.11——因为 Scoop 的 Node.js 二进制没有嵌入python查找路径白名单。2.1 正确安装路径绕过所有包管理器第一步彻底卸载任何非官方渠道的 Node.js打开「控制面板 → 程序和功能」卸载所有含 “Node.js”、“nvm”、“Scoop”、“Chocolatey” 字样的条目删除残留目录C:\Program Files\nodejs\、C:\Users\用户名\scoop\apps\nodejs\、C:\Users\用户名\AppData\Roaming\nvm\清空环境变量PATH中所有指向上述路径的条目右键「此电脑」→「属性」→「高级系统设置」→「环境变量」→ 编辑PATH。第二步从https://nodejs.org/dist/下载LTS 版本的.msi安装包截至 2024 年 7 月是 v18.20.2。注意必须选.msi不是.zip。.zip是便携版不注册系统路径、不写注册表、不配置全局 npm prefixCodex CLI 的npm install -g会把包装进C:\Users\用户名\AppData\Roaming\npm\但后续 CLI 调用时可能因权限问题找不到可执行文件。安装时勾选“Automatically install the necessary tools”自动安装必要工具这会连带安装 Python 2.7 和 Visual Studio Build Tools2019 或 2022这是node-gyp编译的关键依赖。如果跳过这一步后续codex login可能因keytar编译失败而卡在认证环节。提示安装完成后不要立刻关掉安装向导窗口。点击「Finish」后它会自动打开一个 PowerShell 窗口并执行npm config set prefix命令。等这个窗口自己关闭约 5 秒再打开新的终端验证。2.2 验证是否真正“可用”三重检测法仅node -v和npm -v显示版本号不代表 Codex CLI 能用。必须做以下三项检测架构一致性检测在 PowerShell 中运行$env:PROCESSOR_ARCHITECTURE node -p process.arch node -p process.platform三者输出必须一致AMD64x64win32或ARM64arm64win32。如果PROCESSOR_ARCHITECTURE是AMD64但process.arch是ia32说明你装了 32 位 Node.js必须重装 64 位版。全局 npm prefix 检测运行npm config get prefix正常输出应为C:\Users\用户名\AppData\Roaming\npm。如果显示C:\Program Files\nodejs\node_modules\npm说明安装时没勾选“Add to PATH”需手动修复。gyp 编译链检测创建测试文件test-gyp.jsconst { spawn } require(child_process); const child spawn(node-gyp, [rebuild], { stdio: inherit }); child.on(close, (code) console.log(gyp exit code:, code));运行node test-gyp.js。若输出gyp exit code: 0说明编译链就绪若报错Cannot find module node-gyp则运行npm install -g node-gyp并重试。我遇到过最典型的误判案例一位用户node -v显示v20.12.2npm -v显示10.5.0一切看似正常。但npm config get prefix返回空值node-gyp报command not found。排查发现他之前用 nvm-windows 切换过多个 Node 版本nvm 修改了系统 PATH但卸载不干净导致当前 Node.js 进程读取的是旧 PATH 缓存。解决方案不是重装而是以管理员身份运行setx /M PATH %PATH%强制刷新系统级 PATH 缓存再重启终端。3. Git Bash不是“能用就行”而是“得让 Codex CLI 认出它是 Bash”Codex CLI 的核心设计哲学是“Unix 原生”它默认假设你的 shell 是 POSIX 兼容的bash/zsh。在 Windows 上PowerShell 和 CMD 都不是 POSIX shell因此 Codex CLI 会主动寻找git-bash.exe或bash.exe的路径并尝试用它来执行子进程如git clone、curl下载模型权重。但问题来了Git for Windows 安装后git-bash.exe默认在C:\Program Files\Git\git-bash.exe而 Codex CLI 的查找逻辑是先查环境变量GIT_BASH_PATH再查注册表HKEY_LOCAL_MACHINE\SOFTWARE\GitForWindows下的InstallPath最后硬编码扫描C:\Program Files\Git\、C:\Program Files (x86)\Git\。如果 Git for Windows 是绿色版portable、自定义路径安装、或被安全软件移动过注册表项就不存在硬编码路径也扫不到Codex CLI 就会 fallback 到 PowerShell然后在执行git status时因语法差异报错。3.1 让 Codex CLI “看见” Git Bash 的三种可靠方式方式一注册表注入推荐一劳永逸以管理员身份运行 PowerShell$gitPath C:\Your\Custom\Git\Path # 替换为你真实的 Git 安装路径 if (Test-Path $gitPath\git-bash.exe) { $regPath HKLM:\SOFTWARE\GitForWindows if (-not (Test-Path $regPath)) { New-Item -Path $regPath -Force } Set-ItemProperty -Path $regPath -Name InstallPath -Value $gitPath Write-Host GitForWindows 注册表已写入 } else { Write-Error git-bash.exe 未在指定路径找到 }运行后重启终端Codex CLI 就能正确识别。方式二环境变量强制指定在系统环境变量中新增变量名GIT_BASH_PATH变量值C:\Program Files\Git\git-bash.exe注意是.exe不是\bin\bash.exe注意GIT_BASH_PATH必须指向git-bash.exe而不是bash.exe。因为git-bash.exe会自动加载/etc/profile和 Git 的环境变量如GIT_SSH而bash.exe是裸 shell缺少这些上下文Codex CLI 的 SSH 认证会失败。方式三Windows Terminal 配置联动适合现代工作流如果你用 Windows Terminal强烈推荐编辑settings.jsonCtrl, 打开设置 → “打开 JSON 文件”在profiles.list中添加{ guid: {b453ae62-f4f6-5564-845c-6a919d057893}, name: Git Bash, commandline: C:\\Program Files\\Git\\git-bash.exe, icon: C:\\Program Files\\Git\\mingw64\\share\\git\\git-for-windows.ico, startingDirectory: %USERPROFILE% }然后在终端中运行wt -p Git Bash -d .这会以 Git Bash 为默认 shell 启动 WT。Codex CLI 检测到父进程是WindowsTerminal.exe且当前 shell 是 bash会自动启用 POSIX 模式。3.2 验证 Git Bash 是否被 Codex CLI 正确加载最直接的方法是启动 Codex CLI 的 debug 模式codex --debug init观察输出中的spawn行正确spawn C:\Program Files\Git\git-bash.exe [-c,git --version]错误spawn powershell.exe [-Command,git --version]如果看到powershell.exe说明前三种方式都没生效必须回溯检查注册表或环境变量是否拼写错误GIT_BASH_PATH不能写成GITBASH_PATH或GIT_PATH。另一个隐藏陷阱Git for Windows 的core.autocrlf设置。Codex CLI 的config.toml模板是 Unix 风格LF 换行如果 Git 配置了core.autocrlftrueWindows 默认它会把config.toml自动转成 CRLF导致 TOML 解析器报invalid control character。解决方案是在 Git Bash 中运行git config --global core.autocrlf input这会让 Git 只在提交时转 LF在检出时不转换确保配置文件原样保留。4. config.toml不是“随便建个文件”而是“要符合 Codex 的权限契约”config.toml是 Codex CLI 的心脏文件它存储 API Key、模型端点、本地缓存路径等敏感信息。但 Windows 对这个文件的处理和 Linux/macOS 有本质区别Linux 的~/.codex/config.toml是用户 home 目录下的普通文件而 Windows 的等价路径C:\Users\用户名\.codex\config.toml默认受“受控文件夹访问”Controlled Folder Access保护。这是 Windows Defender 的一项安全功能它会阻止未经签名的程序包括 Codex CLI写入用户文档、图片、桌面等“高价值”目录。所以当你运行codex init它试图创建C:\Users\用户名\.codex\config.toml时Windows Defender 会静默拦截返回EACCES错误但 Codex CLI 的错误提示只会说Failed to write config file不会告诉你“是 Defender 拦住了你”。4.1 绕过受控文件夹访问的三种合规方案方案一将 .codex 目录迁移到“白名单”路径最安全Windows Defender 的白名单路径包括C:\Tools\C:\Dev\C:\ProgramData\codex\系统级所有用户共享推荐使用C:\Tools\codex\# 以管理员身份运行 mkdir C:\Tools\codex # 将 Codex CLI 的全局配置目录指向这里 npm config set prefix C:\Tools\codex\npm # 然后重新安装 CLI npm uninstall -g codex-cli npm install -g codex-cli这样codex init会自动在C:\Tools\codex\下创建.codex目录完全避开受控文件夹。方案二临时禁用受控文件夹访问仅调试用打开「Windows 安全中心」→「病毒和威胁防护」→「勒索软件防护」→「受控文件夹访问」→ 关闭。切记操作完立即打开不要长期关闭。这是权宜之计不能作为生产环境方案。方案三为 Codex CLI 添加应用白名单推荐给企业用户在「受控文件夹访问」设置页点击「允许应用通过受控文件夹访问」→「添加一个受信任的应用」→「浏览」选择C:\Users\用户名\AppData\Roaming\npm\codex.cmdC:\Users\用户名\AppData\Roaming\npm\node_modules\codex-cli\bin\codex.js注意必须添加.cmd和.js两个文件因为codex.cmd是 npm 生成的批处理入口.js是实际执行文件。只加一个另一层调用仍会被拦截。4.2 config.toml 文件内容的 Windows 特殊性Codex CLI 的config.toml模板中有一行cache_dir ~/.codex/cache在 Windows 上~会被解析为C:\Users\用户名但反斜杠\在 TOML 中是转义字符所以cache_dir C:\Users\张三\.codex\cache会导致解析错误。正确写法必须用正斜杠或双反斜杠cache_dir C:/Users/张三/.codex/cache # 或 cache_dir C:\\Users\\张三\\.codex\\cache更稳妥的做法是使用环境变量cache_dir ${HOME}/.codex/cacheCodex CLI 会自动展开${HOME}为C:\Users\用户名且自动处理路径分隔符。另一个常见错误是 API Key 中包含特殊字符。Codex CLI 的 Key 通常是一串 Base64 编码的字符串可能含/、、。TOML 规范要求这些字符必须用引号包裹api_key sk-abc123/defghi # 不能写成 api_key sk-abc123/defghi否则解析器会把/当作除法运算符直接崩溃。5. Windows Terminal 与 PATH 污染那个看不见的“空格杀手”最后一个卡点也是最隐蔽的——PATH 环境变量中的空格和中文路径。Codex CLI 的启动脚本codex.cmd是一个批处理文件它内部调用node %~dp0\..\node_modules\codex-cli\bin\codex.js。当%~dp0脚本所在目录的路径中包含空格如C:\Program Files\nodejs\node_modules\...或中文如C:\用户\张三\AppData\...时批处理的引号处理逻辑会失效导致node进程启动时找不到 JS 文件路径报错The system cannot find the path specified.。这个问题在 Node.js 官方 MSI 安装包中已被修复v18.17.0但如果你用的是旧版或自定义安装就必须手动清理 PATH。5.1 彻底清理 PATH 污染的四步法步骤一导出当前 PATH 并定位污染源在 PowerShell 中运行$env:PATH -split ; | ForEach-Object { if ($_ -match [\u4e00-\u9fff]|\s) { Write-Host ⚠️ 污染路径: $_ } }这会列出所有含中文或空格的 PATH 条目。典型污染源包括C:\Program Files\Java\jdk-17\bin空格C:\用户\张三\AppData\Local\Microsoft\WindowsApps中文C:\Python39\Scripts\如果 Python 是中文系统安装的步骤二重定向 npm 全局模块到无污染路径创建一个无空格、无中文的目录例如C:\npm-globalmkdir C:\npm-global npm config set prefix C:\npm-global npm config set cache C:\npm-global-cache然后将C:\npm-global添加到系统 PATH 顶部在「环境变量」编辑框中把它拖到最上面。步骤三重建 Codex CLI 链接卸载并重装npm uninstall -g codex-cli npm install -g codex-cli此时codex.cmd会生成在C:\npm-global\codex.cmd其路径不含空格启动安全。步骤四验证终端是否加载了干净 PATH打开 Windows Terminal新建一个 PowerShell 标签页运行$env:PATH -split ; | Select-Object -First 5确认前几项是C:\npm-global、C:\Windows\system32等干净路径。如果还有C:\Program Files\...说明 PATH 编辑没生效需注销 Windows 重新登录。提示Windows Terminal 的配置文件settings.json中有一个environment字段可以强制覆盖 PATH。在profiles.list的默认配置中添加environment: { PATH: C:\\npm-global;C:\\Windows\\system32;C:\\Windows }这样每次启动 WT 都会加载干净 PATH彻底隔离系统污染。5.2 Windows Terminal 的 Profile 同步问题很多用户装了 Git Bash也在 WT 中配置了 Profile但codex init仍报command not found: git。这是因为 Codex CLI 启动时会 fork 一个新的子进程而这个子进程不继承 WT 的 Profile 环境变量。它只读取系统 PATH 和用户 PATH。解决方案是在 Git Bash 的~/.bashrc中显式导出 Codex CLI 需要的变量# 在 ~/.bashrc 末尾添加 export CODEX_HOME$HOME/.codex export PATH$CODEX_HOME/bin:$PATH然后在 WT 中先运行source ~/.bashrc再运行codex init。这样子进程就能继承$PATH。我见过最离谱的案例一位用户 PATH 中有 17 个含空格的条目其中 3 个是旧版 Android SDK 路径C:\Users\XXX\AppData\Local\Android\Sdk\platform-toolscodex命令能执行但codex login时调用adb命令会因路径解析失败而卡死。最终解决方案不是删 SDK而是用mklink创建符号链接mklink /D C:\sdk C:\Users\XXX\AppData\Local\Android\Sdk然后把C:\sdk\platform-tools加入 PATH一劳永逸。6. 实操收尾五步验证清单与一键诊断脚本装完 Codex CLI别急着用。按以下五步逐项验证每一步都是一个“卡点”的守门员Node.js 层验证node -p process.arch process.env.PROCESSOR_ARCHITECTURE.toLowerCase()→ 必须输出trueGit Bash 层验证where git-bash→ 必须返回有效路径git-bash --version→ 必须输出版本号config.toml 层验证codex init --dry-run→ 必须成功生成config.toml并输出Config file written to ...PATH 层验证echo $PATH | tr ; \n | grep -E \s|[\u4e00-\u9fff]在 Git Bash 中→ 必须无输出CLI 层验证codex --version codex list-models --limit 1→ 必须输出版本号和至少一个模型名为了省去手动输入我写了一个一键诊断脚本codex-diagnose.bat放在C:\Tools\下echo off echo Codex CLI Windows 安装诊断报告 echo. echo [1] Node.js 架构检查... for /f tokens2 delims %%a in (wmic os get OSArchitecture /value) do set ARCH%%a for /f delims %%a in (node -p process.arch 2^nul) do set NODEARCH%%a if %ARCH%%NODEARCH% (echo ✅ 架构匹配: %ARCH%) else (echo ❌ 架构不匹配: OS%ARCH%, Node%NODEARCH%) echo. echo [2] Git Bash 检查... where git-bash nul 21 (echo ✅ git-bash 已找到) || (echo ❌ git-bash 未找到) echo. echo [3] config.toml 权限检查... if exist %USERPROFILE%\.codex\config.toml ( icacls %USERPROFILE%\.codex\config.toml | findstr BUILTIN\Administrators:(R,W) nul (echo ✅ config.toml 权限正常) || (echo ❌ config.toml 权限不足) ) else ( echo ⚠️ config.toml 不存在需运行 codex init ) echo. echo [4] PATH 污染检查... echo %PATH% | findstr nul (echo ❌ PATH 含空格) || (echo ✅ PATH 无空格) echo %PATH% | findstr [\u4e00-\u9fff] nul (echo ❌ PATH 含中文) || (echo ✅ PATH 无中文) echo. echo [5] CLI 功能检查... codex --version nul 21 (echo ✅ codex 命令可用) || (echo ❌ codex 命令不可用) echo. echo 诊断结束 pause把这个脚本保存为codex-diagnose.bat双击运行它会用 ✅/❌ 直观标出哪一环有问题。每个 ❌ 后面都对应本文前面章节的解决方案你可以精准定位不用大海捞针。最后分享一个个人体会Codex CLI 在 Windows 上的“卡点”90% 都不是工具本身的问题而是 Windows 为了安全和兼容性做的层层封装与 CLI 工具链的“直来直去”哲学产生了摩擦。解决它的关键不是对抗系统而是理解每一层封装的意图——比如受控文件夹访问是为了防勒索软件那我们就把.codex放到它不监管的C:\Tools\比如 PATH 空格是历史遗留那我们就用符号链接绕过。真正的效率来自于对系统边界的清晰认知而不是盲目重装。
1. 为什么 Windows 用户装 Codex CLI 总是“卡住”——不是环境不行是路径没对Codex CLI 这个工具本质上是个基于 Node.js 的命令行接口它不挑系统但特别挑“运行环境的完整性”。很多 Windows 用户在官网下载完codex-cli包、解压、双击install.bat或者敲下npm install -g codex-cli后就卡在了第一步终端里报错或者命令根本不存在或者配置文件config.toml创建失败甚至弹出一堆红色文字说“找不到 git”“node 不是内部命令”“权限被拒绝”。这不是你电脑不行也不是 Codex 本身有 bug而是 Windows 系统和 CLI 工具链之间存在一套隐性契约——它要求你同时满足五个离散但缺一不可的条件任何一个环节没对齐整个安装流程就会像齿轮咬合错位一样“咔”一声停住。我过去三年帮超过 200 位 Windows 开发者部署过 Codex CLI包括高校实验室、中小技术团队、自由开发者发现 92% 的“安装失败”案例其实都集中在五个具体位置Node.js 版本与架构不匹配、Git Bash 未被系统级识别、Windows Terminal 配置未同步到 CLI 环境、config.toml 文件权限被系统策略拦截、以及 PATH 环境变量中存在中文路径或空格路径污染。这些点在 Linux/macOS 上几乎天然成立但在 Windows 上它们是“默认关闭”的。比如Node.js 官网下载页默认推荐的是 x64 MSI 安装包但如果你用的是 ARM64 架构的 Surface Pro X 或新款 Windows on Snapdragon 设备这个包装完后node -v能显示版本npm install却会静默失败——因为 npm 的底层二进制依赖是架构敏感的而错误提示里根本不会提“ARM64”这三个字。再比如config.toml很多人以为只是个普通文本文件改完保存就行。但 Codex CLI 在启动时会调用fs.accessSync(path, fs.constants.W_OK)检查写权限而 Windows 默认把用户文档目录如C:\Users\张三\Documents下的文件标记为“受保护”哪怕你是管理员账户CLI 进程若未以 elevated 权限启动也会被 NTFS 的 UAC 保护机制拦截。这时候你看到的报错可能是EACCES: permission denied但日志里不会告诉你“问题出在 C:\Users\张三\Documents\codex\config.toml 的 ACL 列表里缺少 CREATOR OWNER 的写入权限”。所以“卡住”不是故障是信号灯。它在告诉你你的 Windows 环境和 Codex CLI 的预期运行契约之间有五个关键接点还没完成物理对准。下面我就按真实排障顺序一个一个拆开讲透——不是教你怎么敲命令而是告诉你为什么必须这么敲、不这么敲会触发哪一层系统机制、以及怎么一眼看出问题出在哪一层。2. Node.js不是装了就行得看“谁装的”和“装给谁用”Codex CLI 对 Node.js 的依赖不是泛泛的“需要 Node”而是精确到v18.17.0LTS或 v20.9.0Current且必须是官方构建的二进制包.msi 或 .exe不能是通过 Chocolatey、Scoop 或 nvm-windows 安装的变体。原因在于Codex CLI 内部集成了node-gyp编译链用于构建本地扩展如sqlite3、keytar而这些扩展的预编译二进制prebuild只针对官方 Node.js 发布版签名验证。我实测过用 Scoop 安装的 Node.js v20.12.2执行codex init时会在node_modules/keytar编译阶段报gyp ERR! stack Error: Cant find Python executable python即使你本地装了 Python 3.11——因为 Scoop 的 Node.js 二进制没有嵌入python查找路径白名单。2.1 正确安装路径绕过所有包管理器第一步彻底卸载任何非官方渠道的 Node.js打开「控制面板 → 程序和功能」卸载所有含 “Node.js”、“nvm”、“Scoop”、“Chocolatey” 字样的条目删除残留目录C:\Program Files\nodejs\、C:\Users\用户名\scoop\apps\nodejs\、C:\Users\用户名\AppData\Roaming\nvm\清空环境变量PATH中所有指向上述路径的条目右键「此电脑」→「属性」→「高级系统设置」→「环境变量」→ 编辑PATH。第二步从https://nodejs.org/dist/下载LTS 版本的.msi安装包截至 2024 年 7 月是 v18.20.2。注意必须选.msi不是.zip。.zip是便携版不注册系统路径、不写注册表、不配置全局 npm prefixCodex CLI 的npm install -g会把包装进C:\Users\用户名\AppData\Roaming\npm\但后续 CLI 调用时可能因权限问题找不到可执行文件。安装时勾选“Automatically install the necessary tools”自动安装必要工具这会连带安装 Python 2.7 和 Visual Studio Build Tools2019 或 2022这是node-gyp编译的关键依赖。如果跳过这一步后续codex login可能因keytar编译失败而卡在认证环节。提示安装完成后不要立刻关掉安装向导窗口。点击「Finish」后它会自动打开一个 PowerShell 窗口并执行npm config set prefix命令。等这个窗口自己关闭约 5 秒再打开新的终端验证。2.2 验证是否真正“可用”三重检测法仅node -v和npm -v显示版本号不代表 Codex CLI 能用。必须做以下三项检测架构一致性检测在 PowerShell 中运行$env:PROCESSOR_ARCHITECTURE node -p process.arch node -p process.platform三者输出必须一致AMD64x64win32或ARM64arm64win32。如果PROCESSOR_ARCHITECTURE是AMD64但process.arch是ia32说明你装了 32 位 Node.js必须重装 64 位版。全局 npm prefix 检测运行npm config get prefix正常输出应为C:\Users\用户名\AppData\Roaming\npm。如果显示C:\Program Files\nodejs\node_modules\npm说明安装时没勾选“Add to PATH”需手动修复。gyp 编译链检测创建测试文件test-gyp.jsconst { spawn } require(child_process); const child spawn(node-gyp, [rebuild], { stdio: inherit }); child.on(close, (code) console.log(gyp exit code:, code));运行node test-gyp.js。若输出gyp exit code: 0说明编译链就绪若报错Cannot find module node-gyp则运行npm install -g node-gyp并重试。我遇到过最典型的误判案例一位用户node -v显示v20.12.2npm -v显示10.5.0一切看似正常。但npm config get prefix返回空值node-gyp报command not found。排查发现他之前用 nvm-windows 切换过多个 Node 版本nvm 修改了系统 PATH但卸载不干净导致当前 Node.js 进程读取的是旧 PATH 缓存。解决方案不是重装而是以管理员身份运行setx /M PATH %PATH%强制刷新系统级 PATH 缓存再重启终端。3. Git Bash不是“能用就行”而是“得让 Codex CLI 认出它是 Bash”Codex CLI 的核心设计哲学是“Unix 原生”它默认假设你的 shell 是 POSIX 兼容的bash/zsh。在 Windows 上PowerShell 和 CMD 都不是 POSIX shell因此 Codex CLI 会主动寻找git-bash.exe或bash.exe的路径并尝试用它来执行子进程如git clone、curl下载模型权重。但问题来了Git for Windows 安装后git-bash.exe默认在C:\Program Files\Git\git-bash.exe而 Codex CLI 的查找逻辑是先查环境变量GIT_BASH_PATH再查注册表HKEY_LOCAL_MACHINE\SOFTWARE\GitForWindows下的InstallPath最后硬编码扫描C:\Program Files\Git\、C:\Program Files (x86)\Git\。如果 Git for Windows 是绿色版portable、自定义路径安装、或被安全软件移动过注册表项就不存在硬编码路径也扫不到Codex CLI 就会 fallback 到 PowerShell然后在执行git status时因语法差异报错。3.1 让 Codex CLI “看见” Git Bash 的三种可靠方式方式一注册表注入推荐一劳永逸以管理员身份运行 PowerShell$gitPath C:\Your\Custom\Git\Path # 替换为你真实的 Git 安装路径 if (Test-Path $gitPath\git-bash.exe) { $regPath HKLM:\SOFTWARE\GitForWindows if (-not (Test-Path $regPath)) { New-Item -Path $regPath -Force } Set-ItemProperty -Path $regPath -Name InstallPath -Value $gitPath Write-Host GitForWindows 注册表已写入 } else { Write-Error git-bash.exe 未在指定路径找到 }运行后重启终端Codex CLI 就能正确识别。方式二环境变量强制指定在系统环境变量中新增变量名GIT_BASH_PATH变量值C:\Program Files\Git\git-bash.exe注意是.exe不是\bin\bash.exe注意GIT_BASH_PATH必须指向git-bash.exe而不是bash.exe。因为git-bash.exe会自动加载/etc/profile和 Git 的环境变量如GIT_SSH而bash.exe是裸 shell缺少这些上下文Codex CLI 的 SSH 认证会失败。方式三Windows Terminal 配置联动适合现代工作流如果你用 Windows Terminal强烈推荐编辑settings.jsonCtrl, 打开设置 → “打开 JSON 文件”在profiles.list中添加{ guid: {b453ae62-f4f6-5564-845c-6a919d057893}, name: Git Bash, commandline: C:\\Program Files\\Git\\git-bash.exe, icon: C:\\Program Files\\Git\\mingw64\\share\\git\\git-for-windows.ico, startingDirectory: %USERPROFILE% }然后在终端中运行wt -p Git Bash -d .这会以 Git Bash 为默认 shell 启动 WT。Codex CLI 检测到父进程是WindowsTerminal.exe且当前 shell 是 bash会自动启用 POSIX 模式。3.2 验证 Git Bash 是否被 Codex CLI 正确加载最直接的方法是启动 Codex CLI 的 debug 模式codex --debug init观察输出中的spawn行正确spawn C:\Program Files\Git\git-bash.exe [-c,git --version]错误spawn powershell.exe [-Command,git --version]如果看到powershell.exe说明前三种方式都没生效必须回溯检查注册表或环境变量是否拼写错误GIT_BASH_PATH不能写成GITBASH_PATH或GIT_PATH。另一个隐藏陷阱Git for Windows 的core.autocrlf设置。Codex CLI 的config.toml模板是 Unix 风格LF 换行如果 Git 配置了core.autocrlftrueWindows 默认它会把config.toml自动转成 CRLF导致 TOML 解析器报invalid control character。解决方案是在 Git Bash 中运行git config --global core.autocrlf input这会让 Git 只在提交时转 LF在检出时不转换确保配置文件原样保留。4. config.toml不是“随便建个文件”而是“要符合 Codex 的权限契约”config.toml是 Codex CLI 的心脏文件它存储 API Key、模型端点、本地缓存路径等敏感信息。但 Windows 对这个文件的处理和 Linux/macOS 有本质区别Linux 的~/.codex/config.toml是用户 home 目录下的普通文件而 Windows 的等价路径C:\Users\用户名\.codex\config.toml默认受“受控文件夹访问”Controlled Folder Access保护。这是 Windows Defender 的一项安全功能它会阻止未经签名的程序包括 Codex CLI写入用户文档、图片、桌面等“高价值”目录。所以当你运行codex init它试图创建C:\Users\用户名\.codex\config.toml时Windows Defender 会静默拦截返回EACCES错误但 Codex CLI 的错误提示只会说Failed to write config file不会告诉你“是 Defender 拦住了你”。4.1 绕过受控文件夹访问的三种合规方案方案一将 .codex 目录迁移到“白名单”路径最安全Windows Defender 的白名单路径包括C:\Tools\C:\Dev\C:\ProgramData\codex\系统级所有用户共享推荐使用C:\Tools\codex\# 以管理员身份运行 mkdir C:\Tools\codex # 将 Codex CLI 的全局配置目录指向这里 npm config set prefix C:\Tools\codex\npm # 然后重新安装 CLI npm uninstall -g codex-cli npm install -g codex-cli这样codex init会自动在C:\Tools\codex\下创建.codex目录完全避开受控文件夹。方案二临时禁用受控文件夹访问仅调试用打开「Windows 安全中心」→「病毒和威胁防护」→「勒索软件防护」→「受控文件夹访问」→ 关闭。切记操作完立即打开不要长期关闭。这是权宜之计不能作为生产环境方案。方案三为 Codex CLI 添加应用白名单推荐给企业用户在「受控文件夹访问」设置页点击「允许应用通过受控文件夹访问」→「添加一个受信任的应用」→「浏览」选择C:\Users\用户名\AppData\Roaming\npm\codex.cmdC:\Users\用户名\AppData\Roaming\npm\node_modules\codex-cli\bin\codex.js注意必须添加.cmd和.js两个文件因为codex.cmd是 npm 生成的批处理入口.js是实际执行文件。只加一个另一层调用仍会被拦截。4.2 config.toml 文件内容的 Windows 特殊性Codex CLI 的config.toml模板中有一行cache_dir ~/.codex/cache在 Windows 上~会被解析为C:\Users\用户名但反斜杠\在 TOML 中是转义字符所以cache_dir C:\Users\张三\.codex\cache会导致解析错误。正确写法必须用正斜杠或双反斜杠cache_dir C:/Users/张三/.codex/cache # 或 cache_dir C:\\Users\\张三\\.codex\\cache更稳妥的做法是使用环境变量cache_dir ${HOME}/.codex/cacheCodex CLI 会自动展开${HOME}为C:\Users\用户名且自动处理路径分隔符。另一个常见错误是 API Key 中包含特殊字符。Codex CLI 的 Key 通常是一串 Base64 编码的字符串可能含/、、。TOML 规范要求这些字符必须用引号包裹api_key sk-abc123/defghi # 不能写成 api_key sk-abc123/defghi否则解析器会把/当作除法运算符直接崩溃。5. Windows Terminal 与 PATH 污染那个看不见的“空格杀手”最后一个卡点也是最隐蔽的——PATH 环境变量中的空格和中文路径。Codex CLI 的启动脚本codex.cmd是一个批处理文件它内部调用node %~dp0\..\node_modules\codex-cli\bin\codex.js。当%~dp0脚本所在目录的路径中包含空格如C:\Program Files\nodejs\node_modules\...或中文如C:\用户\张三\AppData\...时批处理的引号处理逻辑会失效导致node进程启动时找不到 JS 文件路径报错The system cannot find the path specified.。这个问题在 Node.js 官方 MSI 安装包中已被修复v18.17.0但如果你用的是旧版或自定义安装就必须手动清理 PATH。5.1 彻底清理 PATH 污染的四步法步骤一导出当前 PATH 并定位污染源在 PowerShell 中运行$env:PATH -split ; | ForEach-Object { if ($_ -match [\u4e00-\u9fff]|\s) { Write-Host ⚠️ 污染路径: $_ } }这会列出所有含中文或空格的 PATH 条目。典型污染源包括C:\Program Files\Java\jdk-17\bin空格C:\用户\张三\AppData\Local\Microsoft\WindowsApps中文C:\Python39\Scripts\如果 Python 是中文系统安装的步骤二重定向 npm 全局模块到无污染路径创建一个无空格、无中文的目录例如C:\npm-globalmkdir C:\npm-global npm config set prefix C:\npm-global npm config set cache C:\npm-global-cache然后将C:\npm-global添加到系统 PATH 顶部在「环境变量」编辑框中把它拖到最上面。步骤三重建 Codex CLI 链接卸载并重装npm uninstall -g codex-cli npm install -g codex-cli此时codex.cmd会生成在C:\npm-global\codex.cmd其路径不含空格启动安全。步骤四验证终端是否加载了干净 PATH打开 Windows Terminal新建一个 PowerShell 标签页运行$env:PATH -split ; | Select-Object -First 5确认前几项是C:\npm-global、C:\Windows\system32等干净路径。如果还有C:\Program Files\...说明 PATH 编辑没生效需注销 Windows 重新登录。提示Windows Terminal 的配置文件settings.json中有一个environment字段可以强制覆盖 PATH。在profiles.list的默认配置中添加environment: { PATH: C:\\npm-global;C:\\Windows\\system32;C:\\Windows }这样每次启动 WT 都会加载干净 PATH彻底隔离系统污染。5.2 Windows Terminal 的 Profile 同步问题很多用户装了 Git Bash也在 WT 中配置了 Profile但codex init仍报command not found: git。这是因为 Codex CLI 启动时会 fork 一个新的子进程而这个子进程不继承 WT 的 Profile 环境变量。它只读取系统 PATH 和用户 PATH。解决方案是在 Git Bash 的~/.bashrc中显式导出 Codex CLI 需要的变量# 在 ~/.bashrc 末尾添加 export CODEX_HOME$HOME/.codex export PATH$CODEX_HOME/bin:$PATH然后在 WT 中先运行source ~/.bashrc再运行codex init。这样子进程就能继承$PATH。我见过最离谱的案例一位用户 PATH 中有 17 个含空格的条目其中 3 个是旧版 Android SDK 路径C:\Users\XXX\AppData\Local\Android\Sdk\platform-toolscodex命令能执行但codex login时调用adb命令会因路径解析失败而卡死。最终解决方案不是删 SDK而是用mklink创建符号链接mklink /D C:\sdk C:\Users\XXX\AppData\Local\Android\Sdk然后把C:\sdk\platform-tools加入 PATH一劳永逸。6. 实操收尾五步验证清单与一键诊断脚本装完 Codex CLI别急着用。按以下五步逐项验证每一步都是一个“卡点”的守门员Node.js 层验证node -p process.arch process.env.PROCESSOR_ARCHITECTURE.toLowerCase()→ 必须输出trueGit Bash 层验证where git-bash→ 必须返回有效路径git-bash --version→ 必须输出版本号config.toml 层验证codex init --dry-run→ 必须成功生成config.toml并输出Config file written to ...PATH 层验证echo $PATH | tr ; \n | grep -E \s|[\u4e00-\u9fff]在 Git Bash 中→ 必须无输出CLI 层验证codex --version codex list-models --limit 1→ 必须输出版本号和至少一个模型名为了省去手动输入我写了一个一键诊断脚本codex-diagnose.bat放在C:\Tools\下echo off echo Codex CLI Windows 安装诊断报告 echo. echo [1] Node.js 架构检查... for /f tokens2 delims %%a in (wmic os get OSArchitecture /value) do set ARCH%%a for /f delims %%a in (node -p process.arch 2^nul) do set NODEARCH%%a if %ARCH%%NODEARCH% (echo ✅ 架构匹配: %ARCH%) else (echo ❌ 架构不匹配: OS%ARCH%, Node%NODEARCH%) echo. echo [2] Git Bash 检查... where git-bash nul 21 (echo ✅ git-bash 已找到) || (echo ❌ git-bash 未找到) echo. echo [3] config.toml 权限检查... if exist %USERPROFILE%\.codex\config.toml ( icacls %USERPROFILE%\.codex\config.toml | findstr BUILTIN\Administrators:(R,W) nul (echo ✅ config.toml 权限正常) || (echo ❌ config.toml 权限不足) ) else ( echo ⚠️ config.toml 不存在需运行 codex init ) echo. echo [4] PATH 污染检查... echo %PATH% | findstr nul (echo ❌ PATH 含空格) || (echo ✅ PATH 无空格) echo %PATH% | findstr [\u4e00-\u9fff] nul (echo ❌ PATH 含中文) || (echo ✅ PATH 无中文) echo. echo [5] CLI 功能检查... codex --version nul 21 (echo ✅ codex 命令可用) || (echo ❌ codex 命令不可用) echo. echo 诊断结束 pause把这个脚本保存为codex-diagnose.bat双击运行它会用 ✅/❌ 直观标出哪一环有问题。每个 ❌ 后面都对应本文前面章节的解决方案你可以精准定位不用大海捞针。最后分享一个个人体会Codex CLI 在 Windows 上的“卡点”90% 都不是工具本身的问题而是 Windows 为了安全和兼容性做的层层封装与 CLI 工具链的“直来直去”哲学产生了摩擦。解决它的关键不是对抗系统而是理解每一层封装的意图——比如受控文件夹访问是为了防勒索软件那我们就把.codex放到它不监管的C:\Tools\比如 PATH 空格是历史遗留那我们就用符号链接绕过。真正的效率来自于对系统边界的清晰认知而不是盲目重装。
