How to run Claude Code behind an LLM gateway
To run Claude Code behind an LLM gateway, get two things from whoever runs the gateway: its base URL and a credential. Set ANTHROPIC_BASE_URL to the URL. Put the credential in ANTHROPIC_AUTH_TOKEN if it is a bearer token, ANTHROPIC_API_KEY if it is an x-api-key, or point apiKeyHelper at a command that prints it if it rotates. Test with a one-token curl request, start Claude Code, and run /status to confirm the base URL and credential lines.
In the desktop app it works differently. The app does not read ANTHROPIC_BASE_URL or settings.json for gateway routing. It reads its third-party inference configuration, which your company can push to you, or which you can fill in yourself through Developer Mode. I cover both below.
What an LLM gateway actually does
A gateway is a proxy your organization runs between Claude Code and the model provider. Claude Code sends its requests to the gateway, and the gateway forwards them with the organization's own credential. The provider behind it can be the Anthropic API, Amazon Bedrock, Google Cloud or Microsoft Foundry. The gateway's configuration decides.
- Credentials: the provider key stays on the server. Developers only ever hold a gateway credential, so offboarding someone means revoking one credential.
- Usage tracking: usage is attributed by developer or team, whichever provider serves the request.
- Cost controls: budgets and rate limits are enforced in one place.
- Audit logging: every model request can be logged for compliance.
- Provider switching: change the provider in the gateway's config without touching developer machines, as long as the gateway exposes one Anthropic-format endpoint.
My take: if more than a handful of people on your team use Claude Code on a company API account, a gateway is the right shape. A shared provider key pasted into ten laptops is the setup that ends with a surprise bill. The flip side is that the gateway now holds a funded key, so it needs real authentication, per-person budgets and rate limits before it goes anywhere near the internet. A gateway with no auth is just a leaked key with extra steps.
Claude apps gateway or the gateway you already run?
There are two routes. Claude apps gateway is a self-hosted gateway built into the claude binary itself. Developers sign in with your company's identity provider through /login, model access and managed settings are enforced by group, and usage metrics go out over OpenTelemetry to your own observability stack. The other route is a gateway product your company already runs, which works as long as it exposes a supported API format.
The two gateway routes for Claude Code
| Claude apps gateway | A gateway you already run | |
|---|---|---|
| Where it comes from | Built into the claude binary | Your own gateway product |
| How developers sign in | Company SSO through /login | A gateway-issued key or token |
| Keeping up with new Claude Code features | Ships with each Claude Code release | You update its forwarding rules as Claude Code changes |
| CI pipelines | No service-token flow, so CI goes to the provider directly | Works with a gateway key in CI |
| Non-Claude models | Not supported | Not supported for Claude Code |
My pick: if you are starting fresh, use Claude apps gateway. The biggest hidden cost of a third-party gateway is upkeep. Claude Code adds request fields and headers with each release, and a gateway that strips them breaks the matching features. If your company already runs a gateway for other AI traffic and has a team keeping it current, use that one and follow the rest of this guide.
Step 1: set the base URL and credential
Which variable holds your gateway credential
| Set the credential in | Use when the gateway team says | Header it sends |
|---|---|---|
| ANTHROPIC_AUTH_TOKEN | Bearer token, or Authorization header | Authorization: Bearer |
| ANTHROPIC_API_KEY | API key, or x-api-key | x-api-key |
| apiKeyHelper | The credential rotates or comes from a vault | Both headers |
If nobody told you which kind it is, start with ANTHROPIC_AUTH_TOKEN. A credential in the wrong variable arrives in a header the gateway does not read, and you get a 401. Switch to the other variable and try again.
For your first connection, export ANTHROPIC_BASE_URL and the credential in your shell and test before you save anything. Once it works, move both into the env block of ~/.claude/settings.json so they apply in every project and reach background agents, which shell exports do not reliably do. If a value is set in both places, the settings file wins. The settings.json guide shows where the env block goes, and Claude Code environment variables covers the other places to set them.
Step 2: verify before you trust it
Send a one-token request straight to the gateway with curl: a POST to your base URL plus /v1/messages, with your credential in the matching header, an anthropic-version header and a tiny message. A JSON reply starting with a msg_ id means the URL and credential work. An error naming an unknown model also proves the URL and credential work, because the gateway authenticated you before it rejected the model. A 401 means the credential was rejected or sent in the wrong header.
Then start Claude Code from the same shell, send a message and run /status. On the Status tab, look for two lines. Anthropic base URL should show your gateway address, and it only appears when a gateway is set. An Auth token or API key line should name the variable you set. If you see a Login method line naming your claude.ai account instead, the gateway credential did not reach the session.
If your company already pushed the configuration to your machine through managed settings, you may have nothing to set at all. Run /status first and check those same two lines before you configure anything yourself.
Step 3: set up the surface you actually use
Where each Claude Code surface reads its gateway settings
| Surface | Where the gateway settings go |
|---|---|
| Desktop app | Its third-party inference configuration, pushed by your admin or entered under Developer, then Configure Third-Party Inference |
| Terminal (CLI) | Shell exports, or the env block of ~/.claude/settings.json |
| VS Code extension | claudeCode.environmentVariables in VS Code's own user settings |
| GitHub Actions | ANTHROPIC_BASE_URL in the workflow env block, gateway key as the anthropic_api_key input |
| Agent SDK | The env option on the spawned Claude Code process |
| Slack, cloud sessions, Remote Control | Not part of a gateway deployment |
Desktop app first, since that is where I tell most people to start. If your company has not pushed a configuration, open Help, then Troubleshooting, then Enable Developer Mode. The app restarts with a Developer menu. Open Developer, then Configure Third-Party Inference, and enter the gateway base URL. A configuration your admin distributes takes priority and makes this form read-only. With a gateway active, the app does not offer Anthropic-hosted cloud environments, and Remote Control is off. If the app says Gateway was unreachable, run the curl test above.
Two traps on the other surfaces. In VS Code, values in ~/.claude/settings.json reach the Claude Code process but not the extension's own login check, so put the gateway variables in claudeCode.environmentVariables. In the TypeScript Agent SDK, setting options.env replaces the whole environment, so spread process.env into it or your gateway variables disappear. Python merges instead. For GitHub Actions with a bearer-token gateway, pass the same secret twice: as the anthropic_api_key input and as ANTHROPIC_AUTH_TOKEN in the env block. Claude Code GitHub Actions covers the rest of the workflow.
What happens to your Claude subscription
While a gateway credential or apiKeyHelper is active, requests carry that credential instead of your claude.ai login. Your subscription's usage limits do not apply, and the traffic is billed per token to whoever owns the provider credential behind the gateway, such as your company's Console account or its Bedrock, Google Cloud or Foundry account. Your claude.ai login stays saved on the machine, unused. Unset the variable and Claude Code goes back to it.
The exception catches people out. If you set only ANTHROPIC_BASE_URL with no gateway credential, requests still route through the gateway, but your saved claude.ai login stays the active credential, so your subscription limits and billing still apply. One more detail: ANTHROPIC_AUTH_TOKEN takes over immediately, while ANTHROPIC_API_KEY asks for a one-time approval in an interactive session. If you declined it once, enable it under /config with the Use custom API key option.
Some features need a claude.ai identity and switch off while a gateway credential is active: Remote Control and voice dictation. Remote Control is also off while ANTHROPIC_BASE_URL points at a non-Anthropic host. If you are deciding between a personal plan and a company gateway, which Claude plan for Claude Code and how much Claude Code costs per month cover the plan side.
Optional settings your gateway team may ask for
- ANTHROPIC_CUSTOM_HEADERS adds headers such as a tenant or routing key, one Name: Value pair per line (use \n between pairs inside a JSON settings file).
- apiKeyHelper runs a command that prints the current credential. Its output is cached for five minutes by default; change that with CLAUDE_CODE_API_KEY_HELPER_TTL_MS. The command must print nothing but the key.
- CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 asks the gateway for its model list at startup and adds those names to the /model picker.
- CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 turns off version checks, telemetry and similar traffic that goes around the gateway. It also turns off auto-updates, so plan another update path.
- To route to a cloud provider's own format through the gateway, use the provider block instead of ANTHROPIC_BASE_URL, for example ANTHROPIC_BEDROCK_BASE_URL with CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 and CLAUDE_CODE_USE_BEDROCK=1. Only do this if your gateway team named the provider.
For admins: to make the gateway the only place a managed machine can send model traffic, set allowedProviders to ["customEndpoint"] in your managed settings file and put the gateway's ANTHROPIC_BASE_URL in that file's env block. Claude Code then refuses sessions pointed anywhere else, including Anthropic directly. That needs Claude Code v2.1.285 or later.
Fixes for common Claude Code gateway errors
Gateway errors and what fixes them
| What you see | Likely cause | Fix |
|---|---|---|
| 401 on every request | Wrong credential, or the right one in a header the gateway does not read | Switch between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY, or regenerate the key |
| 400 naming Extra inputs are not permitted or context_management | The gateway's upstream rejects newer request fields | Set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 |
| 400 in the gateway's own words about a context or token limit | The gateway enforces a smaller context than the model, so Claude Code does not auto-compact | Run /compact now, and set CLAUDE_CODE_AUTO_COMPACT_WINDOW to the gateway's limit (it cannot go below 100,000 tokens) |
| 403 with an HTML body, and nothing in the gateway's logs | A web application firewall blocked the request body before it reached the gateway | Exempt the gateway's /v1/messages path from request-body inspection |
| Certificate or TLS errors while curl works | A corporate TLS-inspection proxy with a CA Claude Code does not trust | Set NODE_EXTRA_CA_CERTS to the CA bundle path |
| Asked to log in even though curl works | The credential is only in a project settings file, which applies after first-run setup | Put ANTHROPIC_AUTH_TOKEN in a shell export or ~/.claude/settings.json |
| Gateway models missing from /model | Their names are not in the built-in list | Enable gateway model discovery |
The firewall one is worth knowing in advance. Claude Code prompts include source code and XML-style tags that look like cross-site scripting to body-inspection rules, so a short curl test passes while a real session fails. If your gateway logs show no request at all, look at what sits in front of it. For running the same setup inside CI or a container, Claude Code in GitLab and the devcontainer guide cover the pipeline side.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I connect Claude Code to an LLM gateway?
Set ANTHROPIC_BASE_URL to the gateway's address and put the gateway credential in ANTHROPIC_AUTH_TOKEN for a bearer token, ANTHROPIC_API_KEY for an x-api-key, or an apiKeyHelper command if it rotates. Test with a one-token curl request, then check /status for the base URL and credential lines.
Does the Claude Code desktop app work with an LLM gateway?
Yes, but it does not read ANTHROPIC_BASE_URL. It uses its third-party inference configuration, which your admin can distribute, or which you can enter under Developer, then Configure Third-Party Inference after enabling Developer Mode from the Help menu.
Does my Claude subscription still apply when I use a gateway?
Not while a gateway credential is active. Requests are billed per token to the account behind the gateway's provider credential, and your subscription limits do not apply. If you set only ANTHROPIC_BASE_URL with no credential, your saved claude.ai login is still used.
Should I use ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY for a gateway?
Use ANTHROPIC_AUTH_TOKEN for a bearer token sent in the Authorization header, and ANTHROPIC_API_KEY for a key sent in the x-api-key header. If you are not sure, start with ANTHROPIC_AUTH_TOKEN and switch if you get a 401.
Can I use non-Claude models in Claude Code through a gateway?
Routing Claude Code to non-Claude models through a gateway is not supported. A gateway decides which provider serves Claude models, such as the Anthropic API, Amazon Bedrock, Google Cloud or Microsoft Foundry.
Last reviewed by David Iya on October 28, 2026
