Can I run Claude Code through a proxy?

Claude Code reads the proxy's address from ANTHROPIC_BASE_URL and, when the proxy issues its own credential, reads it from one of three places (Anthropic: connect to a gateway). ANTHROPIC_AUTH_TOKEN is sent as an Authorization: Bearer header, ANTHROPIC_API_KEY as an x-api-key header, and an apiKeyHelper command's output in both. A credential in the header the proxy does not read fails with a 401.

To keep the setting across terminals and background agents, put it in the env block of a settings file. ~/.claude/settings.json applies to all your projects and .claude/settings.local.json to one project (Anthropic: settings).

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

• Never put a credential in a project's .claude/settings.json. That file is committed and shared with everyone who clones the repository (Anthropic).
• When a shell export and a settings file's env block set the same variable, the settings file wins (Anthropic).
• A proxy that needs an extra header, such as a routing key, gets it through ANTHROPIC_CUSTOM_HEADERS, one Name: Value pair per line (\n between pairs inside JSON) (Anthropic: send additional headers).
• The proxy must serve the Anthropic Messages format at /v1/messages and forward the anthropic-version and anthropic-beta headers unchanged (Anthropic: gateway compatibility guide).
• The VS Code extension takes these variables in claudeCode.environmentVariables, and the desktop app reads gateway routing from its own third-party inference configuration, not from ANTHROPIC_BASE_URL (Anthropic: configure each surface).
• On a machine your organization manages, an admin can set allowedProviders to ["customEndpoint"] with a pinned ANTHROPIC_BASE_URL. Claude Code (v2.1.285 or later) then refuses a session pointed anywhere else, a developer's own proxy included (Anthropic: roll out a gateway).

To see what a running session uses, run /status:

1. An Anthropic base URL line shows the proxy's address. If the line is missing, the session is not pointed at a gateway.
2. An Auth token or API key line naming a variable or an apiKeyHelper means a proxy credential is active.
3. A Login method line naming a claude.ai account means your subscription login is the credential.
4. A Proxy line shows a corporate network proxy, which is a separate setting from the base URL (Anthropic: network configuration).

A proxy that issues its own key, separate from your Anthropic login, can take it as a custom header sent through ANTHROPIC_CUSTOM_HEADERS (above). A custom header is not one of the three credential variables, so with none of them set your saved claude.ai login stays the active credential (Anthropic: subscriptions and gateways).

Use ANTHROPIC_BASE_URL when a gateway should receive Claude Code's model requests, and HTTPS_PROXY when your network sends traffic out through a corporate proxy. Both settings carry the word proxy, and they do different jobs. The base URL points model requests at a gateway that reads and forwards them (Anthropic: other LLM gateways). HTTPS_PROXY (or HTTP_PROXY), with NO_PROXY for exceptions, routes Claude Code's traffic through a corporate proxy server, and SOCKS proxies are not supported (Anthropic: proxy configuration). /status shows the network proxy on its own Proxy line.

Yes, when Claude Code sends no gateway credential. Setting only ANTHROPIC_BASE_URL routes requests through the proxy while your saved claude.ai login stays the active credential, so your plan's usage limits and billing apply (Anthropic: subscriptions and gateways). The proxy has to forward the OAuth capability that rides in the anthropic-beta header, and stripping it fails those requests with a 401 (Anthropic: request headers).

A proxy credential changes the bill. While ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY or an apiKeyHelper is active, requests carry that credential in place of your claude.ai login, your subscription's usage limits do not apply to them, and the traffic is billed per token to whoever owns the credential the proxy forwards, such as an organization's Console account (Anthropic). Claude Code keeps the login saved and goes back to it when you unset the variable.

If you mean to work on your plan, run /status before a long session. A token left in a shell profile or settings file takes precedence over the saved login (ANTHROPIC_AUTH_TOKEN at once, ANTHROPIC_API_KEY after a one-time approval) (Anthropic: conflicts with an existing login). The same check for an API key is in am I billed on the API or on my subscription.

Two features depend on a claude.ai identity. Remote Control and voice dictation are unavailable while a proxy credential is active, and Remote Control is also off while ANTHROPIC_BASE_URL points at a host other than Anthropic's (Anthropic).

