Connect Claude Code to an LLM gateway

Who this is for and what you will be able to do

This guide is for developers whose organization already runs an LLM gateway, and for administrators who plan to route Claude Code through one. When you finish, you will know how to connect a local Claude Code install to the gateway, how to roll the configuration out to a team, and which account pays for the traffic.^[1]

What a gateway is and how it differs from a direct connection

An LLM gateway is a proxy that an organization runs between Claude Code and the model provider. Developers do not sign in with a personal claude.ai account. They authenticate to the gateway with a credential the organization issues.^[2]

Claude Code works with any gateway that exposes a supported API format. The gateway compatibility guide lists those formats.^[1] Anthropic does not endorse, maintain, or audit third-party gateway products, and it does not support routing Claude Code to non-Claude models through any gateway.^[1]

A gateway gives the organization one place to attribute usage by developer or team, regardless of which provider serves the request. It can also enforce budgets and rate limits, and it can log every model request for compliance.^[1]

Switching providers without touching developer machines requires the gateway to expose one Anthropic-format endpoint, whatever the upstream provider is. A gateway that exposes a provider's own format ties the client configuration to that provider, and it changes what Claude Code sends and which defaults it applies.^[1]

The trade-off is that the gateway becomes infrastructure the organization has to operate. Claude Code adds capabilities with each release, and a gateway that does not forward them breaks the matching features, so the gateway product has to be kept up to date along with Claude Code.^[1]

How administrators roll out a gateway

The rollout follows four steps, whichever gateway product is chosen.^[1]

1. Deploy the gateway and give it the provider credential, so it can authenticate the requests it forwards.
2. Issue each developer a gateway credential. Usage then maps to a person, and offboarding means revoking one credential.
3. Distribute the base URL and the credential through a managed settings file and your secrets tooling.
4. Have each developer check in Claude Code that the configuration is present, so distribution problems show up before anyone depends on the gateway.^[1]

If an organization has no settings distribution in place yet, developers set the variables themselves by following the connection guide.^[1][2]

To make the gateway the only destination a managed machine may use, set allowedProviders to ["customEndpoint"] in the managed settings file and put the gateway's ANTHROPIC_BASE_URL in that file's env block. Claude Code then refuses any session pointed somewhere else, including Anthropic directly or a developer's own proxy. This pinning needs Claude Code v2.1.285 or later.^[1]

If the gateway is reached through a provider-specific endpoint variable, such as ANTHROPIC_BEDROCK_BASE_URL, the allowedProviders entry names the variable to pin.^[1]

Subscription limits and gateway billing

This is the part most often confused.^[1]

While a gateway credential variable or apiKeyHelper is active, requests carry that credential instead of the developer's claude.ai subscription login. The subscription's usage limits do not apply to those requests. Claude Code still keeps the saved claude.ai login on the machine, but it does not send that login with gateway requests.^[1]

Gateway traffic is billed per token to the owner of the credential the gateway forwards. That owner can be an organization's Anthropic Console account, or the Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry account that the gateway routes to.^[1]

If you set only ANTHROPIC_BASE_URL and no gateway credential, requests still pass through the gateway, but the saved claude.ai login stays the active credential. Its usage limits and billing keep applying. Changing the address alone does not move the cost to an organization account.^[1]

A gateway that passes traffic on to Anthropic must forward the Authorization header and the OAuth capability listed in anthropic-beta.^[1]

How a developer connects

Start by checking whether the administrator already set things up. Run claude in a terminal. If it opens a session, the configuration was distributed. If it stops at the login screen, no gateway credential was distributed and you need to configure it yourself.^[2]

To configure it yourself, ask the gateway team for two things: the base URL and the credential. The credential's type decides which variable to use.

• If the team says bearer token or Authorization header, use ANTHROPIC_AUTH_TOKEN, which is sent as Authorization: Bearer.
• If the team says API key or x-api-key, use ANTHROPIC_API_KEY, which is sent in an x-api-key header.
• If the credential rotates or comes from a vault, use apiKeyHelper, which sends it in both headers.

If the team does not say which kind of credential it is, start with ANTHROPIC_AUTH_TOKEN.^[2]

You can set the base URL and the credential with shell exports, but those last only for the current terminal session. To make them apply everywhere Claude Code runs, put them in the env block of ~/.claude/settings.json.^[2]

Two cautions apply. Never put the credential in a project's .claude/settings.json, because that file is committed and shared with everyone who clones the repository. And when a shell export and a settings-file env block set the same variable, the settings-file value wins. Run /status to see which base URL and credential source is in use.^[2]

Test the connection with curl first

Before you open Claude Code, test the gateway directly. A one-token request sent to the gateway's /v1/messages path, with the credential header attached, shows whether the URL and credential work. If it fails, the cause is the gateway or the network, not the Claude Code configuration.^[2]

A 401 response means the credential was rejected. An error that names an unknown model still shows the URL and credential are valid, because the gateway authenticates the request before it checks the model name. You do not need to find a model the gateway serves for this test.^[2]

After the request succeeds, start claude from the same shell, send a message, and run /status. On the Status tab, the Anthropic base URL line should show your gateway address. An Auth token or API key line that names the variable you set confirms the gateway credential is active rather than a saved claude.ai login.^[2]

Common problems

A startup warning that a gateway credential and a saved login are both active means one must go. Unset the variable to keep the saved login, or run /logout to use the gateway credential.^[2]

An apiKeyHelper command has to print only the credential to standard output. On Claude Code v2.1.227 or later, a banner or log line printed alongside the key makes the helper fail.^[2]

A 400 error that names an unrecognized field, such as context_management, means the upstream behind the gateway rejects pre-release fields that Claude Code sends. Setting CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 suppresses most of those fields.^[2]

Next steps

To set up the gateway itself, follow the four rollout steps above. To make sure each machine connects correctly, use the configuration and verification sections of the connection guide. Both pages are maintained in Claude Code's official documentation, and they are the reference for the full details.^[1][2]