Skip to content

docs(codex-app-models): document Desktop remote allowlist limitation (#241) #999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Yuxin-Qiao wants to merge 1 commit into from
+69 −0
Closed

docs(codex-app-models): document Desktop remote allowlist limitation (#241) #999

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs-site/src/content/docs/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,23 @@ The featured-model list is separate from the Dashboard's **Sub-agent delegation*
controls which overrides Codex offers first; it does not select a model or trigger delegation by
itself.

## Desktop remote servers

Codex Desktop's remote-server mode filters the picker against the client's own
`available_models` allowlist (active when the remote `use_hidden_models` setting is on). Routed
catalog entries are still loaded and served - `model/list` returns them and the bundled CLI reads
them - but the Desktop renderer drops anything that is not on that native-only allowlist before
rendering. opencodex has no hook into that list; the upstream bug is tracked at
[openai/codex#19694](https://github.com/openai/codex/issues/19694).

Until Desktop exposes a control for the allowlist:

- Set the model directly in `~/.codex/config.toml` on the remote machine, for example
`model = "input/grok-4.5"`. The picker may show `Custom`, but requests still use the configured

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use a configured provider in the workaround example

In a standard configuration, input is not a provider, so copying this workaround does not select a routed model: routeModel strips a namespace only when it matches a configured provider, and otherwise may forward the entire invalid input/grok-4.5 string to the default provider. Use a real documented route such as xai/grok-4.5, or an explicit <provider>/<model> placeholder, and update the translated copies accordingly.

AGENTS.md reference: docs-site/AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

routed model.
Comment on lines +151 to +153

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

# Verify whether `input` is an actual provider and whether the example resolves.
rg -n \
  'input/grok-4\.5|xai/grok-4\.5|cursor/grok-4\.5|["'\'']input["'\'']|provider.*input' \
  .

Repository: lidge-jun/opencodex

Length of output: 50375

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- affected documentation ---'
for f in \
  docs-site/src/content/docs/guides/codex-app-models.md \
  docs-site/src/content/docs/ja/guides/codex-app-models.md \
  docs-site/src/content/docs/ko/guides/codex-app-models.md \
  docs-site/src/content/docs/ru/guides/codex-app-models.md \
  docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
do
  echo "### $f"
  rg -n -C 4 'input/grok-4\.5|model directly|モデルを直接|직접 설정|напрямую|直接设置' "$f"
done

printf '%s\n' '--- routing and provider declarations ---'
fd -t f . src | sort | while read -r f; do
  if rg -q 'routeModel|provider.*model|model.*provider|providers:' "$f"; then
    echo "### $f"
    rg -n -C 3 'routeModel|provider.*model|model.*provider|providers:' "$f" | head -160
  fi
done

printf '%s\n' '--- exact input-provider evidence outside documentation/data fields ---'
rg -n --glob '!docs-site/**' --glob '!*.json' \
  '(^|[^[:alnum:]_-])input/grok-4\.5([^[:alnum:]_.-]|$)|provider[[:space:]]*[:=][[:space:]]*["'\''`]input["'\''`]|["'\''`]input["'\''`][[:space:]]*:' \
  src tests gui scripts || true

Repository: lidge-jun/opencodex

Length of output: 50376

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- routeModel definition and call sites ---'
rg -l --glob '*.ts' 'export (async )?function routeModel|function routeModel|routeModel\s*=' src tests | sort
rg -n -C 8 --glob '*.ts' \
  'export (async )?function routeModel|function routeModel|routeModel\s*=' \
  src tests | head -240

printf '%s\n' '--- provider-name validation and config lookup ---'
rg -n -C 8 --glob '*.ts' \
  'isValidProviderName|defaultProvider|config\.providers\[|providers\[provider|providers\[model' \
  src tests | head -320

printf '%s\n' '--- provider registry entries ---'
rg -n -C 3 --glob '*.ts' --glob '*.json' \
  'provider(Name|Id)?[[:space:]]*[:=].*(xai|cursor|input)|["'\''](xai|cursor|input)["'\'']' \
  src tests | head -240

printf '%s\n' '--- exact example count in all affected locales ---'
python3 - <<'PY'
from pathlib import Path
files = [
    Path("docs-site/src/content/docs/guides/codex-app-models.md"),
    Path("docs-site/src/content/docs/ja/guides/codex-app-models.md"),
    Path("docs-site/src/content/docs/ko/guides/codex-app-models.md"),
    Path("docs-site/src/content/docs/ru/guides/codex-app-models.md"),
    Path("docs-site/src/content/docs/zh-cn/guides/codex-app-models.md"),
]
for path in files:
    text = path.read_text()
    print(f"{path}: input/grok-4.5={text.count('input/grok-4.5')}, "
          f"xai/grok-4.5={text.count('xai/grok-4.5')}, "
          f"cursor/grok-4.5={text.count('cursor/grok-4.5')}")
PY

Repository: lidge-jun/opencodex

Length of output: 50375

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- complete routing branches ---'
sed -n '340,465p' src/router.ts

printf '%s\n' '--- routing tests for unknown namespaces and configured providers ---'
rg -n -C 8 --glob '*.test.ts' \
  'No provider configured for model|routeModel\(.*\/|unknown.*provider|provider.*not configured|defaultProvider' \
  tests | head -320

printf '%s\n' '--- provider/model documentation context ---'
for f in \
  docs-site/src/content/docs/guides/providers.md \
  docs-site/src/content/docs/reference/adapters.md \
  docs-site/src/content/docs/guides/codex-app-models.md
do
  echo "### $f"
  rg -n -C 5 'provider/model|provider-qualified|direct|configured|xai/grok-4\.5|cursor/grok-4\.5|openai-chat|catalog' "$f" | head -220
done

printf '%s\n' '--- standalone route decision verifier ---'
python3 - <<'PY'
def route_decision(providers, default_provider, model_id):
    slash = model_id.find("/")
    if slash > 0:
        namespace = model_id[:slash]
        if namespace in providers:
            return ("explicit-provider", namespace, model_id[slash + 1:])
    if model_id.startswith(("gpt-", "o")):
        if "openai" in providers:
            return ("native-openai", "openai", model_id)
        raise RuntimeError(f"no enabled OpenAI provider for {model_id}")
    for name, provider in providers.items():
        if provider.get("defaultModel") == model_id:
            return ("provider-default", name, provider["defaultModel"])
        if model_id in provider.get("models", []):
            return ("provider-model-list", name, model_id)
    if default_provider in providers:
        return ("default-provider-fallback", default_provider, model_id)
    raise RuntimeError(f"No provider configured for model: {model_id}")

configs = [
    (
        "xai configured, input absent",
        {"xai": {"models": ["grok-4.5"]}},
        "xai",
        "input/grok-4.5",
    ),
    (
        "cursor configured, input absent",
        {"cursor": {"models": ["grok-4.5"]}},
        "cursor",
        "input/grok-4.5",
    ),
    (
        "input explicitly configured",
        {"input": {"models": ["grok-4.5"]}},
        "input",
        "input/grok-4.5",
    ),
]
for name, providers, default_provider, model_id in configs:
    try:
        print(name, "=>", route_decision(providers, default_provider, model_id))
    except RuntimeError as exc:
        print(name, "=> ERROR:", exc)
PY

Repository: lidge-jun/opencodex

Length of output: 50377

Use the configured provider/model identifier in all five locale workarounds.

input is not a built-in provider. When it is not configured, routeModel falls through to the default provider and preserves input/grok-4.5, which can cause the upstream request to fail. Replace the example with model = "<provider>/<model>", or use xai/grok-4.5 or cursor/grok-4.5 only when that provider is configured.

Apply this change to docs-site/src/content/docs/guides/codex-app-models.md:151-153 and the corresponding lines in the Japanese, Korean, Russian, and Chinese pages.

📍 Affects 5 files
  • docs-site/src/content/docs/guides/codex-app-models.md#L151-L153 (this comment)
  • docs-site/src/content/docs/ja/guides/codex-app-models.md#L103-L103
  • docs-site/src/content/docs/ko/guides/codex-app-models.md#L147-L148
  • docs-site/src/content/docs/ru/guides/codex-app-models.md#L155-L157
  • docs-site/src/content/docs/zh-cn/guides/codex-app-models.md#L100-L100
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/guides/codex-app-models.md` around lines 151 -
153, Update the model configuration examples in the five locale workaround
sections to use a configured provider/model identifier:
docs-site/src/content/docs/guides/codex-app-models.md:151-153,
docs-site/src/content/docs/ja/guides/codex-app-models.md:103-103,
docs-site/src/content/docs/ko/guides/codex-app-models.md:147-148,
docs-site/src/content/docs/ru/guides/codex-app-models.md:155-157, and
docs-site/src/content/docs/zh-cn/guides/codex-app-models.md:100-100. Replace the
unconfigured input/grok-4.5 example with model =
"&lt;provider&gt;/&lt;model&gt;", or use xai/grok-4.5 or cursor/grok-4.5 only
where that provider is configured.

Source: Path instructions

- Use Codex CLI or TUI instead of the Desktop picker; they do not apply the allowlist and list
routed models normally.

## Refreshing model state

If the picker still shows stale entries, refresh the catalog and restart the target Codex surface:
Expand Down
9 changes: 9 additions & 0 deletions docs-site/src/content/docs/ja/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,15 @@ Codex は、ピッカーに表示されるカタログ エントリを `priority

注目モデルのリストは、ダッシュボードの **サブエージェント委任** の選択とは別のものです。 Codex が提供するものを最初にオーバーライドするものを制御します。モデルを選択したり、委任をトリガーしたりすることはありません。

## Desktop リモートサーバー

Codex Desktop のリモートサーバーモードでは、クライアント自身の `available_models` 許可リストでピッカーがフィルタリングされます(リモートの `use_hidden_models` 設定が有効な場合)。ルーティングされたカタログエントリは引き続きロードされ提供されます。`model/list` はそれらを返し、バンドルされた CLI も読み取れますが、Desktop レンダラーは表示前にこのネイティブのみの許可リストにないものを破棄します。opencodex はこのリストに介入できません。上流のバグは [openai/codex#19694](https://github.com/openai/codex/issues/19694) で追跡されています。

Desktop が許可リストの制御を提供するまでは:

- リモートマシンの `~/.codex/config.toml` でモデルを直接設定します(例: `model = "input/grok-4.5"`)。ピッカーには `Custom` と表示される場合がありますが、リクエストは設定されたルーティングモデルを使用します。
- Desktop ピッカーの代わりに Codex CLI または TUI を使用します。これらは許可リストを適用せず、ルーティングモデルを通常どおり一覧表示します。

## モデルの状態を更新しています

ピッカーに古いエントリがまだ表示されている場合は、カタログを更新し、ターゲットの Codex サーフェスを再起動します。
Expand Down
16 changes: 16 additions & 0 deletions docs-site/src/content/docs/ko/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,22 @@ model override로 노출합니다. `subagentModels`나 대시보드 Subagents
featured-model 목록은 Dashboard의 **Sub-agent delegation** 선택과 별개입니다. Codex가 먼저 보여 줄
override를 정할 뿐, 모델을 고르거나 delegation을 시작하지는 않습니다.

## Desktop 원격 서버

Codex Desktop의 원격 서버 모드는 클라이언트 자체 `available_models` 허용 목록으로 picker를
필터링합니다(원격 `use_hidden_models` 설정이 켜져 있을 때 적용). 라우팅된 카탈로그 항목은
여전히 로드되고 제공됩니다. `model/list`가 항목을 반환하고 번들 CLI도 읽을 수 있지만, Desktop
렌더러는 표시 전에 이 네이티브 전용 허용 목록에 없는 항목을 버립니다. opencodex는 이 목록에
개입할 수 없습니다. 업스트림 버그는
[openai/codex#19694](https://github.com/openai/codex/issues/19694)에서 추적됩니다.

Desktop이 허용 목록을 제어할 수 있게 될 때까지:

- 원격 머신의 `~/.codex/config.toml`에서 모델을 직접 설정하세요(예: `model = "input/grok-4.5"`).
picker에는 `Custom`으로 표시될 수 있지만, 요청은 설정된 라우팅 모델을 계속 사용합니다.
- Desktop picker 대신 Codex CLI 또는 TUI를 사용하세요. 이들은 허용 목록을 적용하지 않으며
라우팅 모델을 정상적으로 나열합니다.

## 모델 상태 새로고침

picker에 오래된 항목이 계속 보이면 카탈로그를 새로 쓰고 대상 Codex 서피스를 다시 시작합니다:
Expand Down
18 changes: 18 additions & 0 deletions docs-site/src/content/docs/ru/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,24 @@ Codex сортирует видимые в picker'е записи каталог
определяет, какие override Codex показывает первыми; он не выбирает модель и не инициирует
делегирование сам по себе.

## Удалённые серверы Desktop

В режиме удалённого сервера Codex Desktop фильтрует picker по собственному списку разрешённых
моделей `available_models` (активируется, когда включена удалённая настройка
`use_hidden_models`). Записи маршрутизированного каталога по-прежнему загружаются и отдаются —
`model/list` возвращает их, и встроенный CLI их читает, — но рендерер Desktop отбрасывает всё,
чего нет в этом списке, ограниченном нативными моделями, ещё до отрисовки. opencodex не может
влиять на этот список; соответствующий upstream-баг отслеживается в
[openai/codex#19694](https://github.com/openai/codex/issues/19694).

Пока Desktop не предоставит управление этим списком:

- Задайте модель напрямую в `~/.codex/config.toml` на удалённой машине, например
`model = "input/grok-4.5"`. Picker может показывать `Custom`, но запросы по-прежнему
используют настроенную маршрутизированную модель.
- Используйте Codex CLI или TUI вместо picker в Desktop; они не применяют этот список и
показывают маршрутизированные модели как обычно.

## Обновление состояния моделей

Если picker всё ещё показывает устаревшие записи, обновите каталог и перезапустите нужную
Expand Down
9 changes: 9 additions & 0 deletions docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,15 @@ Codex 会按 `priority` 升序对选择器可见的目录条目排序，并把

精选模型列表与 Dashboard 的 **Sub-agent delegation** 选择彼此独立。它只决定 Codex 先提供哪些 override；它不会自己选择模型，也不会触发委派。

## Desktop 远程服务器

Codex Desktop 的远程服务器模式会针对客户端自己的 `available_models` 白名单过滤模型选择器（当远程 `use_hidden_models` 设置启用时生效）。路由目录条目仍然会被加载并对外提供——`model/list` 会返回它们，内置 CLI 也能读取——但 Desktop 渲染层在显示前会丢弃任何不在这个仅包含原生模型的白名单中的条目。opencodex 无法影响这份白名单；上游问题在 [openai/codex#19694](https://github.com/openai/codex/issues/19694) 跟踪中。

在 Desktop 提供白名单控制之前：

- 在远程机器的 `~/.codex/config.toml` 中直接设置模型，例如 `model = "input/grok-4.5"`。选择器可能显示为 `Custom`，但请求仍会使用所配置的路由模型。
- 改用 Codex CLI 或 TUI，而不是 Desktop 选择器；它们不应用该白名单，会正常列出路由模型。

## 刷新模型状态

如果选择器里仍然显示旧条目，请刷新目录并重启目标 Codex 界面：
Expand Down
Loading