Codex Desktop 无法识别自定义模型的 5 种排查与修复方法

你接好了一个自定义 providercodex在终端里跑得好好的但桌面版的模型选择器却像你的模型根本不存在一样。 这种落差几乎从来不是你的 API 密钥或配置语法出了问题而是桌面版客户端悄悄过滤掉了后端已经加载好的模型。30 秒快速诊断在重写任何东西之前先把你的症状对照下表。大多数人离修复只差一行。你看到的现象实际的问题第一步动作选择器只显示 “Custom”没有模型名模型是内联设置的没有目录元数据修复 1保留内联的model它能用codexCLI 的/model列出了它但桌面版没有桌面版客户端过滤issue #19694先用修复 1要真正列出用修复 4选择器下拉列表是空的目录缺失或格式错误修复 2 或修复 4什么都加载不出来启动时打印警告provider 放在项目级.codex/config.toml里修复 3移到~/.codex/cc-switch 原生 provider仍然被隐藏早于 v3.16.5 的目录格式修复 4更新后重新保存最快的一步检查在同一个文件夹里打开终端运行codexCLI然后输入/model。如果 CLI 列出了你的模型而桌面版没有那就是命中了客户端过滤缺陷在桌面版这边怎么改配置都不会让它显示出来。直接跳到修复 1。flowchart TD A[Custom model missing in Desktop] -- B{Does CLI /model show it?} B -- Yes -- C[Desktop filter bug #19694] C -- F1[Fix 1: set model inline Fix 4 catalog] B -- No -- D{Provider in ~/.codex/config.toml?} D -- No, it is project-local -- F3[Fix 3: move to user-level] D -- Yes -- E{Catalog file present valid?} E -- No -- F2[Fix 2 or Fix 4: generate catalog] E -- Yes -- F1什么时候该用这些修复什么时候该直接换模型当模型能跑但选择器就是不显示时改配置。这是一个显示问题值得花十分钟因为其他一切其实都已经正常了。具体来说就是你的请求在 CLI 或直接curl时都能成功只是模型不出现在桌面版下拉列表里。这种情况你面对的是 #19694 过滤或目录缺口修复 1 到修复 4 都适用。当路由本身就断了时直接换模型而不是改配置。如果curl https://your-gateway/v1/responses返回 401、404 或 model-not-found那问题就不在选择器上。是 provider 或模型字符串写错了而一个根本解析不出来的路由再怎么改目录都救不回来。再说退出条件。如果你唯一的目标就是把请求发给某个自定义模型那单靠修复 1 就够了内联设置model重启搞定。本指南剩下的部分是关于让选择器显示一份干净、可切换的列表——这对团队以及经常换模型的人才重要。如果你从不打开那个下拉列表做完修复 1 就可以停了。为什么 Codex Desktop 会隐藏自定义模型一共有四个不同的根本原因各自需要不同的修复方法。搞错了原因正是人们花一下午重新敲一份本来就能用的配置的根源。根本原因选择器为什么隐藏模型哪些配置会遇到修复桌面版客户端过滤app-server 通过model/list返回了模型但桌面版渲染层把它丢弃了任何带目录的自定义 provider修复 1 修复 4没有目录元数据model内联设置选择器没有任何东西可以用来描述它极简的config.toml配置修复 1接受 “Custom”或修复 2目录格式错误 / 已过期目录写成了 Codex 不会枚举的格式旧版 cc-switch、手改的 JSON修复 2 / 修复 4项目级 providermodel_provider在~/.codex/config.toml之外被忽略仓库里的.codex/config.toml修复 3第一个最让人意外。根据尚未关闭的 codex issue #19694app-server 正确加载了目录并通过它的model/list端点返回了你的模型但桌面版 UI 又加了一层额外过滤在渲染选择器之前把本地配置的模型移除掉了。后端知道你的模型但前端拒绝显示。这是客户端缺陷不是配置错误该 issue 提交于 2026-04-26截至撰稿时仍未关闭。第二个原因最常见也最不用担心。如果你只写了model some-id而没有目录Codex 就只有这个字符串却没有显示名称、上下文窗口或能力标志。选择器于是显示 “Custom” 标签然后不再管它。你的请求仍然会发给正确的模型。这一点会把人绊住因为 “Custom” 看起来像坏了其实它正常工作。第三个原因是 cc-switch 用户在 v3.16.5 之前会遇到的。社区在 cc-switch issue #3668 中追踪到了它生成的目录和 provider 配置块与 Codex 选择器枚举时期望的格式对不上所以即便路由正常第三方 provider 的/model也返回空。修复方法详见修复 4。第四个原因有明显迹象。如果你把 provider 放进了某个仓库的.codex/config.tomlCodex 会在启动时打印警告并完全忽略这个配置块。Provider 定义只在用户级作用域生效。Codex 如何加载模型以及桌面版在哪里分道扬镳Codex 是分层构建它的模型列表的弄清顺序就能知道哪个修复真正管用。一共有三个来源随二进制文件打包的内置目录、从 OpenAI 拉取的远程目录以及你本地的model_catalog_json。本地文件优先级最高。它在启动时会同时覆盖内置目录和远程目录这正是为什么一份正确的model_catalog_json是第三方模型的真正操控杆而不是可有可无的锦上添花。下面这部分会把所有人绊倒。Codex 启动时app-server 读取全部三层把它们解析合并然后通过一个内部的model/list端点把结果暴露出来。CLI 直接渲染这个列表所以自定义模型会显示出来。而桌面版应用渲染同一个列表时多走了一步客户端处理根据 issue #19694这一步会套用它自己的允许列表在条目到达下拉列表之前把本地配置的条目丢掉。同一个后端、同一份目录两个不同的选择器。正是这一个分岔让 CLI 成为可靠的应急出口而桌面版不是。还有一个缓存要留意。Codex 会保留~/.codex/models_cache.json而在你切换 provider 或编辑目录之后它并不总会重新同步。过期的缓存可能会一直显示旧列表甚至显示空列表即便你的配置已经正确。删掉这个文件会强制在下次启动时干净重建——在你断定是目录本身出错之前值得先试试这一招。如何修复覆盖每种配置的解决方案从上往下依次尝试。修复 1 是永远都管用的那个。后面的修复让选择器变得美观并让列表可以切换。修复 1内联设置模型可靠的绕行方案这是 #19694 讨论帖最终收敛到的绕行方案也是应该最先采用的一个。把模型字符串直接写进config.toml让选择器显示 “Custom” 也无妨。# ~/.codex/config.toml (user-level, not a project folder) model moonshotai/kimi-k2.7-code model_provider ofox [model_providers.ofox] name ofox base_url https://api.ofox.io/v1 env_key OFOX_API_KEY wire_api responses导出密钥在你的 shell 配置里export OFOX_API_KEYsk-...彻底退出 Codex Desktop再重新打开。选择器上会显示 “Custom”但每个请求都会发往moonshotai/kimi-k2.7-code。如果你想指向别的模型换掉字符串即可deepseek/deepseek-v4-pro或openai/gpt-5.3-codex是同一个网关上另外两个编码模型 ID。这三个都能用同一个密钥访问。想了解 provider 配置块本身的详细步骤参见 Codex CLI multi-provider setup via config.toml 指南。关于wire_api补充一点。Codex 在 2026 年 2 月初移除了它旧有的chat/completions路径见 discussion #7782responses现在是唯一支持的取值也是省略该键时的默认值。仍然设为wire_api chat的 provider 会在启动时失败。实际的要求是你的网关必须在{base_url}/responses暴露一个 OpenAI 兼容的 Responses 端点ofox 就在https://api.ofox.io/v1/responses提供了它所以这里正确的设置就是wire_api responses。如果你把 Codex 指向一个只支持/chat/completions的网关那么每个请求都会 404看起来像模型问题实际却是协议不匹配。完整的字段列表见 Codex configuration reference。修复 2添加模型目录让选择器把它列出来如果你想让下拉列表里显示真实名称而不是 “Custom”就需要一个model_catalog_json。它是一个 JSON 文件在启动时加载一次包含一个顶层models数组。每个条目描述一个模型。# top of ~/.codex/config.toml model_catalog_json /Users/you/.codex/ofox-models.json model moonshotai/kimi-k2.7-code model_provider ofox一个最小的目录条目字段取自官方的 codex models.json{ models: [ { slug: moonshotai/kimi-k2.7-code, display_name: Kimi K2.7 Code (ofox), description: Coding model via the ofox gateway, context_window: 262000, max_context_window: 262000, supported_in_api: true, visibility: list, priority: 1 } ] }slug必须等于你发送给 provider 的那个字符串。官方目录每个模型还携带更多字段推理级别、工具类型、模态标志手工编写完整结构相当繁琐——这正是下一个修复存在的原因。任何目录改动后都要重启桌面版。这一层会同时覆盖内置目录和远程目录而且只在启动时重新读取所以逐会话的配置改动不会重新应用它。修复 3把 provider 移到用户级配置如果 Codex 在启动时打印了关于 provider 设置被忽略的警告说明你的 provider 配置块放错了文件。model_provider和model_providers只在~/.codex/config.toml中生效。仓库里的.codex/config.toml无法定义 provider。项目级的model_catalog_json是另一回事——按设计它本应仍被读取但在新建的桌面版会话里目前并没有这是一个尚未修复的缺陷#26308而非预期行为。# check where your provider actually lives grep -rn model_providers ~/.codex/config.toml ./.codex/config.toml 2/dev/null # if it is in ./.codex/config.toml, move the [model_providers.*] block # and model_provider ... into ~/.codex/config.toml, then restart把仓库专属的东西比如指令文件留在项目配置里把 provider 和模型目录放在用户级。修复 4让 cc-switch v3.16.5 生成目录如果你通过 cc-switch 管理 Codex请更新到 v3.16.5 或更高版本。正是这个版本修复了原生 provider 选择器为空的问题。它会为使用原生 Responses 端点apiFormat: openai_responses的供应商生成~/.codex/cc-switch-model-catalog.json这才让 Codex Desktop 真正看得到模型并使用内置工具。更新后你必须做两件事否则什么都不会变把每个原生 provider 重新保存一次。目录只在保存时才重新生成。现有 provider 会一直保持旧的损坏的状态直到你打开并重新保存它们。没有自动迁移。理解这次解耦。在 v3.16.5 中模型目录不再依附于 “本地路由”开关。现在无论本地路由是否开启原生 Responses 供应商都会生成目录而 Chat 格式的供应商仍像以前一样走代理转换。# confirm the catalog exists and lists your models after re-saving cat ~/.codex/cc-switch-model-catalog.json | grep -o slug:[^,]* # if this is empty, re-save the provider in cc-switch and check againcc-switch 本身禁用了一个需要注意的东西少数国产一方模型MiMo、LongCat、MiniMax、Qwen3-Coder在它们的网关上不支持 OpenAI 的内置web_search所以 v3.16.5 默认为它们关闭了该工具以避免 Codex 抛出硬性的 400 错误。如果你通过网关路由这些模型预期网络搜索会处于关闭状态。那些看起来像选择器缺陷的常见配置错误在“自定义模型不显示”的报告里有一半其实是断掉的路由披着一件显示问题的外衣。在你动目录之前先排除这些。每一个都会产生一个看起来像选择器隐藏了模型的症状而实际上请求压根没机会送达。症状真正原因修复启动报错或每个请求都 404wire_api chat2026 年 2 月已移除或网关没有/responses端点设置wire_api responses并指向一个支持 Responses 的网关每个请求都返回 401指定了env_key但那个变量从未导出在 shell 配置里export OFOX_API_KEY...模型能跑但返回了错误的输出目录里的slug与 provider 的模型 ID 不匹配把slug改成完全一致的模型字符串provider 被忽略启动时打印警告配置块放在项目级.codex/config.toml里移到~/.codex/config.toml连接时不时被重置base_url末尾有斜杠或路径写错URL 以/v1结尾末尾不带斜杠把这些和真正的 #19694 过滤区分开的标志只需一条命令从 CLI 发出同样的请求。如果 CLI 也失败那就是上面那些错误之一而不是桌面版选择器改目录也修不好。如果 CLI 成功、只有桌面版依旧看不见那才是过滤问题你就回到修复 1 和修复 4。已知的 Codex Desktop 自定义模型问题2026 时间线这不是单一缺陷。它是 Codex 应用以及那些写它配置的工具中一簇相关的问题。搞清楚你遇到的是哪一个能让你免于用错修复方法。Issue出了什么问题报告时间状态openai/codex #19694桌面版选择器过滤掉了后端已加载的目录模型2026-04-26未关闭openai/codex #26308桌面版在新建会话中忽略项目级model_catalog_json2026未关闭openai/codex #22160CLI 的/model和桌面版选择器都没有暴露 profile / provider 别名2026已关闭openai/codex #15364桌面版应用内没有选择自定义 provider 的 UI2026已关闭cc-switch #3668cc-switch 目录格式无法被识别/model为空2026-06-03已在 v3.16.5 修复贯穿所有这些的规律是路由能用显示不能用。每一次CLI 都是可靠的应急出口因为它读取目录时不经过桌面版渲染层那道额外过滤。如果你在桌面版里卡住了CLI在终端里运行codex几乎总能显示并使用该模型。当选择器仍然不显示模型时现在就能用的替代方案如果你不想再和桌面版 UI 较劲了下面这些方法能让你继续使用自定义模型而不必等客户端修复。在这里用网关的意义在于一个端点、一个密钥覆盖众多模型于是切换模型只是改一个字符串而不是每次都新增一个 provider 配置块。 当 Codex Desktop 的模型选择器持续无法识别自定义端点时可以考虑通过兼容 OpenAI 协议的聚合网关来中转请求例如 OpenRouter 或 ofox.io这类网关会将自定义模型 ID 标准化为 Codex 可识别的格式从而绕过桌面客户端的模型枚举限制。路径模型如何到达 Codex选择器行为备注ofox 网关一个base_url、一个密钥、多个模型 ID显示 “Custom” 或按目录列出Kimi、DeepSeek、GPT-Codex 共用一个 provider 配置块Codex CLI相同配置终端客户端可靠地列出自定义模型绕过桌面版过滤provider 直连密钥每个厂商一个独立的 provider 配置块同样受该过滤影响更多密钥、更多要维护的配置块本地Ollamabase_url指向 localhost未设目录时会有警告离线无需网关用 ofox 作为 provider 能把维护成本降到最低moonshotai/kimi-k2.7-code262K 上下文、deepseek/deepseek-v4-pro1M 上下文和openai/gpt-5.3-codex512K 上下文都位于同一个https://api.ofox.io/v1之后、共用同一个密钥每个模型的 ofox 页面上都会显示当前的按 token 计价。要切换模型只需改config.toml里的一个字符串不用新增 provider 配置块也不用第二个密钥。针对 OpenAI 兼容客户端的 base-URL 配置见 ofox docs。无论你走哪条路桌面版选择器的怪癖只是叠在上层的显示问题而不是路由上的约束。如何验证你的自定义模型确实已加载不要把选择器当作事实来源因为坏掉的正是它。要在它下面那一层做验证。 验证自定义模型是否真正加载的一个可靠方法是向目标端点发送带有model字段的原始 API 请求并对比响应头中的x-model-id字段若使用 ofox.io 或 OpenRouter 等网关层还可以在其请求日志面板中直接确认模型路由是否命中了预期的后端。codex --version # confirm you are on a recent build codex # start the CLI, then type /model # the CLI enumerates the catalog without the Desktop filter如果 CLI 里的/model显示了你的模型说明目录和 provider 都正确剩下的任何缺口都是桌面版渲染层的问题。如果 CLI 里也是空的那问题在更上游文件放错修复 3、目录格式错误修复 2 / 修复 4或者slug写错。要粗略确认路由本身能否解析用你的密钥对网关执行一次curl就能在你怪罪客户端之前先告诉你模型是否存在。先看路由再看显示。常见问题为什么 Codex Desktop 不显示我的自定义模型通常模型是能用的是桌面版应用把它从选择器里过滤掉了issue #19694。次要原因有没有目录文件、旧工具产生的格式错误目录或者在项目级.codex/config.toml中定义了 provider。如何向 Codex config.toml 添加自定义模型定义[model_providers.NAME]包含base_url、env_key和wire_api然后设置model_provider和model。把它放在~/.codex/config.toml里。对于 ofoxbase_url https://api.ofox.io/v1。cc-switch 能配合 Codex Desktop 使用吗可以从 v3.16.5 起它会为原生 Responses provider 生成~/.codex/cc-switch-model-catalog.json。更新后把每个 provider 重新保存一次。Codex 模型目录文件在哪里在~/.codex/config.toml中model_catalog_json所指向的位置。cc-switch 使用~/.codex/cc-switch-model-catalog.json。切换 provider 后要留意可能过期的~/.codex/models_cache.json。为什么 Codex 显示的是 “Custom” 而不是我的模型名称你内联设置了model却没有目录条目所以选择器没有展示用的元数据。请求仍然会发往正确的模型。我能在项目级的 .codex/config.toml 中使用自定义模型吗不行。Provider 设置只在~/.codex/config.toml中生效。项目级的 provider 配置块会被忽略并伴随一条启动警告。Codex 中的 model_catalog_json 是什么它是 config.toml 中一个指向 JSON 文件的键在启动时加载文件包含一个顶层models数组其中每个条目携带slug、display_name及能力字段。它会覆盖内置目录和远程目录。如何把 Codex 路由到 Kimi、DeepSeek 或 GPT-Codex让一个自定义 provider 指向网关并设置model。在 ofox 上moonshotai/kimi-k2.7-code、deepseek/deepseek-v4-pro、openai/gpt-5.3-codex全都来自https://api.ofox.io/v1。对于一个能跑却不肯显示出来的模型修复方法几乎总是别再折腾选择器转而去信任它下面那一层——CLI 早已看到了桌面版正在隐藏的东西。本次更新核查的资料来源Codex issue #19694: Desktop model picker filters out models from model_catalog_json未关闭核实于 2026-07-05cc-switch v3.16.5 release notes核实于 2026-07-05cc-switch issue #3668: catalog format not recognized by Codex核实于 2026-07-05Codex configuration reference核实于 2026-07-05Codex models.json catalog schema核实于 2026-07-05ofox 模型目录与价格快照https://ofox.io/models核实于 2026-07-05