Codex CLI 安装失败、连不上怎么解决？排查全流程
装 Codex CLI 时卡在报错、装完一运行就提示”连不上”，是新手最常踩的坑。这篇按真实排查顺序——Node 版本 → npm 全局权限 → 网络代理 → 验证 → 卸载重装——把问题逐个隔离。每一步都给可复制的命令，照着走基本能定位 90% 的安装与连接故障。还没装过的话，建议先看 Codex CLI 入门教程 走一遍标准流程，再回来对照排查。
为什么装不上、连不上：先分清两类问题
Codex CLI 的故障分两大类，排查思路完全不同：
- 安装阶段失败：
npm install直接报错，命令根本没装上。多半是 Node 版本太低、npm 全局目录没权限，或下载依赖时网络中断。 - 运行阶段连不上：命令装好了，
codex能启动，但一发请求就超时或报认证错误。多半是 网络/代理 或 API 凭证 问题，跟安装没关系。
先用一句话自检：能不能跑通 codex --version？能打印版本号 = 安装没问题，去查网络；报”command not found”或装的时候就红字 = 安装阶段问题。 把这条岔路分清，能省一半时间。
第一步：检查 Node 版本（最高频原因）
Codex CLI 对 Node 有最低版本要求（通常 ≥18，具体以官方文档为准）。版本过低时，安装会报语法错误或依赖解析失败，迷惑性很强。
先看当前版本：
node -v
npm -v
如果 node -v 低于 18（比如还停在 v14、v16），先升级。强烈建议用 nvm 管理 Node 版本，避免系统全局 Node 反复打架：
# macOS / Linux 用 nvm
nvm install 20
nvm use 20
# Windows 可用 nvm-windows，或直接去 nodejs.org 下 LTS 安装包
升级后重开一个终端窗口，再 node -v 确认生效。很多”装不上”其实是版本没切过来——旧终端还认着老版本。
第二步：解决 npm 全局权限（EACCES 报错）
安装时如果看到 EACCES、permission denied、mkdir ... operation not permitted 之类，是 npm 全局目录没有写权限，这是 macOS/Linux 上的经典坑。
不要用 sudo npm install -g 硬装——它会让全局目录权属混乱，后患更多。推荐两种干净做法：
| 方案 | 做法 | 适合 |
|---|---|---|
| 用 nvm | 装了 nvm 后全局目录在用户目录下，天然有权限 | 大多数人，首选 |
| 改 npm 前缀 | 把全局目录指到用户目录 | 不想用 nvm |
改 npm 前缀的命令（方案二）：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后把下面这行加进 ~/.zshrc 或 ~/.bashrc
export PATH=~/.npm-global/bin:$PATH
改完重开终端再装。Windows 上一般没有 EACCES，但若装在受保护目录，用管理员身份运行一次终端通常能过。
第三步：网络与代理（连不上的主因）
安装阶段卡在下载依赖、或运行阶段请求超时，九成是网络问题。分两层处理。
第一层，让 npm 能下包。 如果 npm install 卡在某个依赖很久不动，先确认 npm 能正常拉取。可临时切换更稳定的 registry 镜像源拉依赖（具体源地址以你所在网络环境可用的为准）：
# 查看当前用的源
npm config get registry
# 换成国内镜像试试（能不能用取决于你的网络环境）
npm config set registry https://registry.npmmirror.com
# 装完记得换回官方源，避免以后装其他私有包出问题
npm config set registry https://registry.npmjs.org
换源前先判断是不是真的卡在拉包：npm install 加个 --loglevel verbose 参数，能看到具体卡在哪个包、哪一步。如果日志里全是同一个包反复重试，基本能确定是网络问题而不是权限或版本问题，直接换源或挂代理，不用回头再查 §1、§2。
第二层，让 Codex 运行时能连上服务端。 Codex 启动后请求超时，通常要给它配代理。一般通过环境变量让命令行工具走代理：
# macOS / Linux，让终端走本地代理（端口换成你自己代理软件的端口）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
Windows 用户常卡在这一步，因为 export 是 Unix 语法，PowerShell 和 cmd 都不认。按你实际用的终端选一种：
# PowerShell
$env:https_proxy = "http://127.0.0.1:7890"
$env:http_proxy = "http://127.0.0.1:7890"
:: cmd.exe
set https_proxy=http://127.0.0.1:7890
set http_proxy=http://127.0.0.1:7890
设完在同一个终端窗口里跑 Codex 才生效——新开一个窗口环境变量就没了，这是最容易被忽略的一点。几个高频判断点：
- 代理软件开了，但终端没设环境变量 → 终端不走代理，照样超时。
- 设了代理但端口填错 → 直接连接被拒。先去代理软件里确认真实端口，一般在客户端的”端口设置”或”高级设置”里能看到，常见是 7890、10809 这类，不同软件默认值不同，别照抄别人的端口号。
- 公司内网有防火墙 → 找 IT 确认目标域名是否被放行，具体端点以官方文档为准。
- 用了 WSL（Windows Subsystem for Linux）：WSL 里的终端和 Windows 主机是两套网络环境，Windows 上开的代理软件不会自动被 WSL 感知。需要单独在 WSL 里设置代理指向 Windows 主机的 IP（不是
127.0.0.1），可以用cat /etc/resolv.conf里的nameserver地址作为代理目标 IP，再拼上代理端口。这是 WSL 用户排查”明明开了代理还是连不上”的高频盲点。
想快速判断是不是代理配置本身的问题，可以先脱离 Codex，单独测试网络连通性：
curl -I https://registry.npmmirror.com
如果这条命令都超时或报错，说明问题出在网络层（代理没生效、端口错、防火墙拦截），跟 Codex 本身没关系，先把这条命令跑通再回头装 Codex。
怎么验证安装成功
走完上面三步，按顺序验证，每一关过了再往下：
# 1. 确认命令装上了、能打印版本
codex --version
# 2. 确认登录/鉴权（首次需要配置 API Key 或登录，方式以官方文档为准）
codex login # 或按官方提示完成认证
# 3. 跑一个最小任务，确认能连上服务端
codex "用一句话解释什么是递归"
codex --version 有版本号 = 安装通过；最小任务有正常返回 = 网络与鉴权通过。 两关都过，环境就齐了。
卸载重装：环境彻底乱了用这招
当版本错乱、装了多个来源、怎么都不对劲时，干净卸载再装一遍往往比继续猜更快：
# 卸载全局包
npm uninstall -g <codex 的包名，以官方文档为准>
# 清掉 npm 缓存（缓存损坏也会导致安装失败）
npm cache clean --force
# 确认旧命令已消失
which codex # 没输出 = 卸干净了
# 重新安装
npm install -g <codex 的包名，以官方文档为准>
如果 which codex 还能找到残留，说明有别的路径装了一份（比如之前 sudo 装过），按它给出的路径手动删掉再重装。
常见坑与排查清单
| 报错/现象 | 多半原因 | 解法 |
|---|---|---|
command not found: codex | 没装上 / PATH 没包含全局 bin | 查 §1 版本、§2 权限，确认全局目录在 PATH |
EACCES / permission denied | npm 全局目录无写权限 | 用 nvm 或改 npm 前缀，别用 sudo |
| 安装卡在下载依赖 | 网络拉包慢/中断 | 换镜像源，或挂代理重试 |
| 运行时请求超时 | 终端没走代理 | 同窗口设 https_proxy 环境变量 |
401 / 认证失败 | API Key/登录没配好 | 重新 codex login 或重配 Key |
| 版本号能打但行为怪 | 装了多份 / 缓存损坏 | 卸载 + cache clean + 重装 |
brew 方式安装（macOS 备选）
macOS 用户如果 npm 路线总不顺，可以试试包管理器路线（是否提供 brew 安装方式以官方文档为准）。Homebrew 的好处是依赖和权限由它统一管，能绕开不少 npm 的坑：
brew update
brew install <对应的 formula 名，以官方文档为准>
codex --version
brew 装完同样用 codex --version 验证。注意：brew 版和 npm 版别同时装，否则又会出现”装了多份、版本打架”的问题——选一条路走到底。
常见问题
Q：codex —version 能显示版本号，但一运行就超时，是装错了吗？
不是，安装是好的。版本号能打印说明命令本身没问题，超时是网络/代理问题。在运行 Codex 的同一个终端里设好 https_proxy 环境变量，确认代理端口正确即可。
Q：一定要用 nvm 吗？直接装 Node 行不行？ 行，但强烈建议用 nvm。它能让你随时切版本、且全局 npm 目录天然有写权限，直接绕过 EACCES 权限坑。系统全局 Node 一旦版本对不上，排查起来更费劲。
Q：能不能用 sudo npm install -g 强行装上？
不建议。sudo 装会把全局目录搞成 root 权属，之后正常更新又报权限错，越滚越乱。正确做法是用 nvm 或改 npm 前缀，让你的用户对全局目录有权限。
Q：Windows 上装 Codex CLI 有什么不一样？ Node 版本和网络代理的逻辑一致。差别是 Windows 一般不报 EACCES；遇到装在受保护目录的情况，用管理员身份开一次终端多半能过。代理同样要在终端里配好对应端口。
Q：报 401 或认证失败怎么办？
这是鉴权而非安装问题。重新跑 codex login 或按官方提示重配 API Key，确认密钥没填错、没过期。具体认证方式以官方文档为准。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。