1. 为什么要在本地跑 Codex CLI
我第一次接触 Codex CLI 是在一个需要批量重构老项目的场景里。当时手头有十几个模块文件需要统一调整接口调用方式，如果纯靠人工一个个改，不仅耗时，还容易漏改、错改。Codex CLI 这类终端里的 AI 编程助手，最大的价值就在于它能直接读取你本地的代码上下文，在命令行里完成代码生成、解释、重构、调试建议等操作，不需要你频繁切换到浏览器或者编辑器插件里复制粘贴。
说白了，它把"和 AI 对话写代码"这件事，从网页搬到了你的终端和项目目录里。你可以理解为：以前你要把代码贴到网页对话框，再把结果复制回来；现在你直接在项目根目录敲一行命令，它就能看到你的文件结构，针对性地给你答案，甚至直接帮你改文件。
这篇文章适合哪些人看？如果你是刚听说 Codex CLI、想在自己电脑上装一个试试的开发者，或者你已经在 Windows 上折腾了半天没跑起来、在 Mac 上被环境变量卡住、在 Linux 上不确定该用哪种安装方式，那这篇内容基本能覆盖你的需求。我会把 Windows、Mac、Linux 三个平台，以及 VSCode 里的集成方式，从头到尾讲清楚，包括我踩过的坑和实测有效的排查思路。
需要先说明一点：Codex CLI 本身是一个命令行工具，它的安装方式随着版本迭代会有变化。下面我讲的是目前主流、稳定的安装路径，如果你用的是更新版本，核心逻辑不变，只是个别命令可能有微调。
2. 安装前的环境准备与核心思路
2.1 先搞清楚 Codex CLI 依赖什么
不管你用哪个系统，Codex CLI 的运行都依赖两个基础东西：一个是Node.js 运行环境，另一个是OpenAI 的 API 凭证。前者是工具本身的运行基础，后者是让它能调用模型能力的关键。
Node.js 的版本建议在 18 以上，最好是 20 或 22 的 LTS 版本。为什么强调这个？因为很多安装失败、命令报错的根源，就是 Node 版本太老，导致依赖包不兼容。我见过不少人用系统自带的 Node 12 或者 14，装完之后一运行就报SyntaxError或者模块找不到，折腾半天以为是工具问题，其实是环境太旧。
API 凭证这块，你需要有一个 OpenAI 平台的账号，并在后台生成一个 API Key。这个 Key 是一串以sk-开头的字符串，后面配置的时候会用到。注意，这个 Key 只显示一次，生成后要立刻复制保存，关掉页面就再也看不到了。
2.2 三个平台的安装策略差异
三个系统的安装思路其实可以统一成一句话：先装好 Node 环境，再用包管理器全局安装 Codex CLI，最后配置 API Key。但每个平台在"装 Node"和"配环境变量"这两步上差异比较大。
Windows 的难点在于环境变量和权限，尤其是 PowerShell 的执行策略和路径配置，新手很容易在这里卡住。Mac 的难点在于 Homebrew 的安装和 shell 配置文件的选择，zsh 和 bash 的配置文件不一样，配错了就不生效。Linux 相对最顺，但不同发行版的包管理器不同，而且如果你用的是服务器环境，可能还需要处理权限和全局路径的问题。
我的建议是：不管你用哪个系统，都优先用官方推荐的包管理器来装 Node，而不是去官网下载安装包手动装。原因很简单，包管理器装完之后，后续升级、卸载、切换版本都方便，而且路径会自动配好，省去大量手动配置的麻烦。
2.3 安装方式对比：npm 全局安装 vs 其他方式
目前 Codex CLI 最主流的安装方式是通过 npm 全局安装。我整理了一个简单的对比，方便你判断：
| 安装方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| npm 全局安装 | 所有平台通用 | 命令统一、升级方便 | 需要 Node 环境 |
| 包管理器安装 | Mac/Linux | 系统级管理 | 版本可能滞后 |
| 手动下载二进制 | 特殊环境 | 不依赖 Node | 升级麻烦、易出错 |
实测下来，npm 全局安装是最省心的。一条命令搞定，后续升级也是同一条命令加个版本号就行。所以下面的教程，我主要围绕这个方式来展开，其他方式作为补充说明。
3. Windows 平台完整安装配置
3.1 安装 Node.js 环境
Windows 上装 Node，我强烈建议用官方的安装包或者 winget。如果你用的是 Windows 10 以上版本，直接打开 PowerShell，敲：
winget install OpenJS.NodeJS.LTS这条命令会自动下载并安装最新的 LTS 版本，装完之后路径也会自动配好。如果你没有 winget，就去 Node 官网下载 LTS 版本的.msi安装包，双击一路下一步就行。安装过程中有一个选项叫"Add to PATH"，默认是勾选的，千万别取消。
装完之后，一定要关掉当前的终端窗口，重新开一个，然后验证：
node -v npm -v能正常输出版本号，说明环境没问题。如果提示"不是内部或外部命令"，那就是 PATH 没配好，需要手动把 Node 的安装目录加到系统环境变量里。
注意：Windows 上如果之前装过旧版 Node，建议先卸载干净再装新版，否则可能出现版本冲突，导致 npm 命令指向错误的路径。
3.2 全局安装 Codex CLI
Node 环境就绪后，安装 Codex CLI 就一行命令：
npm install -g @openai/codex这里的-g表示全局安装，装完之后在任何目录都能直接用codex命令。安装过程如果卡住不动，大概率是网络问题，可以换用国内镜像源：
npm config set registry https://registry.npmmirror.com然后再重新执行安装命令。装完之后验证：
codex --version能输出版本号就说明装好了。
3.3 配置 API Key 与环境变量
这一步是 Windows 上最容易出问题的地方。Codex CLI 需要读取你的 API Key，通常是通过环境变量来传递。在 Windows 上设置环境变量有两种方式：
第一种是临时设置，只在当前终端窗口有效：
$env:OPENAI_API_KEY="sk-你的key"第二种是永久设置，通过系统设置或者命令行：
setx OPENAI_API_KEY "sk-你的key"用setx设置完之后，同样需要重开终端才能生效。我建议用第二种，一次配好，以后不用每次开终端都重新设。
提示：如果你在 PowerShell 里执行
setx报权限错误，试着用管理员身份运行 PowerShell。另外，setx设置的变量有长度限制，如果你的 Key 特别长，建议用系统设置界面手动添加。
3.4 Windows 常见报错与排查
Windows 上我遇到过最多的报错是这几类：
第一类是codex : 无法加载文件，因为在此系统上禁止运行脚本。这是 PowerShell 的执行策略问题，解决办法是：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行后输入 Y 确认即可。
第二类是error: start the windows daemon from a non-elevated terminal。这个报错的意思是，某些后台服务不能从管理员权限的终端启动。解决办法很简单：不要用管理员身份运行终端，用普通权限的 PowerShell 或 CMD 重新执行命令。
第三类是安装成功但命令找不到。这通常是 npm 全局路径没有加到 PATH 里。你可以用npm config get prefix查看全局安装路径，然后手动把这个路径加到系统环境变量里。
4. Mac 平台完整安装配置
4.1 用 Homebrew 装 Node 的正确姿势
Mac 上装 Node，首选 Homebrew。如果你还没装 Homebrew，先执行官方安装脚本。这里要提醒一句：Homebrew 的安装脚本需要网络能正常访问相关资源，如果卡在下载环节，多试几次或者换个时间段。
装好 Homebrew 之后，安装 Node：
brew install node这条命令会装上最新稳定版的 Node 和 npm。装完验证：
node -v npm -v如果你之前用其他方式装过 Node，可能会遇到版本冲突。这时候可以用which node看看当前用的是哪个路径下的 Node，确保是 Homebrew 装的那个。
注意：Mac 上如果
brew install报错说权限不足，不要直接加 sudo，而是检查/usr/local或/opt/homebrew目录的归属权限。M 系列芯片的 Mac，Homebrew 默认装在/opt/homebrew，Intel 芯片装在/usr/local，两者路径不同，配置环境变量时要注意区分。
4.2 安装 Codex CLI 并配置 shell
Node 就绪后，安装命令和 Windows 一样：
npm install -g @openai/codexMac 上默认的 shell 是 zsh，所以环境变量要配在~/.zshrc文件里。打开这个文件：
nano ~/.zshrc在文件末尾加上：
export OPENAI_API_KEY="sk-你的key"保存退出后，执行：
source ~/.zshrc让配置立即生效。如果你用的是 bash，那就改~/.bash_profile或~/.bashrc，逻辑一样。
4.3 Mac 上 Homebrew 安装失败的应对
Homebrew 安装失败是 Mac 用户的高频问题。常见原因有三个：网络问题、权限问题、Xcode 命令行工具没装。
网络问题表现为下载卡住或者超时，这个只能多试或者换时间段。权限问题表现为报错说目录不可写，解决办法是修正目录归属：
sudo chown -R $(whoami) /opt/homebrewXcode 命令行工具没装的话，执行：
xcode-select --install按提示安装即可。这个工具是很多开发环境的基础依赖，装上之后能避免大量莫名其妙的编译错误。
4.4 Mac 环境变量不生效的排查
配完环境变量后，如果codex命令还是提示找不到 Key，按这个顺序排查：
先确认配置文件对不对。echo $SHELL看看当前用的是哪个 shell，zsh 就改.zshrc，bash 就改.bash_profile。然后确认配置有没有被加载，echo $OPENAI_API_KEY看看能不能输出你的 Key。如果输出为空，说明配置没生效，检查文件路径和拼写。
还有一个容易忽略的点：如果你在 VSCode 的集成终端里运行，它可能没有加载你的 shell 配置。这时候要么重启 VSCode，要么在 VSCode 设置里把终端改成登录 shell 模式。
5. Linux 平台完整安装配置
5.1 不同发行版的 Node 安装方式
Linux 上装 Node，方式取决于你的发行版。Ubuntu/Debian 系可以用 apt，但系统源里的 Node 版本往往偏旧，我更推荐用 NodeSource 的源：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejsCentOS/RHEL 系用 yum 或 dnf，同样建议加 NodeSource 源。Arch 系直接pacman -S nodejs npm就行。
装完验证版本，确保是 18 以上。如果版本不对，先卸载旧版再装。
5.2 全局安装与权限处理
Linux 上 npm 全局安装最常见的坑是权限问题。直接npm install -g可能报EACCES错误，因为全局目录默认归 root 所有。有两种解决办法：
第一种是改 npm 的全局目录到用户目录下：
mkdir ~/.npm-global npm config set prefix '~/.npm-global'然后把~/.npm-global/bin加到 PATH 里。
第二种是直接用 sudo，但我不推荐，因为 sudo 装的包后续管理麻烦，而且有安全隐患。
配好之后安装：
npm install -g @openai/codex5.3 服务器环境下的配置要点
如果你是在云服务器或者远程 Linux 环境里用，有几个额外注意点。环境变量要配在~/.bashrc或~/.profile里，而且要注意，非交互式 shell 可能不会加载这些文件。如果你是通过脚本调用 codex，可能需要在脚本里显式 export 环境变量。
另外，服务器上通常没有图形界面，Codex CLI 的纯命令行交互模式反而更合适。确保你的终端支持足够的字符编码，避免中文输出乱码。
5.4 Linux 下验证安装是否成功
装完之后，按这个清单逐项验证：
node -v # 确认 Node 版本 npm -v # 确认 npm 可用 codex --version # 确认 codex 装好 echo $OPENAI_API_KEY # 确认 Key 已配置四项都正常，就可以在项目目录里运行codex开始用了。如果哪一项不对，回到对应章节排查。
6. VSCode 集成与高效使用技巧
6.1 在 VSCode 终端里直接用
最简单的集成方式，就是直接在 VSCode 的集成终端里用。打开 VSCode，按Ctrl+`调出终端，确保终端的工作目录是你的项目根目录，然后直接敲codex命令。
这样做的好处是，Codex CLI 能直接读取当前项目的文件，你在终端里让它分析某个文件、生成某段代码，它都能结合项目上下文给出更准确的回答。而且终端和编辑器在同一个窗口，改完代码立刻能看到效果，效率比来回切换高很多。
提示：如果你的 VSCode 终端里 codex 命令找不到，检查一下终端用的是不是系统默认 shell。有时候 VSCode 会用一个精简的环境，导致 PATH 不全。可以在 VSCode 设置里搜索
terminal.integrated.env相关选项进行调整。
6.2 配合 VSCode 插件提升体验
虽然 Codex CLI 本身是命令行工具，但你可以配合一些 VSCode 插件让体验更好。比如用Code Runner快速执行代码片段，用GitLens查看代码变更历史，这些和 Codex CLI 搭配起来，能形成一套完整的开发流。
另外，VSCode 的tasks.json可以配置自定义任务，你可以把常用的 codex 命令配成任务，用快捷键一键触发。比如配一个"让 Codex 解释当前文件"的任务，绑定到某个快捷键上，用起来很顺手。
6.3 多平台同步配置的思路
如果你在 Windows、Mac、Linux 多个平台上都用 Codex CLI，配置同步是个实际问题。我的做法是把 API Key 这类敏感信息放在各平台的环境变量里，不写进任何项目文件。然后把常用的命令别名、脚本放在一个私有仓库里，各平台拉取同一份配置。
VSCode 这边，用 Settings Sync 功能同步插件和设置，这样换平台的时候，编辑器环境能快速恢复，只需要重新配一下系统级的环境变量就行。
7. 常见问题速查与避坑经验
7.1 安装类问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| codex 命令找不到 | 全局路径未加入 PATH | 检查 npm prefix 并加入 PATH |
| 安装卡住不动 | 网络问题 | 换国内镜像源重试 |
| EACCES 权限错误 | 全局目录归 root | 改 npm prefix 到用户目录 |
| 版本不兼容报错 | Node 版本过旧 | 升级到 18 以上 |
| 脚本禁止运行 | PowerShell 策略 | 设置 RemoteSigned |
7.2 配置类问题排查思路
API Key 相关的问题，排查顺序是：先确认 Key 本身有效（在平台后台能看到调用记录），再确认环境变量名拼写正确（必须是OPENAI_API_KEY），然后确认配置文件被正确加载（echo验证），最后确认运行环境能读到这个变量（比如 VSCode 终端可能需要重启）。
我踩过的一个坑是：在 Mac 上配了.zshrc，但在 VSCode 里跑的时候用的是 bash 环境，结果一直读不到 Key。后来统一改成在 VSCode 设置里指定用 zsh 作为集成终端，问题才解决。所以环境不一致这个问题，在多工具协作时特别容易出现。
7.3 使用过程中的实用技巧
第一个技巧是善用项目根目录。Codex CLI 读取上下文是以当前工作目录为基准的，你在项目根目录运行，它能看到整个项目结构；在子目录运行，它就只能看到子目录。所以养成在项目根目录启动的习惯。
第二个技巧是结合.gitignore。Codex CLI 在读取文件时，通常会尊重.gitignore的规则，把不需要的文件排除掉。确保你的.gitignore配置合理，能避免它读取大量无关文件，影响响应速度。
第三个技巧是分步提问。不要一次性让它做太复杂的任务，拆成几步，每步确认结果后再继续。这样不仅准确率高，出问题也容易定位。
8. 我个人的一些实操体会
折腾这几个平台的安装配置，我最大的感受是：环境问题永远比工具本身的问题多。Codex CLI 本身的安装命令就那么一条，但围绕它的 Node 环境、包管理器、shell 配置、权限设置，才是真正消耗时间的地方。
我的建议是，装之前先把 Node 环境弄干净，确认版本正确、路径正确，这一步做好了，后面基本一路顺畅。另外，遇到报错不要慌，先看报错信息里的关键词，大部分问题在速查表里都能找到对应解法。
还有一点，API Key 的管理要养成好习惯。不要把它硬编码到任何会提交到代码仓库的文件里，用环境变量是最稳妥的方式。如果团队协作，每个人配自己的 Key，不要共用。
最后分享一个小技巧：如果你经常需要在不同项目间切换，可以写一个简单的 shell 函数，自动切换到项目目录并启动 codex，省去每次手动 cd 的步骤。这种小优化积累起来，日常效率提升很明显。
