Claude Code proxy: run Claude Code through an LLM gateway

Guide · Coding

A Claude Code proxy is an LLM gateway that sits between Claude Code and the model API, so every request from a developer's terminal passes through infrastructure the organization controls before it reaches Anthropic, Amazon Bedrock, or Google Cloud. Claude Code supports this directly: ANTHROPIC_BASE_URL points it at a gateway, and a second variable carries the gateway-issued credential. This guide covers the settings that redirect Claude Code, what a gateway must forward, setups for Bifrost, LiteLLM, OpenRouter, Bedrock, and Vertex, and a troubleshooting table, as part of our AI coding agents hub.

What is a Claude Code proxy?#

A Claude Code proxy is a gateway that authenticates each developer, applies budgets and logging, and forwards Claude Code's API requests to a model provider with the organization's credential. Anthropic's documentation calls it an LLM gateway. It is an AI gateway configured for one client, and our explainer on what an AI gateway is covers the general architecture.

Anthropic's gateway overview describes two credentials: each developer holds one issued by the gateway, and the gateway holds one provider credential for the organization's account, which developers never see.

Claude apps gateway, Anthropic's own self-hosted gateway, ships inside the claude binary. Any other gateway works if it exposes a supported API format, and Bifrost, LiteLLM, and OpenRouter all document Claude Code setups. Anthropic states that it doesn't endorse, maintain, or audit third-party gateways, and doesn't support routing Claude Code to non-Claude models through any gateway.

Why teams put a proxy in front of Claude Code#

Teams add a Claude Code proxy to give each developer a revocable key with its own budget and request log, to bill usage to a cloud account they already have, to fail over between providers, and to serve MCP tools from one place. Some also use it to try non-Anthropic models, with real limits on quality.

  • Per-developer keys, budgets, and logs. Each developer gets a virtual key instead of the provider key, so offboarding revokes one credential and a budget caps a runaway agent loop.
  • Billing and data residency. A gateway can forward to Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, so usage lands on an existing cloud bill. Anthropic describes Claude apps gateway as built for organizations that route inference through their own cloud, for example to meet data residency requirements.
  • Fallbacks. When one provider or region fails, the gateway retries or sends the request to a backup target, as our guide to LLM routing describes.
  • Central MCP. A gateway that is also an MCP gateway gives Claude Code one tool endpoint and filters which tools each key can call.
  • Other models. A gateway that translates formats can serve a non-Anthropic model behind the Anthropic endpoint, but every edit and command Claude Code runs depends on that model's tool use, so results vary by model.

A gateway is also infrastructure to operate, and one that doesn't forward new Claude Code capabilities breaks the matching features. Sessions through a gateway also aren't eligible for Anthropic's HIPAA configuration.

How a request moves through a Claude Code proxy#

A request leaves Claude Code with a gateway credential. The gateway maps that credential to a developer or team, checks budget and rate limits, picks a provider and model, swaps in the provider credential, and relays the streamed reply back event by event while it records tokens, cost, and the session that made the call.

Claude Code sends a request with a virtual key to a gateway, which checks auth and budget, routes, forwards with the provider credential, relays the stream, and logs usage. Claude CodeDeveloper machineGatewayAuth, budget, log, routeProviderAnthropic or a cloud1POST /v1/messages + key2auth, budget, rate limit3pick provider, model4provider credential5streamed events6relay unbuffered7log tokens, cost
Figure 1: The request path through a Claude Code proxy. The provider never sees the developer's key, and Claude Code never sees the provider's.

The gateway decides where a request goes, not which model the developer picks; that still comes from /model or the model variables below.

How Claude Code talks to the model API#

Claude Code speaks the Anthropic Messages API. It posts each turn to /v1/messages, reads the reply as a stream of server-sent events, and can call /v1/messages/count_tokens to measure context. Redirecting those requests takes a base URL and a credential; choosing which model answers takes a separate set of model variables.

Variables that redirect Claude Code#

These are the variables and settings Anthropic's environment variable reference and gateway connection guide document for proxy setups, as of November 2026.