That depends on who runs the proxy and what it keeps, because it receives everything the model reads. Claude Code sends your full conversation with every request, and each round of tool use sends another request carrying the tool results (Anthropic: costs). So a proxy sees your prompts, the file contents Claude read, command output and every tool result, along with a session id header (Anthropic: request headers). When the proxy keeps your claude.ai login, it also receives that login's credential on every request, because it forwards the request to Anthropic with it (Anthropic: subscriptions and gateways).

Anthropic does not endorse, maintain or audit third-party gateway products, and does not support routing Claude Code to non-Claude models through any gateway (Anthropic). Before you route a session through one, ask:

• Who runs it, and where is it hosted?
• What does it do with the login credential it forwards?
• Where is request data stored, and for how long?
• How do you delete it, and when is a deletion final?
• Is any of it used to train a model?
• Is there a self-hosted version, if the data has to stay on your network?

Our own answers on hosting, storage, deletion, training and self-hosting are in where Perpetuity fits.

Teams use a gateway for credentials and spend. Anthropic lists what one gives an organization as keeping the provider key server-side, attributing usage to each developer, enforcing budgets and rate limits, logging every request for audit and switching providers without touching developer machines (Anthropic: what a gateway provides). A gateway is also infrastructure you operate and keep current. One that does not forward a new Claude Code capability breaks it.

• LiteLLM. Anthropic's cost page says several large enterprises reported using LiteLLM, an open-source proxy that tracks spend by key, and notes it is unaffiliated with Anthropic and has not been audited for security (Anthropic: costs). Its virtual keys record spend per key and can carry a budget cap (LiteLLM: virtual keys).
• Claude apps gateway. Anthropic's own self-hosted gateway for Amazon Bedrock, Claude Platform on AWS, Google Cloud and Microsoft Foundry, with SSO sign-in, per-group model access, OpenTelemetry metrics and per-user and per-group spend limits (Anthropic: Claude apps gateway).
• No proxy at all. If you only need to see usage, Claude Code exports OpenTelemetry metrics from each machine once CLAUDE_CODE_ENABLE_TELEMETRY=1 and an exporter are set, including claude_code.token.usage and claude_code.cost.usage. Prompt text in its events is redacted unless OTEL_LOG_USER_PROMPTS=1 is set (Anthropic: monitoring). Anthropic says OpenTelemetry works on every setup and is the only option that streams per-user token and cost metrics into your own stack in near real time (Anthropic: costs).

Things break when a proxy changes requests or responses on the way through. Anthropic's compatibility guide lists what stops working (Anthropic: gateway compatibility guide):

• Stripped headers. A proxy that drops anthropic-beta silently loses capabilities such as extended context. One that drops the header but passes the matching body field gets 400 errors.
• Prompt caching. A proxy that drops the cache_control markers, or turns structured system content into plain strings, causes no error, but every turn is billed as uncached input.
• Buffered streaming. Claude Code reads responses event by event, and a proxy that buffers a response until it is complete makes Claude Code stall.
• A smaller context limit. A gateway that enforces a smaller window than the model and rewrites the error stops Claude Code from compacting and retrying on its own. Set CLAUDE_CODE_AUTO_COMPACT_WINDOW to the gateway's limit. Claude Code clamps it to at least 100,000 tokens, so below that /compact is the recovery (Anthropic: troubleshoot gateway errors).
• Plan usage display. Claude Code reads the anthropic-ratelimit-unified-* response headers to show a claude.ai login its usage against plan limits, and on a 429 to tell a plan limit or spend cap from a temporary throttle, so a proxy should forward them unchanged on every response (Anthropic: response headers).
• Rewritten history. The API checks each earlier thinking block against the system prompt, tools and earlier messages of the request that produced it. A gateway that rewrites any of them can get a 400 saying the block is bound to a different conversation, and Claude Code then removes earlier thinking blocks from that request and every later one, while new responses still include thinking (Anthropic: automatic retry).
• Checks that skip the proxy. The fast mode availability check calls Anthropic's API directly, so on a network that only allows the proxy, fast mode can report a connectivity error while normal requests work (Anthropic: startup traffic).

Some tools cannot be proxied at all. A proxy at a base URL sees only what a harness sends to that URL, so a tool that sends its model calls through its own servers goes around it.