Claude Code configuration reference

Claude Code LLM gateway: ANTHROPIC_BASE_URL, from the official docs

A gateway sits between Claude Code and the model: one place for auth, usage tracking, budgets, and provider routing. The whole connection comes down to one environment variable and a credential. Here is the exact reference, verified against Anthropic’s docs, and then the part those docs skip: how the same setting works when Claude Code runs inside a GUI, and the three things a wrapper handles that a raw export does not.

Matthew Diakonov, Written with AI

Published June 22, 20268 min read

Direct answer (verified 2026-06-22)

Point Claude Code at a gateway by setting ANTHROPIC_BASE_URL to a gateway that speaks the Anthropic Messages format, then authenticate with ANTHROPIC_AUTH_TOKEN (sent as a bearer Authorization header) or ANTHROPIC_API_KEY (sent as x-api-key when no auth token is set). To surface the gateway’s own models in the picker, also set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129 or later).

Source: code.claude.com/docs/en/llm-gateway

The variables that matter

Most of the gateway integration guides online bury this in a wall of provider-specific YAML. Stripped down, the Anthropic Messages path is five variables, and you only ever need the first two to get traffic flowing.

Variable	What it does	Notes
`ANTHROPIC_BASE_URL`	The gateway URL itself	Point it at a gateway that exposes the Anthropic Messages format (/v1/messages, /v1/messages/count_tokens). This is the one variable that does the routing.
`ANTHROPIC_AUTH_TOKEN`	Auth, sent as a bearer header	When set, its value is sent as the Authorization header. This is the preferred path for most gateways (LiteLLM static keys, JWTs, vault-issued tokens).
`ANTHROPIC_API_KEY`	Auth, sent as x-api-key	Used as the x-api-key header when no ANTHROPIC_AUTH_TOKEN is set. Lower precedence than the auth token.
`ANTHROPIC_CUSTOM_HEADERS`	Extra headers on every request	Forwarded on both inference and the model-discovery request. Use it for tenant IDs, team tags, or anything your proxy keys on.
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	Pull the gateway's model list	Set to 1 to have Claude Code query the gateway's /v1/models at startup and add entries to the /model picker. Off by default. Requires Claude Code v2.1.129 or later.

For Bedrock or Vertex you swap to ANTHROPIC_BEDROCK_BASE_URL / CLAUDE_CODE_USE_BEDROCK=1 or ANTHROPIC_VERTEX_BASE_URL / CLAUDE_CODE_USE_VERTEX=1. Those are pass-through endpoints and do not run model discovery; the docs cover each in full.

What your gateway has to be

ANTHROPIC_BASE_URL is not a magic adapter. The thing on the other end has to talk Anthropic. If you point it at a bare OpenAI-compatible server with no translation layer, requests fail. The minimum bar for the Anthropic Messages path:

Anthropic Messages gateway checklist

Exposes the Anthropic Messages format: /v1/messages and /v1/messages/count_tokens
Forwards the anthropic-beta and anthropic-version request headers unchanged
Speaks Anthropic's wire format, not a raw OpenAI or Gemini key endpoint
Optionally implements /v1/models if you want the model picker populated

The terminal path, step by step

This is the canonical flow from the docs, using LiteLLM’s unified endpoint as the example because it is the one Anthropic itself recommends over the per-provider pass-throughs (load balancing, fallbacks, consistent cost tracking).

Export the base URL

Set ANTHROPIC_BASE_URL to your gateway. For LiteLLM's unified endpoint the docs use a bare host and port, no path (for example, your LiteLLM server on port 4000).

export ANTHROPIC_BASE_URL=<your-gateway-host>:4000

Hand it a token

Set ANTHROPIC_AUTH_TOKEN so it rides as the Authorization header. A static key is fine to start; rotate to an apiKeyHelper script later.

export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

Optionally turn on model discovery

If you want the gateway's models in the /model picker instead of the built-in list, opt in. This needs Claude Code v2.1.129 or later, and only IDs starting with claude or anthropic are added.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

Launch and confirm

Start Claude Code. Discovered models are labeled From gateway in the picker, and the list is cached to ~/.claude/cache/gateway-models.json so a momentary gateway hiccup at startup does not blank your picker.

The same setting, without the shell

Every guide on this assumes you are in a terminal editing a shell profile or settings.json. That is fine until you are running Claude Code inside a desktop app. Fazm wraps the real Claude Code agent loop over the Agent Client Protocol, and it surfaces this entire configuration as one input: Settings → Advanced → AI Chat → Custom API Endpoint. Type a URL there, and the bridge sets ANTHROPIC_BASE_URL for the underlying agent. The field placeholder hints at the expected shape: a full https:// URL with a host and port for your proxy.

What is worth reading, and what no gateway doc covers, is the three things the open-source bridge does around that one field. You can read the exact code in the Fazm repo (ACPBridge.swift).

1. It validates the URL before it can brick chat

The classic failure mode: you type localhost:8766 with no scheme, it lands in ANTHROPIC_BASE_URL, and the Anthropic SDK throws API Error: Invalid URL on every request. The bridge runs the value through validCustomAPIEndpoint, which requires an http or https scheme and a non-empty host. Fail that check and Fazm logs the bad value and falls back to the default Anthropic endpoint, so a typo degrades to working chat instead of a silently broken one.

2. It never hands your proxy Anthropic’s real key

When a custom endpoint is set, the bridge stops sending its built-in Anthropic key and substitutes a placeholder, ANTHROPIC_API_KEY=sk-fazm-custom-endpoint. That keeps Anthropic-compatible local gateways (LM Studio, Ollama bridges, corporate proxies) on the API-key path instead of kicking off a Claude OAuth flow they cannot finish. Your gateway, not Anthropic, decides what credential it actually wants, and the usage does not draw down Fazm’s built-in credits.

