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 12（Monterey）及以上，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 proxy

Windows 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 管理开发软件，我建议直接走 Homebrew：

brew install node

这个命令会把最新的 Node.js 和 npm 一起装好。安装完成后检查一下版本：

node -v npm -v

如果之前装过 Node.js 但是版本偏低，可以先用brew upgrade node升级到最新稳定版。老版本 Node.js 可能导致 Codex 安装过程中出现依赖解析失败的问题，优先排除这个变量。

3.2 用 npm 安装 Codex CLI

Node.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/bin（Apple Silicon 芯片）或者/usr/local/bin（Intel 芯片）。如果安装完成后执行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.js

Windows 上安装 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，解决方法是把执行策略改成 RemoteSigned：

Set-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-size=4096，同时把路径长度限制相关的注册表项打开。大多数情况下新建环境变量后重启终端就能解决。

4.4 Mac 和 Windows 安装流程对照

为了让大家对两边流程有个直观认识，我把对应的操作列成一个对照表：

两边的安装底层逻辑完全一致，只是外围环境和权限策略有差异。

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 / Linux：

export OPENAI_API_KEY="你的API Key"

Windows PowerShell：

$env:OPENAI_API_KEY="你的API Key"

为了每次打开终端都自动生效，建议把环境变量写进配置文件。Mac/Linux 修改~/.zshrc或者~/.bashrc，Windows 通过系统环境变量界面永久添加上去。

配置完成后运行：

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!。我把常见的错误类型和对应的解决办法整理一下：

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 在处理请求时，本地网络中继或者代理通道建立失败，导致请求没能到达服务端。

出现这种报错时，你可以按下面的顺序逐一排查：

1. 检查系统代理设置。如果你用了系统级代理工具，确认端口配置是否正确、当前是否处于启动状态。
2. 检查终端环境里的代理变量。执行env | grep -i proxy（Windows 上用Get-ChildItem Env: | Where-Object { $_.Name -match "proxy" }），看 HTTP_PROXY、HTTPS_PROXY 这些变量是否指向了一个已经不存在的端口。
3. 如果你没有用代理，反而是个别开发工具自动配置了代理，同样的方法查出来并清掉。
4. 如果代理配置都没问题，检查 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 codex（Mac/Linux）或者Get-Command codex（Windows）能返回路径；最后把这个路径填到 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 集成稳定性，保持关注就行。