Codex Desktop でカスタムモデルが表示されない：5つの解決策（2026年版）

カスタムプロバイダを設定し、codex はターミナルから問題なく動くのに、Desktop のモデルピッカーはまるであなたのモデルが存在しないかのように振る舞う。 この食い違いは、ほぼ間違いなく API キーや設定の構文の問題ではありません。バックエンドがすでに読み込んだモデルを、Desktop クライアントがひそかにフィルタリングしているのです。

30秒でできる診断

何かを書き直す前に、症状を下の表と照らし合わせてください。ほとんどの人は、解決まであと1行のところにいます。

最速の確認方法：同じフォルダでターミナルを開いて codex（CLI）を実行し、/model と入力します。CLI にはモデルが表示されるのに Desktop には出ない場合、クライアント側フィルタのバグに当たっており、Desktop 側でどれだけ設定を編集してもモデルは表に出てきません。解決策1に進んでください。

flowchart TD
  A[Custom model missing in Desktop] --> B{Does CLI /model show it?}
  B -- Yes --> C[Desktop filter bug #19694]
  C --> F1[Fix 1: set model inline + Fix 4 catalog]
  B -- No --> D{Provider in ~/.codex/config.toml?}
  D -- No, it is project-local --> F3[Fix 3: move to user-level]
  D -- Yes --> E{Catalog file present + valid?}
  E -- No --> F2[Fix 2 or Fix 4: generate catalog]
  E -- Yes --> F1

これらの解決策を適用すべきとき（と、モデルを乗り換えるべきとき）

モデルは動くのにピッカーに表示されない場合は、設定を直します。これは表示上の問題であり、他のすべてがすでに機能しているのですから、10分かける価値があります。具体的には、CLI や直接 curl からのリクエストは成功するのに、Desktop のドロップダウンにモデルが現れないケースです。これは #19694 のフィルタか、カタログの欠落であり、解決策1から4が該当します。

ルート自体が壊れている場合は、設定を編集するのではなくモデルを乗り換えます。curl https://your-gateway/v1/responses が 401、404、または model-not-found を返すなら、ピッカーが問題なのではありません。プロバイダかモデル文字列が間違っており、解決しないルートはどれだけカタログを編集しても救えません。

そして終了条件です。カスタムモデルにリクエストを送ることだけが目的なら、解決策1だけでたどり着けます。model をインラインで設定し、再起動、以上です。このガイドの残りの部分は、ピッカーにきれいで切り替え可能な一覧を表示させることが目的であり、これはチームや、頻繁にモデルを切り替える人にとって重要です。ドロップダウンを一切開かないなら、解決策1で止めて構いません。

Codex Desktop がカスタムモデルを隠す理由

根本原因は4つあり、それぞれ異なる解決策が必要です。原因を取り違えることが、動いていた設定を丸ごと打ち直して半日を費やす理由になります。

最初のものが、みんなを驚かせるものです。オープン中の codex issue #19694 によると、app-server はカタログを正しく読み込み、model/list エンドポイント経由であなたのモデルを返しますが、Desktop の UI が追加のフィルタをかけ、ピッカーを描画する前にローカル設定されたモデルを削除しています。バックエンドはあなたのモデルを知っています。フロントエンドがそれを表示するのを拒否しているのです。これは設定エラーではなくクライアントのバグで、2026-04-26 に報告され、執筆時点でもまだオープンです。

2つ目の原因は最も一般的で、最も心配のいらないものです。カタログなしで model = "some-id" とだけ書いた場合、Codex には文字列はあっても表示名も、コンテキストウィンドウも、機能フラグもありません。ピッカーは「Custom」というラベルを表示して先に進みます。リクエストは依然として正しいモデルに届きます。「Custom」は実際には動作しているのに壊れているように見えるため、これに人はつまずきます。

3つ目の原因は、v3.16.5 より前の cc-switch ユーザーが当たったものです。コミュニティは cc-switch issue #3668 でこれを突き止めました。生成されたカタログとプロバイダブロックが Codex のピッカーが列挙する内容と一致しておらず、そのためルーティングは機能していてもサードパーティプロバイダでは /model が空で返っていました。修正の詳細は解決策4で説明します。

4つ目の原因には見分ける手がかりがあります。プロバイダをリポジトリの .codex/config.toml に入れた場合、Codex は起動時に警告を出力し、そのブロックを完全に無視します。プロバイダ定義はユーザースコープに限られます。

Codex がモデルを読み込む仕組み（と、Desktop が分岐する場所）

Codex はモデルの一覧をレイヤーで構築しており、その順序を知ることで、どの解決策が実際に効くかがわかります。ソースは3つあります。バイナリにバンドルされたカタログ、OpenAI から取得するリモートカタログ、そしてあなたのローカルの model_catalog_json です。ローカルファイルが勝ちます。起動時にバンドルとリモートの両方のカタログを上書きするため、正しい model_catalog_json は、あると便利なものではなく、サードパーティモデルにとって本当の切り札になります。

ここが全員をつまずかせる部分です。Codex が起動すると、app-server は3つのレイヤーをすべて読み込んで解決し、その結果を内部の model/list エンドポイントで公開します。CLI はその一覧を直接描画するため、カスタムモデルが表示されます。Desktop アプリは同じ一覧を追加のクライアント処理を通して描画し、issue #19694 によれば、独自の許可リストを適用してドロップダウンに届く前にローカル設定されたエントリを落とします。同じバックエンド、同じカタログ、2つの異なるピッカーです。この1つの分岐こそが、CLI が信頼できる逃げ道で Desktop がそうでない理由です。

もう1つ注意すべきキャッシュがあります。Codex は ~/.codex/models_cache.json を保持しており、プロバイダを切り替えたりカタログを編集したりした後でも、常に再同期するとは限りません。古いキャッシュは、設定が正しくなった後でも古い一覧、あるいは空の一覧を表示し続けることがあります。このファイルを削除すると次回起動時にクリーンな再構築が強制されるので、カタログ自体が間違っていると決めつける前に試す価値があります。

解決方法（あらゆる構成向けのソリューション）

上から順に進めてください。解決策1は必ず効くものです。後の解決策はピッカーを見栄えよくし、一覧を切り替え可能にします。

解決策1：モデルをインラインで設定する（確実な回避策）

これは #19694 のスレッドが最終的に落ち着いた回避策で、まず手を伸ばすべきものです。モデル文字列を config.toml に直接入れ、ピッカーには「Custom」と表示させます。

# ~/.codex/config.toml   (user-level, not a project folder)
model = "moonshotai/kimi-k2.7-code"
model_provider = "ofox"

[model_providers.ofox]
name = "ofox"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"

キーをエクスポートし（シェルのプロファイルで export OFOX_API_KEY=sk-...）、Codex Desktop を完全に終了してから再度開きます。ピッカーには「Custom」と表示されますが、すべてのリクエストは moonshotai/kimi-k2.7-code に届きます。別のモデルを指定したい場合は文字列を差し替えてください。deepseek/deepseek-v4-pro や openai/gpt-5.3-codex は同じゲートウェイ上にある他のコーディング用 ID です。3つとも1つのキーから利用できます。プロバイダブロック自体の手順については、Codex CLI multi-provider setup via config.toml ガイドを参照してください。

wire_api に関する注意点です。Codex は 2026年2月初旬に古い chat/completions パスを削除しました（discussion #7782 を参照）。現在 responses が唯一のサポート値で、キーを省略した場合のデフォルトでもあります。wire_api = "chat" のままのプロバイダは起動時に失敗します。実務上の要件は、ゲートウェイが {base_url}/responses に OpenAI 互換の Responses エンドポイントを公開していることで、ofox は https://api.ofox.ai/v1/responses でこれを提供しているため、ここでは wire_api = "responses" が正しい設定です。/chat/completions しか話さないゲートウェイに Codex を向けると、すべてのリクエストが 404 になり、モデルの問題のように見えますが、実際にはプロトコルの不一致です。フィールドの完全な一覧は Codex configuration reference にあります。

解決策2：モデルカタログを追加してピッカーに一覧表示させる

「Custom」ではなくドロップダウンに実際の名前を表示したい場合は、model_catalog_json が必要です。これは起動時に一度読み込まれる JSON ファイルで、トップレベルの models 配列を持ちます。各エントリが1つのモデルを記述します。

# top of ~/.codex/config.toml
model_catalog_json = "/Users/you/.codex/ofox-models.json"
model = "moonshotai/kimi-k2.7-code"
model_provider = "ofox"

公式の codex models.json のフィールドを使った、最小限のカタログエントリ：

{
  "models": [
    {
      "slug": "moonshotai/kimi-k2.7-code",
      "display_name": "Kimi K2.7 Code (ofox)",
      "description": "Coding model via the ofox gateway",
      "context_window": 262000,
      "max_context_window": 262000,
      "supported_in_api": true,
      "visibility": "list",
      "priority": 1
    }
  ]
}

slug はプロバイダに送る文字列と一致していなければなりません。公式カタログはモデルごとにさらに多くのフィールド（推論レベル、ツールの種類、モダリティフラグ）を持っており、完全な形を手書きするのは骨が折れます。それこそが次の解決策が存在する理由です。カタログを変更したら Desktop を再起動してください。このレイヤーはバンドルカタログとリモートカタログの両方を上書きし、起動時にしか再読み込みしないため、スレッドごとの設定変更では再適用されません。

解決策3：プロバイダをユーザーレベルの設定に移動する

Codex がプロバイダ設定を無視した旨の起動時警告を出力する場合、プロバイダブロックが間違ったファイルにあります。model_provider と model_providers は ~/.codex/config.toml でのみ機能します。リポジトリの .codex/config.toml ではプロバイダを定義できません。プロジェクトローカルの model_catalog_json は別の話で、設計上は読み込まれるはずですが、現状は新しい Desktop スレッドでは読み込まれず、これは意図された挙動ではなくオープン中のバグ（#26308）です。

# check where your provider actually lives
grep -rn "model_providers" ~/.codex/config.toml ./.codex/config.toml 2>/dev/null
# if it is in ./.codex/config.toml, move the [model_providers.*] block
# and model_provider = "..." into ~/.codex/config.toml, then restart

instructions ファイルのようなリポジトリ固有のものはプロジェクト設定に残してください。プロバイダとモデルカタログはユーザーレベルに置いてください。

解決策4：cc-switch v3.16.5 にカタログを生成させる

Codex を cc-switch で管理しているなら、v3.16.5 以降にアップデートしてください。このリリースが、ネイティブプロバイダでのピッカーの空表示を修正するものです。ネイティブの Responses エンドポイント（apiFormat: "openai_responses"）を使うサプライヤ向けに ~/.codex/cc-switch-model-catalog.json を生成し、これによって Codex Desktop が実際にモデルを認識し、組み込みツールを使えるようになります。

アップデート後にやらなければならないことが2つあります。さもないと何も変わりません。

1. 各ネイティブプロバイダを一度保存し直す。 カタログは保存時にのみ再生成されます。既存のプロバイダは、開いて保存し直すまで古い（壊れた）状態のままです。自動移行はありません。
2. 切り離しを理解する。 v3.16.5 ではモデルカタログはもう「ローカルルーティング」トグルに乗りません。ネイティブの Responses サプライヤは、ローカルルーティングがオンかどうかにかかわらずカタログを生成するようになり、一方 Chat 形式のサプライヤは従来どおりプロキシ変換を経由し続けます。

# confirm the catalog exists and lists your models after re-saving
cat ~/.codex/cc-switch-model-catalog.json | grep -o '"slug":[^,]*'
# if this is empty, re-save the provider in cc-switch and check again

cc-switch 自身が無効化する1つの注意点：一部のファーストパーティ中国系モデル（MiMo、LongCat、MiniMax、Qwen3-Coder）は、それぞれのゲートウェイで OpenAI の組み込み web_search をサポートしていないため、v3.16.5 は Codex がハードな 400 を投げるのを防ぐべく、これらではデフォルトでそのツールをオフにします。これらをゲートウェイ経由でルーティングする場合は、ウェブ検索がオフになっていることを想定してください。

ピッカーのバグに見えて実は別物の、よくある設定ミス

「カスタムモデルが表示されない」という報告の半分は、実際には壊れたルートが表示上の問題の衣をまとっているだけです。カタログに触れる前に、これらを除外してください。それぞれが、ピッカーがモデルを隠しているように見える症状を生み出しますが、実際にはリクエストが届くチャンスすらなかったのです。

これらを本物の #19694 フィルタと区別する手がかりは1つのコマンドです。同じリクエストを CLI から実行してください。CLI でも失敗するなら、それは上記のエラーのいずれかであって Desktop のピッカーではなく、カタログをどう編集しても直りません。CLI では成功して Desktop だけが見えないままなら、それはフィルタであり、解決策1と解決策4に戻ることになります。

既知の Codex Desktop カスタムモデル問題（2026年タイムライン）

これは1つのバグではありません。Codex アプリと、その設定を書き出すツール群における関連する問題のクラスタです。どれに当たっているかを知れば、間違った解決策を適用せずに済みます。

これらすべてに共通するパターン：ルーティングは機能するのに、表示は機能しない。CLI は毎回、信頼できる逃げ道でした。Desktop レンダラーの追加フィルタなしにカタログを読み込むからです。Desktop で行き詰まっている場合、CLI（ターミナルの codex）はほぼ確実にモデルを表示し、使用できます。

それでもピッカーにモデルが出ないとき：今すぐ機能する代替策

Desktop の UI と戦うのに疲れたなら、クライアントの修正を待たずにカスタムモデルを使い続ける方法があります。ここでゲートウェイを使う意義は、多数のモデルにまたがって1つのエンドポイントと1つのキーを使えることにあり、モデルの切り替えが、毎回新しいプロバイダブロックを書くのではなく、1つの文字列を編集するだけで済みます。

プロバイダとして ofox を使うと保守が一気に楽になります。moonshotai/kimi-k2.7-code（262K コンテキスト）、deepseek/deepseek-v4-pro（1M コンテキスト）、openai/gpt-5.3-codex（512K コンテキスト）はすべて同じ https://api.ofox.ai/v1 と同じキーの背後にあり、現在のトークン単価は各モデルの ofox ページに表示されています。モデルを切り替えるには config.toml の1つの文字列を変えるだけで、新しいプロバイダブロックも2つ目のキーも不要です。OpenAI 互換クライアント向けのベース URL 設定は ofox docs にあります。どの経路を取るにせよ、Desktop ピッカーの癖はその上に乗った表示レイヤーであって、ルーティングの制約ではありません。

カスタムモデルが実際に読み込まれているか確認する方法

ピッカーを真実の拠り所として信頼しないでください。壊れているのはそれ自体だからです。その1つ下のレイヤーで検証しましょう。

codex --version                 # confirm you are on a recent build
codex                           # start the CLI, then type /model
# the CLI enumerates the catalog without the Desktop filter

CLI の /model にモデルが表示されるなら、カタログとプロバイダは正しく、残る食い違いは Desktop レンダラーです。CLI でも空で出るなら、問題は上流にあります。ファイルの間違い（解決策3）、不正なカタログ（解決策2／解決策4）、または slug の誤りです。ルート自体が解決するかの素の確認としては、キーを付けてゲートウェイに1回 curl すれば、そもそもクライアントを疑う前にモデルが存在するかどうかがわかります。ルーティングが先、表示が後です。

FAQ

Codex Desktop でカスタムモデルが表示されないのはなぜですか？ たいていはモデルは動作しており、Desktop アプリがそれをピッカーからフィルタで除外しています（issue #19694）。副次的な原因：カタログファイルがない、古いツールが作った不正なカタログ、プロジェクトローカルの .codex/config.toml でプロバイダを定義している。

Codex の config.toml にカスタムモデルを追加するにはどうすればよいですか？ [model_providers.NAME] を base_url、env_key、wire_api とともに定義し、model_provider と model を設定します。これは ~/.codex/config.toml に置いてください。ofox の場合は base_url = "https://api.ofox.ai/v1" です。

cc-switch は Codex Desktop で動作しますか？ はい、v3.16.5 以降で動作し、ネイティブの Responses プロバイダ向けに ~/.codex/cc-switch-model-catalog.json を生成します。アップデート後は各プロバイダを一度保存し直してください。

Codex のモデルカタログファイルはどこにありますか？ ~/.codex/config.toml の model_catalog_json が指す場所です。cc-switch は ~/.codex/cc-switch-model-catalog.json を使います。プロバイダ切り替え後の古い ~/.codex/models_cache.json に注意してください。

Codex がモデル名の代わりに「Custom」と表示するのはなぜですか？ カタログエントリなしで model をインライン設定したため、ピッカーに表示用メタデータがないのです。リクエストは依然として正しいモデルに届きます。

プロジェクトローカルの .codex/config.toml でカスタムモデルを使えますか？ いいえ。プロバイダ設定は ~/.codex/config.toml でのみ有効です。プロジェクトローカルのプロバイダブロックは起動時の警告とともに無視されます。

Codex の model_catalog_json とは何ですか？ 起動時に読み込まれる JSON ファイルを指す config.toml のキーで、トップレベルの models 配列に slug、display_name、機能フィールドを持つエントリを列挙します。バンドルおよびリモートのカタログを上書きします。

Codex を Kimi、DeepSeek、GPT-Codex にルーティングするにはどうすればよいですか？ 1つのカスタムプロバイダをゲートウェイに向け、model を設定します。ofox では：moonshotai/kimi-k2.7-code、deepseek/deepseek-v4-pro、openai/gpt-5.3-codex で、すべて https://api.ofox.ai/v1 から利用できます。

動くのに表示されないモデルの解決策は、ほぼ常に、ピッカーの編集をやめてその下のレイヤーを信頼することです。CLI は、Desktop アプリが隠しているものをすでに見えているのです。

この更新のために確認した情報源

• Codex issue #19694: Desktop model picker filters out models from model_catalog_json（オープン、2026-07-05 確認）
• cc-switch v3.16.5 release notes（2026-07-05 確認）
• cc-switch issue #3668: catalog format not recognized by Codex（2026-07-05 確認）
• Codex configuration reference（2026-07-05 確認）
• Codex models.json catalog schema（2026-07-05 確認）
• ofox モデルカタログと料金のスナップショット、https://ofox.ai/models （2026-07-05 確認）