ANTHROPIC_BASE_URL tells Claude Code which host to send its API requests to. By default that is api.anthropic.com. Point it anywhere else (a company LLM gateway, a local compression proxy such as headroom) and Claude Code treats that host as the Claude API, but also turns a few features off on purpose.
How it works
You set the variable in your shell or in the env block of a settings file:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"
}
}Claude Code then sends every model request to that host in the Anthropic Messages format, with the same headers and fields it would send to Anthropic. The proxy is expected to forward them unchanged; one that strips or rewrites them breaks the matching features, sometimes with errors, sometimes silently (a proxy that drops cache markers, for example, makes every turn bill as uncached input).
Your subscription still applies
Setting only the base URL does not replace your login. If you also set a gateway credential (an API key, an auth token or an apiKeyHelper), requests carry that credential and are billed per token to its owner, outside your plan. Without one, Claude Code keeps sending your claude.ai login through the proxy, so your plan’s usage limits and billing apply as before.
What switches off
Whenever the base URL points at a host other than api.anthropic.com, whatever the proxy forwards:
- Remote Control (continuing a local session from the Claude app or claude.ai/code) is turned off. Unset the variable to use it.
- Server-managed settings from a Team or Enterprise admin stop applying.
- MCP tool search is off by default, because most proxies do not pass through the blocks it needs. Every MCP tool definition then loads at session start and stays in the context window.
ENABLE_TOOL_SEARCH=trueturns it back on; if the proxy cannot handle those blocks, requests then fail. - Fine-grained tool streaming and gateway hint headers are off by default; each has its own variable to turn it back on.
Some features work only if the proxy forwards requests intact to Anthropic, for example the Advisor. Fast mode’s availability check calls api.anthropic.com directly, not the proxy.
Switching it off for one session
Command-line settings take precedence over user settings in ~/.claude/settings.json. So you can keep the proxy as your default and skip it for one launch:
claude --settings '{"env":{"ANTHROPIC_BASE_URL":""}}' --remote-controlA shell function or alias around this gives you two entry points: the proxied default and a direct one for Remote Control.
Gotchas
- Check what you lost. If Remote Control fails or MCP tools seem to eat more context than before, check whether
ANTHROPIC_BASE_URLis set somewhere, including in a settings file a tool wrote for you. - Managed machines. An admin can pin the allowed base URL with
allowedProviders; Claude Code then refuses a session pointed at your own proxy.
Related
- headroom: a local compression proxy that uses this variable.
- MCP tool search: what you lose when it is off.
- Usage limits: which limits apply to proxied requests.
- Token-saving tools compared: where a proxy fits next to other tools.