Appearance
Codex 使用第三方模型
本教程适用于已配置过本站 Codex 的用户。如果还没有配置，请先完成 Codex 安装使用，再按下面的步骤添加其他模型。
检查密钥分组
请先到 网页后台 确认你的 API Key 所属分组能够看到并调用目标模型。JSON 中出现某个模型，不代表该密钥的分组已开通它。
复制给 Agent 配置
已经配置过本站 Codex 的用户，可以直接把下面的提示词复制给 Agent：
text
帮我给 Codex 添加 CloudAwn 模型目录。我已经配置过本站 Codex，请保留现有 API 地址、密钥和其他设置。
1. 下载 https://docs.cloudawn.top/downloads/model-catalog.json ，确认下载内容是有效的模型目录 JSON，不是 HTML 或错误页面。
2. 创建 ~/.codex/model-catalogs 目录，将文件保存为 ~/.codex/model-catalogs/model-catalog.json。Windows 使用当前用户目录下的 .codex。已有同名文件时先备份。
3. 修改 ~/.codex/config.toml，然后只在文件头部添加这一行：
model_catalog_json = "model-catalogs/model-catalog.json"
这行必须作为顶层配置，放在任何 [表头] 之前。如果已有顶层 model_catalog_json，就修改原字段，不要重复添加。
4. 不要覆盖整个 config.toml，不要修改默认模型、API 地址或密钥。仅为下面的模型列表检查，在本地读取当前 provider 使用的密钥；不要在日志、命令输出或回复中暴露密钥，也不要将它写入其他文件。配置目录以实际 CODEX_HOME 为准（未设置时为 ~/.codex）。
5. 检查 JSON 和 TOML 格式有效，并告诉我修改了哪些文件。完成后提醒我重启 Codex，在模型列表中选择模型；不要自动结束当前会话。
使用当前 API Key，向现有 provider 的 base_url 对应的 /v1/models 端点发送 GET 请求（本站主站为 https://api.cloudawn.top/v1/models），通过 Authorization: Bearer <当前密钥> 认证。不要重复拼接 /v1。检查响应中的 data[].id，确认目标模型是否出现在当前密钥可见的模型列表中；如果我没有指定目标模型，就列出模型目录中哪些模型可见、哪些未返回。只报告检查结果，不输出密钥。模型列表可见不代表实际调用一定成功；请求失败时如实说明，不要推断为已开通权限。如果希望手动配置，按下面的步骤操作。
1. 下载模型目录
在 .codex 目录下新建 model-catalogs 文件夹，把下载的 JSON 文件放进去：
| 平台 | 文件位置 |
|---|---|
| macOS / Linux | ~/.codex/model-catalogs/model-catalog.json |
| Windows | %userprofile%\.codex\model-catalogs\model-catalog.json |
macOS / Linux 可以先创建目录：
bash
mkdir -p ~/.codex/model-catalogs这份 JSON 包含 8 个 Codex 上游 GPT 模型条目，以及部分第三方模型，方便在同一份目录中切换使用：
- OpenAI GPT：
gpt-5.6-luna、gpt-5.6-sol、gpt-5.6-terra、gpt-6-astra、gpt-6.1-sol、gpt-6.1-terra、gpt-6-sol、gpt-6-luna。 - 第三方模型：Gemini 4 Argon、Claude Opus 5.5、GLM、DeepSeek V4.1 Flash / V4 Pro、Grok 4.7、MiniMax M3 / M3.1 Flash、Kimi K3.1 Pro、Qwen、MiMo 等。
上游条目保留各自的 prompt、能力和可见性设置，上下文按本示例统一调整。目录中包含某个模型不代表本站渠道已开通该模型，实际可用性仍以当前 API Key 和渠道为准。
第三方模型和 gpt-* 的默认与最大上下文均设为 272K。 自动压缩阈值统一为 244.8K（244,800 tokens）。
目录中的 OpenAI 内置模型按 Codex 上游同步对应配置和 prompt，上下文按上述示例值覆盖；第三方模型以 GPT-6.1 Terra 的官方完整提示模板和多数工具开关为基准，工具模式使用 direct，Shell 使用 unified_exec，保留各自的模型名称、推理档位和输入模态，不启用 WebSocket 偏好和服务档位，也不复制套餐与内部元数据。具体字段见本文末尾的配置说明，官方条目可查看 Codex 上游模型目录。
第三方部分仍是基础示例，不是完整的模型列表，更多模型和价格请查看 模型广场，你可以参照示例自由添加或修改。
2. 修改 config.toml
放好 JSON 文件后，只需在 config.toml 头部添加一行，其他配置保持不变：
toml
model_catalog_json = "model-catalogs/model-catalog.json"配置文件位置为 ~/.codex/config.toml（Windows 为 %userprofile%\.codex\config.toml）。无需重新填写 API 地址或密钥，也不用替换整个文件。
配置位置
这行必须放在 [model_providers.cloudawn] 等表头之前，作为顶层配置。已有该字段时直接修改，不要重复添加；原有的 API 地址和密钥配置不需要替换。
model_catalog_json 会替换 Codex 当前使用的模型目录，而不是把文件内容自动合并到内置目录。因此这里提供的 JSON 已经把需要保留的 GPT 和第三方模型一起放入；如果你自己制作目录，也要把希望继续使用的模型一并保留。
保存后重启 Codex，再选择目录中的模型。CLI 可以通过 /model 查看模型选项。
如果提示找不到 JSON 文件，可将 model_catalog_json 改为该文件的完整绝对路径。Windows 路径建议使用正斜杠，例如 C:/Users/你的用户名/.codex/model-catalogs/model-catalog.json。
3. 替换或增加模型
示例包含 GPT-6、GLM、Grok、Kimi、DeepSeek 等模型。你可以在 JSON 的 models 数组中参照已有条目添加模型，再将 config.toml 的 model 改为对应的 slug。
| 字段 | 用途 |
|---|---|
slug | 请求使用的模型名称，需与模型广场中的名称一致 |
display_name | Codex 中显示的模型名称 |
description | 模型说明 |
supported_reasoning_levels | 可选择的推理强度，例如 low、medium、high、xhigh |
default_reasoning_level | 默认推理强度，应来自该模型支持的等级 |
input_modalities | 输入类型；["text", "image"] 表示声明支持文字和图片输入 |
能力声明不等于实际能力
模型目录描述的是 Codex 如何展示和使用模型，不会自动给模型增加视觉、推理或工具调用能力。推理强度如何映射、图片是否可用，以及模型能否通过 Responses 接口调用，都取决于 CloudAwn 对应上游的实际支持。不要只改模型名称，就把示例中的全部能力照搬给新模型。
示例中的模型能力按具体型号整理；使用 Codex 官方 prompt 不会自动赋予模型推理或视觉能力，仍要以模型和 CloudAwn 渠道实际支持为准：
| 模型 | 示例推理选项 | 图片输入 | 官方依据 |
|---|---|---|---|
| GPT-5.6 Luna | low / medium / high / xhigh / max | 支持 | Codex 上游模型目录 |
| GPT-5.6 Sol | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-5.6 Terra | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-6 Astra | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-6.1 Sol | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-6.1 Terra | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-6 Sol | low / medium / high / xhigh / max / ultra | 支持 | Codex 上游模型目录 |
| GPT-6 Luna | low / medium / high / xhigh / max | 支持 | Codex 上游模型目录 |
| Claude Opus 5.5 | low / medium / high / xhigh / max | 支持 | 模型说明、推理强度 |
| Gemini 4 Argon | low / medium / high（默认 medium） | 支持 | 官方模型说明 |
| GLM 5.3 Flash | low / high / max | 支持 | 模型卡 |
| MiniMax M3 | none / high（关闭 / 开启自适应思考） | 支持 | Codex 配置 |
| MiniMax M3.1 Flash | low / medium / high / xhigh / max | 支持 | 官方配置与能力说明 |
| Grok 4.7 | low / medium / high / xhigh | 支持 | 官方模型说明 |
| Kimi K3.1 Pro | low / high / max | 支持 | 官方模型配置 |
| Qwen 3.8 Max | low / medium / xhigh | 支持 | 推理说明、发布说明 |
| MiMo V2.5 Pro | none / high（关闭 / 开启思考，不区分深度） | 不支持 | 模型规格、Responses 说明 |
| DeepSeek V4.1 Flash | none / low / high / max | 支持 | 思考模式、视觉说明 |
| DeepSeek V4 Pro | none / low / high / max | 示例按纯文本配置 | 更新日志 |
这是基础配置，你可以按需要保留常用模型、调整顺序或补充其他模型。 修改 JSON 后请保持格式有效，并重启 Codex 加载新的目录。模型能否在当前账号中实际调用，仍需使用当前 API Key 请求 /v1/models 确认，并以实际请求结果为准。
配置字段说明可参考 Codex 官方配置参考。
4. 配置 flag 与作用
以下工具开关取值针对本示例的 第三方模型条目。model_messages 和多数开关对齐 GPT-6.1 Terra 的上游配置，第三方模型使用 direct 工具模式与 unified_exec Shell 工具，不强制通过代码模式统一调度。GPT 模型的工具开关继续使用各型号自己的官方值；第三方模型和 gpt-* 的默认与最大上下文均设为 272K。
这些是模型目录 JSON 的字段，不是让你全部复制进 config.toml 的配置项。标记为支持的功能仍需要当前 Codex 版本、运行环境和转发渠道配合；尤其 supports_reasoning_effort_updates 要求渠道能处理相应的 configuration_update 请求内容。
工具与代理
| 字段 | 示例取值 | 作用 |
|---|---|---|
model_messages | GPT-6.1 Terra 官方完整模板 | 提供主提示、审批、协作模式、多代理和工具相关提示；不再混用旧的 base_instructions 模板。 |
shell_type | "unified_exec" | 使用 exec_command / write_stdin 执行命令和读取运行中的进程输出。 |
apply_patch_tool_type | "freeform" | 使用自由文本补丁格式编辑文件。 |
tool_mode | "direct" | 直接提供命令、补丁等工具，不强制通过 exec 代码模式入口统一调度。 |
use_responses_lite | true | 使用 Codex 的 Responses Lite 路径，需渠道支持。 |
supports_parallel_tool_calls | true | 声明支持并行工具调用。 |
multi_agent_version | "v2" | 使用第二版多代理工具接口。 |
multi_agent_reasoning_effort | "xhigh" | 选择 Ultra 时用于多代理工作的推理强度；不会给模型额外增加 Ultra 或 xhigh 选项。 |
experimental_supported_tools | ["send_user_message_async", "clock"] | 声明异步向用户发送消息及时间相关实验工具；是否提供仍由客户端决定。 |
node_repl_disabled | false | 不在模型条目中禁用 Node REPL。 |
node_repl_auto_review_required | true | 要求 Node REPL 走相应的自动审核流程。 |
requires_sandboxed_review | false | 不额外声明必须使用沙箱审核；不会覆盖系统或用户已有的沙箱要求。 |
auto_review_model_override | null | 不在模型条目中指定其他自动审核模型。 |
guardian | null | 不提供模型专属的 Guardian 覆盖策略，沿用客户端和管理员设置。 |
推理、输入与提示注入
| 字段 | 示例取值 | 作用 |
|---|---|---|
supports_reasoning_effort_updates | true | 声明支持通过 configuration_update 内容更新推理强度。 |
supports_reasoning_summary_parameter | true | 声明接口接受 reasoning.summary 参数。 |
supports_reasoning_summaries | true | 声明推理摘要支持；与参数接收能力分开描述。 |
default_reasoning_summary | "none" | 默认不请求推理摘要。 |
support_verbosity / default_verbosity | true / "low" | 声明支持回答详略参数，默认使用较简洁的输出。 |
supports_search_tool | true | 声明搜索工具支持；不代表转发渠道自动提供搜索后端。 |
web_search_tool_type | "text_and_image" | 使用包含文字与图片结果的搜索工具类型。 |
supports_image_detail_original | true | 声明支持原始细节的图片输入；实际能否发送图片仍由 input_modalities 和渠道决定。 |
supports_experimental_context | false | 不启用模型专属的实验性上下文管理。 |
include_skills_usage_instructions | false | 不通过此开关额外注入技能使用说明，不等于禁用技能。 |
include_apps_usage_instructions | false | 不通过此开关额外注入应用使用说明，不等于禁用应用。 |
include_plugin_usage_instructions | false | 不通过此开关额外注入插件使用说明，不等于禁用插件。 |
minimal_client_version | "0.153.0" | 保留模板声明的最低客户端版本；新增工具的实际支持还取决于所用版本。 |
上下文与主动保留的差异
| 字段 | 第三方示例取值 | 作用 |
|---|---|---|
context_window / max_context_window | 272000 / 272000 | 第三方模型和 gpt-* 的默认与最大上下文均设为 272K。 |
auto_compact_token_limit | 244800 | 在约 244.8K tokens 时触发自动压缩，客户端还会按实际上下文限制调整。 |
effective_context_window_percent | 不填写 | 沿用客户端默认的输入可用比例；当前上游默认 95%，为系统提示、工具和输出预留空间。 |
input_modalities | 按模型分别设置 | 支持视觉的模型包含 "image"，纯文本模型只包含 "text"。 |
default_reasoning_level / supported_reasoning_levels | 按模型分别设置 | 保留各型号实际支持的推理选项，不统一复制 GPT 的档位。 |
prefer_websockets | false | 不声明优先走 WebSocket；连接方式仍受 provider 和客户端设置影响。 |
service_tiers / additional_speed_tiers | [] / [] | 不声明 Fast 等额外服务或速度档位。 |
default_service_tier | 不填写 | 不指定默认服务档位。 |
available_in_plans / available_access_programs | 不填写 | 不复制 OpenAI 的套餐或访问计划限制。 |
comp_hash / model_specialty | 不填写 | 不复制官方压缩兼容标识和模型专长元数据。 |
字段结构和客户端默认行为可对照 Codex 模型目录协议源码；渠道实现方式见 官方模型目录说明。