1. 为什么 Windows 用户值得折腾 Codex CLI
Codex 这个名字最近在开发者圈子里出现的频率越来越高，但很多人第一次听到它的时候会有点懵——它到底是个什么东西？简单说，Codex 是一套面向开发者的命令行 AI 编程助手，可以在终端里直接对话、生成代码、解释报错、重构函数，甚至帮你读懂一个完全陌生的老项目。它最核心的形态就是Codex CLI，一个跑在终端里的交互式工具。
那为什么专门写一篇 Windows 的安装教程？因为 Windows 和 macOS、Linux 的体验差别真的很大。macOS 上你可能三行命令就装完了，Windows 上却要面对 PowerShell 执行策略、Node.js 版本、环境变量、终端编码这一堆坑。我自己第一次在 Windows 上装 Codex CLI 的时候，光是 PowerShell 报“禁止运行脚本”就卡了半小时，后来又遇到中文乱码、npm 全局路径找不到的问题。这些坑在官方文档里往往一笔带过，但对新手来说每一个都能劝退。
这篇内容适合三类人：第一类是刚接触命令行工具、想在 Windows 上把 Codex CLI 跑起来的纯新手；第二类是装到一半卡住了、报错看不懂的中途用户；第三类是想把 Codex 接入自己工作流、顺便了解配置细节的进阶玩家。我会从下载、环境准备、安装、配置到实际使用，把每一步都拆开讲清楚，包括我踩过的坑和对应的解决办法。你不需要有 Linux 经验，只要会用 Windows 的基本操作，跟着走就能跑通。
在正式开始之前，先明确一个概念：Codex CLI 本身是一个 Node.js 包，所以它的安装高度依赖 Node.js 环境。这也是为什么热词里 Node.js 的出现频率那么高。理解了这一层依赖关系，后面很多报错你就能自己推理出原因了。
2. 安装前的环境准备与核心概念
2.1 Node.js 到底是什么，为什么必须先装它
很多人装 Codex CLI 失败，根源不在 Codex 本身，而在 Node.js 没装对。我用一个生活化的类比来解释：Node.js 就像是电脑上的一个“运行引擎”，而 Codex CLI 是跑在这个引擎上的一个“应用”。引擎没装好或者版本太老，应用自然跑不起来。
Node.js 有两个版本线需要区分：LTS（长期支持版）和Current（最新特性版）。对于 Codex CLI 这种工具，我一律建议用 LTS 版本，因为它的稳定性经过更长时间验证，第三方包的兼容性也更好。截至我写这篇内容的时候，Node.js 20.x 和 22.x 都是 LTS 线，选 20 以上的版本基本不会出错。热词里出现的“node.js lts下载”“ubuntu安装node.js 20+”其实都指向同一个诉求——版本要够新，但别追最新。
怎么检查自己有没有装 Node.js？打开 PowerShell，输入：
node -v npm -v如果两条命令都返回了版本号，说明环境已经有了。如果提示“不是内部或外部命令”，那就是没装或者没配好环境变量。这里有个细节：node -v返回的版本号如果低于 18，建议直接升级，因为很多现代 CLI 工具已经不支持更老的版本了。
2.2 PowerShell 的角色和它的“脾气”
Windows 上装命令行工具，绕不开 PowerShell。它是 Windows 自带的终端和脚本环境，Codex CLI 的安装命令、运行命令基本都在这里执行。但 PowerShell 有两个新手最容易踩的坑。
第一个坑是执行策略（Execution Policy）。PowerShell 默认不允许运行脚本，所以你执行某些安装脚本时会看到红色的报错，类似“无法加载文件，因为在此系统上禁止运行脚本”。这不是你操作错了，而是系统的安全默认值。解决办法是临时或永久调整执行策略，后面实操部分我会给具体命令。
第二个坑是中文乱码。热词里“powershell乱码”“powershell乱码解决方法”搜索量很高，说明这是普遍问题。乱码的根源是编码不一致——PowerShell 默认可能用 GBK，而很多工具输出的是 UTF-8。表现出来就是中文变成一堆问号或者方块。这个问题在 Codex CLI 输出中文内容时特别明显，必须提前处理。
2.3 版本选择与下载渠道的取舍
下载 Node.js 有两个主流渠道：官网直接下载安装包，或者用版本管理工具（比如 nvm-windows）。对新手来说，我建议先用官网安装包，因为它是图形化向导，一路下一步就行，出错概率低。等你熟悉了再考虑 nvm 这种可以随时切换版本的工具。
官网下载时注意选Windows Installer (.msi)而不是压缩包，因为 msi 会自动帮你配好环境变量，省去手动配置的麻烦。安装过程中有一个选项叫“Add to PATH”，默认是勾选的，千万别取消，否则装完还是找不到命令。
至于 Codex CLI 本身，它是通过 npm（Node.js 自带的包管理器）安装的，所以你不需要单独去下载 Codex 的安装包。这一点很多人会搞混，以为要去官网下个 exe，其实一条 npm 命令就够了。
3. 手把手实操：从零到跑通 Codex CLI
3.1 第一步：安装 Node.js 并验证环境
先去 Node.js 官网下载 LTS 版本的 Windows Installer。下载完成后双击运行，安装向导里几个关键点：
- 许可协议勾选同意
- 安装路径建议保持默认（通常是
C:\Program Files\nodejs\），避免路径里有中文或空格 - 自定义安装组件那一步，确保“Add to PATH”是选中的
- 后面的原生模块编译工具选项，如果你不打算编译 C++ 扩展，可以不勾，能省不少安装时间
装完之后一定要重启 PowerShell，因为环境变量是在新开的终端里才生效的。重启后输入前面说的node -v和npm -v验证。如果版本号正常显示，这一步就过了。
注意：如果你之前装过旧版本 Node.js，建议先卸载再装新的，避免多个版本冲突导致命令指向混乱。
3.2 第二步：解决 PowerShell 执行策略问题
在装 Codex CLI 之前，先把 PowerShell 的“脾气”捋顺。以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令的意思是：对当前用户，允许运行本地脚本和经过签名的远程脚本。RemoteSigned是一个比较平衡的安全级别，既不像Restricted那样什么都禁，也不像Bypass那样完全不设防。-Scope CurrentUser限定只影响你自己，不动系统全局设置，更稳妥。
执行后会提示你确认，输入Y回车即可。这一步做完，之前那种“禁止运行脚本”的报错就不会再出现了。
3.3 第三步：解决中文乱码
乱码问题要在安装前处理，否则后面 Codex 输出中文你会看得一头雾水。核心思路是把 PowerShell 的输入输出编码统一成 UTF-8。执行：
chcp 65001chcp是 change code page 的缩写，65001 就是 UTF-8 的代码页编号。执行后当前会话的编码就切到 UTF-8 了。但这是临时的，关掉终端就失效。想永久生效，需要改 PowerShell 的配置文件。
先看看配置文件存不存在：
Test-Path $PROFILE如果返回 False，就先创建：
New-Item -Path $PROFILE -ItemType File -Force然后用记事本打开它：
notepad $PROFILE在里面加上这几行：
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8 $OutputEncoding = [System.Text.Encoding]::UTF8 chcp 65001 | Out-Null保存后重启 PowerShell，乱码问题基本就根治了。我实测下来，这套配置对 Codex CLI 输出中文、显示表格都很有帮助。
3.4 第四步：安装 Codex CLI
环境理顺了，安装本身其实很快。在 PowerShell 里执行：
npm install -g @openai/codex这里的-g表示全局安装，装完之后在任何目录都能调用codex命令。安装过程中如果卡住不动，大概率是网络问题——npm 默认的源在国内访问有时候很慢。热词里“node安装codex cli很慢”说的就是这个。解决办法是换一个更快的镜像源：
npm config set registry https://registry.npmmirror.com换完源再重新执行安装命令，速度会明显提升。装完之后验证一下：
codex --version能打印出版本号，就说明安装成功了。
3.5 第五步：首次启动与基础配置
第一次运行codex命令时，它会引导你做初始配置，主要是登录和选择模型。按照提示走就行。如果你在配置过程中遇到“无法加载组织设置”之类的提示，通常是网络或者账号状态的问题，检查一下网络连通性，确认账号正常即可。
配置完成后，你就进入了 Codex CLI 的交互界面。这里先记住几个最常用的命令，热词里也提到了：
| 命令 | 作用 |
|---|---|
/model | 切换使用的模型 |
/compact | 压缩当前对话上下文，节省 token |
/resume | 恢复之前的会话 |
/help | 查看所有可用命令 |
/compact这个命令特别实用。当你和 Codex 聊了很久，上下文越来越长，响应变慢、消耗变大时，执行一次/compact就能把历史对话压缩成摘要，既保留了关键信息，又减轻了负担。我一般在对话超过二三十轮之后就会用一次。
4. 常见报错与排查技巧实录
4.1 安装阶段的典型问题
新手在安装阶段最常遇到的报错，我整理成了一张速查表：
| 报错现象 | 根本原因 | 解决办法 |
|---|---|---|
node 不是内部或外部命令 | Node.js 没装或 PATH 没配 | 重装 Node.js，确保勾选 Add to PATH |
禁止运行脚本 | PowerShell 执行策略限制 | 执行 Set-ExecutionPolicy RemoteSigned |
| 安装卡住不动 | npm 源访问慢 | 切换到国内镜像源 |
EACCES权限错误 | 没有全局安装权限 | 用管理员身份运行 PowerShell |
| 中文显示为乱码 | 编码不一致 | chcp 65001 并配置 PROFILE |
这里重点说一个容易被忽略的点：全局安装路径。有时候npm install -g装完了，但codex命令还是找不到，原因是 npm 的全局 bin 目录没在 PATH 里。你可以用npm config get prefix查看全局路径，然后手动把这个路径下的 bin 目录加到系统环境变量里。
4.2 运行阶段的疑难杂症
装好之后运行阶段也有几个高频问题。比如热词里提到的“codex无法加载组织设置”，这类问题通常和账号配置、网络环境有关，先确认基础网络通畅，再检查配置文件是否完整。
还有一个典型场景是终端被终止，报错信息里出现System.Management.Automation.Utils之类的字样。这多半是 PowerShell 会话本身出了问题，可能是内存占用过高或者某个脚本异常退出。我的处理办法是关掉当前终端，重新开一个干净的会话再试。如果反复出现，检查一下是不是装了某些会干扰终端的插件或脚本。
另外，如果你在 Codex 里让它执行系统命令，偶尔会遇到权限相关的提示。这时候不要盲目用最高权限去跑，先看清楚它要做什么，确认安全再放行。这是使用任何 AI 编程助手都应该养成的习惯。
4.3 我踩过的三个坑和对应经验
第一个坑是装完不重启终端。我第一次装 Node.js 后直接在原来的 PowerShell 里敲node -v，结果一直提示找不到命令，折腾了半天才发现是新环境变量没生效。记住：装完环境类软件，第一件事就是重开终端。
第二个坑是镜像源换了但没生效。有次我换了 npm 源，安装还是慢，后来发现是项目目录下有个.npmrc文件覆盖了全局配置。排查这类问题时，用npm config get registry确认当前实际生效的源是什么。
第三个坑是乱码只解决了一半。我只改了输出编码，没改输入编码，结果在 Codex 里输入中文时又出问题。后来在 PROFILE 里同时设置了[Console]::OutputEncoding和$OutputEncoding才彻底解决。这个细节很多教程都不会提，但实际很关键。
5. 让 Codex CLI 真正好用的进阶配置
5.1 开机自启与环境持久化
如果你希望每次打开 PowerShell 都自动带上正确的编码和路径配置，可以把这些设置写进 PROFILE 文件，前面已经讲过方法。热词里“powershell开机自启脚本”其实也是类似思路——把常用配置固化下来，省得每次手动敲。
对于 Codex CLI 本身，它会在用户目录下生成配置文件，记录你的模型选择、登录状态等信息。这个文件不要随意删除，否则每次都要重新配置。如果你需要在多台机器之间同步配置，可以把这个文件备份出来。
5.2 接入不同模型的思路
Codex CLI 支持切换不同的模型，通过/model命令就能操作。不同模型在代码生成、长上下文理解、响应速度上各有侧重。我的建议是：日常写代码用响应快的，处理复杂重构或者读大项目时切换到上下文能力更强的。具体选哪个，取决于你的实际需求和可用额度。
热词里提到“codex接入deepseek”这类需求，本质上是想把 Codex CLI 作为一个统一的交互入口，后端接不同的模型服务。这种玩法需要对配置文件有一定了解，思路是修改模型端点配置，指向对应的服务地址。操作前建议先备份原配置，改错了能快速回滚。
5.3 日常使用的高效习惯
用了一段时间之后，我总结了几个让 Codex CLI 更顺手的习惯。第一，善用/compact，别让上下文无限膨胀。第二，把常用的提示词存成片段，需要时直接粘贴，比每次重新描述需求快得多。第三，让它解释代码时，尽量把相关文件路径或代码片段一起给它，上下文越完整，回答越准确。
还有一点很重要：不要完全信任它的输出。Codex 生成的代码、命令，尤其是涉及删除、修改系统配置的操作，执行前一定要自己过一遍。它是助手，不是替你做决定的人。这个原则在 Windows 环境下尤其重要，因为很多系统级操作一旦执行错了，恢复起来比较麻烦。
5.4 卸载与重装的正确姿势
万一装崩了想重来，卸载也有讲究。先卸载 Codex CLI：
npm uninstall -g @openai/codex然后如果需要连 Node.js 一起重装，去控制面板卸载 Node.js，再手动检查一下C:\Users\你的用户名\AppData\Roaming\npm和npm-cache这两个目录，把残留清掉，避免旧文件干扰新安装。清理完重启电脑，再按前面的步骤重新装一遍，基本能解决绝大多数“装坏了”的问题。
这套流程我在几台不同的 Windows 机器上都跑过，从 Windows 10 到 Windows 11 都适用。核心就是三件事：Node.js 装对版本、PowerShell 调好策略和编码、npm 源选快的。把这三样搞定，Codex CLI 在 Windows 上的体验其实和 macOS 差不了太多。真正拉开差距的，是你怎么用它——工具只是起点，用它的方式才决定效率。
