---
title: "本地模型目录用 model_catalog_json，改完必须重启"
summary: "启动时加载的 JSON 覆盖内置和远程目录，不是合并。先 dump bundled，再改 slug。桌面选择器可能仍显示 Custom。"
category: config
level: advanced
surfaces: [cli, app]
tags: ["model_catalog_json", "debug models", "模型"]
canonical: /tips/model-catalog-json/
---

# 本地模型目录用 model_catalog_json，改完必须重启

启动时加载的 JSON 覆盖内置和远程目录，不是合并。先 dump bundled，再改 slug。桌面选择器可能仍显示 Custom。

`/model` 没有你要的 slug、或第三方 provider 只显示 Custom 时，不要只改 `model =`。官方扩展点是用户级 `~/.codex/config.toml`：

```toml
model_catalog_json = "/home/you/.codex/model-catalog.json"
model = "your-model-slug"
```

路径必须在启动时就能读到。本地文件会**覆盖**二进制内置目录和远程刷新，不是往上面追加。只写一条模型，其它内置项会从这一进程的目录里消失。稳妥做法：

```bash
codex debug models --bundled
codex debug models
```

`--bundled` 跳过网络刷新，只看编译进二进制的那份。无旗标打印三层合并后的结果。对照 slug、`context_window`、显示名之后，再把需要的条目写进本地 JSON。JSON 顶层是 `models` 数组；具体字段以 dump 出来的形状为准，不要抄过期博客里的网关专用文件。

`profiles.<name>.model_catalog_json` 可按 profile 覆盖，同样只在启动时生效。改文件、改路径、改 `reloadUserConfig` **都不会**让已经在跑的 app-server 重读目录，必须退出 Desktop / CLI。项目 `.codex/config.toml` 不能定义 `model_provider`；目录键按设计可读项目文件，但桌面新线程有时读不到，遇到就写进用户 config。

核对：

```bash
codex debug models | head
```

桌面选择器如果仍过滤掉本地模型，`model =` 仍然会发给 provider，只是 UI 写成 Custom。不要为此去改实验性 rollout 开关。

## 来源

- [OpenAI · Configuration reference](https://developers.openai.com/codex/config-reference)
- [Codex Knowledge Base · Model catalogue](https://codex.danielvaughan.com/2026/05/04/codex-cli-model-catalogue-architecture-providers-discovery-debug/)