docs: add v3.16.4 trilingual release notes and Codex custom-model FAQ

- Add v3.16.4 release notes in zh/en/ja. - Add a trilingual FAQ explaining why custom models don't show in the Codex desktop model picker (upstream Codex Desktop login-identity gating, not a cc-switch bug) and the keep-official-login mitigation; cross-linked both ways with the official-auth preservation guide. - Align the CHANGELOG 3.16.4 release date to 2026-06-27.
2026-07-24 12:44:18 +08:00 · 2026-06-27 11:57:20 +08:00
parent f9547da930
commit e50fc0eb28
10 changed files with 1198 additions and 1 deletions
@@ -0,0 +1,46 @@
+# Can't See Custom Models in the Codex Desktop App? (FAQ)
+
+> Applies to CC Switch v3.16.1 and later. This article explains "why the Codex desktop app can't see custom models" and the available mitigation; for the detailed step-by-step setup with screenshots, see [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md).
+
+## Symptom
+
+After you switch Codex to a third-party / custom model in CC Switch (DeepSeek, Kimi, GLM, MiniMax, an aggregator, etc.):
+
+- The model picker in the **Codex desktop app** doesn't show these custom models — often only the official default model remains, and the reasoning level falls back to the official default;
+- but everything works fine in the **command-line `codex`** `/model` menu.
+
+Many users have run into this. Here's why, and what you can do about it.
+
+## Why this happens
+
+This is **not a CC Switch local-config problem and not a CC Switch bug** — it is the **Codex desktop app's (the upstream closed-source client's) own model-gating behavior**.
+
+The Codex desktop app's model picker decides which models to allow based on your **current login identity**: when it can't detect an official ChatGPT / Codex login state, it forces the picker back to the official default model and hides the custom models you configured through `config.toml` (the reasoning level falls back to the official default too). The upstream has marked "exposing custom-provider models in the desktop GUI" as not planned, so CC Switch cannot fully fix this at the desktop-GUI level.
+
+The command-line `codex` `/model` menu and request routing both recognize the custom providers in `config.toml` correctly — **only the desktop GUI picker is constrained by this gating layer**.
+
+## Mitigation: keep the official login
+
+The workaround is to **keep the official login state** so the desktop app's gating allows your custom models through. The key points are below (the full step-by-step setup with screenshots is in the linked guide):
+
+1. Log in once with an official ChatGPT / Codex account in Codex (a Free subscription is enough) to keep the official login state.
+2. In CC Switch, enable `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers` (**off by default**).
+3. Enable local routing and route Codex through it for this third-party provider (required for Chat Completions providers such as DeepSeek / Kimi / MiniMax).
+4. Fully quit and restart Codex.
+
+Once enabled, CC Switch preserves the official login state in `~/.codex/auth.json` when switching to a third-party provider and writes the third-party key into `config.toml`, so the desktop app still recognizes the official login identity, the gating lets your models through, and the custom models you configured reappear in the picker. **The preserved official token is never sent to the third party** — third-party model requests still use the key you configured, forwarded through the local route.
+
+> 📖 Detailed step-by-step setup: [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
+
+## Still can't see them?
+
+- **Confirm the toggle is on**: this toggle is off by default, and many people overwrite the official login state the first time they switch to a third-party provider, which is exactly why the models disappear — enable it as above.
+- **The official login state expires**: if you haven't used the official login for several days, the picker may go empty again once the token expires — log in to the official account once more to restore it.
+- **Command-line fallback diagnosis**: run `codex debug models` to list the models actually available on the CLI side and confirm the model itself is configured correctly (the CLI is unaffected by this gating).
+- Individual Codex desktop versions may behave slightly differently; this is in the upstream client's domain, and no CC Switch version can fully fix it at the desktop-GUI level.
+
+## References
+
+- [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
+- [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
+- [Local Routing](../user-manual/en/4-proxy/4.2-routing.md)
@@ -0,0 +1,47 @@
+# Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）
+
+> 対象バージョン: CC Switch v3.16.1 以降。本記事は「なぜ Codex デスクトップアプリでカスタムモデルが見えないのか」と、使える緩和策を解説します。図入りの詳細な設定手順は [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md) を参照してください。
+
+## 現象
+
+CC Switch で Codex をサードパーティ / カスタムモデル（DeepSeek、Kimi、GLM、MiniMax、中継サービスなど）へ切り替えた後：
+
+- **Codex デスクトップアプリ**のモデルセレクタにこれらのカスタムモデルが表示されず、多くの場合は公式の既定モデルだけが残り、思考レベルも公式の既定へ戻ってしまう。
+- 一方で**コマンドライン `codex`** の `/model` ではすべて正常に表示される。
+
+多くのユーザーがこの現象に遭遇しています。以下で原因と対処を解説します。
+
+## なぜこうなるのか
+
+これは **CC Switch のローカル設定の問題でも、CC Switch のバグでもありません**。**Codex デスクトップアプリ（上流のクローズドソースクライアント）自身のモデルゲーティング挙動**です。
+
+Codex デスクトップアプリのモデルセレクタは、あなたの**現在のログイン ID** に応じてどのモデルを通すかを決めます。公式 ChatGPT / Codex のログイン状態を検出できないとき、セレクタを公式の既定モデルへ強制的に戻し、`config.toml` で設定したカスタムモデルを隠します（思考レベルもあわせて公式の既定へ戻ります）。公式は「デスクトップ GUI でカスタムプロバイダーのモデルを公開する」ことを not planned としてマークしているため、CC Switch がデスクトップ GUI のレベルでこれを根本的に修正することはできません。
+
+コマンドライン `codex` の `/model` とリクエストルーティングは `config.toml` 内のカスタムプロバイダーを正常に認識できます。**デスクトップ GUI のセレクタだけがこのゲーティングの制限を受けます**。
+
+## 緩和策: 公式ログインを保持する
+
+対処は**公式ログイン状態を保持する**ことで、デスクトップアプリのゲーティングにあなたのカスタムモデルを通させます。要点は次のとおりです（完全な図入り手順は下のリンク先のガイドを参照してください）：
+
+1. まず Codex で公式 ChatGPT / Codex に一度ログインし（Free サブスクリプションで構いません）、公式ログイン状態を保持する。
+2. CC Switch で `設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` をオンにする（**デフォルトはオフ**）。
+3. そのサードパーティプロバイダーでローカルルーティングを有効化し、Codex のルーティングをオンにする（DeepSeek / Kimi / MiniMax など Chat Completions プロトコルのプロバイダーでは必須）。
+4. Codex を完全に終了して再起動する。
+
+オンにすると、CC Switch はサードパーティプロバイダーへ切り替える際に `~/.codex/auth.json` 内の公式ログイン状態を保持し、サードパーティの Key を `config.toml` へ書き込みます。これにより、デスクトップアプリは引き続き公式ログイン ID を認識してゲーティングを通すため、設定したカスタムモデルがセレクタに再び表示されます。**保持された公式 Token がサードパーティへ送られることはありません**——サードパーティのモデルリクエストは引き続き、設定した Key でローカルルーティング経由で転送されます。
+
+> 📖 詳細な図入り手順: [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
+
+## それでも見えない場合は
+
+- **スイッチがオンか確認する**: このスイッチはデフォルトでオフです。多くの人は初めてサードパーティへ切り替えたときに公式ログイン状態を上書きしてしまい、その結果見えなくなっています——上記の手順でオンにしてください。
+- **公式ログイン状態は期限切れになる**: 数日間公式ログインを使わないと、Token が失効した後にセレクタが再び空になることがあります——公式に一度ログインし直せば回復します。
+- **コマンドラインでの確認**: `codex debug models` を使うと CLI 側で実際に利用可能なモデルを一覧でき、モデル自体が正しく設定されていることを確認できます（CLI はこのゲーティングの影響を受けません）。
+- 個々の Codex デスクトップ版で挙動が多少異なる場合があります。これは上流クライアントの範疇であり、CC Switch のどのバージョンでもデスクトップ GUI のレベルで根本解決することはできません。
+
+## 参考リンク
+
+- [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
+- [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
+- [ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+</content>
@@ -0,0 +1,46 @@
+# Codex 桌面应用里看不到自定义模型？（常见问题）
+
+> 适用版本：CC Switch v3.16.1 及以上。本文解释「为什么 Codex 桌面应用看不到自定义模型」以及可用的缓解办法；详细的图文配置步骤见 [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)。
+
+## 现象
+
+在 CC Switch 里把 Codex 切换到第三方 / 自定义模型（DeepSeek、Kimi、GLM、MiniMax、中转站等）后：
+
+- **Codex 桌面应用**的模型选择器里看不到这些自定义模型，往往只剩官方默认模型，思考等级也回落到官方默认；
+- 但**命令行 `codex`** 的 `/model` 里一切正常。
+
+很多用户都遇到过这个现象，下面解释原因与办法。
+
+## 为什么会这样
+
+这**不是 CC Switch 的本地配置问题，也不是 CC Switch 的 bug**，而是 **Codex 桌面应用（上游闭源客户端）自身的模型门控行为**。
+
+Codex 桌面应用的模型选择器会按你**当前的登录身份**来决定放行哪些模型：当它检测不到官方 ChatGPT / Codex 登录态时，会把选择器强制回落到官方默认模型，把你通过 `config.toml` 配置的自定义模型藏起来（思考等级也会一并回落到官方默认）。官方已把「在桌面 GUI 里暴露自定义供应商模型」标记为 not planned，因此 CC Switch 无法从桌面 GUI 层面彻底修复它。
+
+命令行 `codex` 的 `/model` 与请求路由都能正常识别 `config.toml` 里的自定义供应商，**唯独桌面 GUI 的选择器受这层门控限制**。
+
+## 怎么缓解：保留官方登录
+
+办法是**保留官方登录态**，让桌面应用的门控放行你的自定义模型。要点如下（完整图文步骤见下方链接的攻略）：
+
+1. 先在 Codex 里登录一次官方 ChatGPT / Codex（Free 订阅即可），保留官方登录态。
+2. 在 CC Switch 开启 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录`（**默认关闭**）。
+3. 为该第三方供应商开启本地路由并接管 Codex（Chat Completions 协议的供应商如 DeepSeek / Kimi / MiniMax 必须开启）。
+4. 完全退出并重启 Codex。
+
+开启后，CC Switch 在切换第三方供应商时会保留 `~/.codex/auth.json` 里的官方登录态、把第三方 Key 写进 `config.toml`，于是桌面应用仍识别官方登录身份、门控放行，你配置的自定义模型就会重新出现在选择器里。**保留的官方 Token 不会被发往第三方**——第三方模型请求仍用你配置的 Key 经本地路由转发。
+
+> 📖 详细图文步骤：[使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
+
+## 仍然看不到怎么办
+
+- **确认开关已开**：该开关默认关闭，很多人第一次切到第三方就把官方登录态覆盖掉了，所以才看不到——按上面开启即可。
+- **官方登录态会过期**：如果连续几天没用过官方登录，Token 失效后选择器可能又变空——重新登录一次官方即可恢复。
+- **命令行兜底诊断**：用 `codex debug models` 可以列出 CLI 端实际可用的模型，确认模型本身已正确配置（CLI 不受此门控影响）。
+- 个别 Codex 桌面版本的行为可能略有差异；这属于上游客户端范畴，CC Switch 各版本都无法从桌面 GUI 层根治。
+
+## 参考链接
+
+- [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
+- [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
+- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
@@ -202,6 +202,7 @@ Because Codex App Enhancements and routing takeover can create unnecessary troub

 ## References

+- [Can't see custom models in the Codex desktop app? (FAQ)](./codex-desktop-custom-model-visibility-en.md)
 - [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
 - [Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)
 - [Local Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
@@ -202,6 +202,7 @@ Codex アプリ拡張やルーティング管理は、必要ないユーザー

 ## 参考リンク

+- [Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）](./codex-desktop-custom-model-visibility-ja.md)
 - [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
 - [Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)
 - [ローカルプロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
@@ -202,6 +202,7 @@ Codex 的模型目录是启动时读取的。即使 CC Switch 已经生成了新

 ## 参考链接

+- [Codex 桌面应用里看不到自定义模型？（常见问题）](./codex-desktop-custom-model-visibility-zh.md)
 - [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
 - [添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)
 - [本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)