›_ Codex Issues
Codex Issues / #21594

Feature request: model_aliases mapping for gateway model names to canonical Codex model metadata

Open 💬 4 comments Opened May 7, 2026 by dkbush
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI, IDE Extension

What feature would you like to see?

### Summary

Please add first-class support for model alias mapping in Codex config, so enterprise gateway model names can map to canonical Codex model IDs for metadata lookup.

### Problem

In enterprise environments, gateways often expose internal/public model names that reflect security tiers, environment boundaries, or compliance profiles (for example: gpt-5-3-codex-public). These names intentionally differ from canonical model IDs (for example: gpt-5.3-codex).

Today, this causes metadata lookup mismatches and warnings such as:

Model metadata for gpt-5-3-codex-public not found. Defaulting to fallback metadata; this can degrade performance and cause issues.

Workarounds exist (explicit metadata overrides in config.toml, or maintaining a custom model_catalog_json), but both add operational burden and drift risk for enterprise-managed installs.

### Requested feature

Add a config-level alias mapping mechanism, e.g.:

[model_aliases]
gpt-5-3-codex-public = "gpt-5.3-codex"
gpt-5-3-codex-il5 = "gpt-5.3-codex"
gpt-5-3-codex-il6 = "gpt-5.3-codex"

### Expected behavior

  1. If model matches an entry in model_aliases, Codex resolves metadata using the canonical mapped model ID.
  2. Alias resolution should work with custom providers (model_provider + [model_providers.<name>]).
  3. Keep precedence explicit and deterministic, ideally:
  • explicit per-model overrides in config (model_context_window, model_max_output_tokens, etc.)
  • then alias-resolved metadata
  • then fallback metadata
  1. Alias support should work across profile scopes / managed config use cases.
  2. Logs should clearly indicate alias resolution (for troubleshooting/auditability).

### Why this helps

  • Supports enterprise naming conventions without changing gateway public model names.
  • Reduces repetitive config workarounds across user/project/managed configs.
  • Avoids maintaining custom model catalogs just for naming translation.
  • Improves consistency for large deployments with multiple security-tiered aliases.

### Related context

Additional information

_No response_

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 3 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #21070

Powered by Codex Action

metrofun · 18 days ago

There is a useful workaround that reverses where the aliasing happens: keep the canonical identity inside Codex, and translate only at the gateway boundary.

Codex: gpt-5.3-codex
↓
route: gpt-5.3-codex
↓
enterprise gateway: gpt-5-3-codex-public

Codex therefore does its metadata lookup against gpt-5.3-codex, while the enterprise gateway still receives its required public/security-tier alias.

swobuforge/swobu) separates the client-visible route name from the backend model name, so this mapping doesn't require a custom model_catalog_json.

Native model_aliases would still be cleaner, especially for centrally managed Codex installs. But for gateways that can sit behind a local routing boundary, the naming mismatch does not need to leak back into Codex.

<img width="569" height="289" alt="Image" src="https://github.com/user-attachments/assets/deb60da4-5982-4315-8ea5-5f14456ae6a8" />

luoliwoshang · 16 days ago

I have the same underlying requirement, with a concrete case where separating the canonical model ID from the provider request ID would remove the need for a derived model_catalog_json.

My OpenAI-compatible gateway exposes these models:

openai-coding/codex-auto-review
openai-coding/gpt-5.4
openai-coding/gpt-5.4-mini
openai-coding/gpt-5.5
openai-coding/gpt-5.6-luna
openai-coding/gpt-5.6-sol
openai-coding/gpt-5.6-terra

They are the same models as their canonical Codex counterparts. Only the gateway-facing IDs are different. For example:

metadata/catalog model ID: gpt-5.6-sol
provider request model ID: openai-coding/gpt-5.6-sol

I want Codex to select gpt-5.6-sol and retain all of its built-in metadata, including supported reasoning efforts, context window, compaction limits, service tiers, instructions, and tool capabilities, while sending openai-coding/gpt-5.6-sol in the Responses API request.

My current workaround is to export selected bundled models and rewrite their slugs:

codex debug models --bundled |
  jq '
    [
      "codex-auto-review",
      "gpt-5.4",
      "gpt-5.4-mini",
      "gpt-5.5",
      "gpt-5.6-luna",
      "gpt-5.6-sol",
      "gpt-5.6-terra"
    ] as $wanted
    | {
        models: [
          .models[]
          | select(.slug as $slug | $wanted | index($slug))
          | .slug = ("openai-coding/" + .slug)
        ]
      }
  ' > "$HOME/.codex/fenno-model-catalog.json"

I then configure the namespaced model and generated catalog:

model_provider = "custom"
model = "openai-coding/gpt-5.6-sol"
model_catalog_json = "fenno-model-catalog.json"

[model_providers.custom]
name = "custom"
base_url = "https://example.com/v1"
wire_api = "responses"
requires_openai_auth = true

This works, but it makes me maintain a complete copy of model metadata just to translate request IDs. Whenever Codex adds a model or changes reasoning levels, context limits, service tiers, or other metadata, I need to regenerate the file. A stale catalog can silently miss new capabilities.

A provider-level outbound mapping would fit this case well. For example:

[model_providers.custom]
request_model_prefix = "openai-coding/"

or explicit mappings:

[model_providers.custom.model_mappings]
"gpt-5.4" = "openai-coding/gpt-5.4"
"gpt-5.4-mini" = "openai-coding/gpt-5.4-mini"
"gpt-5.5" = "openai-coding/gpt-5.5"
"gpt-5.6-luna" = "openai-coding/gpt-5.6-luna"
"gpt-5.6-sol" = "openai-coding/gpt-5.6-sol"
"gpt-5.6-terra" = "openai-coding/gpt-5.6-terra"
"codex-auto-review" = "openai-coding/codex-auto-review"

Ideally, this mapping would be applied consistently to normal turns, reviews, auto-review, subagents, automations, and other model requests, while model discovery and the picker continue to use canonical Codex IDs and built-in metadata.

If this feature sounds useful to the maintainers, I would be happy to help implement it.

luoliwoshang · 16 days ago

@etraut-openai, would you be willing to take a look at this use case and share whether provider-level outbound model mapping would be a reasonable direction for Codex?

The key requirement is to keep the canonical model ID inside Codex for model discovery, built-in metadata, reasoning levels, context limits, and capability checks, while translating the model ID only when constructing requests for a custom provider.

This would avoid maintaining a derived model_catalog_json solely to rename model IDs.

If the maintainers consider this direction appropriate, I would be happy to help implement it. Thank you!