Variable or setting What it does
ANTHROPIC_BASE_URL Sends API requests to a proxy or gateway instead of Anthropic's API
ANTHROPIC_AUTH_TOKEN Sends the credential as Authorization: Bearer <value>
ANTHROPIC_API_KEY Sends the credential in x-api-key; interactive sessions ask once before using it
apiKeyHelper (settings key) Runs a command that prints the credential, sent in both headers and cached five minutes unless CLAUDE_CODE_API_KEY_HELPER_TTL_MS changes it
ANTHROPIC_CUSTOM_HEADERS Adds Name: Value headers, one per line, such as a routing key
ANTHROPIC_MODEL Sets the model for the session
ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL Set what the opus, sonnet, and haiku aliases resolve to; the Haiku variable also covers background tasks
CLAUDE_CODE_SUBAGENT_MODEL Sets the default model for subagents
CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX Switch to the Amazon Bedrock or Google Cloud request format and credentials
ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL Point the Bedrock or Vertex format at a custom endpoint or gateway
CLAUDE_CODE_SKIP_BEDROCK_AUTH, CLAUDE_CODE_SKIP_VERTEX_AUTH Skip cloud request signing, because the gateway holds those credentials
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY Fills the /model picker from the gateway's /v1/models endpoint

Which credential wins#

Claude Code's authentication docs give a fixed order when several credentials are present:

  1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY is set
  2. ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then apiKeyHelper output
  3. CLAUDE_CODE_OAUTH_TOKEN, then Anthropic profile and federation credentials
  4. The claude.ai subscription login from /login

So a leftover CLAUDE_CODE_USE_BEDROCK=1 sends traffic to Bedrock even when ANTHROPIC_BASE_URL points at a gateway. The order also decides billing. While a gateway credential is active, subscription limits don't apply and tokens are billed to whoever owns the provider credential behind the gateway. Setting only ANTHROPIC_BASE_URL routes through the gateway but keeps the claude.ai login as the credential.

Where the settings live#

Claude Code reads these variables from the shell or from the env block of a settings file, and a settings-file value wins over a shell export. The files are ~/.claude/settings.json for the user, .claude/settings.json for the shared project, .claude/settings.local.json for personal project overrides, and managed settings for organization policy, which take precedence. A credential never belongs in the committed project file.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

For a company rollout, Anthropic's LLM gateway page recommends issuing each developer a gateway credential and distributing the base URL through managed settings. Setting allowedProviders to ["customEndpoint"] there, with the gateway URL in the same file's env block, makes the gateway the only destination a managed machine accepts (Claude Code v2.1.285 or later).

What Claude Code requires of a gateway#

Anthropic's gateway compatibility guide says a gateway must expose at least one supported API format, forward the anthropic-beta and anthropic-version headers unchanged, relay streamed responses event by event, and pass request body fields through rather than allowlisting them. Stripping or rewriting them breaks features, sometimes silently and sometimes with 400 errors.

Format Selected by Endpoints the gateway serves
Anthropic Messages ANTHROPIC_BASE_URL /v1/messages, plus optional /v1/messages/count_tokens
Amazon Bedrock InvokeModel ANTHROPIC_BEDROCK_BASE_URL with CLAUDE_CODE_USE_BEDROCK=1 /model/{model}/invoke, /model/{model}/invoke-with-response-stream, optional /model/{model}/count-tokens
Google Cloud Agent Platform rawPredict ANTHROPIC_VERTEX_BASE_URL with CLAUDE_CODE_USE_VERTEX=1 :rawPredict, :streamRawPredict, optional count-tokens:rawPredict

The format decides what Claude Code sends. In the Anthropic Messages format, it treats the gateway as the Claude API and sends its full set of beta headers and fields, even if the gateway forwards to Bedrock. In the Bedrock or Vertex format, it sends only what those providers accept. Bridging the difference is the gateway's job.

