Codex Desktop 接入第三方模型配置指南

先说明一下，这篇跟之前那篇《Claude Code 与 Codex 接入第三方模型配置指南》不算重复。之前讲的是 Codex CLI，这次是 Codex Desktop——两个不同的东西，配置路径和方法都不一样。

Codex Desktop 是什么

OpenAI 除了 Codex CLI，还做了一个桌面版，叫 Codex Desktop 或 Codex App。界面比 CLI 更直观，适合不想折腾命令行的人。本质上还是调用模型写代码，但多了图形界面、模型选择器、项目管理这些功能。

跟 CLI 相比，Desktop 的配置方式完全不同。CLI 用 ~/.codex/config.toml 和 ~/.codex/auth.json，Desktop 则需要额外的模型目录文件。这也是为什么单独写一篇。

配置思路

Desktop 的核心机制是：通过 model_catalog_json 字段告诉它有哪些模型可选，再通过 [model_providers.xxx] 配置 API 端点。

关键点只有一个：model_catalog_json 必须写在 config.toml 的根级别。写在 provider 段里面，Desktop 不会识别。

创建模型目录文件

假设你有一个中转站，想接入一个 1M 上下文的 Opus 模型。

先创建目录文件，路径可以自己定：

Windows: C:\Users\<用户名>\.codex\model-catalogs\all-models.json macOS/Linux: ~/.codex/model-catalogs/all-models.json

内容：

{
  "models": [
    {
      "slug": "opus-4-7-1m",
      "display_name": "My Proxy / opus-4-7",
      "description": "1M context via third-party proxy",
      "visibility": "list",
      "supported_in_api": true,
      "context_window": 1048576,
      "max_context_window": 1048576,
      "effective_context_window_percent": 95,
      "auto_compact_token_limit": 196608,
      "input_modalities": ["text", "image"],
      "supports_image_detail_original": true,
      "supports_parallel_tool_calls": true,
      "supports_search_tool": true,
      "web_search_tool_type": "text_and_image",
      "apply_patch_tool_type": "freeform",
      "shell_type": "shell_command",
      "supports_reasoning_summaries": true,
      "default_reasoning_summary": "auto",
      "default_reasoning_level": "medium",
      "support_verbosity": true,
      "default_verbosity": "low",
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "priority": 10
    }
  ]
}

字段说明：

• slug：Desktop 实际发送给 API 的模型 ID
• display_name：界面显示的名字
• context_window：上下文窗口大小，1048576 就是 1M
• input_modalities：声明支持文本和图片
• supports_*：各种能力开关，工具调用、搜索、并行等

这些字段只是告诉 Desktop "模型看起来支持什么"，不会让上游 API ���的具备这些能力。中转站不支持图片或工具调用的话，请求照样失败。

修改 config.toml

Desktop 的配置文件也在 ~/.codex/config.toml（Windows 是 C:\Users\<用户名>\.codex\config.toml）。

# 根级别，不要写在 provider 段里
model_catalog_json = 'C:\Users\<用户名>\.codex\model-catalogs\all-models.json'
model = "opus-4-7-1m"
model_provider = "myproxy"

[model_providers.myproxy]
name = "myproxy"
base_url = "https://api.yourproxy.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

几个要点：

• model_catalog_json：必须根级别，这是最容易踩坑的地方
• model：填模型目录里的 slug
• model_provider：填下面的 provider 名称
• base_url：中转站地址
• wire_api：responses 表示 OpenAI Responses API 格式，chat 表示 Chat Completions

设置 API Key

Desktop 从环境变量读 Key，不像 CLI 用 auth.json 文件。

Windows PowerShell：

$env:OPENAI_API_KEY = "sk-yourkey"

macOS/Linux：

export OPENAI_API_KEY="sk-yourkey"

或者直接写到系统环境变量里，省得每次都设。

重启生效

改完配置，完全关闭 Desktop 再重新打开。只刷新页面不行，进程得重启。

常见问题

模型列表没显示？

检查 model_catalog_json 是否在根级别。写在 [model_providers.xxx] 下面，Desktop 会忽略。

请求失败？

模型目录只是声明能力，不代表上游真的支持。检查中转站文档，确认模型 ID 和能力是否匹配。

跟 CLI 配置能混用吗？

不能。CLI 用 auth.json 存 Key，Desktop 从环境变量读。配置文件虽然路径相同，但 Desktop 需要额外的模型目录，CLI 不需要。

账号风险提醒

用第三方中转站接非原生模型到 Desktop，有一定风控风险。比如用 AnyRouter 的 GPT 模型可能没事，但接 Opus 就可能触发检测。建议只用在自己信任的中转站，别拿主账号去试。

---

配置不难，两个文件加一个环境变量。踩坑点就一个：model_catalog_json 放对位置，上游能力确认好。折腾一次，以后换模型改几个字符串的事。

想看 CLI 配置的，可以参考之前的文章：Claude Code 与 Codex 接入第三方模型配置指南