Codex 接入指南
config.toml 配置、env_key 与 experimental_bearer_token 写法,以及各档位模型 ID。
命令行 codex 已经能跑通自定义模型,打开 Codex Desktop 却只看到一个 Custom 标签,下拉菜单里找不到任何自己的模型。顺着配置文件、进程重启和界面层一路往下查,问题其实不在网关。
在 ~/.codex/config.toml 里接好第三方网关之后,很多人会遇到一个很拧巴的状况:在终端里跑 codex -m claude-sonnet-5-5 一切正常,可一打开 Codex Desktop,模型栏却只显示一个 Custom(或者 Custom High),点开下拉菜单,里面除了官方内置的几个 OpenAI 模型,自己配的模型一个都看不见。
第一反应往往是“桌面端是不是没读到 config.toml”,或者“配置格式哪里写错了”。顺着这个疑问往下排查,会发现事情分好几层:有些确实是本地配置顺序和重启方式的坑,但把这些全排掉之后,下拉框里依然不会出现自定义模型。
界面上显示 Custom 不代表配置没生效。只要 config.toml 顶部写对了 model,即使下拉列表里看不到它,Codex Desktop 发出的请求依然会走你填的模型 ID。
怀疑桌面端“不认配置”之前,有两件本地小事很容易把人带偏:
model 和 model_provider 写在了 [表] 下面在 TOML 语法里,写在第一个 [model_providers.xxx] 之前的键才属于顶层配置。如果顺手把 model = "claude-sonnet-5-5" 贴在了配置文件末尾、落进了 [model_providers.codingpass] 这张表里面,顶层默认模型就没有设上,桌面端自然不会用它。
Codex Desktop 只在启动时读取一次 config.toml。在 macOS 上只点窗口左上角的关闭按钮,后台进程还在跑,改完配置重新点开窗口,读的还是旧配置。必须用 Cmd + Q 完全退出(Windows 从系统托盘退出)再重开。
Custom把顶层字段挪到最上面、Cmd + Q 重开之后,如果直接发一条消息测试,会发现对话能正常跑通,服务端收到的模型 ID 也确实是 claude-sonnet-5-5——只是桌面端界面上依然显示 Custom。
拿同一份 config.toml 去跑终端 codex,/model 能看到、-m 也能切;唯独桌面端下拉菜单里没有。把客户端拆开看就会发现,Codex Desktop 底层跑的 app-server 其实已经调用 model/list 把 config.toml 和 model_catalog_json 里的模型都读出来了,真正把它们拦在门外的是外层 Electron 渲染层:
use_hidden_models、available_models、default_model),把不在白名单里的模型直接从 UI 列表里剔除(这也是 openai/codex#19694 讨论的核心原因)。换句话说,后端没坏,是桌面端 UI 主动把非官方列表里的模型藏了起来,只用 Custom 或 Custom High 当占位标签。
既然已经确认“配置生效了、只是 UI 隐藏了下拉项”,就没必要反复折腾 config.toml 格式,按自己的使用习惯挑一种方式即可:
| 做法 | 适用情况 | 代价 |
|---|---|---|
在 config.toml 顶部写死 model | 桌面端固定只用一两个主力模型 | 界面显示 Custom,换模型要改文件并 Cmd + Q 重开 |
| 保留一个 ChatGPT 登录态 | 想解除纯 API Key 会话的界面隐藏 | 需要登录一个官方账号(Free 或 Go 档即可) |
切模型时用 codex CLI | 经常对比或切换多个模型 | 在终端 TUI 里操作,不用桌面端下拉框 |
社区 app.asar 补丁工具 | 一定要在桌面端下拉框里点选模型 | 非官方方案,每次客户端更新都会被覆盖 |
model,直接忽略 Custom 标签如果平时在桌面端固定用某一个模型(比如用 CodingPass 跑 claude-sonnet-5-5 或 gpt-6-2-sol),把 model_provider 和 model 放在 ~/.codex/config.toml 最顶部,写在任何 [表] 之前:
model_provider = "codingpass"model = "claude-sonnet-5-5" [model_providers.codingpass]name = "CodingPass"base_url = "https://codingpass.ai/v1"env_key = "CODINGPASS_API_KEY"wire_api = "responses"Cmd + Q 完全退出再重开后,不用管界面上的 Custom,直接发消息即可。
如果主要是被“纯 API Key 模式下隐藏自定义模型”卡住,可以在桌面端保留一个普通 ChatGPT 账号的登录状态,同时在 config.toml 里留着第三方 provider。官方登录态负责过掉前端检查,实际请求还是按 config.toml 走你的网关。
codex终端版 codex 没有 Electron 前端那层过滤。Codex 0.134.0 起把 profile 改成了一文件一个,你可以把官方配置留在主文件里,另外建一个 ~/.codex/cp.config.toml 放 CodingPass,需要切模型时直接带 -m 启动:
codex --profile cp -m claude-sonnet-5-5app.asar 补丁(仅作备选)因为过滤逻辑就打包在桌面端本地的 app.asar 里,社区出现过 CodexUse 等工具或脚本,改写本地资源里的 use_hidden_models 标记,把隐藏模型放进下拉框。只是每次 Codex Desktop 更新都会覆盖 app.asar,用起来比较折腾,不建议当长期方案。
完整的 config.toml 写法、环境变量与各档位模型列表,见 Codex 接入指南与额度和上限。