Claude Code reaches models three ways: Anthropic format to a gateway, provider format to a gateway, or direct cloud mode to Bedrock or Agent Platform with no gateway. Claude CodeAnthropic formatANTHROPIC_BASE_URLfull beta setProvider formatANTHROPIC_BEDROCK_BASE_URLprovider subsetDirect cloud modeCLAUDE_CODE_USE_BEDROCKno gatewayLLM gatewayauth, budgets, logs, routingAnthropic APIBedrock or Agent PlatformClaude on your cloud accountgateway bridges fieldscloud credentials
Figure 2: The variable you set decides which API format reaches the gateway and how much of Claude Code's feature set it sends.

Headers and fields a gateway must forward#

  • anthropic-version and anthropic-beta: forward verbatim. The beta list changes with Claude Code releases, so the guide warns against allowlisting values.
  • Authorization: forward it when the gateway relies on the developer's claude.ai login rather than its own key, or those requests fail with 401.
  • Body fields and cache_control: pass them through unchanged. Capabilities pair a beta header with a body field, and stripping one half produces 400 errors.
  • Errors and response headers: return upstream error bodies unmodified, because Claude Code's retry logic matches their wording, and send retry-after in integer seconds.

Claude Code also sends x-claude-code-session-id on every request, plus x-claude-code-agent-id and x-claude-code-parent-agent-id on subagent requests, so a gateway log can break spend down by session and by parallel agent. Setting CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 adds hints such as x-claude-code-request-class, which marks a main turn, subagent turn, compaction, or side request.

Claude Code with Bifrost: virtual keys, CLI, and MCP#

Bifrost is an open-source AI gateway from Maxim AI, written in Go and licensed Apache 2.0, that exposes an Anthropic-compatible endpoint at the /anthropic path. Claude Code connects with a Bifrost virtual key, and the same gateway routes to Anthropic, Bedrock, Vertex, or other providers and serves MCP tools at one /mcp endpoint.

Point Claude Code at Bifrost#

Bifrost's Claude Code guide uses this static-key setup. Virtual keys carry an sk-bf- prefix and hold the budgets, rate limits, and provider access for a developer or team, as the virtual keys docs describe.

export ANTHROPIC_BASE_URL=https://bifrost.example.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-bf-your-virtual-key

Governance is optional by default, so a request without a virtual key skips governance checks; setting client.enforce_auth_on_inference to true makes a key mandatory. To keep a claude.ai subscription, a developer signs in with /login and sends the virtual key in an x-bf-vk header through ANTHROPIC_CUSTOM_HEADERS. Bifrost forwards the subscription token to Anthropic and applies governance from the header, while subscription limits still apply.

Launch Claude Code with the Bifrost CLI#

The Bifrost CLI launches Claude Code, Codex CLI, Gemini CLI, and OpenCode through the gateway without hand-editing each tool's configuration. These commands come from its OSS setup and coding agents pages:

npx -y @maximhq/bifrost-cli    # installs to ~/.bifrost/bin/bifrost
bifrost context add local --base-url http://localhost:8080 --use
printf '%s\n' "$BIFROST_VIRTUAL_KEY" | bifrost auth set-virtual-key --stdin
bifrost claude --model anthropic/claude-sonnet-4-6

bifrost claude sets the gateway URL and model only for the Claude Code child process, and removes an inherited ANTHROPIC_API_KEY so a personal key can't override the gateway credential. bifrost configure claude writes the same values into ~/.claude/settings.json after saving a restoration receipt, and bifrost unconfigure claude restores the original files.

Route Claude Code to Anthropic, Bedrock, or Vertex#

Bifrost picks the provider from the model name. Anthropic models need no prefix in Claude Code's model variables, and other providers use a provider/model form such as bedrock/... or vertex/.... Bifrost's Claude Code and Bedrock runbook pins each alias to a Bedrock deployment:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-bifrost-virtual-key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "bedrock/claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "bedrock/claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "bedrock/claude-haiku-4-5-20251001"
  }
}

Each deployment name maps to a Bedrock model ID, such as global.anthropic.claude-sonnet-5. The runbook adds that Bifrost's client settings must allow the headers Claude Code sends, including anthropic-beta, that any CLAUDE_CODE_USE_* variable must be unset, and that a top-level model setting overrides these variables.

