Claude Code proxy and LLM gateway setup: base URL, tokens and HTTPS_PROXY

To run Claude Code through a proxy, set ANTHROPIC_BASE_URL to your LLM gateway's address and put the gateway credential in ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY. If you only need a corporate HTTP proxy for outbound traffic, set HTTPS_PROXY instead. The two solve different problems, and some networks need both.

This guide covers both setups, how to verify them, and the errors you are most likely to hit. It is based on the Claude Code docs pages on other LLM gateways, connecting to a gateway and enterprise network configuration, read on 24 October 2026.

What is the difference between an LLM gateway and an HTTP proxy?

The docs define a gateway as "a proxy your organization runs between Claude Code and a model provider." Claude Code sends model requests to the gateway, and the gateway forwards them with a credential your organization holds. Developers get gateway credentials instead of provider keys.

A corporate HTTP proxy is different. The gateways overview says an HTTPS_PROXY "sits between Claude Code and every server it talks to, including the gateway." It handles network routing, not model access.

According to the docs, a gateway gives one place to manage credentials, usage tracking, cost controls, audit logging and provider switching. Claude Code also ships its own self-hosted option, Claude apps gateway, inside the claude binary; this guide focuses on connecting to a gateway your organization already runs.

How do you point Claude Code at an LLM gateway?

First, check whether your admin already did it. Run claude. If it opens a session without the login screen, run /status and look for an Anthropic base URL line and an Auth token or API key line. If both are there, send a test message and you are done.

If not, get two things from your gateway team: the base URL and a credential. Then pick the variable:

Start with shell exports for the first connection:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

Once it works, move the values into the env block of ~/.claude/settings.json so they apply everywhere, including background agents:

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

The docs warn: "Don't put the credential in a project's .claude/settings.json." That file is committed. If both a shell export and a settings file set the same variable, the settings file wins. The settings guide explains the file scopes.

How do you check the gateway connection works?

Send a one-token request straight to the gateway before opening Claude Code, so a failure points at the gateway and not your config:

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 response starting with {"id":"msg_ means it works. An error naming an unknown model also proves the URL and credential are fine. A 401 means the credential was rejected; if you guessed the variable, switch to the other one. Each variable uses a different header: ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer, ANTHROPIC_API_KEY sends x-api-key, and apiKeyHelper sends both.

Then start claude from the same shell, send a message, and run /status. The Anthropic base URL line should show your gateway.

How do you configure a corporate HTTP proxy?

Claude Code "respects standard proxy environment variables." Set them before launch, since shell variables are read once at startup:

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

Key points from the network configuration page:

• Lowercase variants work too. Claude Code uses the first one set, in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.
• For basic auth, put credentials in the URL, such as http://username:password@proxy.example.com:8080.
• "Claude Code does not support SOCKS proxies."
• For NTLM or Kerberos proxies, the docs suggest an LLM gateway that supports your authentication method.
• If your proxy inspects TLS with a custom certificate authority, set NODE_EXTRA_CA_CERTS to the CA file. By default Claude Code trusts both its bundled Mozilla CA set and your OS store.
• For client certificates, use CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY.

A malformed proxy URL, such as one missing http://, stops launch with an error naming the variable. Run /status and check the Proxy row, or start claude --debug and read the log at ~/.claude/debug/<session-id>.txt.

What happens to your Claude subscription behind a gateway?

While a gateway credential or apiKeyHelper is active, requests carry that credential, and "the subscription's usage limits don't apply to them." That traffic is billed per token to whoever owns the credential the gateway forwards, such as your company's Console account or cloud provider account.

There is one exception. Setting only ANTHROPIC_BASE_URL, with no gateway credential, routes requests through the gateway but keeps your saved claude.ai login as the active credential, so its limits and billing still apply.

A few features need a claude.ai identity and switch off with a gateway credential. Remote Control and voice dictation are unavailable while ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or an apiKeyHelper is active. Claude Code also still sends version checks and telemetry outside the gateway path; set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 on networks that only allow the gateway, noting that it also disables auto-updates.

How do you fix common Claude Code gateway errors?

These rows are a selection from the troubleshooting table in the connect guide, which lists more cases:

For model selection behind a gateway, see the Claude Code models guide. GitHub Actions reads ANTHROPIC_BASE_URL from the workflow env block, covered in the GitHub Actions guide.

Rolling a gateway out to a team

For admins, the docs give a four-step sequence: deploy the gateway with your provider credential, issue each developer a gateway credential, distribute the base URL and credential through managed settings and secrets tooling, then have developers check /status. To lock machines to the gateway, set allowedProviders to ["customEndpoint"] in managed settings (Claude Code v2.1.285 or later).

A gateway standardizes where requests go, but not what you ask. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code with one npx skills add command. Remember the gateway itself needs upkeep: the docs note that "a gateway that doesn't forward them breaks the corresponding features" as Claude Code adds capabilities.