"You Don't Need Matching Model Names to Run AI Coding Tools"

I ran into a boring problem that kept wasting real time:

my coding tool said gpt-5.5, my provider said the deployment was called something else, and suddenly I was debugging configuration instead of code.

Not model quality. Not prompts. Not token limits.

Just names.

The mismatch that keeps showing up

A lot of AI tooling quietly assumes this:

tool model name == provider model name == provider deployment name

That is a nice fantasy.

It falls apart the moment you use:

• Azure OpenAI deployments
• provider-specific aliases
• internal model mapping
• multiple CLI tools that all expect different protocol surfaces

One tool wants gpt-5.5.

Your provider may expose:

model: gpt-5.5
deployment: team-codex-prod

or:

model: claude-sonnet-4-6
upstream target: vertex publisher endpoint

or:

requested model: claude-sonnet-4-6
actual target: gpt-5.4-mini

The names are not the same, and they do not need to be.

The part that annoyed me most

The worst failures were the confusing ones.

The request did not always hard-fail.

Sometimes the tool UI said one thing, the proxy logs said another thing, and the actual upstream target depended on one more layer hidden in provider config.

So you end up asking questions like:

• Is this model being mapped by tier?
• Is it passed through because it already looks native?
• Is the provider overriding it with a deployment name anyway?
• Is the UI showing a discovered model that the mapping page cannot even configure yet?

That is too much ceremony for "send this prompt to the model I meant."

What I changed

I stopped letting the tools own the final name resolution.

I put the decision inside a local gateway.

In CliGate, the flow looks more like this:

Claude Code / Codex CLI / Gemini CLI
        |
        v
     localhost
        |
        +-> routing
        +-> model mapping
        +-> provider translation
        +-> deployment override if needed
        |
        v
   actual upstream target

That means the tool can keep asking for the model name it understands, while the gateway decides what the provider should really receive.

Why this matters more on Azure

Azure OpenAI is where this gets obvious fast.

With Azure, there are usually at least two identities in play:

1. the model name the client thinks it wants
2. the deployment name Azure actually expects

If your bridge code forwards the requested model directly, but the provider later replaces it with:

model: this.deploymentName || body.model

then the real runtime behavior depends on the deployment config, not the string the CLI showed you.

That is not wrong.

It just means you need better visibility and a better configuration surface.

The fix is not "make every name identical"

I do not think the right answer is forcing every tool, provider, and deployment to share the same label.

That breaks down as soon as:

• one provider requires deployment indirection
• another provider wants a publisher-specific route
• a third provider can only support a tier-mapped equivalent

The better rule is:

let the tool ask for a logical model, and let the gateway resolve the physical target

That is what model mapping should be doing.

The two things I actually needed

After working through this, I realized the UI had to support both:

1. discovered models

If the provider can list available models, show them.

That makes it easy to pick things like gpt-5.5 when the upstream already advertises them.

2. manual model or deployment entry

If the provider uses a deployment name that is not auto-discovered the way the UI expects, I still need to type it manually.

This matters a lot for provider bridges where:

• the useful identifier is a deployment, not a catalog model ID
• discovery can lag behind reality
• the operational name is local to one account or tenant

If the UI only gives me a fixed dropdown, it is pretending the ecosystem is cleaner than it is.

What I changed in my own setup

I updated the model mapping flow so it now:

• returns discovered provider models through the model-mapping API
• merges discovered models with static mapping candidates
• allows manual entry instead of forcing a dropdown-only selection

So the configuration step is no longer:

"pick from whatever the UI happened to preload"

It is:

"pick a discovered model or type the real deployment/model name you actually use"

That is a much more honest interface.

The boring but important engineering lesson

I think a lot of AI infra bugs come from mixing up three different concepts:

• display name in the tool
• logical model ID used for routing
• physical upstream target used at the provider edge

When those three collapse into one string, everything feels simple.

When they do not, you need explicit mapping and explicit logs.

Otherwise you get the classic failure mode:

UI says one thing
logs say one thing
provider actually runs something else

That is not really a model problem.

It is an observability problem.

If you're building local AI tooling, I would strongly recommend this split

Do not let every CLI client carry your provider-specific naming quirks.

Let them speak in the model vocabulary they already know.

Then keep the messy parts in one place:

• routing
• provider adaptation
• deployment overrides
• request logs
• model mapping UI

That design has held up much better for me than trying to force the whole stack to agree on one shared name.

Repo:

CliGate on GitHub

How are you handling this right now?

Are you keeping model names and deployment names identical on purpose, or are you hiding the mismatch behind a gateway too?