[Feature] Add model-specific upstream provider routing for Vercel AI Gateway

[yongs3]

Area

Provider adapters

What are you trying to accomplish?

I want to route a model exposed through the vercel-ai-gateway provider to a specific underlying inference provider.

For example, zai/glm-5.2 is available through multiple upstream providers. I need to pin it to one provider, define an ordered preference list, or select providers by cost/latency/throughput while continuing to use Vercel AI Gateway for authentication, billing, observability, and fallback.

OpenCodex already supports the equivalent workflow for OpenRouter through provider-wide openRouterRouting and model-specific modelOpenRouterRouting.

What prevents this today?

Vercel AI Gateway supports request-scoped provider filtering and ordering, but OpenCodex does not currently expose or forward those options for a vercel-ai-gateway configuration.

Vercel documents:

• order: preferred provider order
• only: restrict routing to an allowed provider set
• sort: rank providers by cost, ttft, or tps
• providerOptions in the REST / OpenAI-compatible API
• a top-level provider shorthand in the Chat Completions API

The existing OpenRouter routing configuration cannot be reused as a workaround because OpenCodex intentionally validates it against the canonical https://openrouter.ai/api/v1 endpoint and only emits the OpenRouter request payload for that target.

The Vercel dashboard also does not provide an equivalent persistent per-model routing choice for this OpenCodex workflow.

What should OpenCodex do?

OpenCodex should allow provider-wide and exact model-specific Vercel AI Gateway routing preferences.

Observable behavior:

1. A user can restrict a Vercel-routed model to one or more underlying provider slugs.
2. A user can define the order in which eligible providers are attempted.
3. A user can optionally sort eligible providers by cost, ttft, or tps.
4. Model-specific settings override provider-wide defaults.
5. Requests without these settings preserve Vercel's current dynamic routing behavior.
6. The preferences are forwarded using Vercel's documented OpenAI-compatible request shape.

Example usage or interface

The exact configuration names are only illustrative, but a configuration parallel to the existing OpenRouter fields would make the behavior clear:

{
  "providers": {
    "vercel-ai-gateway": {
      "adapter": "openai-chat",
      "baseUrl": "https://ai-gateway.vercel.sh/v1",
      "vercelGatewayRouting": {
        "sort": "ttft"
      },
      "modelVercelGatewayRouting": {
        "zai/glm-5.2": {
          "only": ["novita"],
          "order": ["novita"]
        }
      }
    }
  }
}

A preference list with restricted fallback could look like:

{
  "modelVercelGatewayRouting": {
    "zai/glm-5.2": {
      "only": ["novita", "deepinfra"],
      "order": ["deepinfra", "novita"]
    }
  }
}

For the OpenAI-compatible Chat Completions wire, the resulting request could use Vercel's documented shorthand:

{
  "model": "zai/glm-5.2",
  "provider": {
    "only": ["novita"],
    "order": ["novita"]
  }
}

Alternatives or workarounds

• Accept Vercel's dynamic provider selection.
• Configure the upstream provider directly in OpenCodex, which loses Vercel AI Gateway billing, observability, and centralized credentials.
• Patch the openai-chat adapter locally to add a provider or providerOptions request field.
• Use OpenRouter instead, where OpenCodex already supports provider-level routing preferences.

None provides the requested Vercel AI Gateway workflow without giving up gateway functionality or maintaining a local patch.

Additional context

• OpenCodex version observed: 2.11.1
• Vercel Provider Options: https://vercel.com/docs/ai-gateway/models-and-providers/provider-options
• Vercel Provider Filtering, Ordering & Sorting: https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering
• Vercel documents that REST/OpenAI-compatible requests accept providerOptions, and Chat Completions also accepts the top-level provider shorthand.
• Existing OpenRouter implementation: src/providers/openrouter-routing.ts and the openai-chat adapter's OpenRouter request-body injection.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[Ingwannu]

Confirmed as a real missing capability on current dev. OpenCodex only validates and emits openRouterRouting / modelOpenRouterRouting; the canonical Vercel AI Gateway preset has no equivalent path, even though Vercel documents provider filtering, ordering, and cost / ttft / tps sorting.

This direction is valuable, with these implementation boundaries:

• use Vercel-specific provider-wide defaults plus exact native-model-id overrides; do not reuse or weaken the canonical OpenRouter gate;
• validate the fields strictly and accept them only for the canonical Vercel gateway with openai-chat;
• preserve Vercel's dynamic routing when no preference is configured;
• emit only the request shape documented for the actual OpenAI-compatible endpoint/transport being used;
• cover provider-wide defaults, exact model replacement, sibling-model isolation, invalid fields, and unchanged requests without configuration;
• document the accepted provider slug and sorting semantics from Vercel's primary documentation.

A focused PR following that contract would be reviewable. Keeping the issue open for implementation.