Codex CLI 升级后模型列表不更新：版本错配与缓存排查

桌面端已经能选到更新的模型，命令行里却还是旧的一批；把 CLI 升到最新版、重开终端，列表依旧纹丝不动。对同时用两端的人来说这只是不方便，对只能用命令行的人来说，等于新能力完全摸不到，只剩「聊聊天」的份。

真正的原因往往不在 CLI 二进制本身，而在它背后那个常驻的后台服务。模型列表由后台进程拉取并写入缓存，缓存里还记着生成这份列表的客户端版本号。前台换了新版本、后台还是老进程，列表就还是老样子——所以「更新 CLI」这一步做完，问题常常看起来毫无变化。

先拆清楚：你面对的是两个版本

排查前要区分三层东西，混淆了就会一直在原地打转：

典型症状是：codex --version 显示的是新版本，但缓存条目里的 client_version 字段还是旧版本号。二者对不上，就说明后台进程仍在用旧逻辑供数。

定位清单：五步确认问题在哪

1. 确认实际生效的可执行文件。同时存在 npm 全局安装、包管理器安装、独立安装包时，PATH 里排在前面的可能不是你刚更新的那个。用 which -a codex（Windows 用 where codex）看全部路径，再用 codex --version 确认跑起来的版本，必要时执行 hash -r 清掉 shell 的命令缓存。
2. 看后台进程。macOS / Linux：ps aux | grep -i codex；Windows：tasklist | findstr /i codex。如果进程的启动时间早于你更新的时间，基本可以确定是它在供旧数据。
3. 看缓存里的版本号。配置文件目录（通常是家目录下的 .codex 一类，具体以你本地版本为准）里会有模型列表与元信息，留意 client_version 字段。
4. 看配置是否硬编码。检查配置文件里有没有手动写死的 model 或模型白名单，这种情况即使列表刷新了，界面也不会跟着变。
5. 看登录态。凭据过期或切换到别的账号后，列表可能退回到旧的可用集合。

处理方案：让后台用新版本重新拉一次

核心动作只有一个——让后台服务重启，使它用新版本重新拉取并覆盖缓存。

1. 结束旧的后台进程

# macOS / Linux
ps aux | grep -i codex        # 找到 app-server 相关进程的 PID
kill <PID>                    # 不退再 kill -9 <PID>

:: Windows
tasklist | findstr /i codex
taskkill /PID <PID> /F

结束后重新执行一次 CLI，让它重新拉起后台服务。多数情况下到这一步列表就更新了。

2. 仍然不行，再清缓存

先把缓存目录整体备份一份，再删除其中的模型列表相关文件，然后重新启动 CLI 触发拉取。清缓存是可逆操作，但会连同一些本地偏好一起重置，备份后动手更稳妥。

3. 顺手核对版本与安装来源

升级后确认版本号确实变了，并检查是不是有多个安装来源互相覆盖。老版本残留的可执行文件是「升级了却没用」的高频原因。

4. 网络侧也值得看一眼

模型列表是向服务端请求后落盘的，本地网络到服务端不稳定时，刷新可能静默失败并继续沿用旧缓存。如果在受限网络下反复失败，把 Codex 放到网络环境稳定的远程机器上长期运行是一种可选做法，例如整台机器托管在新加坡机房、按月租用的远程 Mac，命令行工具可以常驻在线，省掉本地进程反复重启的折腾。这不是必需项，本地排查通过就不必绕这一圈。

两端表现相反，怎么理解

实际使用中存在两种镜像情况：一端有新版列表、另一端没有，或者反过来——命令行的列表是全的，桌面端反而缺。后者常表现为：在命令行里选定某个模型后，桌面端显示为「自定义」。

这通常说明桌面端的展示名依赖一份内置的映射表，遇到它不认识的模型标识就回落到「自定义」。此时请求本身未必有问题，能正常发出去，问题只在于界面上无法确认自己到底选了哪个模型。判断方法很简单：看实际请求是否成功、返回是否符合预期，而不是只看下拉框里的名字。

另一类情况更现实：某些平台上桌面端不可用，只能走命令行。此时「桌面端能用、命令行不能用」就等于完全不可用，这也是最该优先解决后台服务版本错配的场景。

第三方密钥与中转服务要谨慎

如果使用的是非官方渠道的共享密钥、转售密钥或中转接口，模型列表通常由中转层返回，它对上游模型的暴露范围不由你控制，可能出现「明明上游有、这里就是没有」的情况，这种差异在你本地怎么重启都消不掉。

需要提醒的是：使用来源不明的共享账号或转售密钥，存在凭据被回收、请求被记录、服务随时中断的风险，也可能违反服务条款。稳妥做法是使用官方订阅或官方 API 密钥；团队场景走官方渠道并做好密钥分发与额度管理。这部分请以各服务方的最新官方说明为准。

注意事项

• 别只盯 --version：版本号只反映前台，问题多半在后台进程。
• 更新后重开终端：shell 的命令缓存会让旧路径继续生效。
• 清缓存前先备份：模型列表会重建，其他本地设置不一定。
• 区分「列表里没有」和「选了不生效」：前者是供数问题，后者多为展示名映射问题。
• 版本号、模型名称、可用范围随时会变：以官方发布说明为准，别把某次观察到的对应关系当成长期结论。

小结

遇到「升级了 CLI 却看不到新模型」，按这个顺序走一遍：核对实际生效的可执行文件 → 查看后台进程启动时间 → 检查缓存里的 client_version → 结束旧进程让它重新拉取 → 必要时清缓存并重新登录。多数情况在前三步就能定位，第四步解决。如果是两端列表不一致但请求正常，那属于展示层差异，不必大动干戈；如果是第三方密钥导致列表残缺，换回官方渠道比在本地反复折腾更有效。