For failover, Bifrost retries transient errors with exponential backoff, then moves to fallback targets in provider/model form, which a routing rule can supply for Claude Code traffic. Bifrost's session affinity reads x-claude-code-session-id to keep a session on the provider and key that served it, so it keeps hitting the same provider cache.

Serve MCP tools at /mcp#

Bifrost's MCP gateway connects to Model Context Protocol servers over STDIO, HTTP, or SSE and exposes their tools at one /mcp endpoint. Claude Code adds it as an HTTP server:

claude mcp add --transport http bifrost http://localhost:8080/mcp \
  --header "Authorization: Bearer sk-bf-your-virtual-key" \
  --scope user

The virtual key decides which tools the session sees, through Bifrost's MCP tool filtering. The guide recommends turning off Bifrost's automatic tool injection for Claude Code to avoid duplicate tools, and re-adding the server after authentication changes, because Claude Code caches tokens.

Claude Code with a LiteLLM proxy#

LiteLLM's proxy server is a self-hosted, OpenAI-compatible gateway written in Python that also serves the Anthropic Messages format, so Claude Code connects with the same two variables. Each model Claude Code can call is defined in config.yaml under the name Claude Code passes as the model. This config.yaml is condensed from LiteLLM's Claude Code quickstart:

model_list:
  - model_name: claude-opus-4-7
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: claude-bedrock-opus
    litellm_params:
      model: bedrock/invoke/us.anthropic.claude-opus-4-7
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-west-2
  - model_name: claude-opus-vertex
    litellm_params:
      model: vertex_ai/claude-opus-4-7
      vertex_ai_project: "my-test-project"
      vertex_ai_location: "us-east5"
      vertex_credentials: os.environ/VERTEX_FILE_PATH_ENV_VAR
 
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
litellm --config /path/to/config.yaml    # listens on port 4000
export ANTHROPIC_BASE_URL=http://0.0.0.0:4000
export ANTHROPIC_AUTH_TOKEN=sk-your-litellm-key
claude --model claude-bedrock-opus
  • The name passed to --model or the ANTHROPIC_DEFAULT_*_MODEL variables must match a model_name exactly.
  • The master key reaches every model on the proxy; a LiteLLM virtual key is limited to the models assigned to it.
  • For Claude on Bedrock, LiteLLM recommends the bedrock/invoke/ path, and for a Bedrock 400 invalid beta flag it suggests CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, calling both temporary workarounds.
  • LiteLLM also has an Anthropic pass-through endpoint at /anthropic and a tutorial on Claude Code with MCPs.

Pin the LiteLLM version you deploy. Releases 1.82.7 and 1.82.8 on PyPI contained credential-harvesting malware, according to advisory PYSEC-2026-2, published March 24, 2026, which tells anyone who installed them to revoke and rotate the credentials that environment could reach.

Claude Code with OpenRouter#

OpenRouter is a hosted model aggregator, and its Claude Code integration guide connects Claude Code to OpenRouter's Anthropic-compatible endpoint with no local proxy. The guide states that the setup is only guaranteed to work with the Anthropic first-party provider, so treat it as another route to Claude rather than a way to swap models.

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

ANTHROPIC_API_KEY must be an empty string, so a stray key can't take over from the token. Model overrides use OpenRouter slugs in the alias variables, such as ~anthropic/claude-sonnet-latest, and the guide recommends putting the Anthropic first-party provider at the top of your provider priority. /status should then show ANTHROPIC_AUTH_TOKEN as the auth token and https://openrouter.ai/api as the base URL, and requests should appear on OpenRouter's Activity page.

OpenRouter runs outside your network, so prompts and code pass through its service. Teams that need budgets or logs in their own infrastructure can run a self-hosted gateway with OpenRouter as one upstream.

Claude Code on Bedrock and Vertex without a proxy#

