Codex model_catalog_json 配置指南
截至 2026-10-08，model_catalog_json 是 Codex config.toml 里的可选键，值是一个 JSON 模型目录文件的路径，Codex 只在启动时加载它；Codex 开源代码的源码注释中写明，设置后它替换当前进程的内置模型目录，/model 选择器的候选项也从生效的目录生成。profile 文件可以单独覆盖它，两处都设时以 profile 为准。本页按官方配置参考、变更日志与 Codex 开源代码原文，讲清格式、覆盖规则、0.160.0 的变化和 /model 里看不到型号的几种原因。
更新于 2026-10-08
四个要点
什么时候生效
官方配置参考：这是启动时加载的 JSON 模型目录路径。Codex 开源代码的配置 schema 中补充写明，会话内的 config 覆盖会被接受但不会重新应用，改完文件要重启 Codex。
和内置目录的关系
Codex 开源代码的源码注释中写明设置后替换当前进程的内置目录；/model 的候选项从生效的目录生成，按 priority 排序、按认证方式与 visibility 过滤。
两处都设时
官方高级配置：profile 文件也能覆盖 model_catalog_json，两份文件都设时 Codex 用 profile 的值。
显式 provider 目录
2026-10-01 发布的 Codex CLI 0.160.0：显式 provider 模型目录不再混入不支持的内置型号，刷新失败后也不再沿用旧条目。
model_catalog_json 是做什么的
截至 2026-10-08，model_catalog_json 用来给 Codex 指定一份自己的模型目录：官方配置参考的原话是「Optional path to a JSON model catalog loaded on startup」，类型为 string (path)；官方示例配置写作 model_catalog_json = "/absolute/path/to/models.json"，注释是启动时生效的模型目录覆盖。Codex 开源代码的源码注释中进一步写明，设置后这份目录替换当前进程的内置目录，/model 选择器的候选项就从生效的目录生成。所以要让 /model 只列你挑的型号、改显示名或排序，改的就是这份文件。还有两条限制：配置参考在 Work Cloud 的本地电脑访问兼容性限制表里把它列为不支持作为托管云端覆盖项，原话是本地模型目录不会带过去；管理员也可以在 requirements.toml 里强制指定 Codex 启动时使用的 JSON 模型目录。
版本变化（0.156.0 到 0.161.0）
Codex CLI 0.156.0（2026-09-22）的完整变更列表里有 #46561「Support explicit provider model catalog URLs」，对应 PR 写明给 provider 配置加了 model_catalog_url，并且自定义 base_url 的 API key 会话要做目录发现，必须显式给出目录 URL。0.160.0（2026-10-01）的发布说明写道「Explicit provider model catalogs no longer include unsupported bundled models or reuse stale entries after refresh failures」。PR #49135 解释：此前带 model_catalog_url 的 provider 可能列出自己目录里没有的内置型号；改后目录 slug 必须唯一且非空，元数据按确切模型 ID 匹配，启动时没有可用型号会报配置错误，但显式写了 model 的仍然允许。0.161.0（2026-10-07）：GPT-6.1 Sol 成为内置目录和 Amazon Bedrock 目录的默认型号。
模型目录相关的时间线
Codex CLI 0.156.0 发布，完整变更列表含 #46561：provider 配置新增 model_catalog_url。
Codex CLI 0.160.0 发布：显式 provider 模型目录不再混入不支持的内置型号，也不再沿用刷新失败前的旧条目。
Codex CLI 0.161.0 发布：GPT-6.1 Sol 成为内置目录与 Amazon Bedrock 目录的默认型号；本页于 2026-10-08 按官方页核对。
已确认 vs 官方没写的
已确认（官方文档与开源代码逐字可核）
以下都能在 Codex 官方文档、变更日志或 Codex 开源代码（配置 schema、源码与 PR 说明）里逐字核到：model_catalog_json 是启动时加载的 JSON 模型目录路径；会话内 config 覆盖不会重新应用；设置后替换当前进程的内置目录；/model 候选项按 priority 排序、按认证方式与 visibility 过滤；profile 文件可以覆盖它，两处都设时用 profile 的值；0.134.0 起 --profile 不再读 config.toml 里的 [profiles.profile-name] 表；在 Work Cloud 场景下它不支持作为托管云端覆盖项；JSON 解析失败与目录为空各有一条启动报错；0.160.0 起显式 provider 目录不再混入不支持的内置型号；0.161.0 起 GPT-6.1 Sol 是内置目录的默认型号。
官方没写、本页不下结论的
三件事官方没有说明，本页不替官方补：① 目录条目哪些字段必填、各字段的取值范围，官方文档没有字段表，可参照的是 Codex 开源代码自带的 models.json；② 相对路径怎么解析，配置参考只写 string (path)，示例配置正文用绝对路径，profile 示例里出现过 ./models.json，稳妥起见写绝对路径；③ 0.160.0 那条显式 provider 目录的改动，PR 里点名的是 model_catalog_url，本地 model_catalog_json 是否受同样规则约束，官方没有写明。另外截至 2026-10-08，model_catalog_url 能在 Codex 开源代码的配置 schema 与 PR 说明里查到，developers.openai.com 的配置参考页上没有这个键。
model_catalog_json 和 model_catalog_url 怎么选
model_catalog_json（本地文件）
写在 config.toml 或 profile 文件顶层，值是本地 JSON 文件路径，只在启动时读取，设置后替换内置目录。适合想固定 /model 列表、或按 profile 切换不同目录的个人与团队。在 Work Cloud 场景下它不能作为托管云端覆盖项。
model_catalog_url（provider 级）
写在某个 provider 的配置里，Codex 开源代码的配置 schema 中描述为「Optional full URL for a Codex-native model catalog」，PR 说明写明 Codex 会带着该 provider 的认证去取目录。适合网关方自己维护目录的情况；0.160.0 起这类显式目录被当作权威，不再混入目录外的内置型号。
配置步骤
① 先接好 provider。以 QCode 文档为例（provider 名字可自定，文档示例用 crs；环境变量名也可自定，文档示例用 CRS_OAI_KEY）：在 ~/.codex/config.toml 写 model_provider = "crs"、model = "gpt-6-sol"、model_reasoning_effort = "high"、preferred_auth_method = "apikey"，再加 [model_providers.crs] 表：name = "crs"、base_url = "https://api.qcode.cc/openai"、wire_api = "responses"、requires_openai_auth = true、env_key = "CRS_OAI_KEY"。② 准备目录文件：以 Codex 开源代码里的 codex-rs/models-manager/models.json 为样本，顶层是 "models" 数组，每个条目有 slug、display_name、priority、visibility、context_window 等字段；只保留你要的条目，slug 写确切的模型 ID，例如 gpt-6.1-sol、gpt-6-sol、gpt-5.6-sol，不要自编样本里没有的字段。③ 在 config.toml 顶层加 model_catalog_json = "/absolute/path/to/models.json"。④ 要按场景换目录：把 model_catalog_json 写进 ~/.codex/profile-name.config.toml 的顶层，用 codex --profile profile-name 启动，不要再写进 [profiles.profile-name] 表。⑤ 重启 Codex，在会话里输入 /model 核对列表。
在 QCode 上
QCode 的 Codex 接法照 docs.qcode.cc 的 Codex 页：base_url 填 https://api.qcode.cc/openai，wire_api 填 responses，密钥用 QCode 的 API 密钥（以 cr_ 开头）；这条接法只服务 GPT 系，Claude 与国产模型不走这里。QCode 文档的 Codex 配置里没有 model_catalog_json 这一项，按文档配置即可使用。gpt-6.1-sol、gpt-6-sol、gpt-5.6-sol 在 QCode 可调，这三个 ID 也都在 Codex 开源代码的内置目录 models.json 里；想临时换型号可以用 codex -m gpt-6-sol。按 token 计费，各模型单价见 /models。
常见问题
model_catalog_json 是做什么的？
它给 Codex 指定一份 JSON 模型目录。官方配置参考写明这是启动时加载的目录文件路径；Codex 开源代码的源码注释中写明设置后替换当前进程的内置目录，/model 的候选项随之来自这份文件。它是可选键，类型为路径字符串。
为什么自定义的型号在 /model 里看不到？
最常见的原因是目录里没有这一条，或条目没按可见方式写：Codex 开源代码的源码注释中写明 /model 候选项按 priority 排序、按认证方式与 visibility 过滤，Codex 开源代码自带的内置目录里就有 visibility 为 "hide" 的条目。其次是改完文件没重启，它只在启动时生效。如果用的是带 model_catalog_url 的 provider，0.160.0 起目录外的内置型号也不会再混进来。
目录文件是什么格式？
顶层是一个 "models" 数组：Codex 开源代码读取这份文件时检查的就是 models 列表，开源代码自带的 models.json 也是这个结构。数组至少要有一个条目，否则启动报 model_catalog_json path ... must contain at least one model；JSON 写错则报 failed to parse model_catalog_json path ... as JSON。官方文档没有字段表，稳妥的写法是从内置文件复制条目，再改 slug、display_name 与 priority。
profile 和 config.toml 都设了，以哪个为准？
以 profile 为准。官方高级配置写明 profile 文件也能覆盖 model_catalog_json，两份文件都设时 Codex 用 profile 的值。profile 写在 ~/.codex/profile-name.config.toml 的顶层；0.134.0 起 --profile 不再读 config.toml 里的 [profiles.profile-name] 表。
0.160.0 对模型目录改了什么？
显式 provider 模型目录被当作权威：2026-10-01 的发布说明写明它们不再混入不支持的内置型号，刷新失败后也不再沿用旧条目。PR #49135 补充：目录 slug 必须唯一且非空，元数据按确切模型 ID 匹配；启动时一个可用型号都没有会报配置错误，但显式写了 model 的仍然允许。
用 QCode 时一定要配 model_catalog_json 吗？
不是必需的。QCode 文档的 Codex 配置里没有这一项，按文档填 base_url https://api.qcode.cc/openai 与 wire_api = "responses" 即可调 gpt-6.1-sol、gpt-6-sol、gpt-5.6-sol，这三个 ID 也都在 Codex 开源代码的内置目录里。只有想让 /model 只列你挑的几个型号、或改显示名与排序时，才需要自建目录。
信息来源
键的定义、profile 覆盖规则与托管限制：OpenAI 的 Codex 配置参考、高级配置、示例配置与模型页（developers.openai.com，2026-10-08 抓取）。版本变化：Codex 官方变更日志与 GitHub Releases 中 0.156.0、0.160.0、0.161.0 的说明，同日抓取。目录格式、替换规则、报错文案与 /model 过滤规则：openai/codex 开源代码 main 分支的配置 schema、内置目录 models.json 与源码注释，以及 PR #46561、#49135 的说明，同日抓取。QCode 接法：QCode 文档的 Codex 接入页（更新于 2026-09-30），同日抓取。
相关阅读
Codex CLI 接第三方 API：config.toml 与报错
config.toml、base_url 与 wire_api 的写法，以及接入时的常见报错。
Codex 里的 GPT-5.5：2026-10-14 退役，API 可用
GPT-5.5 在 Codex 里的退役日期，以及 API 侧继续可用的情况。
Codex 401 怎么修：登录与 env_key
401 Unauthorized 的登录方式、API 密钥与 env_key 排查。
本页配置写法与引语核对于 2026-10-08，以 OpenAI Codex 官方文档、变更日志与 Codex 开源代码为准，上游调整不另行通知。源码注释与内置目录会随版本变化，以你本机的 Codex 版本为准；模型可用性以 /models 为准。