Codex 这段时间在开发者圈子里讨论热度一直很高。简单说它是 OpenAI 推出的 AI 编程助手既能跑在终端命令行里也能作为插件嵌入 VS Code、JetBrains 这类 IDE帮你生成代码、解释报错、写测试、做代码审查。相比以前把代码复制到网页对话框里来回折腾Codex 更像是直接在开发环境里多了一个结对编程的搭子。这篇文章我会把 Codex 在 Mac 和 Windows 上的安装完整走一遍包括 CLI 命令行工具和 IDE 插件两种使用方式登录认证、环境变量、插件配置、常见报错的排查思路都会覆盖到。适合刚开始接触 Codex、或者装到一半卡住不知道怎么继续的朋友参考。1. Codex 到底是干什么的为什么值得装1.1 CLI 和 IDE 两种形态的定位差异Codex 和 ChatGPT 网页版最大的区别在于它直接长在你的开发环境里。CLI 版本是一个终端命令你在项目目录下敲一句codex它就能读取当前目录的代码文件结合你的问题给出修改建议或者直接生成补丁。IDE 版本则是把同样的能力嵌进编辑器侧边栏或者对话面板不用离开编码界面就能交互。两种形态各有各的适用场景。CLI 适合快速执行、脚本化操作尤其是你想在服务器或者远程机器上跑或者在终端里做批量代码处理的时候非常方便。IDE 插件则适合日常写代码过程中的实时交流比如选中一段代码让 Codex 解释、优化、补测试这些操作在编辑器里完成是最顺手的。需要注意的一点是IDE 插件本身依赖 CLI 才能工作。也就是说无论你最终打算用 VS Code 插件还是 JetBrains 插件第一步永远是先把 Codex CLI 装好并完成登录认证。这个依赖关系很多人容易忽略后面排查问题的时候也经常会绕回来。1.2 适合谁用装机成本有多高如果你是前端、后端、脚本语言开发者日常要写大量样板代码、正则表达式、单元测试或者经常被各种编译报错折磨Codex 能明显减少这些重复劳动。对于刚入门编程的同学Codex 也能充当一个随时在线的导师解释代码逻辑、帮着梳理报错原因。安装成本其实不高。CLI 版本本质上是一个 npm 包依赖 Node.js 环境装上之后跑一次登录就完事。IDE 插件也是从扩展市场直接安装安装完成后和 CLI 关联一下即可。整篇文章走下来最快十几分钟就能跑通。2. 开工之前账号、系统和环境准备2.1 账号准备ChatGPT 账号与 API Key 二选一安装 Codex 之前先把账号问题想清楚因为后面登录那一步一定会用到。Codex 支持两种认证方式一种是用 ChatGPT 账号直接登录输入codex login后它会给你一个链接在浏览器里打开并授权即可另一种是使用 API Key把密钥配置到环境变量里适合没有浏览器或者无法交互登录的服务器环境。如果你平时已经在用 ChatGPT Plus 或者 Pro 会员直接用账号登录体验最完整订阅额度会关联在一起。如果你只打算偶尔调一下 API那就申请一个 API Key 用多少算多少。这里没有绝对的对错按自己的使用频率和付费习惯来选。要提醒一句的是API Key 属于敏感凭证不要提交到 Git 仓库也不要随意分享给别人。一旦泄露别人可以用你的额度调用服务造成不必要的损失。2.2 系统要求和依赖软件清单先把软硬件环境捋一遍避免装到一半才发现版本不满足。操作系统macOS 12Monterey及以上Windows 10 及以上。Apple Silicon 和 Intel 芯片的 Mac 都可以正常安装。Node.js建议 18 LTS 或者 20 LTS 以上版本。npm 会随着 Node.js 一起装上这是安装 Codex 的主要途径。Git虽然不是强制要求但 Codex 经常配合 Git 仓库工作在代码提交前做审查、生成 commit message 都很好用建议提前装好。终端Mac 用自带的 Terminal 或者 iTerm2 都行Windows 推荐 Windows Terminal交互体验比老旧的 cmd 好太多。检查 Node.js 版本可以在终端输入node -v npm -v如果提示命令不存在说明还没装 Node.js或者安装时没把路径加进系统环境变量这一步先补上再继续。2.3 网络与环境变量检查这一步经常被跳过但恰恰是后续各种奇怪报错的根源。Codex 在安装和请求过程中都需要正常的网络出口如果你的机器设置了系统的网络代理前后配置不一致很容易出现连接失败。在终端里先检查一下有没有残留的代理环境变量env | grep -i proxyWindows PowerShell 下可以输入Get-ChildItem Env: | Where-Object { $_.Name -match proxy }如果有输出说明当前终端环境里设置了代理相关的变量确认这些变量的地址和端口是否仍然有效如果代理已经关闭最好先清掉这些变量再继续安装。很多“安装未完成”“请求失败”都跟这个细节有关。3. Mac 端安装 Codex CLI完整步骤与避坑3.1 安装 Node.js 的两种方式Mac 上安装 Node.js 常见的有两种方式一种是直接去 Node.js 官网下载 pkg 安装包双击一路下一步就行另一种是先用 Homebrew 装 Node再通过 npm 继续装 Codex。如果你经常用 Homebrew 管理开发软件我建议直接走 Homebrewbrew install node这个命令会把最新的 Node.js 和 npm 一起装好。安装完成后检查一下版本node -v npm -v如果之前装过 Node.js 但是版本偏低可以先用brew upgrade node升级到最新稳定版。老版本 Node.js 可能导致 Codex 安装过程中出现依赖解析失败的问题优先排除这个变量。3.2 用 npm 安装 Codex CLINode.js 就绪后安装 Codex 就是一条命令的事npm install -g openai/codex这里-g参数表示全局安装装完后codex命令对所有终端会话都可用。如果你不想全局安装也可以去掉-g在项目目录下作为局部依赖使用但那样每次调用需要通过npx codex或者配置 npm scripts稍微麻烦一些日常使用还是建议全局安装。安装过程中如果看到一堆npm WARN提示通常不用太在意只要最终出现类似added xxx packages的字样并且没有npm ERR!开头的报错就说明安装成功了。3.3 环境变量 PATH 配置和使用验证npm 的全局安装目录通常不在系统默认 PATH 里尤其是通过 Homebrew 安装 Node.js 的机器npm 全局 bin 目录一般位于/opt/homebrew/binApple Silicon 芯片或者/usr/local/binIntel 芯片。如果安装完成后执行codex提示 command not found大概率就是 PATH 没包含这个目录。验证方式很简单npm prefix -g这个命令会输出 npm 全局目录的路径检查一下这个路径下的bin目录是否在 PATH 里。如果不在需要修改~/.zshrc文件添加一行export PATH$(npm prefix -g)/bin:$PATH保存后执行source ~/.zshrc让配置生效。然后再输入下面的命令验证codex --version输出codex的版本号就说明 CLI 已经能正常使用了。3.4 Mac 安装时的高频坑第一个坑是权限问题。如果你在终端里执行npm install -g时遇到EACCES: permission denied之类的报错说明 npm 没有权限往全局目录写入文件。很多人第一反应是加sudo但sudo npm会改变全局包的文件属主后续更新和卸载容易出问题。更好的做法是通过npm config set prefix把全局安装目录改到用户目录下或者使用nvm管理 Node.js 版本从根源上避免权限问题。第二个坑是旧版本残留。如果你之前在机器上装过 Codex 的测试版或者旧版本升级新版本前最好先卸载干净npm uninstall -g openai/codex然后再重新安装避免新旧版本的配置文件和二进制文件混在一起导致登录状态错乱。第三点是 Mac 从 App Store 下载的 Xcode Command Line Tools 如果缺失某些 npm 原生依赖编译可能会失败。遇到编译错误时可以运行xcode-select --install补一下开发工具再回来重新安装。4. Windows 端安装 Codex CLI完整步骤与避坑4.1 Windows 环境准备Terminal 与 Node.jsWindows 上安装 Codex 的整体思路和 Mac 一样都是先装 Node.js再用 npm 装 Codex。但 Windows 的环境有一些特殊的地方需要单独处理。终端建议使用 Windows Terminal。它支持多标签页、更好的配色方案对命令行工具的兼容性也更好。如果你机器上还没装可以去微软商店搜 Windows Terminal 安装免费。Node.js 的安装也建议走官网下载 Windows Installer.msi安装包。安装过程中有一步会问是否添加到 PATH一定要勾选上否则装完 Node.js 打不开终端命令后续 Codex 安装也会跟着出问题。4.2 安装 Codex CLI 并验证Node.js 装好之后打开 Windows Terminal或者 PowerShell执行npm install -g openai/codex如果你使用的是 PowerShell执行全局安装的 npm 包时可能会遇到执行策略限制报错内容一般是 “无法加载文件因为在此系统上禁止运行脚本”。这个问题的根源是 Windows 默认的脚本执行策略是 Restricted解决方法是把执行策略改成 RemoteSignedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令只对当前用户生效安全风险可控。修改后再执行codex --version如果能正常输出版本号说明安装成功。如果提示 codex 不是可识别的命令去检查一下 npm 全局目录是否在系统 PATH 里。可以通过下面的命令查看 npm 全局 bin 路径npm prefix -g然后把这个路径下的目录加到系统环境变量的 Path 中或者重新打开一个终端窗口让它重新加载环境变量。4.3 Windows 特有的权限与兼容性问题Windows 上遇到最多的问题之一就是被杀毒软件拦截。npm 在安装过程中会创建大量临时文件部分实时防护软件会扫描这些文件导致安装过程非常慢甚至直接中断。如果你发现npm install卡了很久没反应可以暂时关闭实时防护或者把 npm 的缓存目录加入白名单等安装完成后再恢复。另一个常见情况是 Windows 的路径长度限制。npm 在安装多层嵌套依赖时如果项目路径很深再加上 Windows 默认的 MAX_PATH 限制容易出现意外的安装失败。解决办法是在 Windows 设置里开启长路径支持路径为设置 - 系统 - 系统信息 - 高级系统设置 - 环境变量新建一个名为NODE_OPTIONS的用户变量值为--max-old-space-size4096同时把路径长度限制相关的注册表项打开。大多数情况下新建环境变量后重启终端就能解决。4.4 Mac 和 Windows 安装流程对照为了让大家对两边流程有个直观认识我把对应的操作列成一个对照表步骤MacWindows终端工具Terminal / iTerm2Windows Terminal安装 Node.jsbrew install node / 官网 pkg官网 .msi 安装包安装 Codexnpm install -g openai/codex同上常见问题PATH 配置、目录权限执行策略、杀毒拦截验证命令codex --version同上两边的安装底层逻辑完全一致只是外围环境和权限策略有差异。5. 登录认证ChatGPT 登录与 API Key 的完整选择5.1 codex login 自动登录流程CLI 装好之后第一步就是登录。在终端里输入codex login代码会输出一个 URL 和一个等待授权的提示。你需要把那个链接复制到浏览器里打开用你的 ChatGPT 账号登录并点击授权。授权成功后终端会自动检测到登录状态并显示类似 “You are logged in” 的提示。登录态会保存在本地后续使用不需要重复登录。如果你有多个 ChatGPT 账号或者需要切换账号使用可以重新执行codex login或者先退出再登录codex logout codex login登录过程中如果遇到 opened a browser 之后页面打不开的情况注意看一下终端输出的地址是不是带http://开头的本地地址如果是把这个地址完整复制到浏览器打开。有些终端会自动打开浏览器但不够可靠手动复制粘贴更稳妥。5.2 无浏览器环境的 API Key 配置在服务器或者远程开发机上没有浏览器可用此时codex login的交互式登录方式就行不通了。这种情况下可以用 API Key 完成认证。首先到 OpenAI 平台创建 API Key创建后把 Key 复制下来。然后在终端设置环境变量Mac / Linuxexport OPENAI_API_KEY你的API KeyWindows PowerShell$env:OPENAI_API_KEY你的API Key为了每次打开终端都自动生效建议把环境变量写进配置文件。Mac/Linux 修改~/.zshrc或者~/.bashrcWindows 通过系统环境变量界面永久添加上去。配置完成后运行codex exec test如果 API Key 有效Codex 会正常返回结果不需要额外走浏览器登录流程。5.3 登录后如何确认配置生效登录成功后可以通过几个简单的命令确认配置是否真正生效。首先运行codex --version确认 CLI 本身没问题然后尝试让 Codex 执行一个小任务codex exec 写一个 Python 函数计算斐波那契数列前 20 项如果 Codex 正常返回代码说明 CLI 和认证链路都是通的。如果返回的是认证错误检查 API Key 是否正确、是否已过期或者账号里是否有可用额度。如果是网络错误回到第 2.3 节检查代理环境变量。6. IDE 集成VS Code 和 JetBrains 插件实战6.1 在 VS Code 里安装 Codex 插件CLI 跑通之后现在进入 IDE 集成环节。VS Code 是支持 Codex 最完整的编辑器之一。打开 VS Code进入扩展市场搜索 “Codex”找到 OpenAI 官方发布的 Codex 扩展点击安装。安装完成后左侧边栏会出现 Codex 的图标点击图标会展开一个对话面板。首次使用时插件会检测本机是否已经安装 Codex CLI。如果检测成功它会直接复用 CLI 的登录态如果没有检测到插件会提示你安装 CLI 或者手动指定路径。这个环节就是把 CLI 和 IDE 绑定的关键一步也是最容易出现“找不到 CLI”报错的环节。6.2 IDE 插件与 CLI 的关联配置如果你安装的 VS Code 插件提示找不到 CLI或者报错信息类似 “unable to locate the codex cli binary”需要手动确认 CLI 路径。在 VS Code 设置里搜索 “codex.path”把你的 Codex 可执行文件完整路径填进去。Mac 上通常用which codex查看真实路径Windows 上可以执行Get-Command codex | Select-Object Source。设置好路径之后重启 VS Code。此时打开 Codex 面板它会显示当前登录账号状态你就可以选中一段代码开始提问了。选中代码后右键会看到 “Explain Code”、“Find Bugs”、“Write Tests” 等快捷操作这些都是 IDE 集成带来的便利。6.3 JetBrains 系列插件的安装与配置JetBrains 家的 IDEA、PyCharm、WebStorm 等产品也都支持 Codex。打开 JetBrains IDE进入 Settings或者 Preferences- Plugins搜索 “Codex”安装官方插件后重启 IDE。重启后在右侧或者底部工具栏找到 Codex 窗口。JetBrains 插件同样需要关联 CLI配置方式在 Settings - Tools - Codex 里把 CLI 的路径填进去。有些版本也支持直接填入 OPENAI_API_KEY任选一种即可。JetBrains 版本的 Codex 功能逻辑和 VS Code 版本基本一致但也有些细节不同。比如在 IDEA 中Codex 可以读取 Spring 项目的配置文件理解上下文更充分在 PyCharm 中对 Python 的类型推断更准确。这一点在使用不同 IDE 时可以留意一下。6.4 IDE 集成常见问题IDE 集成阶段最常被问到的就是登录问题。如果你在 IDE 里点击 Codex 图标弹出的界面显示 “login” 按钮点击后跳转到浏览器却无法完成授权多半是因为 CLI 登录态和 IDE 插件之间没有建立关联。最简单的处理办法是确认codex login在终端里已经成功执行过然后重启 IDE 重新加载插件。如果还是不行把 CLI 路径重新指定一次。另一个值得注意的点是代理报错。IDE 内部的应用代理和系统代理并不总是共用同一套配置Codex 插件发请求时走的是系统网络通道如果你在 IDE 里单独设置了代理两者不一致就容易出现 “cc switch local proxy failed while handling codex endpoint /responses” 这类错误。排查思路是统一代理设置要么全部直连要么全部走同一个代理通道不要在 IDE 里额外设置和系统不一致的代理。7. 高频报错排查安装失败、登录失败、请求断开7.1 npm 安装报错与权限问题安装 Codex 时最让人头疼的就是一堆npm ERR!。我把常见的错误类型和对应的解决办法整理一下报错类型原因排查与解决EACCES: permission denied全局目录无写权限优先使用 nvm 管理 Node.js将全局安装目录改到用户目录EEXIST / file exists安装目录残留旧文件先执行 npm uninstall -g openai/codex再重新安装ERESOLVE unable to resolve dependency tree依赖树解析冲突检查 Node.js 版本是否过旧建议升级到 18 或 20 LTSnetwork timeout网络下载慢或超时检查网络稳定性必要时配置 npm 国内镜像再安装npm 镜像配置这个点值得单独说一下。如果你在国内或者网络环境不太稳定npm 默认源访问会比较慢可以用下面的命令切到镜像源npm config set registry https://registry.npmmirror.com镜像源只影响 npm 包的下载速度不影响 Codex 运行时和 OpenAI 服务端的通信所以可以放心使用。7.2 codex 命令找不到怎么办如果你已经执行了npm install -g openai/codex但运行codex仍然提示 command not found问题基本锁定在 PATH 配置上。先确认 npm 全局目录npm prefix -g然后看这个目录下的bin子目录是否在 PATH 里。Mac 用户按第 3.3 节修改 shell 配置文件Windows 用户去系统环境变量里检查 Path把对应的 bin 路径加进去然后重新打开终端。改完 PATH 之后务必开一个新终端窗口再验证因为旧窗口不会自动加载新配置。7.3 cc switch local proxy failed 一类请求报错最近在开发者社区里比较常见的一类报错是cc switch local proxy failed while handling codex endpoint /responses。这个报错的意思是 Codex 在处理请求时本地网络中继或者代理通道建立失败导致请求没能到达服务端。出现这种报错时你可以按下面的顺序逐一排查检查系统代理设置。如果你用了系统级代理工具确认端口配置是否正确、当前是否处于启动状态。检查终端环境里的代理变量。执行env | grep -i proxyWindows 上用Get-ChildItem Env: | Where-Object { $_.Name -match proxy }看 HTTP_PROXY、HTTPS_PROXY 这些变量是否指向了一个已经不存在的端口。如果你没有用代理反而是个别开发工具自动配置了代理同样的方法查出来并清掉。如果代理配置都没问题检查 DNS 解析是否正常ping api.openai.com能否返回正常的 IP。这类问题本质上是网络链路在某个环节断了和 Codex 本身安装没有关系。只要网络通道恢复一致报错自然消失。7.4 找不到 codex cli binary / 安装未完成“chatgpt failed to start. unable to locate the codex cli binary” 这类报错主要出现在 IDE 插件场景。插件需要 CLI 在系统里但它没找到。排查思路如下首先确认 CLI 真的装好了在终端执行codex --version然后确认which codexMac/Linux或者Get-Command codexWindows能返回路径最后把这个路径填到 IDE 插件的配置项里并重启 IDE。“Codex 安装未完成”也是 Windows 用户反馈比较多的问题。这种现象通常不是 Codex 本身的问题而是 npm 安装过程中因为网络中断、杀毒拦截、磁盘空间不足等原因导致安装中断。处理方法比较直接删掉 npm 缓存重新安装。npm cache clean --force npm install -g openai/codex安装过程中不要切换网络也不要合上笔记本盖子让它一次性跑完。7.5 快速自查清单如果你现在装到一半卡住了不要慌按下面的顺序过一遍[ ] Node.js 版本是否在 18 LTS 以上node -v确认[ ] npm 是否可用npm -v确认[ ] Codex 是否已全局安装npm ls -g openai/codex确认[ ] 终端能否识别 codex 命令codex --version确认[ ] 登录状态是否正常运行codex exec hello确认[ ] IDE 插件是否指向正确的 CLI 路径[ ] 系统代理设置是否一致环境变量里没有残留的失效代理大多数安装问题走到这一步都能定位出来。结个尾说点自己的体会Codex 的安装本身并不复杂复杂的是安装过程中各种环境变量、权限策略、代理配置的坑。我在 Mac 和 Windows 上都完整装过几遍最大的感受是先想清楚自己的工作场景再决定装 CLI 还是 IDE 插件这样可以省掉很多来回折腾的时间。如果你在终端里工作比较多建议 CLI 为主IDE 插件辅助如果你主要活动区域在编辑器里那就反过来。两者本身不冲突一份 CLI 登录态可以共享给多个 IDE 使用。文章里提到的具体命令和配置路径建议实际操作时以你安装时的版本输出为准遇到和文章不一致的地方优先看命令行给的提示信息大多数报错在提示里已经写明了原因。Codex 还在快速迭代新版本会持续优化安装体验和 IDE 集成稳定性保持关注就行。
