一转眼2026年了前两年大家还在争论AI编程会不会取代程序员现在使用习惯基本定型日常改需求、写脚本、查历史代码、跑测试越来越多朋友不再只是用编辑器里的补全插件而是直接把Codex CLI这类Agent式工具请进终端。我最初在Windows上把它跑通花了一下午后来又分别在Mac和一台Linux服务器上完整装了一遍发现网上教程最麻烦的是“碎片化”——Windows的教程到Mac就不适用Mac的办法换到Linux又踩坑VSCode联动还得另找资料。这周我把三套环境重新从零装了一次每一步都做了记录把身份认证、网络排查、VSCode集成全部串起来写成这篇跨平台安装配置教程。新手照着走就行老手可以重点看第三章和第六章的排查部分。1. 先理解Codex CLI它不是一个普通的代码补全工具1.1 它能做什么、不能做什么Codex CLI是OpenAI出品的命令行AI编程助手核心体验是直接在你本地项目目录里运行它能读取文件结构、修改代码、执行命令、跑测试、看报错操作维度比传统补全插件高一个级别。你可以把它理解为一个住在你项目目录里的结对工程师你在终端里和它对话它不只会贴代码还会把改动落到磁盘、顺手运行构建命令、根据报错继续调整。但也别把它神化。它不是一个IDE插件的“换皮”虽然官方提供了VSCode扩展底层调用的还是同一套CLI引擎。它的对话质量跟底层模型强相关默认模型写普通增删改查很熟练但遇到复杂的业务逻辑、多模块耦合的重构时你仍然要把上下文、约束条件交代清楚指望它“看一眼就懂全部历史包袱”不现实。边界清楚之后才好安排它的使用位置适合做执行型编程任务不适合替你拍板架构方向。1.2 为什么三个系统可以用同一套安装逻辑很多新手听到“Windows、Mac、Linux”三个词就头疼以为三套安装方法是三座大山。实际上Codex CLI是通过npm以Node包形式分发的本质是一个跨平台的Node.js命令行程序只要机器上有Node运行时装上npm包就能跑。三平台差异只体现在外围三件事上Node从哪来、终端怎么开、环境变量怎么配。把这层逻辑想明白了再看网上那些平台教程本质上就是萝卜换坑——装Node的方式不同后面codex部分的处理几乎一模一样。这也是我写这篇合集教程的底气不需要洋洋洒洒七八套流程把共性和差异性分清楚一套思路走遍三个系统。1.3 为什么推荐npm路线而不是下载安装包官方主推npm路线是有道理的。一条命令、一个包、三大通用天然省掉跨平台分发的麻烦。如果每个平台都做原生安装器用户就得担心版本碎片化、签名弹窗、卸载残留这些破事。采用npm方式升级一句npm update -g openai/codex就完事卸载也是一句话干净利落。所以我特别不建议去搜索“懒人安装包”或“一键免配置版”。那些东西版本来源不明还可能被塞进额外的东西。把Node环境弄好虽然前期多花二十分钟后面长期收益肯定超过走捷径。2. 环境准备装机之前先把三块地基打牢2.1 Node版本怎么选直接上20以上的LTSCodex CLI跑在Node运行时上版本不能太老。我实测下来的体感是Node 20以上的LTS版本最稳偏旧的12、14版本会在加载依赖时冒出各种诡异报错。判断当前Node版本很简单node -v npm -v如果你机器上还没有Node千万别去官网点那个“推荐给大多数用户”的安装包装完就完事——最好先上版本管理工具Windows推荐nvm-windowsMac和Linux推荐nvm这样以后切换Node版本、给不同项目配不同运行时都会方便很多。# Mac / Linux 安装nvm以官方脚本为例 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # Windows下载nvm-windows的exe安装包运行后执行 nvm install 20 nvm use 20为什么折腾版本管理因为代码项目对Node版本的要求一直在变今天这个项目要18明天那个要22如果系统里只有一个Node升级一次就可能把旧项目搞崩。Codex CLI这种工具型应用更需要一个稳定、可切换的运行时底座。2.2 npm全局安装的权限与源两个容易踩的坑准备阶段最容易劝退新手的就是权限问题。Windows下npm全局安装目录默认在AppData\Roaming\npm一般不需要管理员权限。但某些定制环境或公司电脑安装时会提示EACCES权限错误。这时候不要一上来就sudo npm install -g暴力提权容易污染系统目录更优雅的做法是把npm全局目录改到用户目录下npm config set prefix ~/.npm-global然后在~/.bashrc或~/.zshrc里加上对应PATH代码示例export PATH~/.npm-global/bin:$PATH另一个坑是网络源。npm默认源在海外国内环境下动不动超时或慢如蜗牛。临时切换成国内镜像源是常规做法npm config set registry https://registry.npmmirror.com装完东西之后如果不想长期依赖镜像可以把源切回官方npm config set registry https://registry.npmjs.org我不建议把镜像源常驻因为某些内网npm私有包、企业级registry都跟官方源直接相关镜像源可能同步不到。装Codex时切换一下装完恢复是最稳的姿势。2.3 Mac安装Homebrew翻车高频原因处理Mac用户绕不开Homebrew而“Mac安装Homebrew失败”几乎是每周都会被问一次的问题。我自己在Mac上装Homebrew也翻过车总结下来高频原因就三类网络连接不稳定导致官方安装脚本下载中断、系统目录权限没放开、以及旧版Homebrew残留冲突。官方安装命令其实就是一行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)如果卡在脚本下载阶段多半是网络原因。可以多试几次或者把Homebrew的仓库地址替换为国内可访问的镜像仓库手机上查一下“Homebrew 国内镜像 设置方法”就有对应的更新remote命令。这里的关键是不要反复盲目重跑脚本先看清报错是卡在curl阶段还是chown阶段网络问题重试权限问题就按提示执行目录授权sudo chown -R $USER:admin /opt/homebrew3. 三平台安装实操从命令到验证3.1 WindowsPowerShell一键安装与PATH排查Windows平台安装Codex的本质流程不复杂装Node、打开PowerShell、npm装包。用nvm-windows安装Node 20执行nvm install 20后nvm use 20重新打开一个新的PowerShell窗口确认node -v能正常输出版本号执行全局安装npm install -g openai/codex验证安装结果codex --version如果提示“codex不是内部或外部命令”别急着重装先查npm全局目录npm config get prefix把输出的路径比如C:\Users\你的用户名\AppData\Roaming\npm手动加到用户环境变量的Path里然后重新打开PowerShell验证。Windows还有一道特有的关口PowerShell执行策略。有些脚本默认被拦提示“在此系统上禁止运行脚本”。放开当前用户的执行策略即可Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser关于热词“codex windows设置未完成”我用一句话总结我在几个群里看到的案例90%是PowerShell执行策略没放开导致首次初始化脚本中途退出其次是PATH里没有npm目录导致找不到codex命令再就是安装中断后旧缓存残留。按上面两步处理完重新跑codex就能正常进入初始化流程。3.2 Maczsh环境下的安装与卸载心态Mac安装同样是三步有Node环境、npm装包、配置PATH。如果你的Mac已经装了Homebrew就直接用brew装nodebrew install node然后一样装Codexnpm install -g openai/codex验证安装codex --versionMac上最容易出的问题在PATH配置上。使用brew安装的Node可执行文件路径一般是/opt/homebrew/bin正常情况下这个目录已在PATH里但如果你用了nvm就需要在~/.zshrc里补一段export PATH$HOME/.nvm/versions/node/$(cat $HOME/.nvm/alias/default)/bin:$PATH这一段我日常不会写死版本号而是用alias动态读取避免以后切Node版本还要再改配置。Mac遇到权限问题时依然是那个原则优先通过改npm prefix绕开而不是用sudo硬刚。升级旧版Codex前建议先卸干净再装npm uninstall -g openai/codex npm install -g openai/codex别问为什么要卸了再装旧版本残留很容易出现“命令存在但行为诡异”的中间态到时候排查浪费的时间远大于多敲一条命令的时间。3.3 LinuxCentOS/Ubuntu的差异与无图形界面认证Linux服务器场景下安装又是另外几个套路。Ubuntu/Debian系用apt装Node的话版本往往偏旧我建议还是走nvm路线避免系统包管理器锁定版本。CentOS/RHEL系可以用dnf装个基础Node同样推荐nvm。通用安装步骤# 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重载环境或重新登录 nvm install 20 nvm use 20 npm install -g openai/codex codex --versionLinux环境下有两点格外注意。第一不要用root执行全局npm安装除非你清楚自己在做什么。普通用户配合nvm权限和路径都清爽得多。第二无图形界面的服务器默认没有浏览器codex login的浏览器认证会变得麻烦。解决办法也简单命令行登录时Codex会输出一个认证链接或设备码你在自己电脑的浏览器里打开链接、输入设备码、登录账号就能完成验证。这个过程跟很多其他CLI工具的设备码登录是同一个套路不需要图形界面。4. 认证与联网安装完成不等于能用4.1 两种登录方式ChatGPT登录与API Key装好之后第一件事就是认证。Codex支持两种方式使用场景完全不同别搞混。一种是codex login会打开浏览器引导你登录ChatGPT账号适合个人电脑、你日常使用ChatGPT账号的场景。这种方式的优势是统一账号体系ChatGPT订阅用户的权益可以直接衔接。另一种是API Key模式不依赖交互式登录把OpenAI平台生成的API密钥写进环境变量即可适合服务器、CI/CD环境、或者你不想在公共电脑上留下登录态的场合。两种方式怎么选表格对比更直观认证方式适用场景优点缺点ChatGPT登录个人电脑日常使用流程简单与账号权益打通浏览器登录在无界面服务器上麻烦API Key服务器、脚本、团队共享不依赖交互适合自动化Key需要保管好泄露有成本风险4.2 OPENAI_API_KEY环境变量配置使用API Key模式时把密钥写进环境变量是标准做法。Windows PowerShell里临时设置$env:OPENAI_API_KEYsk-你的密钥Mac/Linux里写入当前用户配置export OPENAI_API_KEYsk-你的密钥但临时设置只对当前终端窗口有效下次登录又得重新配置。长期用的做法是写进配置文件echo export OPENAI_API_KEYsk-你的密钥 ~/.zshrc # 或 ~/.bashrc看你用哪个shell source ~/.zshrc实操中的安全提醒不要把API Key直接写进项目仓库里的脚本或.env文件中尤其别上传到公开代码平台。我见过不止一次Key被扫描抓走导致账号被盗刷的案例。个人项目可以放在~/.codex/目录的配置里团队项目建议用系统密钥管理服务或CI平台的Secret变量。4.3 网络连通性检查与报错过招认证通过之后如果Codex请求时一直报连接超时或Failed to connect最直接的排查方式是先确认网络能不能访问OpenAI服务。在终端里执行curl -I https://api.openai.com/v1/models如果返回HTTP状态码和JSON内容说明网络链路是通的如果直接卡住或报Could not resolve host就是域名解析或网络访问的问题。这一步要特别说清楚Codex需要访问OpenAI的在线接口你的网络环境必须允许访问这些服务。如果公司网络策略有限制跟网络管理员确认放行范围如果无线网络本身异常可以短暂切换手机热点测试一下是不是本地网络问题。别在网络上绕来绕去只要确认接口能被正常访问Codex后续就很少再冒出连接类问题。5. VSCode集成从终端到编辑器的效率提升5.1 官方扩展安装与登录联动Codex并不只在终端里能用官方在VSCode插件市场提供了同名扩展。安装步骤很简单打开VSCode扩展面板搜索“Codex”认准OpenAI官方出品点击安装。安装完成后侧边栏会出现Codex面板。插件首次使用也需要登录登录状态会和CLI联动。如果你之前在终端里已经codex login过插件通常能直接复用登录态。如果插件提示找不到Codex CLI需要在扩展设置里手动指定可执行文件路径指向npm prefix下的codex命令。Windows下一般是C:\Users\你的用户名\AppData\Roaming\npm\codex.cmdMac/Linux直接指向codex即可。装完插件后如果界面显示英文不舒服按常规做法在扩展市场搜索“Chinese (Simplified)”安装中文语言包这属于VSCode的基础设置和Codex本身没有冲突。5.2 本地服务端口占用的处理Codex在编辑器里跑测试或启动本地开发服务是高频操作而端口占用是绕不开的日常问题。Windows上用netstat一眼就能看出来netstat -ano | findstr :3000输出里找到占用端口的PID再用taskkill结束taskkill /PID 12345 /FMac/Linux用lsoflsof -i :3000 kill -9 12345这里有个经验教训杀进程前先确认PID对应的程序是什么有些是别的项目正在用的服务杀错了整个工作区都要重启。配合tasklist或ps aux先看进程名多花十秒总比把环境搞乱强。5.3 几个我常用的VSCode操作套路实际用下来Codex插件在编辑器里最舒服的几个操作模式是一是选中代码块在Codex面板里直接让它“解释这段逻辑”或“提一个更简洁的写法”不用把代码复制来复制去。二是用workspace提问整仓库结构比如问“支付模块里这个回调最终被谁调用”它能沿着代码索引给出链路这比人肉全局搜索高效太多。三是让它处理机械性工作比如给整个项目补测试用例、批量修改日志格式、统一错误处理结构。四是让Codex执行测试并基于测试结果自动修代码告诉它“跑一下测试把失败的修好”它会自己运行命令、解读报错、修改代码直到通过或明确告诉你无法解决。需要提醒的是Codex在编辑器里改文件是直接落盘的操作所以在让它做较大重构之前最好先git commit一次。我吃过这个亏让它整理一个模块的导入顺序它顺手把几个无关文件也格式化了git diff一片混乱最后只能手动挑着回滚。6. 常见问题速查表与排错实战6.1 安装阶段典型报错安装阶段最常见的三类错误EACCES permission denied权限问题根本原因是npm全局目录写在系统保护路径里解决方式不是提权而是改npm prefixnetwork相关错误多半是网络源不稳定切换镜像源或重试基本能过codex不是内部或外部命令在所有平台都可能出现本质就是PATH里没有codex所在的目录用npm config get prefix查路径再补进PATH即可。还有一类被统称为“设置未完成”的中文报错核心场景是Windows上的PowerShell执行策略卡住了初始化脚本或安装缓存不完整。按顺序做三件事放开执行策略、检查PATH、清掉npm缓存重装。绝大多数情况能解决。6.2 运行阶段典型报错运行阶段的高频问题则集中在认证和配额上。认证过期时重新登录一次codex login遇到429限流多半是短时间内请求太多或账户配额用完。前者等一会儿自然恢复后者需要去账号后台查看用量记录考虑调整模型或升级配额。模型不可用时的处理方式是查看当前可用模型列表在配置里切换到可用型号不要硬套官方教程里的固定模型名。6.3 断点式排查五步法与其零散地搜报错不如养成一条固定的排查链路。我自己的五步法是这样第一步看版本。node -v、npm -v、codex --version三个命令挨个跑任何一个报错或版本太旧问题大概率出在环境本身。第二步看路径。确认codex是否在PATH里Mac/Linux用command -v codexWindows用where codex找不到就去补PATH。第三步看网络。用curl -I https://api.openai.com/v1/models判断接口是否可达。第四步看日志。CLI通常支持--verbose参数插件可以在VSCode的“输出”面板里切到Codex频道报错原文往往比提示信息更有价值。第五步看缓存和旧版。清理npm缓存、卸载重装把异常状态复位。这套排查法我沿用很久了每次都能把问题从“不知道哪错了”收敛到“具体某个环节有问题”节省的时间远大于按报错信息一个个试。6.4 速查表格症状可能原因处理命令 / 操作npm安装时EACCES报错npm全局目录没有写权限修改npm prefix到用户目录或按提示授权目录npm下载超时/卡住默认源访问慢临时切换npmmirror镜像源装完切回codex命令找不到PATH未包含npm全局目录npm config get prefix查路径补进PATHPowerShell禁止运行脚本执行策略限制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser认证失效登录态过期codex login重新登录请求返回429限流或配额耗尽等待恢复或去账号后台检查用量插件提示找不到CLI插件设置中CLI路径未指定扩展设置中指向codex可执行文件端口被占用其他进程占用本地端口Windows用netstattaskkillMac/Linux用lsofkill升级后行为异常旧版残留npm uninstall -g openai/codex后重装最后说两个我自己的使用习惯。第一升级永远比修复优先每周跑一次npm update -g openai/codex让工具保持在当前版本能避免很多“旧版本才有的bug”。第二别把它当作单纯的问答机器人把VSCode插件和CLI结合着用——小改动在编辑器里让它快速改整仓库梳理和批量重构放到终端里做各干各擅长的活。工具是好工具但真正拉开效率差距的还是使用方式和排错思路。