lidge-jun · github-actions · Aug 7, 2026 · Aug 5, 2026 · Aug 6, 2026
@@ -4,8 +4,8 @@ description: How opencodex models appear in Codex App, Codex CLI, and Codex TUI
 ---
 
 opencodex does not patch Codex App. It writes the same Codex configuration and model catalog that
-Codex CLI/TUI already use. Because Codex App reads that shared state, routed models can appear in the
-App's model picker as normal Codex catalog entries.
+Codex CLI/TUI use. The app-server reads that shared state, but some Codex Desktop releases apply a
+second remote model allowlist in the renderer and can still remove routed rows from the picker.
 
 OpenAI entries use two credential routes: native Codex login and the namespaced
 `openai-apikey/<model>` API-key transport. Changing `codexAccountMode` between Pool and Direct by
@@ -41,6 +41,21 @@ cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json
 
 Earlier v1 three-provider configurations migrate automatically into the single option-aware row.
 
+## Desktop remote-allowlist limitation
+
+If `codex debug models` and app-server `model/list` contain a routed model but Desktop does not show
+it, check the upstream [Codex issue #19694](https://github.com/openai/codex/issues/19694). With the
+remote `use_hidden_models` policy active, Desktop can keep only ids in its native
+`available_models` list and can also display native rows whose catalog visibility is `hide`.
+Catalog refreshes and proxy restarts alone cannot change that renderer policy.
+
+For an equivalent routed model, opencodex provides an explicit, default-off native-alias combo mode.
+It publishes an allowlisted bare slug with an honest custom display label and routes that exact slug
+through the configured combo before canonical OpenAI routing. It also omits disabled bare native
+rows from the effective catalog while compatibility aliases exist, so Desktop cannot resurrect
+them by ignoring `visibility`. See [Codex Desktop native-allowlist compatibility](/guides/combos/#codex-desktop-native-allowlist-compatibility)
+for the command, disable-key semantics, and safety constraints.
+
 ## Integration path
 
 `ocx init`, `ocx start`, and `ocx sync` wire the shared Codex config and catalog into the proxy; see
@@ -99,6 +114,9 @@ the configuration manually:
 - Native GPT ids are bare slugs. Disabling one keeps its catalog entry but changes `visibility` to
   `hide`, preserving the exact entry for a later re-enable; it hides the bare row and every
   selector-qualified clone for that model from discovery.
+- With at least one native-alias combo configured, disabled bare native rows are omitted rather than
+  retained hidden because affected Desktop releases ignore the hidden flag. The dashboard keeps
+  their static switches and sync restores native metadata when a row is re-enabled.
 - Native rows come from the supported static set, so a disabled native model stays visible in the
   dashboard and can be turned back on.
 

@@ -63,8 +63,8 @@ An optional alias gives the combo a different public model name. An alias:
 - may be bare, such as `daily-fast`, or contain one `/`, such as `team/daily-fast`;
 - cannot be `combo` or start with `combo/`;
 - cannot duplicate another combo alias; and
-- cannot be a bare native OpenAI-family name beginning with `gpt-`, `o1-`, `o3-`, `o4-`, or
-  `codex-`.
+- cannot normally be a bare native OpenAI-family name beginning with `gpt-`, `o1-`, `o3-`, `o4-`,
+  or `codex-`. The explicit Desktop compatibility mode below is the only exception.
 
 Even when an alias is set, the canonical `combo/<id>` form still resolves. Canonical lookup runs
 before alias matching, so an alias cannot take over another combo's canonical id.
@@ -74,6 +74,51 @@ Aliases change the public name clients request; they do not change the combo's s
 concrete provider/model selectors behind it.
 :::
 
+## Codex Desktop native-allowlist compatibility
+
+Some Codex Desktop releases apply a remote native-only `available_models` allowlist after the
+app-server has already loaded `model_catalog_json`. Normal routed ids such as
+`Nova1/codex-gpt-5.6-sol` are then usable by the CLI but absent from the Desktop picker. This is the
+upstream [Codex Desktop bug](https://github.com/openai/codex/issues/19694) tracked by
+[opencodex #241](https://github.com/lidge-jun/opencodex/issues/241).
+
+When you control an equivalent routed target, a combo can explicitly take over one native slug:
+
+```bash
+ocx combo set nova-sol \
+  --targets Nova1/codex/gpt-5.6-sol \
+  --alias gpt-5.6-sol \
+  --native-alias \
+  --display-name 'Nova1 - codex-gpt-5.6-sol'
+```
+
+This mode is deliberately opt-in and requires both `--native-alias` and a non-empty display label.
+The alias must be one of the native model ids supported by this opencodex release; a native-family
+prefix alone is not accepted because removal must be able to restore authoritative metadata.
+When the routed target's discovery response supplies only a model id, the compatibility row fills
+missing context, modality, and reasoning metadata from the native id it replaces. Explicit target
+limits still win, so this fallback never raises a context cap or overrides declared capabilities.
+It changes exact routing precedence: requests for `gpt-5.6-sol` resolve to `combo/nova-sol` before
+the canonical OpenAI native-family route. The catalog contains one bare row with the configured
+display label, not duplicate native and combo rows. Account-qualified rows such as
+`main/gpt-5.6-sol` remain genuine OpenAI routes.
+
+Visibility keys stay unambiguous:
+
+- `combo/nova-sol` hides the compatibility combo from discovery.
+- The bare `gpt-5.6-sol` entry in `disabledModels` continues to mean the dormant native OpenAI row;
+  it does not hide the combo that currently owns that public slug.
+- While at least one native alias is configured, disabled bare native rows are omitted from the
+  effective Codex catalog instead of retained as `visibility: "hide"`. This prevents Desktop's
+  allowlist from resurrecting rows it should not show. The Models page still lists unshadowed native
+  switches, and re-enabling one restores its preserved or current native metadata.
+
+:::caution
+A native alias intentionally takes over a first-party-looking model id. Use it only when the target
+is operationally equivalent and label the picker row honestly. Removing the combo restores normal
+native routing and catalog identity on the next sync.
+:::
+
 ## Choose a strategy
 
 ### Failover: ordered primary and backups
@@ -214,10 +259,11 @@ ocx combo set <id> --targets provider/model[:weight],...
 ocx combo remove <id> --yes
 ```
 
-`set` also accepts `--strategy`, `--sticky`, `--effort`, `--alias`, and `--rename-from`. Use `-`
-as the value of `--effort` or `--alias` to clear that field. `create` and `update` are aliases for
-`set`; `delete` is an alias for `remove`; and the same subcommands are available under
-`ocx route combo`.
+`set` also accepts `--strategy`, `--sticky`, `--effort`, `--alias`, `--native-alias`,
+`--display-name`, and `--rename-from`. Use `-` as the value of `--effort`, `--alias`, or
+`--display-name` to clear that field. `--native-alias` requires a currently supported bare native
+model alias and a non-empty display name. `create` and `update` are aliases for `set`; `delete` is an alias for
+`remove`; and the same subcommands are available under `ocx route combo`.
 
 ### Management API
 
@@ -257,6 +303,8 @@ Combos are stored in the top-level `combos` object, keyed by combo id:
 | `stickyLimit` | No | `1` | Integer from 1 to 100 successful requests per round-robin selection. |
 | `defaultEffort` | No | `null` | `low`, `medium`, `high`, `xhigh`, `max`, or `ultra`; applied only when the caller omits effort and the target advertises support. |
 | `alias` | No | none | Optional trimmed public model id; use the alias rules above. An empty value is stored as no alias. |
+| `nativeAlias` | No | `false` | Explicitly permit a currently supported bare native `alias` to take routing and catalog precedence. Never inferred from the alias. |
+| `displayName` | No | none | Bounded display-only catalog label. Required and non-empty when `nativeAlias` is true. |
 
 ## Troubleshooting
 

@@ -3,7 +3,10 @@ title: Codex App モデル ピッカー
 description: opencodex モデルが、共有 Codex カタログを通じて Codex App、Codex CLI、Codex TUI にどのように表示されるか。
 ---
 
-opencodex は Codex アプリにパッチを適用しません。 Codex CLI/TUI が既に使用しているのと同じ Codex 設定とモデル カタログを書き込みます。 Codex アプリはその共有状態を読み取るため、ルーティングされたモデルは通常の Codex カタログ エントリとしてアプリのモデル ピッカーに表示されます。
+opencodex は Codex アプリにパッチを適用しません。Codex CLI/TUI と同じ Codex 設定とモデル
+カタログを書き込みます。app-server はその共有状態を読み取りますが、一部の Codex Desktop
+リリースは renderer 側で追加の remote allowlist を適用し、routed row を picker から除外する
+ことがあります。明示的な `nativeAlias: true` combo が、この上流不具合向けの互換モードです。
 
 OpenAI エントリには、ネイティブ Codex ログインと、名前空間付きの `openai-apikey/<model>` API キーという 2 つの資格情報ルートがあります。`codexAccountMode` だけを Pool と Direct の間で変更しても、ピッカー ID は変わりません。ただし、`codexAccountNamespaces` に対象アカウントが存在する selector がある場合、opencodex は対応するアカウントごとに `<selector>/<native-openai-model>` 行を追加し、ピッカーでは bare native 行を非表示にします。Selector 名はユーザーが決める公開ラベルであり、組み込みのアカウント role の意味はありません。`selector` 付きの行を選択すると、対応付けられたアカウントだけが使用され、アクティブな Pool アカウントは変更されません。対象を利用できない場合、別のアカウントへ切り替えずにリクエストが失敗します。詳しくは [Codex アカウントの明示的な selector](/reference/configuration/routing/#exact-codex-account-selectors) を参照してください。API GPT-5.6 エントリは 1,050,000 コンテキスト / 922,000 最大入力を使用し、`*-pro` ピッカー ID は `reasoning.mode: "pro"` のベース ワイヤ モデルに解決されますが、ログ、使用状況、およびピッカー状態は仮想 ID を保持します。 API カタログは、`gpt-5.5`、`gpt-5.6`、Sol/Terra/Luna、およびそれらの 3 つの Pro 仮想 ID の 8 つの ID に固定されています。汎用の `gpt-5.6-pro` エイリアスはありません。コンパクト リクエストは、選択された層を保持しますが、推論オブジェクトなしで基本モデルを送信します。
 

@@ -53,8 +53,8 @@ ocx combo show main
 - `daily-fast` のように裸の場合もあれば、`team/daily-fast` のように `/` を 1 つ含む場合もあります。
 - `combo` にしたり、`combo/` で始めることはできません。
 - 別のコンボ エイリアスを複製することはできません。そして
-- `gpt-`、`o1-`、`o3-`、`o4-`、またはで始まる裸のネイティブ OpenAI ファミリ名は使用できません。
-`codex-`。
+- 通常、`gpt-`、`o1-`、`o3-`、`o4-`、または `codex-` で始まる bare native OpenAI
+  family 名は使用できません。明示的な `nativeAlias: true` Desktop 互換モードだけが例外です。
 
 エイリアスが設定されている場合でも、正規の `combo/<id>` 形式は解決されます。正規ルックアップはエイリアスの一致の前に実行されるため、エイリアスが別のコンボの正規 ID を引き継ぐことはできません。
 
@@ -175,7 +175,10 @@ ocx combo set <id> --targets provider/model[:weight],...
 ocx combo remove <id> --yes
 ```
 
-`set` は、`--strategy`、`--sticky`、`--effort`、`--alias`、および `--rename-from` も受け入れます。そのフィールドをクリアするには、`--effort` または `--alias` の値として `-` を使用します。 `create` および `update` は、`set` のエイリアスです。 `delete` は `remove` のエイリアスです。同じサブコマンドが `ocx route combo` で使用できます。
+`set` は、`--strategy`、`--sticky`、`--effort`、`--alias`、`--native-alias`、
+`--display-name`、および `--rename-from` も受け入れます。`--native-alias` には現在
+サポートされている bare native alias と空でない display name が必要です。`create` および `update` は `set` の
+エイリアス、`delete` は `remove` のエイリアスです。
 
 ### 管理 API
 
@@ -212,6 +215,8 @@ ocx combo remove <id> --yes
 | `stickyLimit` |いいえ | `1` |ラウンドロビン選択ごとの成功したリクエストの数は 1 ～ 100 の整数です。 |
 | `defaultEffort` |いいえ | `null` | `low`、`medium`、`high`、`xhigh`、`max`、または `ultra`;呼び出し元が努力を省略し、ターゲットがサポートをアドバタイズした場合にのみ適用されます。 |
 | `alias` |いいえ |なし |オプションのトリミングされたパブリック モデル ID。上記のエイリアス ルールを使用します。空の値はエイリアスなしで保存されます。 |
+| `nativeAlias` |いいえ | `false` | 現在サポートされている bare native alias に routing/catalog の優先権を明示的に与えます。 |
+| `displayName` |いいえ |なし | catalog 表示専用ラベル。`nativeAlias` が true の場合は必須です。 |
 
 ## トラブルシューティング
 

@@ -46,7 +46,7 @@ selector の後には bare native OpenAI-family id だけを指定できます
 
 ## コンボ (`config.combos`)
 
-各コンボ キーは `[A-Za-z0-9][A-Za-z0-9._-]{0,63}` に一致する ID です。これは常に `combo/<id>` として直接アドレス指定可能であり、1 つの `alias` を公開することもあります。エイリアスは一意である必要があり、`combo/` 名前空間を占有することはできず、`gpt-*`、`o1-*`、`o3-*`、`o4-*`、または `codex-*` などの予約されたベア ネイティブ ファミリを使用することはできません。
+各コンボ キーは `[A-Za-z0-9][A-Za-z0-9._-]{0,63}` に一致する ID です。これは常に `combo/<id>` として直接アドレス指定可能であり、1 つの `alias` を公開することもあります。エイリアスは一意である必要があり、`combo/` 名前空間を占有することはできず、通常は `gpt-*`、`o1-*`、`o3-*`、`o4-*`、または `codex-*` などの予約された bare native family を使用できません。明示的な `nativeAlias: true` Desktop 互換契約だけが例外です。
 
 |キー |タイプ |デフォルト |意味 |
 | --- | --- | --- | --- |
@@ -55,6 +55,8 @@ selector の後には bare native OpenAI-family id だけを指定できます
 | `stickyLimit?` | `number` | `1` |成功したリクエストは 1 つのラウンドロビン バッチに保持されます。範囲は 1 ～ 100。 |
 | `defaultEffort?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max" \| "ultra" \| null` |設定を解除する |呼び出し元が努力を省略し、選択されたターゲットが要求されたラングをアドバタイズする場合にのみ適用されます。 |
 | `alias?` | `string` | — |正規のピッカー スラグの代わりのオプションのパブリック モデル ID。 |
+| `nativeAlias?` | `boolean` | `false` | 現在サポートされている bare native id に限り、その未修飾 id で優先します。アカウント修飾およびプロバイダー修飾の OpenAI ルートは別のままです。 |
+| `displayName?` | `string` | — | catalog 表示専用ラベル。native alias では空でない値が必須です。 |
 
 ```json
 {

@@ -3,9 +3,10 @@ title: Codex App 모델 선택기
 description: 공유 Codex 카탈로그를 통해 opencodex 모델이 Codex App, Codex CLI, Codex TUI에 표시되는 방식.
 ---
 
-opencodex는 Codex App을 직접 고치지 않습니다. Codex CLI/TUI가 이미 쓰는 Codex 설정과 모델 카탈로그를
-같은 위치에 씁니다. Codex App도 이 공유 상태를 읽기 때문에, 라우팅된 모델이 일반 Codex 카탈로그
-항목처럼 App의 모델 선택기에 나타날 수 있습니다.
+opencodex는 Codex App을 직접 고치지 않습니다. Codex CLI/TUI와 같은 Codex 설정과 모델 카탈로그를
+씁니다. app-server는 이 공유 상태를 읽지만, 일부 Codex Desktop 릴리스는 renderer에서 추가 remote
+allowlist를 적용해 routed row를 picker에서 제거할 수 있습니다. 명시적 `nativeAlias: true` combo가
+이 업스트림 버그를 위한 호환 모드입니다.
 
 OpenAI 항목에는 네이티브 Codex 로그인과 네임스페이스가 붙은 `openai-apikey/<model>` API key
 경로라는 두 가지 credential 경로가 있습니다. `codexAccountMode`만 Pool과 Direct 사이에서 바꾸는 것은

@@ -53,7 +53,8 @@ ocx combo show main
 - `daily-fast`처럼 단독일 수도 있고, `team/daily-fast`처럼 `/`를 하나 포함할 수도 있습니다.
 - `combo`일 수 없고 `combo/`로 시작할 수도 없습니다.
 - 다른 콤보 alias와 중복될 수 없습니다.
-- `gpt-`, `o1-`, `o3-`, `o4-`, `codex-`로 시작하는 bare OpenAI 계열 이름일 수 없습니다.
+- 일반적으로 `gpt-`, `o1-`, `o3-`, `o4-`, `codex-`로 시작하는 bare OpenAI 계열 이름일 수
+  없습니다. 명시적 `nativeAlias: true` Desktop 호환 모드만 예외입니다.
 
 alias를 설정해도 정식 `combo/<id>` 형식은 계속 해석됩니다. 정식 조회가 alias 매칭보다 먼저 실행되므로, alias가 다른 콤보의 정식 ID를 가로챌 수는 없습니다.
 
@@ -174,7 +175,9 @@ ocx combo set <id> --targets provider/model[:weight],...
 ocx combo remove <id> --yes
 ```
 
-`set`은 `--strategy`, `--sticky`, `--effort`, `--alias`, `--rename-from`도 받습니다. `--effort` 또는 `--alias` 값으로 `-`를 주면 해당 필드를 지울 수 있습니다. `create`와 `update`는 `set`의 별칭이고, `delete`는 `remove`의 별칭입니다. 같은 하위 명령은 `ocx route combo` 아래에서도 사용할 수 있습니다.
+`set`은 `--strategy`, `--sticky`, `--effort`, `--alias`, `--native-alias`, `--display-name`,
+`--rename-from`도 받습니다. `--native-alias`에는 현재 지원되는 bare native alias와 비어 있지 않은
+display name이 필요합니다. `create`와 `update`는 `set`의 별칭이고 `delete`는 `remove`의 별칭입니다.
 
 ### Management API
 
@@ -211,6 +214,8 @@ ocx combo remove <id> --yes
 | `stickyLimit` | 아니요 | `1` | round-robin 선택 한 번당 성공 요청 1에서 100회 사이의 정수입니다. |
 | `defaultEffort` | 아니요 | `null` | `low`, `medium`, `high`, `xhigh`, `max`, 또는 `ultra`입니다. 호출자가 effort를 생략하고 대상이 지원을 광고할 때만 적용됩니다. |
 | `alias` | 아니요 | 없음 | 선택적으로 앞뒤 공백을 제거한 공개 모델 ID입니다. 위의 alias 규칙을 따릅니다. 빈 값은 alias 없음으로 저장됩니다. |
+| `nativeAlias` | 아니요 | `false` | 현재 지원되는 bare native alias가 routing/catalog 우선권을 갖도록 명시적으로 허용합니다. |
+| `displayName` | 아니요 | 없음 | catalog 표시 전용 label입니다. `nativeAlias`가 true이면 필수입니다. |
 
 ## 문제 해결