Codex Desktop 无法识别自定义模型的 5 种解决方法（2026 最新）

你接好了一个自定义 provider，codex 在终端里跑得好好的，但桌面版的模型选择器却像你的模型根本不存在一样。 这种落差几乎从来不是你的 API 密钥或配置语法出了问题，而是桌面版客户端悄悄过滤掉了后端已经加载好的模型。

30 秒快速诊断

在重写任何东西之前，先把你的症状对照下表。大多数人离修复只差一行。

最快的一步检查：在同一个文件夹里打开终端运行 codex（CLI），然后输入 /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 会隐藏自定义模型

一共有四个不同的根本原因，各自需要不同的修复方法。搞错了原因，正是人们花一下午重新敲一份本来就能用的配置的根源。

第一个最让人意外。根据尚未关闭的 codex issue #19694，app-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.toml，Codex 会在启动时打印警告并完全忽略这个配置块。Provider 定义只在用户级作用域生效。

Codex 如何加载模型（以及桌面版在哪里分道扬镳）

Codex 是分层构建它的模型列表的，弄清顺序就能知道哪个修复真正管用。一共有三个来源：随二进制文件打包的内置目录、从 OpenAI 拉取的远程目录，以及你本地的 model_catalog_json。本地文件优先级最高。它在启动时会同时覆盖内置目录和远程目录，这正是为什么一份正确的 model_catalog_json 是第三方模型的真正操控杆，而不是可有可无的锦上添花。 与 CLI 版本直接读取环境变量中的 OPENAI_API_BASE 不同，Codex Desktop 在启动时会对模型列表进行静态缓存，这意味着OpenRouter 或 等兼容网关暴露的自定义模型，需要满足特定的 /v1/models 响应格式才能被桌面端正确枚举。

下面这部分会把所有人绊倒。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 = ""

[model_providers.]
name = ""
base_url = ""
env_key = "API_KEY"
wire_api = "responses"

导出密钥（在你的 shell 配置里 export API_KEY=sk-...），彻底退出 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 #7782）；responses 现在是唯一支持的取值，也是省略该键时的默认值。仍然设为 wire_api = "chat" 的 provider 会在启动时失败。实际的要求是：你的网关必须在 {base_url}/responses 暴露一个 OpenAI 兼容的 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/-models.json"
model = "moonshotai/kimi-k2.7-code"
model_provider = ""

一个最小的目录条目，字段取自官方的 codex models.json：

{
 "models": [
 {
 "slug": "moonshotai/kimi-k2.7-code",
 "display_name": "Kimi K2.7 Code ",
 "description": "Coding model via the 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 again

cc-switch 本身禁用了一个需要注意的东西：少数国产一方模型（MiMo、LongCat、MiniMax、Qwen3-Coder）在它们的网关上不支持 OpenAI 的内置 web_search，所以 v3.16.5 默认为它们关闭了该工具，以避免 Codex 抛出硬性的 400 错误。如果你网关路由这些模型，预期网络搜索会处于关闭状态。

那些看起来像选择器缺陷的常见配置错误

在“自定义模型不显示”的报告里，有一半其实是断掉的路由披着一件显示问题的外衣。在你动目录之前，先排除这些。每一个都会产生一个看起来像选择器隐藏了模型的症状，而实际上请求压根没机会送达。

把这些和真正的 #19694 过滤区分开的标志只需一条命令：从 CLI 发出同样的请求。如果 CLI 也失败，那就是上面那些错误之一，而不是桌面版选择器，改目录也修不好。如果 CLI 成功、只有桌面版依旧看不见，那才是过滤问题，你就回到修复 1 和修复 4。

已知的 Codex Desktop 自定义模型问题（2026 时间线）

这不是单一缺陷。它是 Codex 应用以及那些写它配置的工具中一簇相关的问题。搞清楚你遇到的是哪一个，能让你免于用错修复方法。

贯穿所有这些的规律是：路由能用，显示不能用。每一次，CLI 都是可靠的应急出口，因为它读取目录时不经过桌面版渲染层那道额外过滤。如果你在桌面版里卡住了，CLI（在终端里运行 codex）几乎总能显示并使用该模型。

当选择器仍然不显示模型时：现在就能用的替代方案

如果你不想再和桌面版 UI 较劲了，下面这些方法能让你继续使用自定义模型，而不必等客户端修复。在这里用网关的意义在于：一个端点、一个密钥，覆盖众多模型，于是切换模型只是改一个字符串，而不是每次都新增一个 provider 配置块。 当 Codex Desktop 的模型选择器持续无法识别自定义端点时，开发者可以转向 OpenRouter 或 等聚合网关，标准 OpenAI 兼容 API 格式将请求路由至目标模型，从而绕过桌面客户端的本地配置解析流程。

用 作为 provider 能把维护成本降到最低：moonshotai/kimi-k2.7-code（262K 上下文）、deepseek/deepseek-v4-pro（1M 上下文）和 openai/gpt-5.3-codex（512K 上下文）都位于同一个 之后、共用同一个密钥，每个模型的 页面上都会显示当前的按 token 计价。要切换模型，只需改config.toml` 里的一个字符串，不用新增 provider 配置块，也不用第二个密钥。针对 OpenAI 兼容客户端的 base-URL 配置见 docs。无论你走哪条路，桌面版选择器的怪癖只是叠在上层的显示问题，而不是路由上的约束。

如何验证你的自定义模型确实已加载

不要把选择器当作事实来源，因为坏掉的正是它。要在它下面那一层做验证。

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 里。对于 ，base_url = ""。

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。在 上：moonshotai/kimi-k2.7-code、deepseek/deepseek-v4-pro、openai/gpt-5.3-codex，全都来自 `

对于一个能跑却不肯显示出来的模型，修复方法几乎总是：别再折腾选择器，转而去信任它下面那一层——CLI 早已看到了桌面版正在隐藏的东西。

本次更新核查的资料来源

• Codex issue #19694: Desktop model picker filters out models from model_catalog_json（未关闭，核实于 2026-07-05）

• cc-switch v3.16.5 release notes（核实于 2026-07-05）

• cc-switch issue #3668: catalog format not recognized by Codex（核实于 2026-07-05）

• Codex configuration reference（核实于 2026-07-05）

• Codex models.json catalog schema（核实于 2026-07-05）

• 模型目录与价格快照， 2026-07-05）

参考来源

• ofox 文档：模型目录 — https://docs.ofox.io/zh/develop/models