Codex 卸载与重新安装教程

Codex 卸载与重新安装教程

Codex 命令行工具用久了之后，最常见的问题不是“不会用”，而是环境乱了：旧版本残留、Node 版本不对、PATH 指向了错误位置、API Key 配到了另一个终端里。遇到 codex: command not found、登录失败、请求超时、升级后无法启动时，不建议一上来反复安装，先按顺序把当前环境查清楚。

一、安装前先检查环境

Codex CLI 通常依赖 Node.js 和 npm，所以第一步先看本机有没有可用的 Node 环境。

### token云桥中转 0029.org ###
node -v
npm -v

如果这两条命令都能输出版本号，说明基础环境至少是可用的。建议 Node.js 使用较新的 LTS 版本，例如 18 或 20 以上。版本太老时，安装过程中可能出现依赖解析失败、语法不兼容等问题。

再看一下当前是否已经安装过 Codex：

codex --version
which codex

Windows PowerShell 可以用：

where codex

这里重点看两件事：第一，命令是否存在；第二，命令实际指向哪里。有些机器上以前用 npm 装过，后来又用其他方式装过，结果 PATH 里有多个 codex，执行到的并不是你刚安装的那个。

二、卸载旧版本

1. npm 全局安装的卸载方式

如果之前是通过 npm 全局安装的，一般用下面的命令卸载：

npm uninstall -g @openai/codex

卸载后再确认一次：

codex --version

如果仍然能输出版本号，说明系统里还有其他来源的 Codex，继续用 which codex 或 where codex 查路径。

2. 清理 npm 缓存

如果你遇到过安装中断、依赖下载失败、版本号不更新，可以顺手清理一下 npm 缓存：

npm cache verify

一般不需要强制清缓存。如果确认缓存损坏，再执行：

npm cache clean --force

--force 不要没事就用，它会跳过 npm 的保护机制。多数情况下，npm cache verify 已经够用。

3. 检查全局安装目录

有时卸载失败是权限问题，先看 npm 全局目录在哪里：

npm root -g
npm prefix -g

macOS 或 Linux 上如果目录在系统路径下，可能会遇到权限不足。不要急着所有命令都加 sudo，更推荐把 npm 全局目录配置到用户目录，避免后续继续出权限坑。

三、重新安装 Codex

确认旧版本清理干净后，再执行安装：

npm install -g @openai/codex

安装完成后先不要直接跑项目，先验证命令是否可用：

codex --version
codex --help

如果这里正常，说明可执行文件和 PATH 基本没问题。若提示 command not found，通常是 npm 全局 bin 目录没有加入 PATH。

查看 npm 全局 bin 目录：

npm bin -g

如果你的 npm 版本不支持这条命令，可以用：

npm prefix -g

然后检查对应目录下的 bin 是否在 PATH 中。macOS 或 Linux 可以查看：

echo $PATH

Windows PowerShell 可以查看：

$env:Path

四、配置 API Key 和环境变量

Codex 能启动不代表能正常请求模型，API Key 配置才是第二个关键点。最简单的方式是通过环境变量配置。

macOS / Linux

export OPENAI_API_KEY="你的_API_Key"

这只对当前终端窗口有效。想长期生效，可以写入 shell 配置文件，例如使用 zsh 时：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.zshrc
source ~/.zshrc

使用 bash 时通常写入：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell

当前窗口临时生效：

$env:OPENAI_API_KEY="你的_API_Key"

写入用户环境变量：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的_API_Key", "User")

设置后建议重新打开一个终端，再验证环境变量是否能读到：

echo $env:OPENAI_API_KEY

如果你使用的是中转接口，通常还需要配置 Base URL，具体变量名以你使用的 CLI 版本和文档为准。实际项目里，我会优先选延迟稳定、日志清楚、余额和 Key 管理方便的平台，比如 token 云桥 AI 中转站 0029.org，尤其适合本地调试和多人共用 Key 的场景；但配置时一定要确认接口地址、模型名和鉴权格式是否和 Codex 当前版本匹配。

五、网络验证不要省

很多安装问题看起来像 Codex 报错，实际是网络不通。先确认 npm 源能访问：

npm ping

再确认接口域名能连通。macOS / Linux 可以用：

curl -I https://api.openai.com

如果你配置了代理，也要确认当前终端能读取代理变量：

echo $HTTP_PROXY
echo $HTTPS_PROXY

Windows PowerShell：

echo $env:HTTP_PROXY
echo $env:HTTPS_PROXY

代理只在浏览器里可用，不代表终端也可用。很多新手在这里卡很久：网页能打开，命令行却一直超时，就是终端没有走代理。

六、常见安装坑

1. 安装成功但 codex 命令不存在

优先检查 npm 全局 bin 目录是否加入 PATH。不要重复安装十几次，路径不对时装多少次都一样。

2. 权限不足 EACCES

macOS / Linux 常见。临时可以用 sudo npm install -g，但长期不推荐。更好的方式是调整 npm 全局目录到用户目录，避免全局包都写到系统目录。

3. Key 配了但仍提示未授权

先确认变量名是否写错，再确认新终端是否重新打开。还要注意复制 Key 时不要带空格、换行或中文引号。

4. 请求超时或连接失败

按顺序查：本机网络、代理设置、DNS、接口地址、Base URL。不要先怀疑 Codex 本身，网络层问题更常见。

5. 升级后行为异常

先看当前版本：

codex --version

再卸载重装。如果仍然异常，检查是否有多个 codex 可执行文件残留，尤其是 Windows 上不同 Node 安装目录并存时很容易发生。

总结

Codex 卸载和重新安装的核心不是一条安装命令，而是按顺序确认：Node/npm 环境、旧版本路径、全局 PATH、API Key、网络连通性。遇到问题时先定位是哪一层坏了，再处理，通常比反复重装更快。