Codex ：Windows / Mac / Linux 三平台实测

OpenAI 的 Codex 这两年在开发者圈子里越来越受关注——它是 OpenAI 官方这款能自主读代码、改代码、跑命令的编程智能体，前身叫 Codex CLI，后来正式并入 ChatGPT 生态，提供 CLI 和 IDE 扩展两种形态。

这篇文章我按 Windows / macOS / Linux 三个平台各跑了一遍安装，把完整步骤和踩过的坑记下来。命令都能直接复制，版本验证那段建议你亲手跑一遍确认环境没问题。

〇、安装前的环境要求

项目	要求
Node.js	≥ 18（建议用 20 LTS 或更高，老版本会报错）
npm	随 Node 自带，确认能执行 npm -v
登录方式	ChatGPT 账号（Plus/Pro/Team 等订阅），或 API key
网络	能访问 OpenAI 服务（国内网络需要自行处理代理）

先确认 Node 环境，一条命令：

node -v && npm -v
# 预期输出类似：
# v20.19.0
# 10.9.2

如果 node 命令不存在，先装 Node——Windows 去官网下 LTS 安装包，macOS 推荐 brew install node，Linux 用系统包管理器装完再看下面。

一、Windows 安装

Windows 上官方推荐用 npm 全局安装：

npm install -g @openai/codex

装完验证版本：

codex --version

Windows 踩坑记录（这一步我花的时间最多）：

1. PowerShell 执行策略报错：装完运行 codex 提示"无法加载，因为在此系统上禁止运行脚本"。解决：以管理员身份开 PowerShell 执行

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. 安装卡住/超时：npm 默认源在国内慢。换淘宝源再装：

   npm config set registry https://registry.npmmirror.com
   npm install -g @openai/codex
   

3. 代理导致登录失败：如果配置了系统代理，Codex 登录时可能连不上。确认代理正常或临时关闭再试。

二、macOS 安装

同样用 npm：

npm install -g @openai/codex
codex --version

macOS 特有坑：

1. 权限报错 EACCES：npm 全局目录权限不足。建议用 nvm 管理 Node（别用 sudo 硬装），或者

   npm config set prefix ~/.npm-global
   export PATH="$HOME/.npm-global/bin:$PATH"
   

2. 首次运行 Gatekeeper 弹窗：从 npm 装的 CLI 一般不会触发，但如果运行第三方编译版本被拦，去"系统设置 → 隐私与安全性"里允许。

三、Linux 安装

Debian/Ubuntu 系（其他发行版同理，先把 Node 装好）：

npm install -g @openai/codex
codex --version

Linux 坑：

1. 全局路径不在 PATH：npm 全局 bin 目录默认是 /usr/local/bin（root）或 ~/.npm-global/bin（用户级），不在 PATH 就手动加：

   export PATH="$PATH:$(npm config get prefix)/bin"
   

2. 缺依赖：个别精简发行版缺 libstdc++ 之类，报错后 apt install 对应包即可。

四、安装后的登录与验证

三平台登录流程一致：

codex login

按提示选登录方式：

• ChatGPT 账号：浏览器授权，回填验证码
• API key：codex login --api-key 或环境变量 OPENAI_API_KEY

验证是否真正可用，跑一个最简单的任务：

codex "print hello world in python and run it"

预期：Codex 会自己写一个 Python 文件并执行，输出 hello world。看到这一步，安装就完全通了。

五、常见问题速查

现象	原因	处理
codex 不是内部或外部命令	全局 bin 不在 PATH	见上文各平台 PATH 配置
安装卡在 npm install	网络/源问题	换 npmmirror 源
登录转圈失败	网络/代理冲突	检查代理，重试 codex login
提示需要订阅	免费额度用尽/无订阅	检查账号订阅状态，或用 API key

六、总结与 FAQ

核心要点回顾

三平台安装流程高度一致，核心就三步：装 Node → npm 全局装 Codex → 登录验证。共性问题集中在三处：

• PATH 配置：Windows 的 PowerShell 执行策略、macOS/Linux 的全局 bin 路径，本质都是让系统能找到 codex 命令。
• 网络与源：国内 npm 默认源慢、代理冲突，是安装卡住和登录失败的最常见原因，换 npmmirror 源 + 检查代理基本能解决。
• 权限问题：macOS 的 EACCES、Linux 的缺依赖，都属于环境层面的小坑，按上文对应处理即可。

高频问题 FAQ

问题	解答
如何升级 Codex？	重新执行 npm install -g @openai/codex 即可覆盖安装到最新版，装完用 codex --version 确认。
如何卸载 Codex？	执行 npm uninstall -g @openai/codex。若想连配置一起清掉，再删除用户目录下的 ~/.codex 配置文件夹。
如何切换登录方式？	先 codex logout 退出当前账号，再重新 codex login，按提示选择 ChatGPT 账号或 API key 即可。
如何配置代理？	在 shell 里设置环境变量，例如 export HTTPS_PROXY=http://127.0.0.1:7890（Windows PowerShell 用 $env:HTTPS_PROXY="http://127.0.0.1:7890"），再重试登录。
如何查看日志？	Codex 的日志默认写在 ~/.codex/log 目录下，按时间戳命名，排查登录或运行异常时直接看最新的日志文件。