Claude Code can call Amazon Bedrock or Google Cloud's Agent Platform directly, with no gateway, by setting one provider variable and supplying the cloud's own credentials. That covers billing through a cloud account and regional routing, while per-developer controls come from the cloud's IAM, quotas, and logging rather than from a gateway.

Amazon Bedrock#

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile-name
export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

Anthropic's Bedrock page adds these details:

  • /setup-bedrock, or 3rd-party platform at the login prompt, starts a wizard that writes these values to ~/.claude/settings.json.
  • The IAM policy needs bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListInferenceProfiles, and bedrock:GetInferenceProfile.
  • Pin model versions before a team rollout, because unpinned aliases resolve to built-in defaults that can lag new releases or be unavailable in the account.
  • Amazon Bedrock Guardrails apply through ANTHROPIC_CUSTOM_HEADERS, and the WebSearch tool isn't available on Bedrock.

Google Cloud's Agent Platform (Vertex AI)#

gcloud auth application-default login
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

According to Anthropic's Agent Platform page, you first enable aiplatform.googleapis.com, request Claude model access in Model Garden, and grant roles/aiplatform.user. CLOUD_ML_REGION accepts global, a multi-region location such as eu, or a region such as us-east5, and VERTEX_REGION_CLAUDE_* variables override it for models the global endpoint doesn't serve. Prompt caching is on automatically.

Put a gateway in front of either cloud#

To keep the provider's own format and still add a gateway, point the provider base URL at the gateway and turn off client-side signing:

export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key    # only if the gateway wants its own token

Leave AWS_BEARER_TOKEN_BEDROCK unset here, or Claude Code sends that Bedrock key as the Authorization header instead of the gateway token. The Vertex version uses ANTHROPIC_VERTEX_BASE_URL and CLAUDE_CODE_SKIP_VERTEX_AUTH=1, with the project ID and region still set.

Other options: Claude apps gateway and Claude Code Router#

Two more options sit at opposite ends of the scale. Claude apps gateway is Anthropic's self-hosted gateway for organizations, run from the claude binary. Claude Code Router is an open-source local gateway that one developer runs on their own machine to reach many providers from Claude Code and other agents.

Claude apps gateway starts with claude gateway --config gateway.yaml. Developers sign in through /login with an OIDC identity provider such as Okta or Microsoft Entra ID and get short-lived tokens instead of keys. It needs PostgreSQL and a private network address, maps identity provider groups to model allowlists and managed settings, emits OTLP usage metrics, and fails over between upstreams. It ships with each Claude Code release, so there is no header allowlist to maintain, but it has no service-token flow for CI.

Claude Code Router is an MIT-licensed local model gateway and desktop app that gives Claude Code, Codex, OpenCode, and other agents one local endpoint. It routes to providers such as OpenRouter, DeepSeek, and Mistral, with retries, key rotation, fallback models, and request logs, and it fits individual setups rather than organization-wide governance.

Claude Code proxy options compared#

The options differ in where they run, how Claude Code authenticates, and which controls they document. Self-hosted gateways keep prompts and logs in your network, a managed service removes the operations work, and direct cloud mode skips the proxy entirely in exchange for fewer per-developer controls.

Option Where it runs How Claude Code connects Claude upstreams Controls documented for Claude Code
Bifrost Self-hosted, Apache 2.0 /anthropic base URL plus virtual key, or bifrost claude Anthropic, Bedrock, Vertex Virtual keys with budgets and rate limits, routing rules, fallbacks, MCP at /mcp
LiteLLM proxy Self-hosted, MIT outside its enterprise directory Proxy base URL plus master or virtual key Anthropic, Bedrock, Vertex Model-scoped virtual keys, MCP
OpenRouter Managed service https://openrouter.ai/api plus OpenRouter key Anthropic first-party provider is the guaranteed path Provider priority, activity dashboard
Direct Bedrock or Vertex No proxy CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX The cloud's Claude models Cloud IAM and quotas, Bedrock Guardrails
Claude apps gateway Self-hosted, in the claude binary /login with corporate SSO Bedrock, Claude Platform on AWS, Agent Platform, Foundry, Anthropic API Per-group model access, managed settings, OTLP metrics, failover
Claude Code Router Local app, MIT Local endpoint Anthropic and other providers Retries, fallback models, request logs

