Codex CLI 怎么安装？版本与 Node 的要求

AI 编程智能体要在终端里跑起来，第一道门槛就是安装：命令敲下去，有人直接报命令不存在，有人卡在 Node 版本上，还有人装完发现版本不对劲——同一台机器装出了两份 Codex。安装这一步看着简单，坑都集中在来源与版本上。这篇给出 npm 与 brew 两条安装路、装完怎么验证、Node 版本这道坎怎么过、多来源冲突怎么排查，以及升级的标准动作。

两条安装路：npm 与 brew

主流安装走 npm：npm install -g @openai/codex，一条命令全局安装，Windows、macOS、Linux 通用，前提是机器上已有 Node 环境。macOS 上还有第二条路：brew install codex，走 Homebrew 管理。两条路装的是同一个工具，选一条顺手的走就行，装好后终端里敲 codex 就能进交互界面。想直接看装完之后怎么用，见首次使用 Codex CLI一篇的完整链路；命令行形态的编程工具与编辑器插件怎么分工，见AI 编程插件与 CLI一篇。

装完先验版本

安装是否成功，用 codex --version 一验便知：能吐出版本号，说明装上了、PATH 也通；提示命令不存在，多半是安装没完成或者可执行文件没进 PATH。验证这步别省——后面排查任何问题时，第一件事都是确认当前版本，很多「莫名怪问题」其实是版本对不上。同理，去社区求助或查 issue 时带上版本号，别人才能对上号。

Node 版本这道坎

Codex CLI 依赖 Node 运行环境，Node 太旧，轻则装不上、重则装上了运行时行为异常。排查顺序：先 node -v 看当前版本，再对照官方安装文档标注的最低要求——具体支持哪个版本区间以官方文档为准，本文不代填数字。版本不够就升 Node，用 nvm 之类的版本管理器最稳，切换自如，不干扰系统里其他依赖 Node 的项目。Node 与 Codex 都处理完，重跑 codex --version 确认。

一台机器两份 Codex

安装失败与行为怪异的另一个高频根源是多来源：先用 npm 装过，后来又用 brew 装了一遍，机器上存在两份可执行文件，PATH 里谁排前面就用到谁——你以为在用新版，实际跑的是旧版，或者反过来。排查用 which codex 看路径，输出指向哪条安装来源一目了然（Windows 下用 where）。确认冲突后卸载其一，只保留一条来源，以后升级也只动这一条。这个坑属于典型的「装了但没装对」，AI 编程工具新手的常见错误清单里它常年上榜。

升级与固定版本

日常升级一条命令：npm i -g @openai/codex@latest，装的就是最新版；brew 安装的用 brew upgrade 对应处理。升级前值得扫一眼官方更新日志，新版可能带来行为变化，审批方式、沙箱行为都出现过跨版本调整的先例，升级与回滚的取舍见版本升级与回滚一篇。另外，安装与更新都要联网走官方源，公司网络下 npm 或 brew 走不通，先怀疑代理与证书，配置思路见代理配置专项一篇。动手装之前想让流程更稳，可以把你的操作系统与包管理器情况告诉豆包，让它生成一份对应的安装检查清单；卡在报错上时，把 codex --version 与报错原文一起丢给 DeepSeek 或 Kimi 分析，先分清是版本问题还是来源冲突，再动手卸装。

Codex CLI 安装速查

• npm install -g @openai/codex 全局安装，macOS 也可走 brew
• 装完 codex --version 验证，命令不存在先查 PATH
• node -v 核对 Node 版本，最低要求以官方文档为准
• npm 与 brew 装了两份会打架，which codex 定位后卸载其一
• 升级用 npm i -g @openai/codex@latest，升级前看更新日志

关于 CLI 安装的三问三答

• 装完敲 codex 没反应怎么办？：按顺序查三处：安装命令是否真的执行成功、codex --version 是否有输出、which codex 指向的路径是否在 PATH 里。多数情况是 PATH 没包含全局安装目录，重开一个终端窗口再试一次也常能解决。
• npm 和 brew 两条路可以混用吗？：不建议。两份安装会互相遮蔽，版本对不上时排查极费时间；选定一条来源后固定用它安装与升级，另一条来源卸干净。
• Node 要什么版本才够？：以官方安装文档标注的最低版本为准，文档随版本更新会调整；拿不准就先把 Node 升到当前稳定版，再装 Codex。