[Feature]: add per-model service_tier overrides #1086

Area

Proxy and routing / Dashboard / model configuration

Current status

This request is partially implemented.

Current dev already supports a global tri-state fast/service-tier setting:

Auto
Default
Priority

Conceptually:

Auto     -> preserve the client's service_tier behavior
Default  -> remove/disable priority service tier
Priority -> force service_tier: "priority"

The active global setting is applied on each request, so an operator can change it without stopping the current Codex session.

Service-tier handling is also capability-gated.

Only providers that explicitly support:

supportsServiceTier: true

may receive the OpenAI-style service_tier field.

Providers that do not support it must remain protected from accidental injection.

The remaining feature tracked here is therefore per-model service-tier override policy.

Goal

Allow different routed models to use different service-tier behavior while preserving the existing global setting as the fallback.

For example:

gpt-5.6-sol       -> Priority
gpt-5.6-luna      -> Auto
gpt-5.6-terra     -> Default
other models      -> use global setting

Changing one model's override should affect subsequent requests using that model without requiring the user to restart or interrupt the active Codex session.

Desired configuration contract

Add an optional per-model override map with three states:

auto
default
priority

Conceptually:

{
  "fastMode": null,
  "serviceTierByModel": {
    "openai/gpt-5.6-sol": "priority",
    "openai/gpt-5.6-luna": "auto",
    "openai/gpt-5.6-terra": "default"
  }
}

The exact public configuration key can follow existing naming conventions.

Precedence

Resolve service tier only after the final provider/model route is known.

Suggested precedence:

explicit per-model override
        ↓
global OpenCodex fastMode/service-tier setting
        ↓
client-supplied service_tier / Auto behavior

The provider capability gate remains authoritative after policy resolution.

Conceptually:

resolve final route/model
        ↓
resolve per-model/global desired tier
        ↓
check provider supportsServiceTier
        ↓
apply or strip service_tier safely

A per-model override must never bypass provider capability metadata.

Model identity

Overrides should key against a stable OpenCodex routed model identity.

Do not accidentally apply an override to another provider merely because both expose the same upstream model name.

For example:

provider-a/gpt-x
provider-b/gpt-x

must be independently configurable.

If flattened aliases and raw namespaced IDs can refer to the same routed model, normalize them to one canonical identity before lookup rather than maintaining conflicting override entries.

Dashboard behavior

Expose service tier alongside the existing model-level controls.

For each eligible model:

Service tier
[ Auto ▾ ]

with:

Auto
Default
Priority

The UI should make clear when:

• a model has an explicit override;
• the model inherits the global setting;
• the selected provider does not support service tier.

For unsupported providers/models, do not offer a control that appears functional.

A disabled state such as:

Service tier
Not supported by this provider

is preferable to silently ignoring the user's selection.

CLI / management API

Provide an equivalent non-GUI management surface.

The exact command can follow existing configuration conventions, but users should be able to:

• inspect the effective override;
• set auto;
• set default;
• set priority;
• clear the model override so it inherits global behavior.

Management API updates should support partial mutation without replacing unrelated model overrides.

Runtime behavior

The override must be evaluated for each request after routing has resolved the final model.

Changing an override while OpenCodex is running should therefore affect the next applicable request.

It must not require:

• proxy restart;
• Codex restart;
• restarting the active conversation.

Existing in-flight requests must not change behavior midway through delivery.

Capability safety

The existing:

supportsServiceTier

contract remains authoritative.

Supported provider

For:

supportsServiceTier: true

the resolved model policy may produce:

service_tier: "priority"

or explicitly remove priority behavior.

Unsupported provider

For:

supportsServiceTier: false

OpenCodex must not inject service_tier, even if stale configuration contains a per-model priority override.

The GUI/API should expose that the override is currently inapplicable.

Unknown/custom provider

Do not infer service-tier support purely from:

• adapter type;
• model name;
• compatibility with /v1/responses.

Use the existing capability policy.

Debugging / observability

The request debugging surface should distinguish:

client service tier
global override
per-model override
effective service tier
provider capability

without logging sensitive request data.

For example:

requested: auto
global: default
model override: priority
effective: priority
source: model_override

If the provider rejects service-tier support through its capability metadata:

model override: priority
effective: omitted
reason: provider_unsupported

The visual treatment can follow the existing reasoning/effort override presentation.

Existing delivered behavior

The following should not be reimplemented as part of this issue:

• global tri-state fast/service-tier control;
• request-time global setting updates;
• provider supportsServiceTier capability gating;
• stripping the field from known unsupported providers.

Those are existing foundations.

Out of scope

This issue does not require:

• inventing service-tier support for providers that do not expose it;
• translating priority into provider-specific proprietary speed controls;
• changing reasoning-effort overrides;
• changing model routing selection;
• changing billing/cost estimation behavior.

Provider-specific equivalents to OpenAI service_tier should be designed separately unless they share a proven common contract.

Acceptance criteria

• Global Auto / Default / Priority service-tier behavior exists.
• Global changes can affect subsequent requests without session restart.
• Service-tier injection is capability-gated.
• A per-model override map exists.
• Per-model values support Auto, Default, and Priority.
• Models without an explicit override inherit the global behavior.
• Overrides are resolved only after the final provider/model route is known.
• Overrides use canonical provider/model identity.
• A model override cannot bypass supportsServiceTier.
• Unsupported providers clearly expose that service tier is unavailable.
• Dashboard users can inspect, set, and clear model overrides.
• CLI/API users can inspect, set, and clear model overrides.
• Changing a model override affects subsequent requests without restarting OpenCodex or Codex.
• In-flight requests retain the policy with which they started.
• Debugging surfaces identify the effective tier and override source.
• Regression tests cover global fallback, explicit model overrides, unsupported providers, and runtime setting changes.
• Accepted implementation is merged into dev.

Related work

• fix(codex): honor tri-state fastMode in Codex config injection #1022 — global tri-state fastMode foundation.
• fix(responses): gate service tiers by provider capability #860 / later provider capability work — supportsServiceTier safety boundary.