Dokumentacja

Dokumentacja

Claude Code

Claude Code treats any Anthropic-format endpoint as a gateway. Two variables point it at Kunavo, three more pin models Kunavo serves, the install is untouched, and every session bills per token from your balance instead of a subscription.

Two environment variables — ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN — move Claude Code onto pay-as-you-go without changing the install.

# One terminal session
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # origin, no /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves. Claude Code's default and its opus/sonnet aliases
# follow Anthropic's newest models; the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, /model sonnet 404s.
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-5

claude
ANTHROPIC_BASE_URL is the origin. Claude Code appends /v1/messages itself — Anthropic's own verification snippet is curl "$ANTHROPIC_BASE_URL/v1/messages" — so a value ending in /v1 produces requests to /v1/v1/messages and a 404. This is the single most common setup failure; the ANTHROPIC_BASE_URL page covers the rest of them.
Pin the models. Claude Code's built-in default is the newest Opus (Opus 5.5 as of September 2026, per Anthropic's model configuration docs), and a model Kunavo does not serve yet answers 404 on the first request. The sonnet alias asks for Sonnet 5.5 and the haiku alias for Haiku 5.5 (from v2.1.293), neither of which Kunavo serves, so /model sonnet, /model haiku and subagents set to those aliases 404 unless they are pinned too. ANTHROPIC_MODEL sets the session model; ANTHROPIC_DEFAULT_OPUS_MODEL covers /model opus (Opus 5.5 needs Claude Code v2.1.280 or later), ANTHROPIC_DEFAULT_SONNET_MODEL covers /model sonnet, and ANTHROPIC_DEFAULT_HAIKU_MODEL covers /model haiku plus the background calls. Any id from GET /v1/models works.
Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. The two variables pick a header: AUTH_TOKEN sends Authorization: Bearer, API_KEY sends x-api-key. Kunavo reads either, but API_KEY needs a one-time approval prompt in an interactive session before it takes effect, and AUTH_TOKEN does not.

Claude Code releases that change what happens behind a custom ANTHROPIC_BASE_URL, from its CHANGELOG, each dated by its npm release:

  • 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 ToolSearch disallowed 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.

The Agent SDK runs the same CLI; which Claude Code each SDK release bundles is on the Agent SDK page.

Rather not edit environment variables by hand? CC Switch can hold Kunavo as a saved Claude Code provider — the same service root and the same bearer key as above; the field-by-field setup is on the CC Switch page.
No key yet? Create a Kunavo account, make a key (it starts with sk-kn-) and add credit from $10 — calls are paid from that balance, and failed calls are not billed. The dashboard then opens on the Claude Code setup.

Step by step

  1. Create a key at /app/keys and copy it — it is shown once.
  2. Export the variables above for the session, or persist them in the env block of ~/.claude/settings.json: {"env":{"ANTHROPIC_BASE_URL":"https://api.kunavo.com","ANTHROPIC_AUTH_TOKEN":"sk-kn-...","ANTHROPIC_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_OPUS_MODEL":"claude-opus-5-5","ANTHROPIC_DEFAULT_SONNET_MODEL":"claude-sonnet-5","ANTHROPIC_DEFAULT_HAIKU_MODEL":"claude-haiku-4-5"}}. Anthropic's docs are explicit that the credential does not belong in a project's .claude/settings.json — that file gets committed.
  3. Run claude and open the Status tab. A line naming Auth token confirms the gateway credential is active; a Login method line naming a claude.ai account means the variable was not picked up.
  4. If you are also signed in to claude.ai, Claude Code prints claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set at startup. That is expected with a gateway key: requests run on the Kunavo key, and claude.ai connectors, Remote Control and /schedule are off in that session; this guide shows where the key is read from and how to keep both setups.
  5. For the VS Code extension the variables go in claudeCode.environmentVariables in VS Code's own user settings — the extension checks credentials before it launches, so ~/.claude/settings.json reaches the spawned process but not that check.

Checked against Anthropic's “Connect Claude Code to an LLM gateway” on October 3, 2026. Third-party settings move; if a field name here no longer matches what you see, that page is the authority, not this one.

This is the short version. The full walkthrough — model choice, what a real session costs, and the failure modes — is in the Claude Code API key guide.

Verify before you debug the client

One request settles whether a failure is the endpoint, the key, or the configuration file. If this returns JSON, the same base URL and key work in Claude Code.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Which model id to put in the field

Every text model is reachable as a model id — the live list is GET /v1/models, and the catalog with prices is on the models page. Rates are USD per 1M tokens, input / output.

Model idKunavo in / outWhere it fits in Claude Code
claude-sonnet-5$1.40 / $7.00the default working model — set with /model or ANTHROPIC_MODEL
claude-opus-5-5$2.80 / $14.00planning and architecture-level edits
claude-haiku-4-5$0.70 / $3.50the haiku alias and Claude Code's own background calls — pin it with ANTHROPIC_DEFAULT_HAIKU_MODEL
claude-fable-5-2$5.60 / $28.00the frontier tier, for the plans that are worth its rate
Billing is per token from a prepaid balance with no monthly fee — see billing. On repeated context — which is most of what an editor or a chat client sends — prompt caching moves the bill more than the model choice does.

Frequently asked questions

How do I use Claude Code without a Claude subscription?

Set ANTHROPIC_BASE_URL to an Anthropic-format endpoint and ANTHROPIC_AUTH_TOKEN to that endpoint's key, and pin ANTHROPIC_MODEL to a model the endpoint serves — Claude Code's built-in default may not be one. Claude Code then authenticates to the endpoint instead of claude.ai, and usage is billed per token by whoever owns that credential rather than against a subscription plan. Anthropic documents this as gateway mode; the saved claude.ai login stays on disk, unused, and returns as soon as the variables are unset.

Should ANTHROPIC_BASE_URL include /v1?

No. Claude Code appends the route itself, so the variable is the origin — https://api.kunavo.com, not https://api.kunavo.com/v1. Anthropic's own verification command is curl "$ANTHROPIC_BASE_URL/v1/messages", which shows the concatenation directly. A base URL that already ends in /v1 sends requests to /v1/v1/messages and returns 404.

What is the difference between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY?

They put the credential in different HTTP headers: ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer, ANTHROPIC_API_KEY sends x-api-key. A key in the wrong variable reaches the endpoint in a header it does not read and the request fails with 401. If a gateway's documentation says "bearer token", use ANTHROPIC_AUTH_TOKEN; if it says "API key" or "x-api-key", use ANTHROPIC_API_KEY.

Which Claude Code features stop working behind a custom base URL?

Remote Control and voice dictation both need a claude.ai identity and are unavailable while a gateway credential is set; Remote Control is additionally disabled whenever ANTHROPIC_BASE_URL points at a non-Anthropic host. /schedule and the connectors you added at claude.ai are off too: Claude Code loads claude.ai connectors only when a claude.ai login is the credential in use, so if you are signed in to claude.ai as well, it says at startup: "claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set". The fast-mode availability check also goes directly to api.anthropic.com rather than following the base URL. Everything in the core loop — the agent, tools, subagents and the MCP servers you add to Claude Code yourself — runs on the Messages API and is unaffected.