★ FEATURED ARTICLE 1. 装之前先搞清楚Codex CLI 到底是个什么东西很多人第一次听到 Codex CLI脑子里浮现的是那个写代码的 AI 助手但具体它跑在哪里、怎么跑、跟浏览器里用的有什么区别其实并不清楚。我先把这件事讲透不然后面装到一半遇到报错你连自己在装什么都不知道排查起来会很痛苦。Codex CLI 是一个跑在终端里的命令行工具。你可以把它理解成一个住在你电脑命令行里的编程助手你在 PowerShell 里敲一句话它给你返回代码、解释、修改建议甚至直接帮你改文件。它不是一个带界面的软件没有窗口、没有按钮全靠命令和参数驱动。这一点非常关键因为后面所有的操作——安装、配置、启动、退出——都是在黑底白字的终端里完成的。那为什么有人愿意用命令行而不是网页版我自己的体会是三点。第一它离你的项目更近。你在项目根目录启动它它能直接读到你的文件结构、代码内容不用你一段段复制粘贴。第二它可以被脚本化。命令行工具天然适合嵌进自动化流程比如批量处理、CI 环节。第三响应链路更短。没有浏览器渲染、没有页面加载交互更直接。但代价也很明显它对环境有要求。Codex CLI 本身是用 Node.js 生态分发的也就是说你电脑上必须先有一个能跑的 Node.js 和 npmNode 的包管理器它才能被安装进来。这就像你想装一个手机 App得先确认手机系统版本够不够——Node.js 就是那个系统版本。所以这篇教程的路线图是这样的先装 Node.js → 再确认 npm 能用 → 然后用 npm 装 Codex CLI → 最后跑通第一次对话。每一步我都会告诉你为什么这么做、容易在哪翻车、翻车了怎么救。零基础没关系但你得按顺序来跳步是这类工具安装失败的头号原因。提示整篇教程默认你用的是 Windows 10 或 Windows 11并且有管理员权限或者至少能自己装软件。如果你在公司电脑上操作先确认一下有没有软件安装限制否则后面会卡在权限上。2. 第一步把 Node.js 装对比装快更重要2.1 为什么非得是 Node.js不能直接下个 exe 吗这是新手问得最多的问题。答案是Codex CLI 的官方分发渠道就是 npm 仓库它没有提供一个双击安装的独立 exe。npm 是 Node.js 自带的包管理器所以你想要 npm就必须先有 Node.js。这俩是捆绑的装 Node.js 的时候 npm 会一起进来不用单独装。那 Node.js 又是什么简单说它是一个让 JavaScript 能脱离浏览器、直接在电脑上运行的环境。以前 JavaScript 只能活在网页里Node.js 把它解放出来让它能读写文件、开网络服务、跑命令行工具。Codex CLI 就是这样一个用 JavaScript 写的命令行工具所以它需要 Node.js 来托底。理解了这层关系你就明白为什么网上那些Codex CLI 安装失败的帖子十有八九根子都在 Node.js 上——要么没装要么版本太老要么装了但环境变量没配好导致终端根本找不到它。2.2 下载哪个版本LTS 是唯一正确答案打开 Node.js 官网你会看到两个下载按钮一个写着LTS一个写着Current。很多人手一抖点了 Current然后后面各种奇怪的报错就来了。我的建议非常明确永远选 LTS。LTS 是 Long Term Support 的缩写意思是长期支持版稳定、经过大量验证、生态兼容性最好。Current 是最新版包含最新特性但也可能有没被发现的 bug而且很多 npm 包还没跟上适配。具体到 Codex CLI 这类工具它对 Node 版本通常有个最低要求比如 18 或 20 以上。LTS 版本一般都能满足而且不会因为版本太新导致依赖冲突。我见过有人用 Current 版装完跑起来报一堆模块找不到的错换成 LTS 立刻就好了——这种坑完全没必要踩。下载的时候选Windows Installer (.msi)那个 64 位版本别去下 zip 压缩包。msi 安装包会自动帮你配好环境变量zip 包得手动配对零基础来说纯属给自己找麻烦。2.3 安装过程中的三个勾选项别乱动双击 msi 之后一路 Next 就行但中间有个界面会出现几个复选框我逐个说Add to PATH这个必须勾。它的作用是把 Node.js 和 npm 的路径写进系统环境变量这样你在任意目录打开 PowerShell 都能直接敲node和npm。不勾的话你得手动配新手极易配错。npm package manager默认勾选保持勾选。这就是 npm 本体。Tools for Native Modules这个可选会额外装一些编译工具体积不小。如果你只是用 Codex CLI可以不勾省时间。但如果以后要装需要编译的 npm 包可能会用到到时候再补也行。装完之后一定要重启 PowerShell。注意是关掉当前窗口重新开一个不是在里面敲个命令刷新。因为环境变量是在进程启动时读取的老窗口读的是旧环境你不重启它永远找不到新装的 node。2.4 验证安装两条命令定生死重开 PowerShell 之后敲这两条node -v npm -v正常的话会分别打印出版本号比如v20.11.0和10.2.4。看到版本号说明 Node.js 和 npm 都到位了。如果报错说无法将 node 识别为 cmdlet、函数、脚本文件或可运行程序的名称那就是环境变量没生效。先确认你是不是真的重开了窗口如果重开了还不行检查安装时 Add to PATH 有没有勾再不行就手动去系统环境变量的 Path 里加一条 Node.js 的安装目录通常是C:\Program Files\nodejs\。注意有些人的电脑上装了多个 Node 版本比如以前装过又忘了这时候node -v出来的可能不是你刚装的那个。用where node可以看当前实际调用的是哪个路径下的 node确认一下是不是你新装的那个。3. PowerShell 的脚本执行策略那个让 npm 报错的隐形门槛3.1 为什么 npm 会突然无法加载文件这是 Windows 上装 Codex CLI 最经典的拦路虎没有之一。你 Node.js 装好了node -v也正常结果一敲npm install就蹦出这么一段npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。第一次看到这个报错很多人以为是 npm 坏了跑去重装 Node.js结果重装完还是这个错。其实 npm 一点问题没有问题出在PowerShell 的脚本执行策略上。PowerShell 出于安全考虑默认不允许运行任何.ps1脚本文件。而 npm 在 Windows 上恰恰是通过一个叫npm.ps1的脚本被调用的。策略禁止运行脚本npm 自然就起不来。这跟 npm 本身无关是 PowerShell 的门槛。3.2 查看当前策略再决定怎么改先看看当前是什么策略Get-ExecutionPolicy大概率会返回Restricted意思就是禁止一切脚本。这就是罪魁祸首。解决方式是把它改成RemoteSigned。这个策略的含义是本地自己写的脚本可以跑从网上下载的脚本需要有数字签名才能跑。对日常开发来说这是安全性和可用性平衡得比较好的一个档位比直接设成Unrestricted什么都不管要稳妥。改的时候有个关键点要改当前用户级别的策略而不是整个系统级别的。命令是Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned它会问你确认输入Y回车。这样改只影响你自己的账户不需要管理员权限也不会动到系统全局设置相对安全。改完再敲一次Get-ExecutionPolicy应该返回RemoteSigned。这时候再回去跑 npm 命令那个报错就消失了。3.3 改策略这件事到底安不安全我知道有人会担心把脚本执行放开是不是等于给病毒开门这里说清楚。RemoteSigned的核心逻辑是本地脚本放行远程脚本要签名。也就是说如果有个恶意脚本是从网上下载到你电脑上的它没有可信签名照样跑不起来。真正被放开的只是你自己在本地创建或修改的脚本。对于开发者来说这个策略是业界普遍推荐的最低可用配置。真正危险的是Unrestricted和Bypass那两个才是几乎不设防。所以别图省事直接设成 Unrestricted用 RemoteSigned 就够了。提示如果你在公司的域环境里执行策略可能被组策略锁死Set-ExecutionPolicy会报被覆盖之类的错。这种情况得找 IT 管理员自己改不动。个人电脑一般不会遇到。4. 用 npm 把 Codex CLI 装进来4.1 全局安装还是本地安装npm 装包分两种全局-g和本地不带-g。Codex CLI 这种命令行工具要的是全局安装因为你需要它在任何目录下都能被调用而不是只在某个项目文件夹里能用。命令是npm install -g openai/codex这里的openai/codex是包的完整名称openai是作用域scopecodex是包名。作用域的作用是把同一个组织下的包归类避免和别人的同名包冲突。敲下去之后npm 会去仓库拉取这个包以及它依赖的一堆东西屏幕上会滚动一堆进度。等它停下来没有红色ERR字样基本就是成功了。4.2 国内网络环境下的加速方案如果你在国内直接跑上面那条命令可能会非常慢甚至卡住不动。原因是 npm 默认的仓库地址在国外拉包要跨网络速度不稳定。解决办法是换成国内镜像源。常用的是淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设完之后再用npm config get registry确认一下返回的是你刚设的地址就对了。然后再跑安装命令速度会有肉眼可见的提升。这里有个经验镜像源不是万能的。有些包在镜像上同步不及时或者某些作用域包镜像没收录这时候反而会报找不到包。如果换了镜像装不上可以临时切回官方源试试npm install -g openai/codex --registryhttps://registry.npmjs.org这条命令只对当前这一次安装生效不会改你的全局配置比较灵活。4.3 安装完怎么确认真的装上了装完之后敲codex --version如果打印出版本号说明装好了而且 PATH 也配对了。如果报无法识别 codex那可能是全局包的安装目录没在 PATH 里。用这条命令看全局包的安装位置npm config get prefix返回的路径比如C:\Users\你的用户名\AppData\Roaming\npm就是全局包的可执行文件所在目录。确认这个目录在系统环境变量的 Path 里。如果不在手动加进去然后重开 PowerShell。注意改完环境变量一定要重开终端窗口这个规则在整篇教程里反复出现因为它真的太容易被忽略了。很多人改完 Path 发现还是不行就是因为没重开窗口。5. 第一次启动 Codex CLI 与常用命令上手5.1 在哪个目录启动决定了它能看见什么Codex CLI 是上下文敏感的工具它在哪个目录启动就默认能访问那个目录下的文件。所以正确的做法是先 cd 到你的项目根目录再启动。cd D:\projects\my-app codex如果你在C:\Users\你的用户名这种地方启动它看到的就是一堆系统文件夹对你写代码没帮助还可能因为权限问题读不了某些目录。启动之后通常会进入一个交互式界面你可以直接输入自然语言描述你的需求比如帮我看看这个函数为什么报错或者给这个文件加个单元测试。它会读取当前目录的上下文来回应你。5.2 几个你迟早会用到的内置命令Codex CLI 的交互界面里除了直接说话还有一些以斜杠开头的内置命令用来控制会话本身。这些命令不是给 AI 的指令而是给工具的操作指令。常见的几个命令作用什么时候用/compact压缩当前会话的上下文对话太长、响应变慢或开始忘事时/model切换使用的模型想换一个更强或更快的模型时/resume恢复之前的会话关掉终端后想接着上次继续聊/compact这个特别值得说。AI 对话有个上下文窗口的概念就是它能同时记住的内容有上限。聊得越久累积的内容越多一旦超过窗口早期的内容就会被挤掉表现为它开始忘记你前面说过的话。/compact的作用就是把之前的对话压缩成摘要腾出空间同时保留关键信息。感觉对话变迟钝了敲一下它往往能救回来。/resume则是解决手滑关了窗口的痛点。它会列出你之前的会话让你选一个继续不用从头再来。5.3 退出与卸载退出交互界面一般是敲/exit或者按CtrlC两次。具体看版本界面上通常会有提示。如果哪天你不想用了卸载命令是npm uninstall -g openai/codex这条命令会把全局安装的 Codex CLI 移除。注意它不会动你的 Node.jsNode.js 要单独卸去控制面板的程序列表里找。6. 装完跑不起来按这个顺序排查6.1 排查要讲顺序别东一榔头西一棒子新手遇到报错最容易犯的错就是看到什么错就搜什么改一堆东西最后把环境搞得更乱。正确的做法是从底层往上查Node.js → npm → 执行策略 → 包安装 → PATH。因为上层依赖下层下层不通上层怎么改都没用。我整理了一个排查顺序表照着走基本能定位到问题现象最可能的原因验证命令处理方式node不是命令Node 没装或 PATH 没配where node重装并勾选 Add to PATHnpm.ps1 禁止运行脚本执行策略是 RestrictedGet-ExecutionPolicy设为 RemoteSigned安装卡住不动网络到官方源太慢无换国内镜像源装完codex不识别全局目录不在 PATHnpm config get prefix手动加进 Path 并重开窗口启动后读不到项目文件启动目录不对pwdcd 到项目根目录再启动6.2 两个我踩过的真实坑第一个坑是多版本 Node 打架。我电脑上以前装过一个老版本 Node后来装新版的时候没卸干净结果node -v显示的是老版本npm 装包各种报错。用where node一看居然有两个路径。解决办法是把老版本卸掉或者调整 Path 里的顺序让新版本排在前面。第二个坑是镜像源设了但没生效。我明明设了淘宝源装包还是慢。后来发现是项目目录下有个.npmrc文件里面的 registry 配置覆盖了全局设置。npm 的配置是有优先级的项目级 用户级 全局级。所以如果你在某个项目里设过源它会盖过你全局设的。检查项目根目录有没有.npmrc有的话看看里面写了什么。6.3 关于 PowerShell 乱码和闪退有人的 PowerShell 中文显示成乱码这通常是编码问题。可以临时用chcp 65001把当前窗口切到 UTF-8 编码。想永久解决得改系统区域设置或者 PowerShell 配置稍微麻烦点但日常用临时切换基本够。至于脚本命令闪退多半是因为脚本执行完就自动关窗口了。解决办法是在脚本末尾加一句pause或者从已经打开的 PowerShell 窗口里手动执行脚本而不是双击运行。7. 把它用顺手的几个个人习惯装好只是起点真正让它产生价值的是使用习惯。我自己用下来有几个做法明显提升了效率。第一项目根目录放一个说明文件。Codex CLI 读取上下文时如果根目录有个清晰的 README 或者项目结构说明它给出的建议会准确很多。相当于你先给它交代了背景它就不用瞎猜。第二描述需求时带上具体文件路径。与其说帮我改一下登录逻辑不如说看一下src/auth/login.js里的登录逻辑把错误处理补全。路径越具体它定位越准来回拉扯的次数越少。第三长会话记得用/compact。我一开始不知道这个命令一个会话聊到后面它开始答非所问我还以为是模型不行。后来学会定期压缩上下文体验完全不一样。第四换模型用/model按需切换。简单任务用快模型复杂重构用强模型不必一直用最贵的那个。这个习惯能省不少等待时间。最后说一句关于版本更新的。Node.js 和 Codex CLI 都在持续迭代偶尔会遇到新版本引入的兼容问题。我的做法是生产环境用的版本不轻易升等社区反馈稳定了再动。如果升级后出问题回退到上一个 LTS 版本通常能立刻恢复。工具是拿来干活的稳定比尝鲜重要。
阅读完成 · 觉得有帮助？
