如果你和我一样每天有三分之一的时间泡在终端里那2026年你大概率已经听说了Codex CLI这个名字。它是OpenAI官方的命令行AI编程助手在终端敲一个codex它就能读你仓库里的代码、按你的要求改文件、跑测试再把diff摆在你面前等你确认。和网页版比起来CLI最大的价值是能真正接触你本地的项目而不是在一个聊天框里空对空。这篇东西我拖了很久才写。网上教程要么只讲Windows要么只讲Mac很少有人把三大平台和VSCode串在一起讲。这篇文章就围绕Codex CLI安装配置这件事把Windows、macOS、Linux、VSCode四条路一次走通。无论你是刚接触命令行的小白还是已经在CI里跑自动化脚本的老手按下面的步骤走基本不会再被安装环节卡住。1. 安装前的核心认知先弄清楚自己需要哪个Codex1.1 Codex CLI到底是什么和网页版、桌面版有什么区别很多人第一次接触Codex是通过浏览器里的网页聊天界面后来OpenAI又出了桌面应用再加上CLI三样东西都叫Codex但定位完全不一样。网页版适合零散提问比如“帮我看看这段SQL哪里有问题”“这个正则解释一下”。它不会碰你本地的文件聊完就结束了。桌面版适合不爱碰命令行的人界面更友好能直接编辑文件但自动化能力弱。CLI则是给开发者准备的“硬核模式”它跑在终端里直接以当前目录作为工作区能调用git、读取文件、执行命令、修改代码。我在实际使用中的理解是CLI更像一个“住进你项目里的实习生”。你说需求它先分析仓库结构给出改动方案每步操作前问你同不同意。网页版做不到这一点因为它看不到你硬盘上的东西。所以如果你想把AI真正嵌入到日常开发流程里CLI是绕不开的那一环。桌面版你可以有但CLI才是脚本、CI、远程服务器场景下的唯一解。1.2 安装前置条件Node.js版本、Git、终端与账号Codex CLI通过npm分发所以第一个前提是装好Node.js和npm。我不只一次看到有人卡在报错上最后发现Node版本是12、14这种老古董根本跑不动。建议直接上Node.js 20 LTS及以上我实测22 LTS最稳。检查命令node -v npm -v如果没有输出或者版本太低先去Node官网下载LTS版本安装。Windows用户直接跑安装包macOS和Linux用户建议用nvm管理后面会细说。第二个强烈建议是Git。Codex CLI会把整个项目当成git仓库来看待diff、撤销改动全靠git。Windows上装Git for Windows时记得勾选“Add to PATH”否则在PowerShell里找不到git命令。第三个是终端。Windows上我推荐Windows Terminal加PowerShell 7或者干脆用Git BashmacOS用自带的Terminal或iTerm2都行Linux直接系统终端。VSCode内置终端也算后面第三节专门讲。账号层面你需要一个OpenAI账号以及下面两种认证方式中的任意一种ChatGPT账号登录或者API Key。这两条路的区别我放到1.3讲。1.3 认证方式ChatGPT账号登录还是API KeyCodex CLI的认证有两种模式很多人第一次就在这里被绕晕。第一种是ChatGPT账号登录。首次运行codex它会拉起浏览器跳转到OpenAI的登录页面授权后回调到本地地址终端显示“登录成功”。这个方式对普通用户最友好不需要管Key但有个缺点在无浏览器环境、远程服务器里会卡住而且每次换机器都要重新登录。第二种是API Key模式。打开OpenAI平台进入API keys页面创建一个Secret Key然后在终端里设置成环境变量export OPENAI_API_KEYsk-你的key设置好后直接运行codexCLI检测到环境变量就会自动采用API Key模式不再弹浏览器。这个方式适合服务器、CI、脚本场景。我的建议是本地日常开发用ChatGPT登录省事服务器和自动化环境用API Key不会遇到“认证卡住”“设置未完成”这类问题。安全提醒一句API Key相当于你账号的钥匙千万别写进代码仓库也别截图发到群里。我见过有人把Key硬编码在配置文件里然后推到GitHub几分钟就被盗刷了。环境变量是底线更讲究的可以用密钥管理服务。2. 三大平台安装实操Windows / macOS / Linux2.1 WindowsPowerShell、npm与两大高发报错Windows是Codex CLI安装问题最多的平台但不是因为Codex本身复杂而是PowerShell和npm在Windows上有一些历史包袱。我先把标准流程过一遍再把高频报错单独拎出来讲。第一步装好Node.js LTS和Git for Windows检查node -v、npm -v、git --version三个命令都有输出。第二步按Win X打开PowerShell注意这里用普通用户身份不要“以管理员身份运行”。运行全局安装命令npm install -g openai/codexlatest为什么强调不要管理员因为npm在Windows上的全局目录是%APPDATA%\npm普通用户本来就有写权限。一旦用管理员装了全局包之后每次升级都要管理员权限边界变得很混乱还会在VSCode集成终端里遇到“权限不足”的诡异问题。第三步运行codex --version验证安装。如果能输出版本号说明Core已经装好接下来登录即可。接下来是两个真正的“拦路虎”。第一个是PowerShell执行策略报错。很多人在安装时看到的是这样一段话npm : 无法加载文件 ... 因为在此系统上禁止运行脚本这是PowerShell默认执行策略Restricted导致的它会拦截.ps1脚本。解决办法是在当前用户作用域下放宽策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后输入Y确认。之后重开PowerShellnpm命令就能正常跑了。如果你不想动执行策略另一个办法是直接用cmd窗口来跑npmcmd不检查执行策略。第二个是平台二进制包缺失报错长这样missing optional dependency openai/codex-win32-x64. reinstall codex: npm i -g openai/codexlatest这个报错被问得最多原因也比较隐蔽。Codex CLI在设计上用了npm的optionalDependencies机制根据平台自动安装对应的二进制包Windows装openai/codex-win32-x64macOS装darwinLinux装linux。如果npm缓存坏了、网络中断或者某个镜像源没有同步这个平台包就会出现“主包装好了但是平台包没装全”的状态。解决办法是老几样清缓存npm cache clean --force卸载npm uninstall -g openai/codex重装并强制包含optional依赖npm install -g openai/codexlatest --includeoptional如果你配置了npm镜像源建议临时切回官方源再试一次。这不是什么玄学只是镜像源同步可能滞后造成平台包不全。安装完成后首次运行codex会进入登录流程。如果浏览器没自动弹出或者弹出后一直转圈运行codex login重新走一次认证。Windows上偶尔会遇到“Codex Windows设置未完成”的提示绝大多数情况是OAuth回调没有写回终端。解决方法是把浏览器地址栏里的回调URL手动复制粘贴到终端提示的位置基本都能救回来。2.2 macOSHomebrew、nvm与权限边界macOS上的安装比Windows顺畅但也有几处需要提前绕开的坑。装Node我推荐二选一nvm或者Homebrew。用nvm的好处是版本切换灵活也不会污染系统目录。如果你用Homebrew一条命令搞定brew install node22装完检查node -v、npm -v。macOS上最大的坑是权限。很多人图省事直接sudo npm install -g openai/codexlatest装是能装上但后患无穷。因为macOS的系统Node目录是/usr/local或/opt/homebrew普通用户没有写权限sudo装完的全局包之后每次升级都要再sudo。更麻烦的是一旦哪天用nvm切换了Node版本全局包路径对不上命令就找不到了。所以我推荐的方式是先用nvm装好Node再执行npm install -g openai/codexlatest完全不需要sudo。如果你用MacBook的Apple Silicon芯片正常走这条流程装到的是arm64原生版本性能最好。万一你发现codex在活动监视器里以x86_64模式运行大概率是你的终端本身跑在Rosetta转译下需要重新安装arm64版的Homebrew或nvm。还有一个容易被忽略的点macOS的隐私权限。首次运行codex时系统可能会弹窗询问“是否允许终端访问文件”或“开发者工具权限”。一定要点允许否则后面读项目文件时会很痛苦。如果之前手滑点了拒绝去“系统设置 - 隐私与安全性”里把权限重新打开就行。如果你下载的是OpenAI官方桌面版Codex.app第一次打开可能被Gatekeeper拦截。不要慌右键点击应用选择“打开”系统会弹出确认对话框再点一次“打开”就能用了。2.3 Linux无头服务器与SSH环境下的认证Linux的安装逻辑和macOS类似但有两个特殊场景要处理系统自带Node版本太老以及没有浏览器时怎么登录。先看系统自带Node。Ubuntu/Debian的apt仓库里Node版本通常落后好几个大版本直接apt install nodejs装出来的可能是16甚至12跑不动Codex。老老实实用nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完nvm重开终端执行nvm install 22 npm install -g openai/codexlatest如果你不想用nvm也可以用NodeSource的二进制仓库但nvm最省心。然后是全局目录权限。如果非要装系统Node会遇到EACCES权限错误。官方建议是配置npm全局目录到用户目录我一般这么干npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样全局包都装在自己的home目录下权限干净。接下来是关键无头服务器。很多人的Codex是装在VPS、开发机、CI Runner上的这些环境没有浏览器ChatGPT登录流程会卡在“等待浏览器回调”。解决方式就是API Key模式export OPENAI_API_KEYsk-你的key codexCLI检测到OPENAI_API_KEY环境变量后会跳过OAuth引导直接用API Key完成认证。之后你想在任何新服务器上快速复用把这一行export写进~/.bashrc或~/.zshrc永久生效。如果你是通过VSCode Remote-SSH连到远程服务器开发Codex其实跑在远程机器上文件也是远程的。本地VSCode窗口只是显示界面而已。所以远程机器能访问OpenAI API就能正常用如果发现调用超时先检查远程服务器的网络出口而不是折腾本地配置。3. VSCode集成、Shell与编辑器玩法3.1 VSCode官方扩展与CLI的关系标题里说“VSCode一篇搞定”这里展开讲。2026年OpenAI官方Codex扩展已经比较成熟了你直接在VSCode扩展市场搜索“Codex”认准OpenAI官方发布者安装即可。但要注意一个关系官方扩展并不是一个独立工具它复用的是你本地已经装好的Codex CLI。换句话说扩展是“面条”CLI才是“汤底”。你装了扩展但CLI没装、没登录扩展面板打开后什么都干不了。所以第三节内容必须建立在前面的CLI安装完成之上。安装扩展后左侧边栏会出现Codex图标。打开面板你可以直接对话、查看Codex生成的改动、审阅diff。实际体验下来面板适合“可视化审阅改动”的场景但如果你是纯键盘流我反而推荐直接用集成终端跑CLI两种方式各有取舍不冲突。3.2 在VSCode集成终端中使用CodexVSCode内置终端本质上是操作系统终端的嵌入式版本Windows默认走PowerShell。如果你在Windows上没解决执行策略问题VSCode终端里跑codex也会报同样的“禁止运行脚本”错误。所以先回到2.1把执行策略设好或者把默认终端Profile改成Git Bash一劳永逸。打开集成终端的快捷键是Ctrl然后直接输入codex进入交互模式后你可以像聊天一样描述需求。Codex会给出它的执行计划涉及修改文件、运行命令时每一步都会停下来问你确认。我个人建议第一次用某个项目时先在测试仓库里跑别直接在大型生产仓库上试因为AI的“热情”可能超乎你想象。VSCode终端里还有一个优势是分屏。左边是Codex对话右边是代码编辑器你可以实时看它改了哪些文件。配合VSCode的源代码管理面板改动一目了然不满意就直接还原比纯终端体验好很多。如果你觉得每次输入codex麻烦可以在配置里加一个别名。macOS/Linux的~/.bashrc或~/.zshrc里写alias cxcodexWindows PowerShell里可以在$PROFILE文件里加Set-Alias cx codex之后输入cx就能进入效率高不少。3.3 配置文件与模型选择Codex CLI的配置目录是~/.codex主要的配置文件是config.toml。Windows上位于C:\Users\你的用户名\.codex\config.tomlmacOS和Linux在~/.codex/config.toml。首次运行Codex后会自动生成一般不需要手动创建。这个配置文件是TOML格式网站和很多工具都在用语法很简单。我常用的配置项大概是这个样子model gpt-5-codex approval_policy on-request [history] enabled true解释一下这几个字段的作用。model控制使用哪个模型。不同时期OpenAI会有不同的Codex优化模型默认值通常是最适合编程的版本。我的建议是先用默认不要盲目追新。真要切换模型在这个字段改然后保存重启codex即可。approval_policy控制Codex执行操作时的确认策略。on-request表示每次修改文件、执行命令前都会问你。如果你非常信任当前项目也可以设成更宽松的自动执行但我不建议特别是对有git历史的重要仓库。AI写得快改得也快出问题的时候连代码和错误信息一起给你恢复成本全在被确认的每一次操作里。[history]控制历史记录是否保存写代码时保持开启方便回溯之前的对话。不同版本的Codex配置字段可能会有差异最准确的做法是运行codex --help或者在VSCode命令面板里找“Codex: Open Settings”以实际版本输出为准。4. 高频报错排查速查表从Windows踩到Linux这一节算是我这份教程里最值钱的干货。下面这些报错我多多少少都在真实环境里见过有些甚至是反复出现的经典问题。直接做成速查表按现象查原因按原因给解法。4.1 Windows高频报错速查表报错现象原因解决方式npm : 无法加载文件 ... 因为在此系统上禁止运行脚本PowerShell执行策略为RestrictedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUsermissing optional dependency openai/codex-win32-x64. reinstall codexnpm平台包没装全缓存或镜像源问题清缓存、卸载、用--includeoptional重装codex : 无法将“codex”项识别为 cmdlet、函数、脚本文件或可运行程序的名称npm全局目录没加到PATH或终端没重开重开终端检查%APPDATA%\npm是否在PATH首次运行提示“Codex Windows设置未完成”OAuth回调没有回到终端运行codex login重新认证手动粘贴回调地址engine unsupported或类似报错Node版本太低升级到Node 20 LTS以上推荐22 LTSnpm install时频繁超时或下载中断网络到npm官方源不稳定配镜像源npm config set registry https://registry.npmmirror.com清缓存重装本地回调端口被占用报端口相关错误上一次运行的进程没退出netstat -ano这里再啰嗦一句npm config set registry切镜像源是常规加速手段装完遇到诡异的平台包问题时如果镜像不全记得先切回官方源再重装两者来回切换能解决一大半“装不完整”的问题。4.2 认证、模型与网络类问题速查表codex login或首次运行时浏览器没有自动弹出点击无反应这个情况在Windows和Linux服务器上都出现过。解法是把终端输出的授权链接手动复制到浏览器访问授权后浏览器跳转到类似http://localhost:...的回调地址如果页面打不开把这段地址复制回终端回车Codex会继续完成认证。核心思路是不要等它自动自己手动把两端的地址接上。API Key模式下出现401 unauthorized一般是Key不正确、过期或者账号没有对应模型的访问权限。重新去OpenAI平台生成一个新Key确认环境变量用的是新值然后重开终端。模型返回类似“model not available”的提示大概率是当前账号对那个模型没有访问权限。去OpenAI平台查看账号的模型权限如果确实没有切换回默认模型。还有一种容易被忽略的情况明明设置过OPENAI_API_KEY但Codex还是弹出登录界面。先确认环境变量是否真的生效echo $OPENAI_API_KEYLinux/macOS或echo $env:OPENAI_API_KEYPowerShell。如果输出为空说明变量设置没成功或者终端打开时变量还没写入。4.3 排查思路先看日志再动配置遇到问题不要慌先按三步走能省很多时间。第一步确认装上没有运行codex --version。如果版本号能出来说明主程序没问题问题多半出在认证或配置。如果命令都找不到回到PATH和全局目录的排查。第二步确认认证通不通运行codex exec say hello这是一个最简单的非交互请求。如果它能正常返回说明认证、网络、模型链路都是通的返回401或超时就去查Key和网络。第三步确认工作区环境codex exec explain this repository看它能不能正确读取项目结构。如果卡住或报权限错误检查当前目录是不是git仓库、文件权限是不是只读、Windows下有没有被OneDrive或云同步软件锁住文件。很多人在这一步栽跟头是因为Codex默认按git仓库的边界来判定改动范围。你在一个没有git init的目录里跑它要么拒绝执行要么行为很怪异。进项目前先git init或git clone是最基本的自觉。5. 从会用到用好几条实操习惯与配置建议5.1 三平台通用的安装习惯这篇教程走到这里安装已经没有秘密了。最后聊几个能让你长期舒心的习惯。第一个是用版本管理器装Node。Windows上可以用nvm-windowsmacOS和Linux用nvm装好之后Node版本随时切换全局包不会因为系统升级而失效。用系统自带的Node一旦哪天系统更新了版本全局包目录就乱了你都不知道自己装的codex去哪了。第二个是永远用普通用户身份跑npm和codex。Windows别右键管理员macOS别sudoLinux别用root。全局npm包装在用户目录下权限清晰升级方便还能避免很多“根目录污染”的问题。这个概念和家里钥匙一个道理平时用自己那把别拿总钥匙到处开丢了更麻烦。第三个是养成“先更新再排查”的习惯。Codex迭代速度很快你今天遇到的一个灵异报错可能三天前的新版本就修了。遇到问题可以先执行npm update -g openai/codex然后再复现问题。我给过很多朋友的排查建议里这一条经常直接终结战斗。第四个是API Key不进项目目录。密钥放环境变量、放密钥管理工具都可以就是不放进代码仓库。这个习惯能帮你避开99%的密钥泄露事故。5.2 把Codex用进日常工作的几个建议安装配置只是起点真正决定体验的是你怎么用它。我建议从“解释代码”开始。接手一个新项目第一件事不是改需求而是跑codex exec explain the architecture of this repository and point out the entry point让它先复述对项目的理解。如果它讲的和你看到的代码一致说明它真的读懂了项目你才放心让它改。第二步是让AI“给方案你执行”。比如让它列出重构计划或者写一份改动清单然后你手动操作关键文件。这个阶段你会逐渐熟悉它的能力边界知道什么场景靠谱、什么场景需要盯紧。第三步才是让它直接改但每次改动都要看diff。VSCode的源代码管理面板在这时最有用一行一行看确认没问题再保留。Codex不是不可信任而是它“太配合了”你说改A它可能顺手把B也改了审diff能及时发现这种越界行为。最后一个小技巧不要在工作目录里塞太多无关文件。Codex读取仓库结构时如果项目里有几百兆的模型文件、node_modules、日志文件它的分析速度和准确度都会受影响。把无关内容加进.gitignore或者干脆在干净的小项目里试体验会顺很多。我对Codex CLI的体会是安装环节的坑都是“纸老虎”无非是Node版本、执行策略、平台包缺失这几个老问题按速查表一个个对十分钟内都能解决。真正的难点是怎么在和AI协作的过程里保持对代码的控制权——从一开始就养成看diff、分批操作、保持git历史干净的习惯你就能把它当作一个靠谱的结对编程伙伴而不是一个偶尔闯祸的自动补全。从看懂它的每一步改动开始再让它放手干你会比大多数人少踩很多坑。