Claude Code and ANTHROPIC_BASE_URL: routing the agent through a custom endpoint

The variable, and the three places it can live

ANTHROPIC_BASE_URL does one thing: it changes the host Claude Code talks to. Everything else, the agent loop, the tool surface, the prompts, the model selection, is unchanged. The official environment-variable reference is precise about scope: the variable is to “override the API endpoint to route requests through a proxy or gateway.” It does not carry a credential. It does not pick a model. It is the address, nothing more.

There are three supported places to set it. The simplest is the shell you launch claude from:

# shell profile (~/.zshrc, ~/.bashrc) or the current terminal
export ANTHROPIC_BASE_URL="YOUR_ENDPOINT_BASE_URL"
export ANTHROPIC_AUTH_TOKEN="YOUR_ENDPOINT_TOKEN"
claude

The second is ~/.claude/settings.json, which applies the value to every session and is the cleanest way to roll a gateway out to a whole team. The official docs note you can set these variables in settings.json under the env key to apply them to every session:

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "YOUR_ENDPOINT_BASE_URL",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_ENDPOINT_TOKEN"
  }
}

The third is process-level injection: whatever launches Claude Code puts the variable into the child process environment directly. That is how an editor extension or a desktop wrapper does it, and it is the case the rest of this page is about.

One nuance worth knowing before you ship a gateway to a team: the docs state that when ANTHROPIC_BASE_URL points at a non-first-party host, MCP tool search is disabled by default. Tool search relies on the upstream forwarding tool_reference blocks, and a proxy may strip them. If yours forwards them intact, you can turn it back on with ENABLE_TOOL_SEARCH=true.

The part the other guides skip: the variable is read once

Here is the failure mode that sends people in circles. You set ANTHROPIC_BASE_URL, you test it, it works. Later you change the URL, or you turn the gateway off, and Claude Code keeps hitting the old endpoint. You re-check your shell profile, your settings.json, everything looks right. Nothing is broken. The variable is just doing exactly what environment variables do.

Environment variables are copied into a process at the moment it is spawned. From that point the process holds its own private snapshot. Editing your shell profile, exporting a new value in another terminal, or rewriting settings.json does not reach into an already-running process. Claude Code reads ANTHROPIC_BASE_URL at startup and keeps that value until it exits. A change only takes effect on the next launch.

For the bare CLI that is mild: you quit and relaunch claude. For anything that runs Claude Code as a long-lived background process, it is the whole design problem. The host cannot just update a value; it has to tear down and respawn the child. Here is the sequence, including the step where an edit silently does nothing:

The red message is the one that costs people an afternoon. There is no error, no warning, no log line. The edit lands in a file or a shell, the running process keeps its old snapshot, and the only signal you get is that traffic is still hitting the host you thought you changed.

How a desktop wrapper wires the same variable

Fazm is a native macOS app I work on. It runs the real Claude Code agent loop, not a reimplementation, by speaking ACP (the Agent Client Protocol) to a Node bridge that owns the Claude Code process. Because the bridge spawns that process, it also owns the environment, which means a custom endpoint becomes a setting instead of a shell ritual. The source is MIT-licensed at github.com/m13v/fazm, so every claim below has a file and a line number.

// Desktop/Sources/Chat/ACPBridge.swift, line 527
// Custom API endpoint (allows proxying through Copilot,
// corporate gateways, etc.)
if let customEndpoint = defaults.string(forKey: "customApiEndpoint"),
   !customEndpoint.isEmpty {
  env["ANTHROPIC_BASE_URL"] = customEndpoint
}

The lifecycle problem from the previous section does not disappear, it gets handled. Editing the field or toggling it off calls a function named restartBridgeForEndpointChange() in ChatProvider.swift. It stops the ACP bridge so the next query respawns the Claude Code process with the updated environment. The code comment is blunt about why: “Stop the ACP bridge so it picks up the new custom API endpoint on next start.” That is the tear-down-and-respawn step that the red arrow in the diagram demands, done for you instead of left as a manual quit-and-relaunch.

So the practical difference is not magic. It is that the variable, the three-place configuration, and the mandatory restart are collapsed into one toggle. You type a URL, the host injects ANTHROPIC_BASE_URL and restarts the bridge; you clear the URL, it injects nothing and restarts again, back to the default API.

What the thing on the other end has to be

ANTHROPIC_BASE_URL only moves the address. It does not translate anything. Claude Code keeps speaking the Anthropic Messages API, so whatever answers at that address has to speak it too. That rules out pointing the variable straight at a plain OpenAI-style chat endpoint: the request shapes do not match, and you need a translation shim in between. The checklist for an endpoint that will actually work:

A corporate gateway built for Anthropic traffic, a regional endpoint, or a bridge that adapts another model into the Messages API all satisfy this. A local server such as LM Studio works once it is running an Anthropic-compatible API surface and has a model loaded. The variable does not care which of those it is; it just hands the request to the address and trusts the address to answer correctly.

When it breaks: reading the error from the right layer

A custom endpoint adds a layer, and the layer can fail on its own terms. The most confusing case is when the endpoint is reachable, so the connection succeeds, but the server behind it is not ready. With a local model server the classic version of this is an error that says, in effect, no models loaded, use the load command. That is not a Claude Code bug and not an Anthropic outage. The HTTP server answered; it just has nothing to serve yet.

Raw, that error reaches you as an opaque API failure and people blame the wrong layer. Fazm intercepts it. When a custom endpoint is configured, the bridge inspects the upstream error text and, if it sees markers like “no models loaded” or “lms load”, it rewrites the message into something actionable, along these lines:

Your custom API endpoint (<your endpoint>) reported no model
is loaded. Load a model in your local server (e.g. LM Studio ->
Developer -> Load Model), or turn off Custom API Endpoint in
Settings -> Advanced -> AI Chat to use Fazm's built-in Claude.

It does the same for connection-refused failures: if the endpoint is unreachable, the message names the endpoint and points you at the toggle to fall back to the default API. The logic is in the same ACPBridge.swift file, in the error path that runs only when customApiEndpoint is set. The principle generalizes whether or not you use a wrapper: when a custom endpoint misbehaves, separate the three layers before you debug.

Connection refused or DNS failure is a network or address problem, check the base URL. A 401 or 403 is a credential problem, check ANTHROPIC_AUTH_TOKEN against what the endpoint expects. A 400 about request shape, or an error mentioning no model, is the endpoint or the server behind it, not Claude Code. And if a change you made seems ignored entirely, it is the lifecycle gotcha: the process has not been restarted.