Codex Model Picker

简体中文

An experimental Windows launcher that detects visible local catalog models missing from the Codex Desktop frontend allowlist and switches to catalog-driven model visibility only when needed.

This project does not grant model access, modify the Codex installation, or include any Codex/OpenAI binaries.

Requirements

• Windows 10 or 11.
• The Codex Desktop app installed through its normal distribution channel.
• A working Codex configuration with model_catalog_json.
• The target models must already work through the configured provider and Codex CLI/app-server.

Quick Start

1. Download codex-model-picker-win-x64.zip from GitHub Releases.
2. Extract the entire archive to a stable folder.
3. Fully quit Codex Desktop from the system tray.
4. Double-click Launch.cmd.
5. Optionally run Doctor.cmd to verify the runtime hook and model menu.

Install.cmd creates a desktop shortcut pointing to the extracted folder. Keep that folder in place after installing the shortcut.

Configuration

The launcher first reads:

%LOCALAPPDATA%\CodexModelPicker\config.json

The default Codex home is %USERPROFILE%\.codex. Set CODEX_HOME or codexHome when Codex uses another location. If catalogPath is absent, the launcher reads model_catalog_json from the detected config.toml.

Example:

{
  "codexHome": null,
  "codexConfigPath": null,
  "codexAppPath": null,
  "catalogPath": null,
  "expectedModels": ["gpt-custom-a", "gpt-custom-b"],
  "requireAllExpectedVisible": false
}

• codexHome: optional custom Codex configuration directory.
• codexConfigPath: optional direct path to config.toml.
• codexAppPath: optional direct path to ChatGPT.exe or its install folder.
• catalogPath: optional explicit model catalog path.
• expectedModels: optional slugs checked by Doctor.cmd. Empty means the non-hidden catalog models. Both hidden: true and visibility: "hide" are recognized.
• requireAllExpectedVisible: require every expected item to fit in the current viewport. Leave false for long, scrollable model lists.

Environment equivalents are CODEX_HOME, CODEX_CONFIG_PATH, CODEX_MODEL_CATALOG, and CODEX_DESKTOP_PATH. Paths support %VAR%, ${VAR}, and ~.

Never put API keys in this project configuration.

How It Works

The launcher starts Codex Desktop with a random loopback DevTools port. Before the renderer loads, it hooks the existing Statsig override adapter and finds the model-picker dynamic config by structure, not by a hardcoded config ID. It compares non-hidden local catalog models with the original remote allowlist. If none are missing, it leaves the config unchanged. Otherwise, it switches to the verified catalog-driven mode and records the missing models as bypassedModels.

Current Codex builds do not safely accept custom-catalog models merged back into available_models; that path was tested and left the UI on its loading screen. Catalog-driven mode therefore relaxes the frontend allowlist as a whole. Use a filtered catalog, or the catalog's hidden-model mechanism, to control the final visible set.

If multiple matching configs are found, the launcher removes the injection and reloads the normal page. The first candidate may be overridden briefly while the complete config list is being checked. Failed hooks are removed and the normal page is reloaded.

This detects a frontend allowlist difference. It does not query or prove model access at a custom provider. A model must exist in the local catalog and already work with the configured provider.

See docs/how-it-works.md for details.

Security

• The DevTools endpoint binds to loopback and remains available until Codex exits. Other processes on the same machine may be able to inspect it.
• The project does not patch files under WindowsApps.
• The project does not disable antivirus software or add exclusions.
• The project does not bypass provider permissions or account entitlements.
• App updates can change the frontend integration and require a project update.
• Compatibility with every future Codex build or custom proxy cannot be guaranteed. Multi-source discovery and fail-closed checks reduce risk; they do not create a universal compatibility contract.

Read SECURITY.md before redistribution.

Development

npm test
npm run check
node src/launcher.mjs --doctor --no-wait

Create a local portable ZIP:

npm run package:windows

Status

Verified locally with Codex Desktop 26.707.3748.0. Compatibility is checked at runtime; this is not an official OpenAI project.