Skip to content

Auto-generated English stub on 2026-04-24. Replace with a proper translation.

title: "Codex CLI 更新未生效？4 种已验证的修复方法（缓存、重复安装、全新安装）" description: "运行 npm/brew 更新后 codex --version 仍显示旧版本？清除缓存、移除重复安装、全新重装，并通过一份检查清单验证新版本。" date: 2026-02-13 tags: ["Codex", "CLI", "troubleshooting", "developer-environment"] category: "Developer Tools"

Codex CLI 更新未生效？4 种已验证的修复方法（缓存、重复安装、全新安装）

Codex CLI 完全指南

本指南帮你解决的问题

找出 Codex CLI 无法识别最新版本的原因 应用四种修复方法：版本检查、Shell 缓存重置、重复安装卸载、全新重装 采取预防措施确保问题不再复发

如果你已经运行了 npm install -g @openai/codex@latest 或 brew upgrade codex，但 codex --version 仍然显示旧版本号，你并不孤单。Codex CLI 更新经常因为重复安装、缓存路径、Shell 命令缓存或版本显示 Bug 而失败。请按照以下四种修复步骤操作——版本检查、缓存重置、重复安装卸载、全新重装——确保启动的是最新版本。

适用读者

  • 通过 npm 或 Homebrew 更新 Codex CLI 后仍然启动旧版本的开发者
  • 需要消除团队 Codex CLI 部署中版本不一致问题的技术负责人

五分钟内的成果

  1. 精确定位 Shell 正在调用的 Codex 可执行文件
  2. 移除重复安装和过期缓存条目
  3. 确认启动的确实是最新版 Codex CLI

为什么 Codex CLI 更新不生效

三种故障模式几乎可以解释所有"更新没有生效"的问题报告。

三大根本原因

通过 npm、Homebrew、winget 或手动下载安装 Codex 会留下多个可执行文件。最旧的那个通常在 PATH 中排在前面，尤其是在 Windows 上，%AppData%\npm、C:\Program Files\Git\usr\bin 和临时副本会同时存在。

Bash 和 Zsh 会缓存命令位置。除非你打开新终端（或运行 hash -r / rehash），否则升级后 Shell 仍会使用旧路径。

如 GitHub Issue #4986 所记录，codex --version 可能报告错误的版本号。实际二进制文件已是最新版，但输出的版本字符串存在滞后。

Windows 用户注意

官方文档仍将原生 Windows 支持标记为实验性。如果稳定性很重要，请在 WSL 中安装 Codex CLI 并从 WSL 环境运行。

3 分钟诊断"codex cli update command"问题

当 codex cli update 更新不生效时的快速检查清单
  1. 版本检查 — 将 codex --version 与 npx -y @openai/codex@latest --version 的输出进行对比，排除版本显示 Bug。
  2. 查找重复安装 — 运行 which -a codex（macOS/Linux）或 Get-Command codex -All（PowerShell）查看是否存在多个可执行文件。如果存在，先卸载所有副本再继续。
  3. 重装 + PATH 验证 — 统一使用一种安装方式（npm install -g @openai/codex@latest 或 brew install codex），打开全新终端，通过 which codex / Get-Command 确认只剩一个路径。

这个快速流程解决了最常见的"codex cli update command"搜索意图：为什么新版本没有出现，如何确保它能正确显示？

三组诊断命令

首先确认 Shell 调用的是哪个可执行文件，以及 npm 当前如何跟踪 Codex。

# Windows PowerShell
Get-Command codex -All | Select-Object -Expand Source
where.exe codex
npm root -g
npm ls -g @openai/codex --depth=0

# macOS / Linux
which -a codex
npm root -g
npm ls -g @openai/codex --depth=0

当 Get-Command codex -All 或 which -a codex 显示多个路径时，即确认存在重复安装。当 /usr/local/bin/codex 和 ~/.npm-global/bin/codex 同时存在时，Shell 的路径优先级决定了启动哪一个。

使用 npx 绕过 PATH

npx -y @openai/codex@latest --version 直接从 npm 运行最新包。如果它输出的版本比 codex --version 更新，就证明这是 PATH 问题。

确保更新生效的三个步骤

完成诊断后，按照以下修复清单统一到单一安装方式。

步骤 1：移除所有重复安装

从你曾经使用过的每个包管理器中卸载 Codex。将其视为一次全新开始。

# npm 安装
npm uninstall -g @openai/codex

# Homebrew 安装 (macOS/Linux)
brew uninstall codex

# winget 安装 (Windows)
winget uninstall OpenAI.Codex

步骤 2：从单一来源重新安装

选择一种分发渠道——npm 或 Homebrew——并在未来的升级中始终使用它。

# 推荐（跨平台）: npm
npm cache clean --force
npm install -g @openai/codex@latest

# 备选（macOS/Linux）: Homebrew
brew install codex

步骤 3：在新终端中验证

打开一个全新的 Shell，然后验证二进制文件路径和版本号。这会自动清除 Shell 缓存。

# 确认只剩一个可执行文件
which codex                  # macOS/Linux
Get-Command codex -All       # Windows PowerShell

# 检查报告的版本号
codex --version

# 与 npx 交叉验证
npx -y @openai/codex@latest --version

成功的标志

你应该看到只有一个路径，并且 codex --version 的输出与 npx 的结果一致。如果 CLI 仍然显示旧版本号但 npx 报告的是最新版，说明你遇到了已知的版本显示 Bug——实际上你已经在使用最新版本了。

常见故障模式及修复方法

现象可能原因修复方法
codex --version 显示旧版但 npx 显示新版版本显示 Bug视为外观问题；关注 GitHub Issue #4986
新终端仍加载旧版本PATH 优先级问题检查 echo $PATH；将 npm/global bin 目录移到旧目录之前
Windows 原生安装持续崩溃实验性支持在 WSL 中重新安装，从 Linux 层运行
VS Code 或 Cursor 扩展感觉过时扩展版本滞后手动更新扩展并重启编辑器
如何更新 VS Code 扩展
  1. 打开 VS Code 的扩展侧边栏
  2. 搜索 "OpenAI Codex"
  3. 点击 Update
  4. 完全重启 VS Code（关闭所有窗口后重新打开）
  5. 从侧边栏重新登录 Codex

要点总结

Codex CLI 更新失败的原因是重复安装的二进制文件、Shell 缓存或外观性版本 Bug。运行诊断命令，统一到一种安装方式，并在新终端中验证，即可终结这个循环。

  • 使用 which -a codex / Get-Command codex -All 定位重复安装
  • 清除所有安装，然后使用单一包管理器重新安装
  • 在新 Shell 中验证，并用 npx 进行交叉确认

一旦所有机器都统一使用同一种安装方式（npm install -g @openai/codex@latest 或 brew upgrade codex），未来的升级就会变得简单直接。

下一步行动

延伸阅读