Our AI gateways directory lists more gateways by deployment model, and the AI coding tools directory covers the agents they serve.

Caveats: what can break behind a Claude Code gateway#

Most proxy problems come from a gateway changing something Claude Code depends on: stripping a header, flattening a field, buffering a stream, or renaming a model. Anthropic's compatibility guide documents each failure, and most show up either as a 400 error or as a quiet loss of a feature such as caching.

Prompt caching#

Claude Code attaches cache_control markers to system blocks and messages. A gateway that drops them, or flattens block-form content to strings, raises no error: every turn bills as uncached input, visible as high input_tokens with little cache activity. Since v2.1.181, the attribution block at the start of the system prompt stays stable behind a custom base URL, so a gateway-side cache keyed on the request body still works. On Bedrock, prompt caching may not be available in every region.

Extended thinking#

For current Claude models and unrecognized model names, Claude Code sends thinking: {"type": "adaptive"}, and an upstream build that doesn't accept it returns a 400 naming thinking. Recent versions retry with the other thinking type, and drop earlier thinking blocks when an upstream rejects a thinking signature, which happens when a gateway rewrites system, tools, or earlier messages. Interleaved thinking rides on an anthropic-beta value alone, so stripping the header removes it silently.

Token counting#

Without the optional token-counting endpoints, Claude Code falls back to a character-based estimate, so /context shows approximate counts. A gateway that enforces a smaller context window than the model's, and rewrites the too-long error in its own words, stops automatic compaction; setting CLAUDE_CODE_AUTO_COMPACT_WINDOW to the gateway's limit prevents that, down to a floor of 100,000 tokens.

Model name mapping#

Behind an ANTHROPIC_BASE_URL gateway, Claude Code treats an unrecognized model ID as a current Claude model: it assumes a 1M token context window and sends adaptive reasoning, effort, and context management fields, which an alias's real model may reject. A modelOverrides entry maps the alias to the Anthropic ID of the model behind it. Model discovery keeps only IDs containing claude or anthropic.

Features that call Anthropic directly#

The fast mode availability check and the WebFetch domain safety check call api.anthropic.com directly, so they fail on a network that blocks that host while inference keeps working. Remote Control and voice dictation are unavailable while a gateway credential is active. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 stops version checks and telemetry outside the gateway path, and auto-updates with them.

Streaming#

Claude Code reads each response event by event, so the stream has to pass through intact. A gateway that buffers responses makes Claude Code stall, and a body that ends before the final message_delta and message_stop events counts as a dropped connection. Stripping SSE ping events can trip the idle timeout during long thinking pauses, and in Bedrock format the binary event stream must keep its original Content-Type.

Claude Code with other models#

A non-Anthropic model behind a gateway works only as well as its tool calling, and Anthropic doesn't support the setup. Bifrost's guide adds that such models may lack Claude-specific server-side tools such as web search, and that some providers stream empty tool-call arguments, which breaks file operations. Test on your own repository first; our overview of AI coding agents covers how to run that trial.

Verify and troubleshoot a Claude Code proxy#

Test the gateway with a one-token request before opening Claude Code, then confirm the route with /status. A failure in the direct request points at the gateway, URL, or credential; a failure only inside Claude Code points at configuration, headers, or a field the upstream rejects.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

