Claude Code custom API base URL: what ANTHROPIC_BASE_URL really does

What ANTHROPIC_BASE_URL is, in one paragraph

Claude Code talks to api.anthropic.com by default. The official environment-variable reference describes ANTHROPIC_BASE_URL as a way to “override the API endpoint to route requests through a proxy or gateway.” When it is set, every request goes to the URL you give it instead. The request body, the streaming protocol, and the auth headers do not change; only the destination does. Whatever sits behind that URL just has to accept the same shape of request that Anthropic accepts.

For the CLI, the durable way to set it is the env block of your settings file, because that survives shell restarts and applies to every session:

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8766"
  }
}

For a one-off, an export before launching the CLI works just as well:

export ANTHROPIC_BASE_URL="http://127.0.0.1:8766"
claude

That is the whole “how.” If you want the longer setup walkthrough, with a minimal working proxy and the GitHub Copilot bridge pattern, there is a companion guide for that. This page is about the failure mode that guide does not dwell on.

The part every guide skips: the variable is frozen at spawn

Here is the mental model that fixes most ANTHROPIC_BASE_URL confusion. An environment is not a live channel. When the operating system creates a process, it hands that process a copy of the environment as it existed at that instant. The process keeps that copy for its entire life. Nothing you do in a shell afterward reaches back into a process that already started.

So the order of operations matters more than the value. Export the variable, then start claude: it works. Start claude, then export the variable in another tab: that running session never sees it. Put the variable in settings.json: Claude Code reads the file when it starts, so a new session picks it up, but a session that is already open does not re-read the file mid-run. Every one of these is the same rule with a different surface.

This is also why the variable behaves so differently for a terminal tool versus a desktop app. A terminal session inherits whatever your shell currently has. A macOS app launched from the Dock, Spotlight, or Finder inherits almost nothing from your shell, because ~/.zshrc only runs for interactive shells and LaunchServices never opens one. A custom endpoint exported in your shell can work perfectly for claude in a terminal and have literally zero effect on the same agent running inside an app.

Verify it instead of assuming it

You do not have to guess whether a process actually has the variable. On macOS and Linux, ps eww <pid> prints a process’s full environment. Grep it for the variable name and you get a definitive yes or no, with no detour through your shell:

How Fazm makes the restart invisible

Fazm is a native macOS app that wraps the real Claude Code agent loop. Because it is a GUI app, the “export in your shell” path does not exist for it at all. So the custom endpoint is handled entirely inside the app, in three short pieces of source you can read yourself.

The shape is worth noticing. A CLI user has to know that the environment is frozen at spawn, has to remember to restart the right process, and has to verify it landed. Fazm collapses all of that into a text field and one function call. You paste a URL; the subprocess that was holding the stale value is stopped, and the next one comes up with the new endpoint. The whole thing is readable at github.com/m13v/fazm.

One behavior change worth knowing: MCP tool search

This one is recent enough that most older write-ups miss it entirely. Setting a custom base URL does not only redirect traffic; it also flips a default. The official documentation states that when ANTHROPIC_BASE_URL is set to a non-first-party host, MCP tool search is disabled by default. If your proxy correctly forwards tool_reference blocks, you can turn it back on by also setting ENABLE_TOOL_SEARCH=true.

The practical takeaway: if you point Claude Code at a custom endpoint and then notice tool discovery behaving differently than it did on the default API, do not assume your proxy is broken. Check whether you need that toggle first. A custom endpoint is a configuration change with a side effect, not just a hostname swap, and this is the side effect.

Troubleshooting, by symptom

Almost every “ANTHROPIC_BASE_URL is not working” report comes down to one of five things. Match the symptom, not the theory.