Docs
ANTHROPIC_BASE_URL
The environment variable that points Claude Code and the Anthropic SDKs at an endpoint other than api.anthropic.com — the full variable reference, per-client setup, and the two traps that produce almost every failure.
ANTHROPIC_BASE_URL tells the Anthropic SDKs and Claude Code which host to send API requests to, replacing the default https://api.anthropic.com. Set it to an origin with no path — the client appends /v1/messages itself — and pair it with ANTHROPIC_AUTH_TOKEN, which becomes the Authorization: Bearer header.
That is the whole of a "bring your own key" or "custom base URL" setup: ANTHROPIC_BASE_URL set to Kunavo's endpoint and your Kunavo key as ANTHROPIC_AUTH_TOKEN, and requests reach Claude through Kunavo in the Anthropic Messages format. Pin all four model variables too, because the sonnet and haiku aliases ask for models Kunavo does not serve and, unpinned, answer 404.
# The origin only — no trailing /v1, no trailing slash.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# Claude Code: pin all four model variables to models the endpoint serves.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5Open a new terminal afterwards: Claude Code and the SDKs read these variables at process start, so a session that was already running keeps the old endpoint.
https://api.kunavo.com/v1 produces requests to /v1/v1/messages and every call returns 404. The OpenAI SDK uses the opposite convention and does want /v1 in its base_url — that difference is the single most common configuration mistake here.Every variable, and what it does
The full list Claude Code reads is in Anthropic's environment-variable reference. These are the ones that matter when you are redirecting the endpoint.
| Variable | Value | What it controls |
|---|---|---|
ANTHROPIC_ | https://api. | The origin every request goes to. No path, no trailing slash. |
ANTHROPIC_ | sk-kn-… | Credential sent as Authorization: Bearer. This is the one a gateway wants. |
ANTHROPIC_ | sk-ant-… | Credential sent as the x-api-key header, the form api. |
ANTHROPIC_ | claude-sonnet-5 | The main model Claude Code uses for the conversation. |
ANTHROPIC_ | claude-opus-5-5 | The model behind the opus alias (/model opus). Claude Code's own default is the newest Opus, so pin it to one the endpoint serves. Opus 5.5 needs Claude Code v2.1.280 or later. |
ANTHROPIC_ | claude-sonnet-5 | The model behind the sonnet alias (/model sonnet). The alias asks for Sonnet 5.5 by default, so pin it to a Sonnet the endpoint serves. |
ANTHROPIC_ | claude-haiku-4-5 | The model behind the haiku alias (/model haiku, subagents set to haiku), and the one Claude Code uses for its own background calls. The alias asks for Haiku 5.5 from v2.1.293, so pin it to a Haiku the endpoint serves. |
GET /v1/models.Per-client setup
Claude Code
Put the exports in the shell profile Claude Code starts from, then open a new terminal. Nothing about the install or the workflow changes.
# ~/.zshrc (or ~/.bashrc) — applies to every Claude Code session.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# Pin models this endpoint serves. Claude Code's default and its opus/sonnet
# aliases follow Anthropic's newest models, which may not be served here —
# unpinned, those calls 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5Run /status inside Claude Code to confirm which endpoint the current session is using. Step-by-step, including where to generate the key: set an API key in Claude Code.
Anthropic SDK (Python / TypeScript)
The SDKs read the same environment variables, and both settings can also be passed to the constructor — useful when one process talks to more than one endpoint.
from anthropic import Anthropic
# The Anthropic SDK appends /v1/messages, so pass the origin — not .../v1.
client = Anthropic(
base_url="https://api.kunavo.com",
auth_token="sk-kn-...", # sets the Authorization: Bearer header
)
msg = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Say hi"}],
)
print(msg.content[0].text)OpenAI SDK — the other convention
If your code already speaks OpenAI, you do not need ANTHROPIC_BASE_URL at all. Point base_url at the OpenAI-compatible path — with the /v1 this time — and call the same Claude models through /v1/chat/completions.
from openai import OpenAI
# The OpenAI SDK is the other convention: it wants the /v1 in the base_url.
client = OpenAI(
api_key="sk-kn-...",
base_url="https://api.kunavo.com/v1",
)
r = client.chat.completions.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Say hi"}],
)
print(r.choices[0].message.content)Cline, Roo Code, Kilo Code, Cursor
Editor agents mostly expose the same two settings in their own UI rather than through the environment: a "base URL" or "custom endpoint" field and an API-key field. The rules do not change — origin without /v1 for an Anthropic-style provider, and the key in the API-key field. Per-client walkthroughs: Cline, Roo Code, Kilo Code.
Check that it worked
One curl proves the base URL and the credential at the same time. A 200 with a JSON body means both are right.
# 200 and a JSON body means the base URL and the token are both right.
curl -sS https://api.kunavo.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,
"messages":[{"role":"user","content":"ping"}]}'
# In Claude Code, /status shows the endpoint the session is actually using.When it does not work
| Symptom | Cause | Fix |
|---|---|---|
| 404 on every request | /v1 left on the end of ANTHROPIC_ | Set the origin only. The client appends /v1/ |
| 401 / invalid x-api-key | Credential set as ANTHROPIC_ when the endpoint authenticates with bearer tokens | Use ANTHROPIC_ instead — the difference in full |
| Still hitting api. | Variables exported after the session started, or set in a profile that shell does not read | Open a new terminal; confirm with echo $ANTHROPIC_ |
| 404 model_ | Model id the endpoint does not serve | Set ANTHROPIC_ to an id from GET /v1/models |
| 404 on /model sonnet, /model haiku or a subagent | The alias asks for a model the endpoint does not serve | Pin ANTHROPIC_ |
| Every request fails after updating Claude Code | Version 2.1.304 turned tool search on behind a custom base URL; it retried a 400 or 422 without it, but with ToolSearch disallowed or left out of --tools every request failed | Update to 2.1.305 or later, which retries without tool search |
| Claude Code says the credit balance is too low | Requests are reaching the endpoint and being billed to the key, not the subscription | Expected — top up, or unset the token to return to the plan. See insufficient credit |
Version notes
Anthropic API SDKs, 2026-10-21. The Python SDK 2.0.0 and the TypeScript SDK 1.0.0 send anthropic-version: 2026-10-21 and put the API key in Authorization: Bearer instead of X-Api-Key. Kunavo reads the key from either header, so the upgrade needs no change on this side. Under that API version a request with temperature, top_p or top_k is refused with a 400 (Anthropic's migration guide for API version 2026-10-21, read 2026-10-22), and the new SDKs no longer take them as arguments: the Python SDK 2.1.0 raises a TypeError. Kunavo calls the model with API version 2023-06-01 whatever version the client names, so a request that still carries temperature (through extra_body, say) is not refused: a model that takes it receives it, and on a model that does not, Kunavo drops it and names it in the X-Kunavo-Dropped-Params response header. Checked on 2026-10-22 with the Python SDK 2.1.0 and the TypeScript SDK 1.1.0 against a local Kunavo build.
Claude Code releases that change what happens behind a custom ANTHROPIC_BASE_URL, from its CHANGELOG, each dated by its npm release:
- 2.1.285 (npm, 2026-09-29): sessions behind a custom base URL use the 1M context window of models that have one (Opus 4.7 and later, Sonnet 5 and later, Fable); if a gateway stops at 200K tokens,
/autocompact 200ksets the limit back. - 2.1.299 (npm, 2026-10-14): the requests Claude Code makes to Anthropic itself (feature flags, start-up, fast mode, profile and feedback) no longer carry the key you set for a third-party gateway, and a stream through a custom base URL now waits 300 seconds for data instead of 180.
- 2.1.304 (npm, 2026-10-19): tool search is on by default behind a custom base URL, and a 400 or 422 from the gateway is retried without it.
- 2.1.305 (npm, 2026-10-20): fixes a 2.1.304 regression in which every request failed on Vertex, Bedrock and other providers when the endpoint or a gateway rejected tool search, and behind gateways with
ToolSearchdisallowed or left out of--tools; Claude Code now retries without it.
Run 2.1.305 or later: 2.1.299 is the first release that keeps the gateway key away from Anthropic's own endpoints, and 2.1.305 the first that also recovers when ToolSearch is disallowed or left out of --tools.
What this does to a Pro or Max subscription
While a credential variable is set, Claude Code bills the key rather than the logged-in subscription: plan limits stop applying and usage is charged to whoever owns the key. The subscription itself is untouched — remove the variable, open a new terminal, and Claude Code goes back to the plan. The two never combine, and the cost arithmetic between them is in Claude Code pricing.
Next
Frequently asked questions
What is ANTHROPIC_BASE_URL?
ANTHROPIC_BASE_URL is the environment variable that tells the Anthropic SDKs and Claude Code which host to send API requests to, instead of the default https://api.anthropic.com. Set it to an origin with no path — the client appends /v1/messages itself — and pair it with ANTHROPIC_AUTH_TOKEN, which becomes the Authorization: Bearer header. Any Anthropic-compatible endpoint works; on Kunavo the value is https://api.kunavo.com.
Should ANTHROPIC_BASE_URL include /v1?
No. ANTHROPIC_BASE_URL takes the origin only — https://api.kunavo.com, not https://api.kunavo.com/v1 — because the Anthropic SDKs and Claude Code append the /v1/messages path themselves. Including /v1 produces requests to /v1/v1/messages, which return 404. The OpenAI SDK follows the opposite convention and does want /v1 in its base_url, which is why the same gateway is written two different ways depending on which client is calling it.
What is the difference between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY?
ANTHROPIC_AUTH_TOKEN sends the credential as an Authorization: Bearer header, while ANTHROPIC_API_KEY sends it as the x-api-key header that api.anthropic.com expects. A gateway that authenticates with bearer tokens needs ANTHROPIC_AUTH_TOKEN; setting ANTHROPIC_API_KEY instead is the most common cause of a 401 after changing ANTHROPIC_BASE_URL. Set one, not both — when both are present the behaviour depends on the client version.
How do I set a custom base URL in Claude Code?
Export ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in the shell profile Claude Code starts from (~/.zshrc or ~/.bashrc), then open a new terminal so the variables are inherited. Claude Code reads them at startup, so a session that was already running keeps the old endpoint. Run /status inside Claude Code to confirm which endpoint the current session is using.
Does setting ANTHROPIC_BASE_URL disable my Claude Pro or Max subscription?
While a credential variable such as ANTHROPIC_AUTH_TOKEN is set, Claude Code bills the key rather than the logged-in subscription, so Pro and Max plan limits no longer apply and usage is charged to whoever owns the key. The subscription itself is unaffected and unset — remove the variable and open a new terminal, and Claude Code goes back to the plan.