3. It warns you that the override is Claude-only

ANTHROPIC_BASE_URL only routes Anthropic-format traffic, so Gemini and Codex models bypass the gateway completely. In raw Claude Code that is silent, and you stare at a gateway logging zero requests. Fazm checks the active model: if it is not a Claude model, Settings shows a warning that the endpoint does not apply and offers a one-click Switch to a Claude model button, because the default model for new users is not a Claude model and the endpoint would otherwise do nothing.

Two ways to set the same thing

Identical result on the wire. The difference is what you maintain and what happens when you get it wrong.

You edit a shell profile or settings.json, export ANTHROPIC_BASE_URL plus a token, and remember to re-source it. A missing scheme bricks chat with Invalid URL and no hint why. A non-Claude model silently bypasses the endpoint.

Lives in your shell profile or settings.json
Malformed URL throws Invalid URL on every request
No warning when the model bypasses the gateway

Routing Claude Code through a gateway and want the GUI path?

Walk through pointing Fazm at your LiteLLM, corporate proxy, or local Anthropic-compatible server, and the model-routing gotchas, on a quick call.

Frequently asked questions

How do you point Claude Code at an LLM gateway?

Set ANTHROPIC_BASE_URL to your gateway URL, where the gateway exposes the Anthropic Messages format (/v1/messages and /v1/messages/count_tokens). Authenticate with ANTHROPIC_AUTH_TOKEN, which is sent as the Authorization header, or ANTHROPIC_API_KEY, which is sent as the x-api-key header when no auth token is set. That is the whole minimum. Everything else (model discovery, custom headers, pass-through endpoints) is optional. The official reference is at code.claude.com/docs/en/llm-gateway.

What is the difference between ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY?

They do different jobs. ANTHROPIC_BASE_URL changes where requests go: instead of api.anthropic.com, they go to your gateway. ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) changes how the request authenticates. ANTHROPIC_AUTH_TOKEN is sent as a bearer Authorization header and takes precedence; ANTHROPIC_API_KEY is sent as x-api-key when no auth token is present. Most gateways want the auth token. You almost always set the base URL and one of the two credential variables together.

Does ANTHROPIC_BASE_URL alone show the gateway's models in Claude Code?

No. By default Claude Code uses the standard model names for the API format and does not query your gateway for its model list. To pull the list you also set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, which makes Claude Code call the gateway's /v1/models endpoint at startup and add the results to the /model picker, each labeled From gateway. Discovery is off by default so a gateway backed by a shared key does not surface every model that key can reach to every user. It requires Claude Code v2.1.129 or later, and only models whose ID begins with claude or anthropic are added.

What does the gateway have to support for Claude Code to work?

Per the official docs the gateway must expose at least one of three API formats: Anthropic Messages (/v1/messages, /v1/messages/count_tokens), Bedrock InvokeModel, or Vertex rawPredict. For the Anthropic Messages path it must forward the anthropic-beta and anthropic-version request headers. If those headers are dropped you get reduced functionality or features that refuse to run. A raw OpenAI-key or Gemini-key endpoint does not satisfy this; the gateway has to speak Anthropic's wire format.

Can I set ANTHROPIC_BASE_URL without using a terminal?

Yes, if you run Claude Code through a GUI host. Fazm wraps the real Claude Code agent loop over the Agent Client Protocol and exposes a single Custom API Endpoint field under Settings, Advanced, AI Chat. Whatever you type there becomes ANTHROPIC_BASE_URL for the underlying agent. You never touch a shell profile or settings.json. The field is the same lever the docs describe, surfaced as one input.

Why does a bad gateway URL sometimes break Claude Code chat entirely?

Because a malformed value still lands in ANTHROPIC_BASE_URL, and then the Anthropic SDK throws API Error: Invalid URL on every request. A value like localhost:8766 with no scheme is the classic trap. Fazm guards against this: its bridge runs the value through validCustomAPIEndpoint, which requires an http or https scheme and a non-empty host. If the value fails that check, Fazm logs it and falls back to the default Anthropic endpoint instead of bricking chat. The protection lives in the open-source ACPBridge, not in raw Claude Code.

Will my gateway receive Anthropic's real API key?

Not from Fazm. When you set a custom endpoint, Fazm explicitly stops sending its built-in Anthropic key to your proxy and substitutes a harmless placeholder, ANTHROPIC_API_KEY=sk-fazm-custom-endpoint. That keeps Anthropic-compatible local gateways (LM Studio, Ollama bridges, corporate proxies) on the API-key path instead of triggering a Claude OAuth flow they cannot complete, and it means your own gateway, not Anthropic, decides what credential is required. Usage through a custom endpoint also does not count against Fazm's built-in credits.

Why did my custom endpoint receive zero requests even though I set it?

Almost always because the selected model is not a Claude model. ANTHROPIC_BASE_URL only overrides Anthropic-format traffic, so Gemini and Codex models bypass the gateway entirely. In raw Claude Code this is silent. In Fazm, if your active model is not a Claude model, Settings shows a warning that the custom endpoint does not apply and offers a one-click Switch to a Claude model button, because new users default to a non-Claude model and would otherwise see the endpoint do nothing.

Does routing through a gateway change the model or my plan?

The gateway changes where the request goes and what credential it carries, nothing about the agent loop. If you point at a LiteLLM or proxy in front of the real Claude models, you get the same Claude responses with centralized auth, usage tracking, and cost controls in the middle. If you point at a local server hosting a different model, you get that model. The wrapper question is separate: a host like Fazm running Claude Code over ACP uses the same agent loop, same tools, same prompts; it only changes what surrounds the request, including making ANTHROPIC_BASE_URL a field instead of an export.