Running Claude Code with Alternative Models: How the Endpoint Swap Works and What Breaks

Claude Code talks to an HTTP endpoint. That single fact is what makes alternative models possible at all: the tool is not hard-wired to one provider, it is wired to the Anthropic Messages API shape. Anything that can serve that shape convincingly can sit behind it.

What follows is how the swap actually works, which capabilities survive it, and a concrete way to tell whether a given model is usable for real work rather than just able to return a response.

How the swap works

Claude Code reads its endpoint and credentials from the environment. Point those two variables at a different base URL and the client sends the same requests somewhere else:

• ANTHROPIC_BASE_URL — the base address of the endpoint that will serve requests.
• ANTHROPIC_AUTH_TOKEN — the credential that endpoint accepts.

Set them in the shell that launches the tool, and every request goes to the new destination. Nothing else in the client changes. That is the whole mechanism, and it is why the interesting question is not can you swap, but what does the endpoint on the other side actually implement.

Two distinct things get called "alternative models" here, and they behave differently:

Anthropic models via a different route. The same model family, reached through a gateway, a cloud provider's hosted offering, or a relay endpoint. Behaviour is essentially unchanged, because the model is the same; what changes is billing, latency, and availability.

A different model family behind a translation layer. A non-Anthropic model wrapped so it accepts Messages API requests. Here the request shape matches but the model underneath does not share Claude's training on the agentic loop, and that is where the real differences appear.

Which routes are actually available

The first category above is not open-ended. Anthropic documents a specific set of deployment routes, and every one of them runs Claude models — what changes is where inference happens and who bills you:

• Amazon Bedrock — AWS-native deployment, paid through AWS.
• Claude Platform on AWS — AWS Marketplace billing, with Claude API features available.
• Google Cloud's Agent Platform — formerly Vertex AI; GCP-native, paid through GCP.
• Microsoft Foundry — Azure-native, paid through Azure.
• An LLM gateway in front of any of the above, when you need centralised authentication, usage tracking across teams, or per-team budgets.

Each cloud route has its own base URL variable for when a gateway sits in front of it — ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_AWS_BASE_URL, ANTHROPIC_VERTEX_BASE_URL and ANTHROPIC_FOUNDRY_BASE_URL — alongside the generic ANTHROPIC_BASE_URL used above. A corporate HTTP proxy is a separate layer that stacks with any of them, configured through HTTPS_PROXY.

On the cloud routes, pin model versions explicitly with ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL. Without pinning, the aliases resolve to a built-in default for that provider, which can lag the newest release or point at a model your account has not enabled yet.

To confirm which provider, base URL and proxy a session is actually using, run /status inside Claude Code. That single check settles the "is it even routing where I think it is" question before you start debugging the model itself.

The second category — a non-Claude model behind a translation layer — has no equivalent published list. It is reached through the generic base URL variable, and what you get depends entirely on how faithfully that layer implements the Messages API. Which is what the rest of this article is about.

What survives the swap, and what does not

Ranked by how often it breaks in practice:

Tool use is the first thing to check. Claude Code is an agentic loop — it reads files, runs commands, and edits code by calling tools in sequence. A model that supports tool calling in principle but is imprecise about it produces a loop that stalls, retries, or issues malformed calls. This is the most common reason an alternative model is technically connected but practically unusable.

Long context matters more than headline benchmarks. Real sessions accumulate file contents, command output, and prior turns. A model with a large stated window that degrades in the second half of it will feel fine for ten minutes and then start losing track of earlier decisions.

Prompt caching is a billing question, not a capability question — until it is missing. Agentic sessions resend a large, stable prefix on every turn. Endpoints without cache support bill the full prefix each time, which can dominate the cost of a long session.

System prompt handling varies. Claude Code sends substantial system instructions. Translation layers sometimes concatenate, truncate, or reorder them, and the symptom is a model that ignores project conventions it was clearly told about.

Streaming and stop behaviour. Partial or non-standard streaming shows up as output that appears in bursts, or a loop that does not recognise completion.

A five-check acceptance pass

Run these before trusting an alternative model with real work. Each one isolates a failure mode above.

1. Single tool call. Ask it to read one specific file and report a fact from it. If the call is malformed or skipped, stop here.
2. Chained calls. Ask for a change that requires reading, then editing, then verifying. This is where imprecise tool use surfaces.
3. Long-session recall. After twenty or so turns, refer back to a decision made early without restating it. Watch whether it holds.
4. Cost per turn. Compare the billed input tokens on turn one against turn ten. A flat, large number on every turn means no caching is in effect.
5. Failure behaviour. Give it a command that errors. A usable model reads the error and adapts; a poor fit repeats the same call.

A model that clears all five is usable. A model that clears one and two only is fine for short, well-scoped edits and will frustrate on anything longer.

When not to swap

If the reason for switching is cost, compare against caching-aware pricing first — a cached Anthropic session can cost less than an uncached cheaper model, because the prefix dominates. Claude API pricing covers what actually drives the bill.

If the reason is access rather than model preference, the endpoint is the variable, not the model. Routing to the same model through a different endpoint keeps behaviour identical and solves the access problem on its own — the routes are compared in using Claude Code from China.

If the work is agentic and long-running, the tolerance for imprecise tool use is low, and a cheaper model that stalls the loop is not cheaper.

Frequently asked questions

Which providers can Claude Code officially route to?

Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform (formerly Vertex AI) and Microsoft Foundry, optionally behind an LLM gateway. All four serve Claude models. Pointing the client at a non-Claude model is done through the generic ANTHROPIC_BASE_URL variable and is not one of the documented provider routes.

Can Claude Code use models other than Claude?

Yes, provided the endpoint it points at serves the Anthropic Messages API shape. The client does not enforce which model is behind that endpoint; the practical limits come from how well the model handles tool calling and long context.

How do I point Claude Code at a different endpoint?

Set ANTHROPIC_BASE_URL to the endpoint's base address and ANTHROPIC_AUTH_TOKEN to a credential it accepts, in the shell that launches the tool.

Why does an alternative model connect but fail to do anything useful?

Almost always tool calling. Serving the request shape is easy; issuing well-formed, correctly sequenced tool calls across a long loop is not.

Does switching models save money?

Sometimes, and less often than expected. Agentic sessions resend a large stable prefix, so an endpoint with prompt caching frequently beats a nominally cheaper one without it.

Will an alternative model behave identically?

No. Identical behaviour only holds when the same model is reached through a different route. A different model family behind a translation layer matches the interface, not the behaviour.