最近好多朋友在问Codex到底怎么装尤其是Windows用户折腾半天卡在依赖环境上的不在少数。先说结论Codex就是OpenAI推出的命令行AI编程助手英文名叫OpenAI Codex CLI2025年开源之后热度一直没降。它跟网页版ChatGPT最大的区别是它直接住在你的终端里能读写项目文件、执行命令、跑测试相当于把一个会写代码的AI塞进了本地开发环境。这篇教程我按“下载安装教程”这个主线把免费安装包怎么拿、一键安装脚本怎么用、Windows/Mac/Linux三个平台分别怎么处理全部过一遍。写这篇文章的目标读者就是三类人第一次听说Codex想试试的小白、在Windows上折腾半天装不上的朋友、以及想用一键脚本给团队快速部署的开发者。我自己在三个平台都装过中间踩了不少坑下面这些内容基本都是实测过的操作照着做基本不会翻车。1. 先把Codex讲清楚它是什么装它到底值不值1.1 Codex不是网页AI是一套跑在本地终端的工具链很多人一听Codex就以为它是又一个网页聊天框其实完全不是一回事。Codex CLI是一个开源工具装好之后你打开终端输入codex它会进入一个交互式的命令行界面。你可以在里面直接描述需求比如“帮我把这个Python文件里的函数拆成两个”它会阅读文件内容、给出修改方案甚至可以自己动手改改完让你检查。它跟网页版的差别在哪网页版你只能粘贴代码进去它给你返回代码片段然后你自己复制、自己贴、自己测试。Codex不一样它有文件系统访问能力能直接读取你当前项目的目录结构能运行测试命令能执行lint检查能提交git commit。说白了网页版是“你问我答”Codex是“你布置任务它直接干”。2026年这个节点上Codex已经更新了好几轮安装和使用方式也比早期版本稳定得多现在装一次基本能长期用不需要反复折腾。它最适合干什么我的经验是这三类场景最值一是给陌生项目写测试你让它先读代码再补用例二是批量改代码比如重命名变量、迁移API调用三是解释整个项目的架构让它画个脑图或者写个说明文档。如果你只是偶尔问几句代码问题网页版其实够了没必要装命令行工具。但如果你天天跟代码打交道想让AI真正参与开发流程Codex是绕不开的工具。1.2 “免费安装包”到底指什么这里必须把话说清楚不然很多人会误解。Codex CLI这个工具本身是开源免费的安装包就是官方发布的npm包openai/codex你通过npm命令就能下载不需要花一分钱买授权。但“免费安装包”不等于“免费无限使用”——装好之后你要用一个OpenAI账号登录或者配置API Key去调用模型这部分涉及账号权限和API额度按官方政策来就行。网上有些所谓的“破解版Codex”“无限Key共享包”我建议一律别碰。首先Codex根本不需要破解你破解它没有任何意义因为工具本身是免费的其次那些共享Key随时可能失效甚至可能收集你的代码和隐私得不偿失。我的建议是安装包一律从官方渠道拿登录用你自己的OpenAI账号这是最省心也最安全的路线。这跟装VS Code、装Git是一个道理工具免费但平台服务是按账号走的。1.3 为什么安装这件事值得专门写一篇教程按理说一个npm包而已一条命令就装完了至于写篇长文吗等你真去装就会发现事情没那么简单。Codex依赖Node.jsNode.js版本有严格要求它在Windows上跑会遇到PowerShell执行策略问题在macOS上会遇到权限问题在Linux服务器上会遇到PATH环境变量问题。再加上网络环境不稳定npm下载可能超时装完还可能遇到代理配置导致的请求报错。我见过太多人在群里问“为什么我codex不是内部或外部命令”“为什么npm安装报engine错误”这些问题十有八九不是Codex本身的问题而是环境问题。所以我这篇安装教程的思路很简单先把三平台通用环境讲清楚再逐个平台给完整步骤最后把高频报错和排查方法列出来争取让读者一次装成功不用在搜索框里来回折腾。2. 安装前的准备工作一份三平台通用的检查清单2.1 第一件事确认Node.js环境Codex官方推荐的安装方式是通过npm全局安装所以Node.js是绕不开的前置依赖。这里有一个重点Node.js版本不能太低。早期版本可能要求18就够了但按2025年底到2026年的情况官方要求基本是Node.js 20.11或更高版本低版本安装时会直接报engine不兼容的错让你装都装不上。检查方法很简单打开终端执行node -v npm -v如果没有输出或者版本低于20.11那就先装Node.js。三个平台分别说Windows用户去Node.js官网下载Windows Installer.msi文件选LTS版本安装时注意勾选“Add to PATH”其他选项默认就好。这里我提醒一句别用网上那种“Node.js环境一键配置工具”很多人装了一堆用不上的东西还污染了系统变量最后排查问题更麻烦。macOS用户推荐先用Homebrew把Node装上brew install node如果你还没装Homebrew可以去brew官网按提示装装完再执行上面这条命令。Linux用户以Ubuntu/Debian为例可以用NodeSource仓库curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs如果你不想用NodeSource也可以直接去nodejs.org下载编译好的二进制包解压然后把bin目录写进PATH原理是一样。实测下来NodeSource最省事装完node和npm都齐了。2.2 第二件事Git和终端环境Codex在实际使用中经常要调用git比如查看当前分支、对比代码改动、生成commit消息所以Git建议提前装好。检查命令git --version没有的话Windows装Git for WindowsmacOS用brew install gitLinux用sudo apt install git。安装完重启终端确保git命令能识别。终端方面我多说两句。Windows用户建议把默认终端换成Windows Terminal配合PowerShell 7用交互体验比老版cmd好太多。安装Codex的时候我推荐以管理员身份打开PowerShell后面会有个执行策略的问题管理员身份处理起来更直接。Linux服务器场景多说一句如果你是通过SSH远程连接服务器来安装终端交互肯定不如本地顺滑但Codex本身对SSH环境支持还行。只要你能接受在纯命令行里跟它互动服务器上装Codex完全没问题。装好之后可以通过tmux或screen挂后台避免SSH断开导致任务中断。2.3 免费安装包去哪下载以及怎么判断来源靠不靠谱Codex的“安装包”其实就是npm包官方发布渠道就一个npm install -g openai/codex包名是openai/codex发布者必须是OpenAI官方组织。在npm官网搜codex的时候要看清楚包名和发布者现在蹭热度的同名包不少有些是测试包有些是第三方封装装错的话可能跑起来行为完全不一样。安装时留意npm输出的下载来源正常情况下是从registry.npmjs.org下载的。除了npmmacOS用户还可以通过Homebrew安装brew install codex但说实话我建议优先用npm方式。原因有两个第一npm包更新最快官方发版后几分钟就能拉到最新版第二Homebrew的formula维护存在滞后有时候版本不是最新的。如果你只是图省事brew装也行但想追新版本还是用npm。另外务必去GitHub上的openai/codex仓库看一眼官方文档里面会写清楚不同版本对Node的要求、已知问题、配置方法。很多人装完出现奇怪问题其实去Issues里搜一下马上就有答案比在论坛问效率高得多。还是那句话别去第三方网站下载“Codex破解版安装包”这工具本来就是免费的第三方渠道只可能给你加料。3. 实操过程Windows/Mac/Linux三平台安装全流程3.1 Windows原生终端安装不需要先搞WSL先说结论现在的Codex在Windows上原生就能跑不需要为了装它去开WSL。网上的老教程可能让你先装WSL再装Ubuntu那是早期弯路现在已经没必要了。Windows安装步骤第一步装好Node.js LTS版本并确认node -v有输出。如果之前装过旧版本建议先卸载干净再装新版不然可能出现node命令找不到的情况。第二步以管理员身份打开PowerShell执行npm install -g openai/codex等它跑完理论上就装好了。但很多人在这一步会遇到PowerShell执行策略限制具体报错是“无法加载文件...因为在此系统上禁止运行脚本”。解决办法Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser输入Y确认然后重新打开PowerShell。这个操作只是允许本机脚本运行不会有什么安全隐患。第三步验证安装codex --version如果输出一个版本号恭喜你装上了。如果提示“codex不是内部或外部命令”通常是npm全局目录没加到PATH后面排查章节会专门说。我额外提醒一个Windows下容易踩的坑如果你的Windows用户名是中文npm的全局路径会默认指到C:\Users\中文名\AppData\Roaming\npm有些老程序对中文路径处理不好。建议手动改一下npm全局前缀执行npm config set prefix C:\npm-global然后把C:\npm-global加到PATH里再重新安装一次Codex。这一步不是必须的但如果你的用户名是中文提前改了能省不少后面的麻烦。3.2 macOS两种方式对比推荐npmmacOS装Codex有两种主流方式我给出对比安装方式安装命令优点缺点Homebrewbrew install codex依赖管理统一卸载干净版本更新可能滞后npmnpm install -g openai/codex版本最新跟官方发版同步需要Node环境我更推荐npm方式理由前面说过主要是版本同步问题。Apple Silicon芯片M系列的Mac没有任何特殊要求Node.js官方包和npm会自动识别arm64架构不用手动处理。macOS下最容易遇到的问题就是“权限不足”。如果你执行npm install -g时看到“EACCES: permission denied”之类的报错不要直接加sudo那是把问题延后而不是解决。正确做法是用nvm管理Nodecurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 22 nvm use 22用nvm装的Nodenpm全局目录在当前用户目录下不会碰到系统目录的权限问题装Codex自然就不需要sudo了。这也是我在这台M系列Mac上实测最稳的方案。装完同样验证一下codex --version3.3 Linux以Ubuntu/Debian为例服务器也能装Linux环境下我按Ubuntu/Debian举例其他发行版思路一样区别只在包管理器。第一步装Node.js和Git。如果前面准备工作已经做完这步就跳过。第二步全局安装Codexsudo npm install -g openai/codex这里我用的是sudo因为系统级npm目录需要root权限。如果你不想给npm全局权限可以像macOS那样配置用户级npm目录把全局bin写到~/.bashrc里。配置方法其实不复杂执行npm config set prefix $HOME/.npm-global echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新安装Codex。这样以后装任何全局npm包都不用sudo了。第三步验证codex --versionDebian、Fedora、Arch这三类系统的差异我简单列一下方便对号入座系统包管理器Node安装建议Ubuntu/DebianaptNodeSource仓库或二进制包Fedora/RHELdnfNodeSource仓库Arch/Manjaropacmanpacman -S nodejs npm 或 nvmLinux服务器上装Codex还有一个实际好处它可以在CI流水线里跑也可以在远程开发机上通过SSH操作。团队协作的时候把Codex装到统一的开发环境里大家用起来省很多事情。3.4 一键安装脚本到底怎么用很多朋友想要“一键安装脚本”核心诉求是省事不要手动装Node、配PATH、改权限一条命令搞定。我写了一个通用bash脚本实测在macOS和Ubuntu上都能跑思路是先检测系统类型再检测已有依赖缺啥装啥最后用npm装Codex。脚本内容如下#!/usr/bin/env bash set -e # 检测是否需要安装 git if ! command -v git /dev/null 21; then echo [1/4] 未检测到 git开始安装... if [[ $(uname) Darwin ]]; then brew install git else sudo apt-get update sudo apt-get install -y git fi else echo [1/4] git 已安装跳过 fi # 检测 node/npm 版本 if command -v node /dev/null 21; then NODE_VERSION$(node -v | sed s/v// | cut -d. -f1) if [ $NODE_VERSION -lt 20 ]; then echo [2/4] Node.js 版本过低需要 20请先升级 Node.js exit 1 else echo [2/4] Node.js 版本满足要求$(node -v) fi else echo [2/4] 未检测到 Node.js请先安装 Node.js 20 exit 1 fi # 安装 codex echo [3/4] 开始安装 openai/codex... npm install -g openai/codex # 验证 echo [4/4] 验证安装... codex --version echo 安装完成直接在终端输入 codex 开始使用用法很简单chmod x install_codex.sh ./install_codex.shWindows用户想要类似效果可以用PowerShell脚本。但Windows下最省心的方法其实还是手动三步装Node、改执行策略、npm全局安装。因为Windows的环境差异太大脚本要考虑的边界情况反而比bash版本多不少。关于一键脚本我必须啰嗦一句网上任何来路不明的脚本执行前一定要先打开看看内容搞清楚每一行在干什么再跑。这个习惯不管在哪个平台都适用。我的脚本顶多帮你检测环境和装包不需要任何系统级敏感操作。如果你看到某些脚本里有curl ... | sudo bash这种套娃写法又看不懂里面内容最好别执行风险自担。4. 安装完成后的第一次运行认证与配置4.1 两种登录方式API Key和ChatGPT账号装完之后直接在终端输入codex第一次运行会进入登录引导它会让你选择认证方式。目前主流就两种。第一种是API Key方式。到OpenAI的platform后台创建一个API Key创建好之后在终端里这样配置codex --api-key sk-你的一长串key或者直接设置环境变量export OPENAI_API_KEYsk-你的一长串keyWindows PowerShell用户对应命令$env:OPENAI_API_KEYsk-你的一长串key第二种是ChatGPT账号登录。如果你有ChatGPT订阅可以直接选“Sign in with ChatGPT”浏览器会弹出一个授权页面登录后终端自动完成认证。这种方式的好处是不用管API Key适合日常使用缺点是对账号类型有要求免费账号的权限会受限制而且有些自动化功能可能用不了。配置好之后你可以先跑一个最简单的对话验证codex 你好介绍一下你自己能正常回复说明Codex已经能跟模型服务通信了安装工作到这里才算真正完成。4.2 配置文件的保存位置和几个常用设置Codex的配置文件保存在~/.codex/config.toml。你可以手动打开编辑也可以用codex交互界面里的配置指令来改。我建议新手至少了解三个配置项。第一个是默认模型。如果没特别设置Codex会用它在那个版本里的默认模型。你可以在config.toml里这样指定model gpt-5-codex第二个是模型提供方。默认是OpenAI但你也可以加第三方提供方下面会讲。第三个是沙箱模式。Codex执行命令时会走沙箱隔离限制它对系统的访问权限。测试阶段我建议保留默认的沙箱设置等熟悉之后再考虑放开。如果遇到Codex要读写某些特殊目录但被沙箱拦截可以查一下对应版本的沙箱参数说明别一上来就关掉沙箱不然AI真给你跑了一条危险命令哭都来不及。4.3 可选的扩展把Codex接到其他模型现在很多人不满足于只用OpenAI的模型想接入其他服务比如DeepSeek。Codex CLI其实支持自定义model provider在~/.codex/config.toml里加一段配置即可大致长这样[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY这里base_url要以你所用服务官方文档给出的地址为准env_key对应存放API Key的环境变量名。配置好之后运行Codex时指定provider和模型codex --model_provider deepseek --model deepseek-chat接第三方模型的时候要注意Codex的很多自动化功能依赖模型调用工具也就是function calling。如果目标模型不支持工具调用Codex能做的事会大打折扣可能只能做纯文本问答没法读写文件、执行命令。所以不是所有兼容OpenAI接口的模型都能完美跑Codex接入前先确认模型能力。5. 踩坑记录我在安装和使用中遇到的典型问题5.1 “cc switch local proxy failed while handling codex endpoint /responses”这个报错这个报错很多人在刚开始用Codex的时候遇到终端里刷出一长串日志里面有“local proxy failed”“codex endpoint /responses”这些关键词看着像是Codex本身崩了其实跟Codex客户端一点关系都没有。这个报错的意思是Codex在向API服务发请求时走了本机配置的HTTP代理但代理地址、端口或者认证信息有问题导致请求发不出去。我遇到这个报错是在公司内网环境。公司网络要求所有外部请求走统一代理但代理服务偶尔不稳定Codex的请求就被打断了。排查步骤我按顺序列出来第一步查看代理环境变量。macOS/Linux执行echo $http_proxy echo $https_proxyWindows PowerShell执行echo $env:http_proxy echo $env:https_proxy如果有输出说明有代理设置在工作。第二步查看npm代理配置npm config get proxy npm config get https-proxy第三步确认这个代理是不是必须的。如果是公司内网要求检查地址、端口、认证信息是否写对了如果只是之前折腾其他工具留下的系统代理可以清掉相关环境变量再重试。第四步如果根本不需要代理直接清空unset http_proxy https_proxy all_proxyWindows PowerShell对应Remove-Item Env:http_proxy, Env:https_proxy, Env:all_proxy清完重启终端再执行codex。还有一种做法是在环境变量里给API域名设NO_PROXY把api.openai.com加进去让它绕过代理直连。这个方法在保留公司代理的同时可以解决Codex请求失败的问题。这个报错还有一个坑它会先输出一堆类似“resume failed”的日志容易误导人往会话恢复的方向排查。我的经验是看到local proxy关键字先查代理别浪费时间去看别的。很多人重装了好几遍Codex也没解决其实就是代理环境变量在作怪。5.2 codex命令找不到command not found / 不是内部或外部命令这个问题在Windows上尤其常见。安装过程没报错但输入codex就提示“不是内部或外部命令”。原因只有一个npm的全局bin目录不在PATH环境变量里。排查方法先查npm全局目录npm config get prefixWindows默认通常返回C:\Users\你的用户名\AppData\Roaming\npm把录这个路径加到系统PATH里。macOS/Linux通常是/usr/local或者~/.npm-global后者的话别忘了在shell配置里加export PATH$HOME/.npm-global/bin:$PATH如果是用nvm装的Node全局路径一般在~/.nvm/versions/node/v22.x.x/binnvm一般会自动处理PATH但如果你手动改过shell配置也可能把这个路径挤掉了。我建议执行npm bin -g看输出路径再确认这个路径确实在PATH里。改完PATH之后记得重开终端再试不会立刻生效。还有一个小概率情况安装过程中npm报了下载失败但被忽略Codex包没真正装到位。这时重新执行一遍安装命令留意输出里有没有added 1 package或者error字样。5.3 Node版本不匹配导致安装失败如果你在npm安装时看到关于engine的报错十有八九是Node版本问题。报错信息里会直接要求某个Node版本范围低版本装不上。解决思路是用版本管理器不要手动卸载重装。Windows推荐nvm-windowsmacOS/Linux用nvm或fnm。以nvm为例nvm install 22 nvm use 22日常开发如果还有其他项目依赖特定Node版本用nvm切换比固定一个全局版本的灵活性大得多。我是建议无论什么平台Node环境一律用版本管理器来管能省下很多环境冲突的麻烦。5.4 安装速度慢、超时怎么办npm默认官方源在某些网络环境下下载速度确实一般安装openai/codex时经常卡在某个依赖包上下不动。这时可以临时切到国内镜像源npm install -g openai/codex --registryhttps://registry.npmmirror.com如果以后都想用镜像可以设置成默认npm config set registry https://registry.npmmirror.com这里我要提醒一点镜像源有时候同步不及时当你发现安装的Codex版本落后于官方好几个版本时运行npm install -g openai/codexlatest重新装一次。如果真的嫌镜像源太慢也可以换回官方源装最新版各取所需。还有一种情况是安装中某个二进制文件下载失败Codex的安装过程会拉一些平台相关的二进制包。这种偶发失败通常重试一次就能解决不放心的话先清npm缓存再试npm cache clean --force5.5 常见问题速查表问题现象主要原因第一排查动作codex命令找不到npm全局bin不在PATH执行 npm config get prefix把目录加入PATHnpm安装报engine错误Node.js版本过低用nvm切换Node 20.11PowerShell禁止运行脚本执行策略限制Set-ExecutionPolicy RemoteSigned安装卡住或超时网络波动换npmmirror镜像重试请求时报local proxy failed本机代理配置异常检查http_proxy/https_proxy环境变量登录后无法对话API Key失效或余额不足去OpenAI平台确认Key状态第三方模型无法读写文件模型不支持工具调用换支持function calling的模型Codex这个工具安装只是第一步真正值钱的是装好之后怎么把它嵌进工作流里。最后分享两个小经验第一次跑Codex的时候先拿一个小目录练手比如一个只有几个文件的Python脚本项目让它做一次重构或者补测试熟悉一下它的交互节奏不要一上来就扔一个庞大的monorepo给它那样容易失控。第二个建议是如果企业内网环境经常出幺蛾子平时可以把代理环境变量写进专门的脚本在启动Codex前加载、不需要时清空省得每次手动处理。我个人实际用下来Codex的日常开销主要集中在模型调用上工具本身非常轻量装好之后几乎不用管。最后再啰嗦一句安装包走官方渠道登录用自己账号遇到问题先去本地日志和环境变量里找原因比到处重装靠谱得多。