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.
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.
- 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.
- Chained calls. Ask for a change that requires reading, then editing, then verifying. This is where imprecise tool use surfaces.
- Long-session recall. After twenty or so turns, refer back to a decision made early without restating it. Watch whether it holds.
- 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.
- 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
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.