1. 从一次版本升级说起为什么模型列表突然“少了一个”上周我把手头的 Codex CLI 从旧版本升到了最新版重启终端之后第一反应是模型选择列表里那个熟悉的 GPT 6 不见了。不是报错不是崩溃就是干干净净地消失了像从来没存在过一样。当时我第一反应是“是不是配置文件被覆盖了”翻了一遍~/.codex/config.toml发现配置项还在但 CLI 启动时压根不去读那个模型名了。这个现象其实在最近一段时间的社区反馈里非常集中。关键词里出现的the gpt-5.6-sol model is not supported when using codex with a chatgpt acc、cc switch local proxy failed while handling codex endpoint /responses、unable to load sign-in requirements chatgpt这几条本质上都指向同一类问题Codex CLI 的模型发现机制和账号鉴权链路在最近几个版本里做了调整旧版本里“写死模型名就能用”的玩法失效了。先把结论摆在前面方便你对号入座如果你升级后发现模型列表变短、或者干脆只剩一两个默认项大概率不是你的配置坏了而是新版 CLI 改了模型枚举逻辑。如果你看到model is not supported when using codex with a chatgpt acc这类提示说明当前账号类型和请求的模型不匹配CLI 在客户端侧就做了拦截。如果你遇到cc switch local proxy failed while handling codex endpoint /responses那是本地代理层在转发/responses端点时握手失败通常和鉴权头、base URL 或代理进程状态有关。这篇内容适合三类人看一是刚装完 Codex CLI、还在npm install阶段就被 PowerShell 拦住的纯新手二是升级后模型列表异常、想搞清楚背后机制的老用户三是想把 Codex CLI 接到自建端点或第三方兼容服务上的折腾党。下面我会按“先搞懂它怎么工作再动手修”的顺序把整条链路拆开讲。2. Codex CLI 的模型发现与鉴权链路拆解2.1 模型列表到底是从哪来的很多人以为 Codex CLI 的模型列表是写死在代码里的其实不是。它大致分三层来源第一层是内置默认模型打包在 CLI 的发布产物里作为兜底。第二层是远端模型清单CLI 启动或切换账号时会向服务端拉一次可用模型列表这个列表和你的账号类型、订阅状态强相关。第三层是本地配置覆盖也就是你在config.toml里手动写的model xxx。关键点在于新版 CLI 把第二层的优先级提高了。以前你本地写什么就用什么现在它会先拿远端清单做一次校验如果本地写的模型不在清单里就直接忽略表现就是“模型消失了”。这就解释了为什么配置文件没动模型却不见了。提示判断自己属于哪种情况最快的办法是启动 CLI 时加详细日志参数看它有没有发出拉取模型清单的请求以及返回了什么。2.2 账号类型如何影响可用模型the gpt-5.6-sol model is not supported when using codex with a chatgpt acc这条报错信息量很大。它明确说了两件事一是模型名是gpt-5.6-sol这种带后缀的标识二是当前用的是 ChatGPT 账号体系。不同账号体系能访问的模型池是不一样的。免费账号、Plus 账号、团队账号、以及通过 API Key 走计费的账号各自对应不同的模型白名单。CLI 在发起请求前会做一次本地校验把“账号类型 请求模型”这个组合拿去比对不匹配就直接在客户端拦掉连网络请求都不发。所以你看到的不是服务端 403而是本地就报错了。这里有个容易踩的坑有些人为了用上某个模型去改配置文件里的账号类型字段结果导致鉴权头和服务端预期不一致反而触发了unable to load sign-in requirements chatgpt。这个报错的意思是登录态加载失败CLI 拿不到有效的鉴权凭证自然也就没法继续。2.3 本地代理层在中间扮演什么角色cc switch local proxy failed while handling codex endpoint /responses这条报错涉及的是 CLI 和远端之间的本地代理环节。Codex CLI 在某些配置下会起一个本地转发进程把请求先发到本地端口再由它加上鉴权头转发出去。这样做的好处是鉴权信息不直接暴露在业务请求里也方便做请求改写。但这也多了一个故障点。代理进程没起来、端口被占用、或者代理配置里的 base URL 写错了都会导致/responses端点处理失败。实测下来这类问题里超过一半是代理进程残留导致的——上一次没退干净新进程起不来或者起来了但绑到了旧配置。3. 升级后模型不显示的完整排查与修复流程3.1 第一步确认 CLI 版本和安装方式动手之前先别急着改配置先把现状摸清楚。打开终端执行codex --version which codex npm list -g --depth0这三条命令分别告诉你当前 CLI 版本号、可执行文件的实际路径、以及全局 npm 包列表。为什么要看安装路径因为很多人机器上存在多个 Codex 安装源——一个是 npm 全局装的一个是手动下载的二进制还有一个可能是某个 IDE 插件自带的。which codex返回的路径决定了你实际在跑哪一个。如果你在 Windows 上遇到npm : 无法加载文件 d:\program files (x86)\nodejs\npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 的执行策略在拦。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned执行完再npm -v验证一下。这一步是很多新手卡住的第一关不解决它后面全免谈。3.2 第二步清理旧配置与缓存模型列表异常很大概率是旧缓存和新版本打架。建议按下面顺序清理备份现有配置把~/.codex/整个目录复制一份到别处出问题能回滚。删除缓存文件重点清理~/.codex/cache/和~/.codex/sessions/下的临时数据。重置模型字段把config.toml里的model行先注释掉让 CLI 用远端清单的默认值启动。注意不要一上来就把整个.codex目录删掉。里面有你的登录凭证和历史会话删了要重新登录而且历史记录找不回来。备份永远比删除稳妥。清理完之后重新启动 CLI观察模型列表是否恢复。如果恢复了说明就是缓存问题如果还是缺继续往下走。3.3 第三步核对账号类型与模型白名单这一步是解决model is not supported类报错的核心。你需要确认两件事当前登录的是哪种账号体系。你想用的模型是否在该账号的白名单里。在 CLI 里执行账号状态查询命令不同版本命令名略有差异常见的是codex auth status或codex whoami看返回的账号类型。然后对照官方文档里的模型可用性矩阵。如果确实不匹配有两条路要么换一个白名单内的模型要么切换到支持该模型的账号体系。我个人的经验是不要试图通过改配置绕过白名单校验。新版 CLI 的校验逻辑做得比较靠前硬改配置只会让鉴权链路更乱最后连能用的模型都用不了。3.4 第四步修复本地代理与端点转发针对cc switch local proxy failed while handling codex endpoint /responses按这个顺序排查排查项检查方法常见问题代理进程状态查看本地端口监听情况进程残留、端口被占代理配置检查 config 里的 proxy 段base URL 写错、协议不匹配鉴权头抓包看请求头token 过期、格式不对网络连通直接 curl 目标端点DNS 解析失败、超时先杀掉所有残留的代理进程再重新启动 CLI 让它自己拉起代理。如果还是失败把代理配置里的 base URL 单独拿出来用 curl 测一下确认端点本身可达。这一步能快速区分是“代理层问题”还是“远端问题”。4. 从零安装 Codex CLI 的避坑指南4.1 npm 安装与国内源配置如果你是从零开始第一步是装 Node.js 环境。装完之后别急着npm install先把源配好否则下载速度会让你怀疑人生。配置国内源的命令npm config set registry https://registry.npmmirror.com npm config get registry第二条命令用来验证是否生效。配好之后安装 Codex CLInpm install -g openai/codex安装过程中如果看到npm warn deprecated node-domexception1.0.0: use your platforms native dome这类警告可以忽略它只是提示某个依赖用了旧 API不影响功能。但如果看到unable to locate the codex cli binary or required runtime components那就是二进制没下载成功通常是网络问题重试或者换源即可。4.2 Windows 环境下的特殊处理Windows 用户踩坑概率明显更高主要集中在三处第一处是 PowerShell 执行策略前面已经讲过。第二处是 PATH 环境变量npm 全局包的安装目录必须加到 PATH 里否则会出现npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。第三处是路径里的空格和中文d:\program files (x86)\nodejs\这种带空格的路径在某些脚本里会出问题建议 Node.js 装在纯英文无空格路径下。提示装完之后一定要新开一个终端窗口再测试旧窗口的环境变量不会自动刷新。4.3 首次登录与鉴权初始化安装完成后第一次运行 CLI会引导你登录。这一步如果卡在unable to load sign-in requirements chatgpt通常是网络到鉴权服务不通或者本地时间不准导致证书校验失败。先校准系统时间再确认网络能正常访问鉴权域名。登录成功后CLI 会把凭证写到本地配置目录。这时候再去看模型列表应该就是当前账号能用的完整清单了。如果清单里还是没有你想要的模型回到第 3.3 节那属于账号白名单问题不是安装问题。5. 常见报错速查与实战排查技巧5.1 报错信息与根因对照表把最近高频出现的报错整理成一张表方便你直接对号入座报错关键词根因方向优先排查model is not supported账号与模型不匹配账号类型、模型白名单cc switch local proxy failed本地代理转发失败代理进程、base URLunable to load sign-in requirements登录态加载失败网络、系统时间、凭证unable to locate codex cli binary二进制缺失重装、换源npm.ps1 禁止运行脚本PowerShell 策略执行策略设置npm 无法识别为 cmdletPATH 未配置环境变量这张表建议存下来下次遇到直接查能省掉大量瞎试的时间。5.2 三个我踩过的真实坑第一个坑升级后没重启终端。npm 全局包升级后旧终端里的命令缓存还是老版本表现就是“升级了但没变化”。新开窗口就好了这个坑我踩过不止一次。第二个坑多版本共存导致命令错乱。机器上同时有 npm 装的和手动下载的PATH 顺序决定了跑哪个。用which codex确认实际路径别想当然。第三个坑代理配置残留。之前配过自定义端点后来不用了但配置没删CLI 启动时还去连那个已经不存在的地址报错信息看起来像网络问题实际是配置问题。定期清理不用的配置段能避免很多莫名其妙的故障。5.3 排查的通用思路遇到任何 Codex CLI 的问题我习惯按这个顺序走先看版本和路径确认跑的是哪个再看配置和缓存排除本地干扰然后看日志和报错定位是客户端拦截还是网络失败最后才动账号和网络层。这个顺序的好处是大部分问题在前两步就能解决不用去碰复杂的鉴权链路。很多人一上来就怀疑账号被封、网络被墙结果折腾半天发现只是缓存没清。排查要讲性价比从最简单的可能性开始排除。6. 模型接入与端点扩展的进阶玩法6.1 接入自建兼容端点的思路Codex CLI 支持把请求指向自定义的兼容端点这也是关键词里codex接入deepseek这类需求的来源。核心思路是CLI 本身只负责组装请求和展示结果真正干活的是背后的端点。只要端点实现了兼容的接口协议CLI 就能接。配置上主要改两处一是 base URL 指向你的端点二是鉴权方式改成端点要求的格式。改完之后用 CLI 发一个最简单的请求测试看能不能拿到正常响应。如果报/responses端点处理失败说明端点没实现这个路径或者请求格式对不上。注意接入自建端点时模型名要填端点实际支持的标识不能照搬官方模型名否则会触发前面说的白名单校验或者端点侧 404。6.2 模型切换的配置管理如果你经常在不同模型之间切换建议用配置文件分环境管理而不是每次手动改。可以准备几份配置比如config.work.toml、config.personal.toml启动时通过参数指定用哪份。这样切换模型就是换个启动参数的事不用反复编辑同一个文件减少出错概率。实测下来把配置分文件管理之后我误改配置导致模型消失的情况基本没有了。因为每份配置职责单一改坏了也知道是哪份的问题。6.3 版本升级的正确姿势最后说说升级。Codex CLI 迭代很快但不建议无脑追最新版。我的做法是先看当前版本用得稳不稳稳就不动要升级时先备份配置升完在新终端里验证模型列表和基本功能确认没问题再删备份。如果升完发现模型少了、功能异常直接回滚到旧版本等下一个版本再试。回滚命令很简单指定版本号重装即可npm install -g openai/codex旧版本号版本号从 npm 的版本历史里查。这个操作我做过好几次比在新版本上死磕排查效率高得多。我个人在实际操作中的体会是Codex CLI 这类工具的很多“故障”其实不是故障而是版本迭代带来的行为变化。模型列表变短、报错信息变了、配置项失效了背后往往是官方调整了机制。与其对抗变化不如先理解它为什么变再决定是适配还是回滚。搞清楚模型发现、账号鉴权、本地代理这三条链路大部分问题都能自己定位不用到处问人。