Codex Router 模型缺失？修复模型选择器

最常见的”不工作”报告就是外部模型没有出现在 Codex 模型选择器里。几乎每次的原因都是三者之一：供应商未启用、凭据缺失、或 Codex 没有完全重启。本页给出完整的修复步骤。

为什么目录是凭据感知的

Codex Router 只包含来自已启用、且存有 API Key 或有效 OAuth 会话的外部供应商的模型。原生 GPT 模型仅在 codex login status 确认 OpenAI 登录后才包含。所以一个模型可能”已注册”却不在你的选择器里，直到其供应商被启用并完成认证。

第 1 步：检查供应商状态

./bin/model-router codex providers

目标供应商必须同时报告 SHOW 与 ready：

• SHOW 表示供应商在目录中可见。
• ready 表示凭据或 OAuth 会话存在。

供应商不是 SHOW 就启用它：

./bin/model-router codex providers enable deepseek

是 SHOW 但不是 ready 就设置密钥或登录。每个供应商的正确命令见模型教程。

第 2 步：刷新目录

./bin/model-router codex refresh-catalog
./bin/model-router codex doctor

refresh-catalog 根据当前注册表、已启用供应商与已存凭据重新生成合并目录。

第 3 步：完全重启 Codex

Codex 只在启动时加载 model_catalog_json。关窗口不会重载它。

1. 完全退出 Codex——macOS 用 Command-Q；Windows 用应用的 Quit 命令或在托盘存在时从托盘结束。
2. 重新打开 Codex。
3. 新建任务。
4. 打开模型选择器。

模型仍缺失时再次运行 refresh-catalog，完全退出再打开。

第 4 步：查看启动目录

codex debug models

这显示 Codex 启动时实际加载的目录。路由模型在此但选择器里没有，可能是应用被挂起而不是退出——完全退出重开。这里也没有，说明目录捕获或供应商选择有问题，重新检查第 1–2 步。

路由模型子代理缺失

拉取 main 只更新源码检出。把它应用到按用户安装并验证生成的自定义代理：

./bin/model-router codex update
./bin/model-router codex doctor

doctor 应对 Routed model agents 报告 OK。否则：

./bin/model-router codex doctor --fix

然后完全退出 Codex、重新打开并新建任务。生成的个人代理定义存放在 $CODEX_HOME/agents/（通常为 ~/.codex/agents/）。

仍然缺失？检查托管配置

配置根应恰好包含一个 codex-router-managed 块，含 4102 端口回环 base URL、生成的 /_codex-router/.../v1 路径，以及 $CODEX_HOME/codex-router/merged-models.json 目录。分享诊断时用会脱敏生成路径的 ./bin/status，绝不要把完整托管 URL 粘贴进 issue。

都不行时

运行 doctor --fix、创建 support bundle，并在仓库 开 issue 附上脱敏输出。完整诊断流程见故障排查总览与 doctor 指南。