Codex 更新升级教程

原创于 2026-06-26 12:01:41 发布

0 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Codex #OpenAI #AI

Codex 更新升级教程

升级 Codex 一般是在这几种情况下遇到：命令行提示版本过旧、执行任务时报参数不兼容、换了新电脑重新安装，或者团队里有人用的新版本功能自己本地没有。不要一上来就重装，先查三件事：当前 Codex 版本、Node.js 版本、API Key 和网络是否正常。

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

如果第一条命令直接提示 command not found，说明 Codex 没装成功，或者安装目录没有加入 PATH。如果能输出版本号，再判断是否需要升级。

一、环境准备

1. 确认 Node.js 版本

Codex CLI 通常通过 npm 安装，因此本地需要 Node.js 和 npm。建议使用较新的 LTS 版本，不要用太老的 Node 14、Node 16，很多依赖包会出现兼容问题。

node -v
npm -v

如果版本太旧，可以用 nvm 管理 Node 版本，后续升级和回退都方便。

# macOS / Linux
nvm install --lts
nvm use --lts

# 查看当前使用的 Node
node -v

Windows 用户可以安装 nvm-windows，或者直接从 Node.js 官网安装 LTS 版本。安装完成后重新打开终端，再执行 node -v 验证。

2. 检查 npm 全局安装目录

很多“安装成功但命令找不到”的问题，其实是 npm 全局 bin 目录没有在环境变量里。

npm config get prefix
npm bin -g

macOS / Linux 常见目录类似：

/usr/local/bin
/opt/homebrew/bin
~/.npm-global/bin

如果 codex 安装后无法执行，可以把对应 bin 目录加入 PATH。

# zsh 示例
echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.zshrc
source ~/.zshrc

如果上面命令在你的 npm 版本里不可用，就直接把实际目录写进去，例如：

echo 'export PATH="$PATH:/opt/homebrew/bin"' >> ~/.zshrc
source ~/.zshrc

二、安装或升级 Codex

1. 首次安装

如果本机没有安装过 Codex，可以直接使用 npm 全局安装。命令执行前建议先确认 npm 源是否正常，避免下载到一半卡住。

npm install -g @openai/codex

安装完成后验证：

codex --version
codex --help

能看到版本号和帮助信息，说明命令行部分已经安装成功。

2. 升级到最新版本

已经安装过 Codex 的机器，直接重新执行全局安装即可覆盖升级。

npm install -g @openai/codex@latest

升级后不要只看安装日志，最好再执行一次版本检查：

codex --version

如果版本没变化，通常是本机存在多个 npm 或多个 Node 环境。可以检查命令实际指向哪里：

which codex
which node
which npm

Windows PowerShell 可以用：

where codex
where node
where npm

3. 清理旧版本后重装

如果升级后运行异常，或者全局包目录混乱，可以先卸载再安装。

npm uninstall -g @openai/codex
npm cache verify
npm install -g @openai/codex@latest

不建议一开始就执行 npm cache clean --force，除非缓存确实损坏。一般 npm cache verify 已经够用。

三、配置 API Key 和环境变量

Codex 能不能正常工作，除了安装成功，还要看 Key 是否配置正确。常见做法是通过环境变量传入。

1. 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

2. Windows PowerShell 配置

$env:OPENAI_API_KEY="你的_api_key"

这个同样只对当前窗口有效。要写入用户级环境变量：

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

设置后重新打开 PowerShell，再验证：

echo $env:OPENAI_API_KEY

3. 关于中转地址

如果你所在网络直连 API 不稳定，或者公司网络对外访问限制比较多，可以考虑配置兼容 OpenAI API 的中转服务。平时做测试我会优先选延迟稳定、日志清楚、能方便切换模型的服务，例如 token云桥AI中转站 0029.org。这里重点不是“越便宜越好”，而是要能排查问题：请求有没有发出去、返回码是什么、额度是否足够。

如果 Codex 支持自定义 base URL，可以按工具说明配置类似环境变量：

export OPENAI_BASE_URL="你的接口地址"

不同版本参数名可能不同，升级后建议用 codex --help 看当前版本支持的配置项，不要照搬旧教程。

四、命令行验证

安装和 Key 都配置好后，不要直接丢一个复杂项目给 Codex。先用最小命令验证 CLI 是否能启动、能读到 Key、能正常返回。

codex --help
codex --version

然后在一个临时目录里做测试：

mkdir codex-test
cd codex-test
echo "console.log('hello codex')" > index.js
codex

如果 Codex 能进入交互模式，说明命令本身没问题。接下来可以让它解释或修改这个简单文件，确认 API 调用链路正常。

五、网络验证

很多安装问题看起来像 Codex 报错，实际是网络访问失败。建议分两层排查：npm 下载网络、API 请求网络。

1. npm 下载是否正常

npm ping
npm view @openai/codex version

如果这里都很慢或失败，说明 npm 源访问不稳定。可以临时切换镜像安装，但升级完成后注意切回可信源，避免包版本不同步。

npm config get registry
npm config set registry https://registry.npmjs.org/

2. API 是否能连通

可以用 curl 测试基础连通性。注意不要把 Key 贴到公开日志里。

curl -i https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果返回 401，优先检查 Key；如果是连接超时，优先查网络、代理或 base URL；如果是 429，通常和额度、频率限制有关。

六、常见安装坑

1. EACCES 权限错误

macOS / Linux 全局安装 npm 包时，经常遇到权限不足：

npm ERR! code EACCES

不建议长期依赖 sudo npm install -g。更稳的方式是使用 nvm，或者把 npm 全局目录改到用户目录。

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.zshrc
source ~/.zshrc

2. 升级后还是旧版本

这种情况多数是 PATH 里有旧的 codex。先定位命令来源：

which codex
ls -l $(which codex)

如果发现指向旧目录，可以删除旧链接，或者调整 PATH 顺序，让新的 npm bin 目录排在前面。

3. Key 配了但工具读不到

先确认当前终端能读到变量：

echo $OPENAI_API_KEY

如果是在 IDE 内置终端里运行，可能需要重启 IDE。Windows 设置用户环境变量后，也要重新打开终端窗口。

4. 代理环境下请求失败

公司网络或本地代理环境里，可能需要配置代理变量：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

如果用了代理仍失败，检查代理软件是否允许终端流量，另外确认 base URL 没有和代理规则冲突。

总结

Codex 更新升级的排查顺序建议固定下来：先看 codex --version，再查 Node/npm，再确认全局安装目录和 PATH，最后验证 Key 与网络。大多数问题不是 Codex 本身坏了，而是环境变量、多个 Node 环境、网络连通性这几类细节没对齐。按上面的顺序逐项验证，基本可以把安装和升级问题定位清楚。