A JSON body starting with {"id":"msg_, or an unknown-model error, proves the URL and credential work. Inside Claude Code, /status should show an Anthropic base URL line with the gateway address and an Auth token or API key line naming your variable. The gateway's request log is the final check; our guide to LLM observability covers tracing beyond it. The symptoms below come from Anthropic's connection guide and Bedrock page.

Symptom Likely cause Fix
Startup warning naming two credential sources A gateway credential and a saved claude.ai login are both active Unset the variable to use the login, or run /logout to use the gateway credential
401 naming an invalid or unrecognized token The credential is in a header the gateway doesn't read, or was revoked Switch between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY, or reissue the key
400 naming context_management or Extra inputs are not permitted An Anthropic-format gateway forwards to an upstream, often Bedrock, that rejects newer fields Set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, or connect in the provider's format
400 naming thinking or adaptive The upstream model build doesn't accept adaptive reasoning Upgrade the upstream model build
Context-limit error in the gateway's own words The gateway enforces a smaller window and rewrites the error Run /compact, then set CLAUDE_CODE_AUTO_COMPACT_WINDOW
Claude Code stalls while waiting for a reply The gateway buffers the stream until the response completes Relay server-sent events unbuffered, including ping events
Error beginning Bedrock streaming response has content-type The gateway rewrote Bedrock's event-stream Content-Type Forward body and header unmodified, or connect with ANTHROPIC_BASE_URL
High input_tokens with no cache activity The gateway strips cache_control or flattens content Forward cache_control and block-form content unchanged
403 with an HTML body and nothing in gateway logs A web application firewall blocked the prompt body as cross-site scripting Exempt /v1/messages from request-body inspection
Gateway models missing from /model The names aren't in Claude Code's built-in list Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, with IDs that contain claude

Where to go next: our explainer on what an AI gateway is covers gateways beyond Claude Code, and our guide to LLM routing covers the fallback and load-balancing strategies a Claude Code proxy can apply.

Frequently asked questions

Can I use Claude Code with other models?

Technically yes: a gateway that translates formats, such as Bifrost or LiteLLM, can serve a non-Anthropic model behind the Anthropic Messages endpoint Claude Code calls. Anthropic doesn't support this setup, though. Claude Code relies on tool calling for every edit and command, so the model must handle tools well, and Claude-specific features such as server-side web search may be missing. Test on your own tasks first.

How do I use Claude Code with Amazon Bedrock?

Set CLAUDE_CODE_USE_BEDROCK=1, provide AWS credentials through a profile, SSO, access keys, or a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK, and set AWS_REGION if your profile has none. Pin model versions with ANTHROPIC_DEFAULT_OPUS_MODEL and its Sonnet and Haiku counterparts. The /setup-bedrock wizard writes these values for you. To route through a gateway, add ANTHROPIC_BEDROCK_BASE_URL and CLAUDE_CODE_SKIP_BEDROCK_AUTH=1.

How do I use Claude Code with OpenRouter?

OpenRouter's Claude Code guide sets three variables: ANTHROPIC_BASE_URL to https://openrouter.ai/api, ANTHROPIC_AUTH_TOKEN to your OpenRouter API key, and ANTHROPIC_API_KEY to an empty string. No local proxy is needed. OpenRouter states the setup is only guaranteed to work with the Anthropic first-party provider, and recommends putting Anthropic first in your provider priority. Run /status to confirm the base URL and token.

How do I connect Claude Code to a LiteLLM proxy?

Define Claude models in LiteLLM's config.yaml under model_list, start the proxy with litellm --config, then set ANTHROPIC_BASE_URL to the proxy address, port 4000 by default, and ANTHROPIC_AUTH_TOKEN to a LiteLLM master or virtual key. The model name you pass to Claude Code must match a model_name in the config exactly. For Bedrock, LiteLLM recommends its bedrock/invoke/ model path.

Does a Claude Code proxy use my Claude subscription?

Not when a gateway credential is active. With ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, or apiKeyHelper set, requests carry that credential instead of your claude.ai login, so subscription limits don't apply and usage is billed to the account behind the gateway. If you set only ANTHROPIC_BASE_URL, requests still pass through the gateway, but your claude.ai login stays the active credential and its limits and billing apply.

Terms in this guide

Cite this guide

The AI Engineering Editors. "Claude Code proxy: run Claude Code through an LLM gateway." The AI Engineering, updated Nov 19, 2026. https://theaiengineering.com/articles/claude-code-proxy

Title
Claude Code proxy: run Claude Code through an LLM gateway
Author
The AI Engineering Editors
Publisher
The AI Engineering
Published
Updated
View as Markdown

The AI Engineering Editors ·