---
title: "Claude Code proxy: run Claude Code through an LLM gateway"
description: "A Claude Code proxy routes Claude Code through an LLM gateway. Set ANTHROPIC_BASE_URL for Bifrost, LiteLLM, OpenRouter, Bedrock, or Vertex, and fix errors."
summary: "Claude Code can send every model request through an LLM gateway instead of straight to Anthropic, giving a team per-developer keys, budgets, logs, and a choice of upstream. This guide covers the variables that redirect it, what a gateway must forward, five setups, and fixes for common errors."
type: "guide"
canonical_url: "https://theaiengineering.com/articles/claude-code-proxy"
markdown_url: "https://theaiengineering.com/articles/claude-code-proxy.md"
topic: "AI coding agents"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
published: "2026-11-19"
updated: "2026-11-19"
keywords: ["claude code proxy","claude code bedrock","claude code openrouter","claude code litellm","claude code gateway","claude code with other models"]
citation: "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"
---

# Claude Code proxy: run Claude Code through an LLM gateway

## TL;DR

- Claude Code sends Anthropic Messages API requests to /v1/messages, and setting ANTHROPIC_BASE_URL plus a gateway credential in ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY routes them through a proxy.
- Anthropic's gateway compatibility guide requires a gateway to forward the anthropic-beta and anthropic-version headers unchanged, pass request body fields through, and relay streamed events without buffering.
- With a gateway credential active, Claude Code stops using the developer's claude.ai subscription, and the tokens are billed to the account behind the gateway's provider credential.
- Claude Code can also call Amazon Bedrock or Google Cloud's Agent Platform, formerly Vertex AI, directly with CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX and no proxy at all.
- Anthropic doesn't support routing Claude Code to non-Claude models through any gateway, and OpenRouter guarantees its Claude Code setup only with the Anthropic first-party provider.

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](https://theaiengineering.com/topics/ai-coding) 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](https://theaiengineering.com/glossary/ai-gateway) configured for one client, and our explainer on [what an AI gateway is](https://theaiengineering.com/articles/what-is-an-ai-gateway) covers the general architecture.

[Anthropic's gateway overview](https://code.claude.com/docs/en/gateways) 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](https://theaiengineering.com/glossary/model-failover) 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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/articles/llm-routing) describes.
- **Central MCP.** A gateway that is also an [MCP gateway](https://theaiengineering.com/glossary/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](https://theaiengineering.com/glossary/rate-limiting), 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.

**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.**

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.

Steps:

1. Claude Code → Gateway: POST /v1/messages + key
2. Gateway → Gateway: auth, budget, rate limit
3. Gateway → Gateway: pick provider, model
4. Gateway → Provider: provider credential
5. Provider → Gateway: streamed events
6. Gateway → Claude Code: relay unbuffered
7. Gateway → Gateway: log tokens, cost

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](https://theaiengineering.com/glossary/llm-streaming) 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](https://code.claude.com/docs/en/env-vars) and [gateway connection guide](https://code.claude.com/docs/en/llm-gateway-connect) 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](https://code.claude.com/docs/en/authentication) 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](https://code.claude.com/docs/en/settings), 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.

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

For a company rollout, Anthropic's [LLM gateway page](https://code.claude.com/docs/en/llm-gateway) 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](https://code.claude.com/docs/en/llm-gateway-protocol) 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.

**Figure 2: The variable you set decides which API format reaches the gateway and how much of Claude Code's feature set it sends.**

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.

Components:

- **Claude Code**
- **Anthropic format**: ANTHROPIC_BASE_URL full beta set
- **Provider format**: ANTHROPIC_BEDROCK_BASE_URL provider subset
- **Direct cloud mode**: CLAUDE_CODE_USE_BEDROCK no gateway
- **LLM gateway**: auth, budgets, logs, routing
- **Anthropic API**
- **Bedrock or Agent Platform**: Claude on your cloud account

Connections:

- Claude Code → Anthropic format
- Claude Code → Provider format
- Claude Code → Direct cloud mode
- Anthropic format → LLM gateway
- Provider format → LLM gateway
- LLM gateway → Anthropic API
- LLM gateway → Bedrock or Agent Platform: gateway bridges fields
- Direct cloud mode → Bedrock or Agent Platform: cloud credentials

### 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](https://docs.getbifrost.ai/cli-agents/claude-code) 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](https://docs.getbifrost.ai/features/governance/virtual-keys) describe.

```bash
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](https://docs.getbifrost.ai/cli-agents/overview) 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](https://docs.getbifrost.ai/quickstart/cli/oss-setup) and [coding agents](https://docs.getbifrost.ai/quickstart/cli/coding-agents) pages:

```bash
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](https://docs.getbifrost.ai/runbooks/claude-code-bedrock) pins each alias to a Bedrock deployment:

```json
{
  "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](https://docs.getbifrost.ai/features/retries-and-fallbacks) transient errors with exponential backoff, then moves to fallback targets in `provider/model` form, which a [routing rule](https://docs.getbifrost.ai/providers/routing-rules) 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](https://docs.getbifrost.ai/mcp/overview) connects to [Model Context Protocol](https://theaiengineering.com/glossary/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:

```bash
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](https://docs.getbifrost.ai/features/governance/mcp-tools). 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](https://theaiengineering.com/glossary/openai-compatible-api) 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](https://docs.litellm.ai/docs/tutorials/claude_responses_api):

```yaml
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
```

```bash
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](https://docs.litellm.ai/docs/tutorials/claude_mcp).

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](https://osv.dev/vulnerability/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](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration) 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.

```bash
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

```bash
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](https://code.claude.com/docs/en/amazon-bedrock) 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)

```bash
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](https://code.claude.com/docs/en/google-vertex-ai), 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](https://theaiengineering.com/glossary/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:

```bash
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](https://code.claude.com/docs/en/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](https://github.com/musistudio/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](https://theaiengineering.com/platforms/ai-gateways) lists more gateways by deployment model, and the [AI coding tools directory](https://theaiengineering.com/platforms/ai-coding-tools) 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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/articles/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.

```bash
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](https://theaiengineering.com/articles/llm-observability) covers tracing beyond it. The symptoms below come from Anthropic's [connection guide](https://code.claude.com/docs/en/llm-gateway-connect) 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](https://theaiengineering.com/articles/what-is-an-ai-gateway) covers gateways beyond Claude Code, and our guide to [LLM routing](https://theaiengineering.com/articles/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

- [AI gateway](https://theaiengineering.com/glossary/ai-gateway): An AI gateway is a proxy layer between applications and model providers that exposes one API for many models and centralizes routing, failover, access control, cost tracking, caching, and logging.
- [Virtual key](https://theaiengineering.com/glossary/virtual-key): A virtual key is an API key issued by an AI gateway that maps a caller to its allowed models, budget, and rate limits, while the gateway keeps the real provider credentials.
- [Rate limiting](https://theaiengineering.com/glossary/rate-limiting): Rate limiting is the enforcement of a maximum number of requests or tokens a client may send to an API within a time window, with excess requests rejected, usually with HTTP 429.
- [Model failover](https://theaiengineering.com/glossary/model-failover): Model failover is the automatic rerouting of an LLM request to a backup model, deployment, or provider when the primary target returns an error, times out, or hits a rate limit.
- [MCP gateway](https://theaiengineering.com/glossary/mcp-gateway): An MCP gateway is a proxy that sits between MCP hosts and many MCP servers, exposing them through one endpoint and centralizing authentication, tool access policy, and audit logging.
- [Model Context Protocol (MCP)](https://theaiengineering.com/glossary/model-context-protocol): Model Context Protocol (MCP) is an open protocol, introduced by Anthropic in November 2024, that standardizes how AI applications connect to external tools, data sources, and prompts through MCP servers.
- [Tool calling](https://theaiengineering.com/glossary/tool-calling): Tool calling is an LLM capability in which the model, given a list of tool definitions, outputs a structured request naming a tool and its arguments, which the application executes and returns.
- [OpenAI-compatible API](https://theaiengineering.com/glossary/openai-compatible-api): An OpenAI-compatible API is an HTTP API that accepts OpenAI's request and response formats, so code written for OpenAI's SDKs can call another server by changing the base URL, API key, and model name.
- [Prompt caching](https://theaiengineering.com/glossary/prompt-caching): Prompt caching is an LLM API and inference-server feature that stores the computed attention state for a repeated prompt prefix, so later requests sharing that prefix skip reprocessing it.
- [Context window](https://theaiengineering.com/glossary/context-window): A context window is the maximum number of tokens a language model can take into account in a single request, including the system prompt, conversation history, tool results, and the generated output.
- [LLM streaming](https://theaiengineering.com/glossary/llm-streaming): LLM streaming is the delivery of a language model's output in small chunks as it is generated, usually as server-sent events over HTTP, so clients can show text before the response is complete.

## Related guides

- [AI coding agents: how they work and how the major tools compare](https://theaiengineering.com/articles/ai-coding-agents): AI coding agents compared: how they differ from autocomplete, the four main categories, a comparison table of major tools, and how to evaluate and secure them.
- [What is an AI gateway? How it works and when you need one](https://theaiengineering.com/articles/what-is-an-ai-gateway): An AI gateway is a proxy between your apps and model providers. Learn how it works, its core features, AI gateway vs API gateway, and open source options.
- [LLM routing: strategies, fallbacks, and learned routers](https://theaiengineering.com/articles/llm-routing): LLM routing guide: rule-based and cost-aware strategies, fallbacks, load balancing, semantic and learned routers like RouteLLM, router evals, and pitfalls.
- [LLM observability: what to capture, which metrics, and tools](https://theaiengineering.com/articles/llm-observability): LLM observability guide: what to capture in traces and spans, metrics to track, OpenTelemetry GenAI conventions, tool categories, and keeping prompts private.

Part of the [AI coding agents](https://theaiengineering.com/topics/ai-coding) topic hub.

## 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: 2026-11-19
- Updated: 2026-11-19
- URL: https://theaiengineering.com/articles/claude-code-proxy
- Markdown: https://theaiengineering.com/articles/claude-code-proxy.md

To cite one section, link to its anchor:

- [What is a Claude Code proxy?](https://theaiengineering.com/articles/claude-code-proxy#what-is-a-claude-code-proxy)
- [Why teams put a proxy in front of Claude Code](https://theaiengineering.com/articles/claude-code-proxy#why-teams-put-a-proxy-in-front-of-claude-code)
- [How a request moves through a Claude Code proxy](https://theaiengineering.com/articles/claude-code-proxy#how-a-request-moves-through-a-claude-code-proxy)
- [How Claude Code talks to the model API](https://theaiengineering.com/articles/claude-code-proxy#how-claude-code-talks-to-the-model-api)
- [What Claude Code requires of a gateway](https://theaiengineering.com/articles/claude-code-proxy#what-claude-code-requires-of-a-gateway)
- [Claude Code with Bifrost: virtual keys, CLI, and MCP](https://theaiengineering.com/articles/claude-code-proxy#claude-code-with-bifrost-virtual-keys-cli-and-mcp)
- [Claude Code with a LiteLLM proxy](https://theaiengineering.com/articles/claude-code-proxy#claude-code-with-a-litellm-proxy)
- [Claude Code with OpenRouter](https://theaiengineering.com/articles/claude-code-proxy#claude-code-with-openrouter)
- [Claude Code on Bedrock and Vertex without a proxy](https://theaiengineering.com/articles/claude-code-proxy#claude-code-on-bedrock-and-vertex-without-a-proxy)
- [Other options: Claude apps gateway and Claude Code Router](https://theaiengineering.com/articles/claude-code-proxy#other-options-claude-apps-gateway-and-claude-code-router)
- [Claude Code proxy options compared](https://theaiengineering.com/articles/claude-code-proxy#claude-code-proxy-options-compared)
- [Caveats: what can break behind a Claude Code gateway](https://theaiengineering.com/articles/claude-code-proxy#caveats-what-can-break-behind-a-claude-code-gateway)
- [Verify and troubleshoot a Claude Code proxy](https://theaiengineering.com/articles/claude-code-proxy#verify-and-troubleshoot-a-claude-code-proxy)
- [Frequently asked questions](https://theaiengineering.com/articles/claude-code-proxy#faq)
