1. 为什么 Windows 用户装 Codex 总在第一步卡住如果你在 Windows 上搜过 Codex 的安装方法大概率见过两种极端情况一种是教程里三行命令就装完了另一种是评论区一堆人卡在npm install报错、PowerShell 提示禁止运行脚本、或者装完之后敲codex直接提示找不到命令。这两种情况都是真的区别只在于——前者用的是干净环境加稳定网络后者踩的是 Windows 特有的坑。Codex CLI 本质上是一个跑在终端里的命令行工具它依赖 Node.js 运行时通过 npm 全局安装。这个链路在 macOS 和 Linux 上基本一路顺畅但到了 Windows中间会多出好几层Windows 特色的干扰PowerShell 的执行策略、npm 全局路径没进 PATH、网络下载慢导致超时、终端编码乱码等等。这些问题单独看都不难但新手往往不知道是哪一层出了问题只能对着红色报错发呆。这篇内容就是把这个链路完整拆开讲。从 Node.js 该装哪个版本、PowerShell 需要提前做什么设置、npm 安装慢怎么换源、装完之后怎么验证、到日常使用中几个高频命令怎么用每一步我都会说清楚为什么这么做和不做会怎样。适合完全没接触过命令行的 Windows 新手也适合装过一次但没跑起来、想搞清楚问题出在哪的人。你不需要任何编程基础但需要愿意打开终端敲几条命令。2. 装 Codex 之前先把 Node.js 这层地基打对2.1 Node.js 版本选择为什么别用最新版也别用太老的Codex CLI 对 Node.js 有最低版本要求官方一般建议 Node.js 18 以上实际用下来 20 LTS 或 22 LTS 是最稳的区间。这里有个新手常犯的错去官网首页看到一个大大的最新版按钮就点了结果装了个奇数版本比如 21、23这类版本属于过渡版生命周期短某些依赖包可能还没适配。另一个极端是电脑里早就装了 Node.js 14 甚至更老直接拿来用结果 Codex 安装时报engine不兼容。正确的做法是认准LTS长期支持版。LTS 版本经过更长时间的测试生态兼容性最好。截至我写这篇内容时Node.js 20 LTS 和 22 LTS 都是安全选择。如果你不确定自己装的是哪个版本打开 PowerShell 敲node -v npm -v第一行输出v20.x.x或v22.x.x就对了。如果提示不是内部或外部命令说明 Node.js 根本没装或者没进 PATH往下看。2.2 下载安装 Node.js安装包里那个勾千万别取消去 Node.js 官网下载 Windows 的.msi安装包双击运行。安装过程基本一路 Next但有一个界面必须留意——Tools for Native Modules那个勾选项。很多人习惯性不勾觉得用不上但 Codex 的某些依赖在安装时可能需要编译原生模块缺了这套构建工具就会报node-gyp相关的错。勾上它安装程序会顺带装一套 Python 和 Visual Studio Build Tools虽然多花几分钟但能省掉后面一堆麻烦。另一个关键点是安装路径。默认路径一般是C:\Program Files\nodejs\建议就用默认的别改到中文路径或者带空格的奇怪目录下。Windows 上很多命令行工具对中文路径支持不好这是历史遗留问题能避就避。安装完成后必须重新打开一个 PowerShell 窗口。已经开着的窗口不会自动加载新的环境变量这是新手最容易忽略的一点——装完了在旧窗口里敲node -v还是提示找不到以为装失败了其实只是窗口没刷新。2.3 验证安装PATH 到底通没通重新打开 PowerShell 后再敲一次node -v和npm -v。如果都能正常输出版本号说明 Node.js 这层地基打好了。如果还是提示找不到命令按下面顺序排查打开此电脑右键属性进高级系统设置点环境变量在系统变量里找Path看里面有没有C:\Program Files\nodejs\这一条。没有的话手动加上保存后重开终端。如果 Path 里有但还是不行检查是不是装了多个 Node.js 版本互相打架。用 Windows 的应用和功能搜一下 node把多余的卸载掉只留一个。还有一种情况是装了 nvm-windows 这类版本管理工具但没执行nvm use激活某个版本这时候node命令是空的。敲nvm list看看有没有激活的版本。这三步走完Node.js 的问题基本都能解决。地基稳了后面装 Codex 才不会有莫名其妙的报错。3. PowerShell 这道坎执行策略和编码问题一次说清3.1 禁止运行脚本报错是怎么回事Windows 新手装 Codex 时遇到最多的拦路虎就是 PowerShell 弹出一句红字无法加载文件因为在此系统上禁止运行脚本。这不是 Codex 的问题是 PowerShell 的默认安全策略在起作用。Windows 默认的执行策略是Restricted意思是任何脚本都不许跑包括 npm 安装时自动生成的.ps1包装脚本。解决办法是改执行策略。以管理员身份打开 PowerShell开始菜单搜 PowerShell右键以管理员身份运行敲Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。这条命令的意思是对当前用户允许运行本地脚本但从网络下载的脚本必须有签名。RemoteSigned是微软官方推荐的平衡点比直接设成Unrestricted安全得多。-Scope CurrentUser表示只影响你自己这个账户不动系统全局设置更稳妥。改完之后用普通非管理员PowerShell 敲Get-ExecutionPolicy确认一下输出RemoteSigned就对了。这一步做完npm 安装时的脚本报错基本就消失了。注意不要图省事直接设成Unrestricted那等于对所有脚本敞开大门安全性差很多。RemoteSigned足够日常开发使用。3.2 PowerShell 乱码中文显示成方块怎么修另一个高频问题是终端里中文显示成乱码或者方块。这通常是编码不匹配导致的——PowerShell 默认可能用 GBK 编码而 Codex 输出的内容是 UTF-8。表现就是命令能跑但提示信息里中文全是乱码看着糟心有时候还会影响你判断报错内容。修复方法是把 PowerShell 的编码统一成 UTF-8。在 PowerShell 里敲[Console]::OutputEncoding [System.Text.Encoding]::UTF8 chcp 65001第一行设置控制台输出编码第二行把代码页切到 65001也就是 UTF-8。这两条命令只对当前窗口生效关掉就没了。想永久生效可以把它们写进 PowerShell 的配置文件里。敲notepad $PROFILE打开配置文件如果提示文件不存在先敲New-Item -Path $PROFILE -Type File -Force创建把上面两行粘进去保存。以后每次开 PowerShell 都会自动执行。如果你用的是 Windows Terminal推荐比自带控制台好用太多可以在设置里把默认配置文件改成 PowerShell字体选一个支持中文的等宽字体比如Cascadia Code或JetBrains Mono乱码问题基本绝迹。3.3 终端选择为什么我建议用 Windows Terminal自带的 PowerShell 窗口功能比较基础复制粘贴、多标签、字体渲染都一般。Windows Terminal 是微软后来推出的现代终端支持多标签、分屏、自定义配色对 UTF-8 支持也好。Win11 一般自带Win10 可以去 Microsoft Store 搜Windows Terminal免费装。装好之后把默认终端设成 Windows Terminal默认配置文件设成 PowerShell。这样你以后打开终端就是干净好用的环境省掉很多编码和显示上的小毛病。这一步不是必须的但能明显提升后续使用体验尤其是你要经常跟命令行打交道的话。4. 正式安装 Codex CLI慢和报错都有解4.1 npm 全局安装命令与它背后的逻辑Node.js 和 PowerShell 都准备好之后安装 Codex CLI 本身其实就一条命令npm install -g openai/codex-g是 global 的意思表示全局安装装完之后在任何目录下都能直接敲codex调用。不加-g的话只会装到当前目录的node_modules里出了这个目录就找不到了。这条命令执行时npm 会去官方仓库拉取 Codex 的包和它依赖的一堆东西。国内网络环境下这一步经常卡住或者特别慢因为 npm 默认的仓库地址在国外。表现就是进度条半天不动或者报ETIMEDOUT、network timeout之类的错。4.2 换国内镜像源解决安装慢的根本办法解决下载慢最直接的办法是换 npm 镜像源。国内有几个稳定的镜像比如淘宝的 npmmirror。敲这条命令切换npm config set registry https://registry.npmmirror.com设完之后可以用npm config get registry确认一下输出的是你刚设的地址就对了。然后再跑安装命令速度通常会有质的提升。如果你不想改全局配置比如公司电脑有规定可以只在这一次安装时临时指定源npm install -g openai/codex --registryhttps://registry.npmmirror.com这样只影响这一条命令不改动全局设置。我个人习惯是全局改掉因为后续装别的工具也用得上省事。注意有些镜像源同步官方仓库有延迟如果装的时候提示找不到某个版本可以换回官方源https://registry.npmjs.org再试一次或者等几个小时让镜像同步。4.3 安装卡住或报错时的排查顺序即使换了源偶尔还是会遇到问题。按这个顺序排查基本能定位到原因现象可能原因处理办法进度条长时间不动网络问题或源不稳定换镜像源或加--verbose看卡在哪一步EACCES权限错误没用管理员权限或 npm 目录权限不对用管理员 PowerShell 重试或修复 npm 全局目录权限node-gyp编译失败缺构建工具重装 Node.js 时勾选 Tools for Native Modules404 Not Found镜像源没同步到该版本换回官方源重试装完敲codex找不到命令npm 全局路径没进 PATH见下一节其中装完找不到命令是最常见的收尾问题。npm 全局安装的包会被放到一个特定目录这个目录必须在系统 PATH 里才能直接调用。敲npm config get prefix能看到这个目录Windows 上一般是C:\Users\你的用户名\AppData\Roaming\npm。把这个路径加到系统环境变量的 Path 里重开终端codex命令就能用了。5. 装完之后怎么确认真的能用5.1 版本检查与首次启动安装完成后敲codex --version能输出版本号说明命令已经能被系统识别安装成功。如果提示找不到命令回到上一节检查 PATH。接着敲codex直接启动第一次运行通常会引导你做初始配置比如登录账号或者填入 API 相关的信息。按提示走就行。如果启动时报错把完整报错信息复制下来对照下面几个常见情况提示缺少某个模块可能是安装不完整重新跑一次安装命令。提示配置文件格式错误检查用户目录下的配置文件有没有写错必要时删掉重新生成。启动后立刻退出多半是 Node.js 版本不兼容确认是 20 或 22 LTS。5.2 几个高频命令先混个脸熟Codex CLI 日常用到的命令不多先记住这几个就够开始干活了/model切换使用的模型。不同模型在速度和能力上有差异按任务复杂度选。/compact压缩当前会话的上下文。聊得太长的时候用能省 token 也让模型注意力更集中。/resume恢复之前的会话。不小心关掉终端或者想接着上次继续聊用这个。/help查看所有可用命令。记不住的时候敲这个。这些命令都是在 Codex 交互界面里输入的前面带斜杠。刚开始不用全记住知道有这么几个用到时查一下就行。5.3 一个容易忽略的验证跑个真实小任务光看版本号还不够最好跑一个真实的小任务确认整条链路通畅。比如让 Codex 帮你写一个简单的脚本、解释一段代码或者做一次文件操作。能正常返回结果说明从终端到模型服务这条链路是通的。如果这一步失败问题往往出在账号配置或网络访问上而不是安装本身。这时候重点检查配置信息填得对不对而不是反复重装。6. 那些教程不会告诉你的实操心得6.1 别在中文路径下折腾我见过太多人把项目放在桌面或者我的文档里而这些目录的中文名在某些工具链里会出问题。Codex 本身对路径的容忍度还行但它调用的某些底层工具不一定。养成习惯把工作目录放在纯英文路径下比如D:\projects\这种能避免一大类莫名其妙的报错。6.2 全局包多了之后的管理用久了你会发现 npm 全局装了一堆工具升级、卸载、查版本都得管。几个常用命令npm list -g --depth0 # 列出所有全局包 npm update -g openai/codex # 升级 Codex 到最新版 npm uninstall -g openai/codex # 卸载定期npm update -g一下能拿到新功能和修复。但注意大版本升级偶尔会有破坏性变更升级后如果发现行为不对可以回退到指定版本npm install -g openai/codex版本号。6.3 网络不稳时的应对思路Codex 工作时需要访问模型服务网络不稳会表现为响应慢或者中途断开。这不是安装问题但会影响使用体验。我的经验是如果频繁超时先确认基础网络是否正常再检查是不是代理配置干扰了有些工具会读取系统代理设置。把代理配置理清楚比反复重装有用得多。6.4 遇到报错的通用排查姿势最后分享一个通用思路遇到任何报错先看报错的最后几行那里通常是真正的错误原因前面的都是调用栈。然后把报错信息里的关键词比如某个模块名、某个错误码拿去搜比直接搜整段报错更容易找到答案。Codex 这类工具的用户社区比较活跃你遇到的问题大概率别人也遇到过。装 Codex 这件事说穿了就是把 Node.js、PowerShell、npm 这三层依次理顺。每一层单独看都不复杂难的是新手不知道问题出在哪一层。按这篇的顺序走一遍把每步的验证做扎实后面用起来就顺了。真正开始用之后你会发现安装这点折腾跟它能帮你省下的时间比起来完全不值一提。