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

[Yuxin-Qiao]

Summary

• Document why routed models do not appear in the Codex Desktop picker when the app runs against a remote server: Desktop filters the picker against its own available_models allowlist (active with the remote use_hidden_models setting), after the app-server has already loaded and served the routed catalog entries.
• Record the two workarounds: set model = "<provider>/<model>" directly in ~/.codex/config.toml (the picker may show Custom, but requests still route correctly), or use Codex CLI/TUI, which do not apply the allowlist.
• Sync the new section across zh-cn, ko, ru, and ja locales.

Why

• Tracks opencodex issue [Bug]: Routed models are loaded by Codex app-server but missing from Desktop model picker #241: routed models are loaded by the Codex app-server but missing from the Desktop model picker. The remaining filter lives in the Desktop client, not in this repository; no proxy-side change can populate that allowlist.
• Upstream bug: Codex Desktop model picker filters out models returned from model_catalog_json openai/codex#19694 (open). Related: /model does not list GPT-5.6 models that are available via -m openai/codex#31873.

Validation

• Docs-only change; no runtime code touched, so typecheck/test are unaffected.
• git diff --check clean; bun run privacy:scan passes.
• Local docs build could not complete: both bun install and npm install stall on the pretendard font tarball through the current network. CI docs build is the gate.

Summary by CodeRabbit

• Documentation
  • Added guidance for Codex Desktop remote-server model filtering.
  • Explained why routed models may appear in the model catalog or CLI but not in the Desktop model picker.
  • Documented workarounds, including selecting a model directly in remote configuration or using Codex CLI/TUI.
  • Added the guidance in English, Japanese, Korean, Russian, and Simplified Chinese.

[coderabbitai]

📝 Walkthrough

Walkthrough

The guides document Codex Desktop remote-server model filtering across English, Japanese, Korean, Russian, and Simplified Chinese. They describe the difference between Desktop and CLI/TUI model availability and provide configuration workarounds.

Changes

Desktop remote-server model documentation

Layer / File(s)	Summary
Document remote-server model filtering and workarounds docs-site/src/content/docs/guides/codex-app-models.md, docs-site/src/content/docs/{ja,ko,ru,zh-cn}/guides/codex-app-models.md	The guides explain available_models filtering, the continued availability of routed models through model/list and CLI/TUI, the upstream limitation, and direct config.toml configuration as a workaround.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: wibias, lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documented Codex Desktop remote allowlist limitation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d849dc631e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

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 👍 / 👎.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@docs-site/src/content/docs/guides/codex-app-models.md`:
- Around line 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 =
"<provider>/<model>", or use xai/grok-4.5 or cursor/grok-4.5 only
where that provider is configured.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bdb19f9d-03e6-4be0-bdad-457b230654cd

📥 Commits

Reviewing files that changed from the base of the PR and between e44d234 and d849dc6.

📒 Files selected for processing (5)

• 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

[coderabbitai]

🎯 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 =
"<provider>/<model>", or use xai/grok-4.5 or cursor/grok-4.5 only
where that provider is configured.

Source: Path instructions