Skip to content

Claude Code

Two environment variables and every model call Claude Code makes, in the terminal, in your editor and in its subagents, is governed: checked against your policies, charged to the developer's team and recorded in Request logs. An admin can put the same two values in managed settings so developers configure nothing.

What it is

Claude Code is Anthropic's coding agent: a command-line tool, with extensions for VS Code and JetBrains, that reads and edits your code and runs commands. It speaks the Anthropic Messages format, which the gateway accepts at /v1/messages, and calls the gateway from the developer's machine. Claude Code's own docs call this setup an LLM gateway.

The two settings

Setting Environment variable Value
Base address ANTHROPIC_BASE_URL https://<your-gateway> (no /v1: Claude Code adds /v1/messages)
Key ANTHROPIC_AUTH_TOKEN (sent as Authorization: Bearer) or ANTHROPIC_API_KEY (sent as x-api-key) Your Vidai key (starts vk_)

The gateway accepts either header; ANTHROPIC_AUTH_TOKEN is the simpler choice, because Claude Code asks once before it uses a key from ANTHROPIC_API_KEY. Set one of the two, not both. The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway; the key comes from Keys › Issue a key (its secret is shown once).

export ANTHROPIC_BASE_URL="https://<your-gateway>"
export ANTHROPIC_AUTH_TOKEN="vk_…"
claude
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<your-gateway>",
    "ANTHROPIC_AUTH_TOKEN": "vk_…"
  }
}
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://<your-gateway>" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "vk_…" }
  ]
}

In VS Code's user settings (Preferences: Open User Settings (JSON)).

The settings file applies everywhere Claude Code runs, background agents included. Never put the key in a project's .claude/settings.json, which is committed with the repository. If your keys come from a vault, use an apiKeyHelper instead: a command that prints the key (Claude Code sends its output in both headers; the gateway accepts that, as the value is the same).

{ "apiKeyHelper": "~/bin/get-vidai-key.sh" }

A minimal call

  1. Set the two variables and start claude.
  2. Run /status: the Anthropic base URL line shows your gateway, and Auth token names ANTHROPIC_AUTH_TOKEN.
  3. Send "Reply with exactly: ok". A short answer means the address and key are right.

To test the address and key without Claude Code:

curl -sS "$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.5","max_tokens":5,"messages":[{"role":"user","content":"ping"}]}'

Streaming

Claude Code streams every answer. The gateway passes Anthropic's own events through for Claude models and writes the same events for a translated model, so Claude Code sees no difference.

Tool calls

Claude Code's tools (Read, Edit, Bash, Grep and the rest) are its own tools, sent as ordinary tool definitions, so they work on every provider the gateway translates to. WebSearch is different: it uses Anthropic's server-side web search. On a Claude model it works as usual; on another provider the gateway maps it to that provider's search where one exists (Gemini's Google Search, OpenAI's search-capable models) and otherwise drops it, so the model answers without searching.

Reading what the gateway did

Claude Code doesn't show response headers. Look the calls up in Request logs: filter on Key, Model or Path (/v1/messages). A session shows as many calls: the main conversation, subagents, and small background calls such as session titles.

Errors

Claude Code shows the gateway's error message, which arrives in the Anthropic format. Common ones while setting up:

What you see Usual cause
401, invalid_api_key or missing_api_key The key is wrong or a provider's key; or the credential is in a variable Claude Code isn't using (check /status)
403, model_not_allowed Your key may not call that model; set the model variables below to approved names
404, model_not_found Claude Code asked for a name your organisation hasn't set up, often its own default; see Model names
429, rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded A limit on the key or team was reached
400 naming an unknown field or anthropic-beta value A newer Claude Code feature the model behind the gateway doesn't accept; set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

The full list is in Headers and errors. Claude Code retries failed calls by itself (up to 10 times; CLAUDE_CODE_MAX_RETRIES changes that). The gateway's own 429 carries no Retry-After, so Claude Code uses its own backoff.

Model names

Claude Code asks for Anthropic's current model ids unless you tell it otherwise: today default and opus mean Opus 5.5 (claude-opus-5-5), sonnet Sonnet 5.5 and haiku Haiku 5.5 (claude-haiku-5-5), and they move to newer models when Anthropic releases them. If your organisation's names differ, or you want another model, set them:

Variable Used for
ANTHROPIC_MODEL The model a session starts on (also claude --model <name> or "model" in settings)
ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL What the sonnet and opus choices in /model mean
ANTHROPIC_DEFAULT_HAIKU_MODEL The haiku choice, and background work such as session titles (replaces the older ANTHROPIC_SMALL_FAST_MODEL)
CLAUDE_CODE_SUBAGENT_MODEL Subagents that aren't given a model another way
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<your-gateway>",
    "ANTHROPIC_AUTH_TOKEN": "vk_…",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.5-flash"
  }
}

With CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, Claude Code asks the gateway's GET /v1/models (which lists only the models your key may call) and adds them to /model; it keeps only names that contain claude or anthropic, so add other models with the variables above or ANTHROPIC_CUSTOM_MODEL_OPTION. For a name Claude Code doesn't recognise it assumes a 200K context window; set CLAUDE_CODE_MAX_CONTEXT_TOKENS if the model's window differs.

Claude Code on GPT or Gemini

Because the gateway translates both ways, Claude Code runs on any model approved under Models, a GPT or a Gemini model as well as Claude: set its name in the variables above. The answers come back as Anthropic messages, tools and streams included. Anthropic doesn't support Claude Code on other models, so test the model on real work first, and expect these differences:

  • Prompt caching: Claude Code's cache markers are removed on other providers. The provider's own caching still applies and cache hits are still reported, but you don't choose what is cached.
  • Thinking: thinking and effort settings are mapped to the provider's reasoning settings. Thinking from another provider carries no Anthropic signature, so Claude Code drops earlier thinking from later turns (it does this on its own when the signature is refused).
  • WebSearch: mapped to the provider's own search where there is one, otherwise left out (see Tool calls).
  • Token counts: Claude Code's /v1/messages/count_tokens calls go to Anthropic for Claude models; for others the gateway counts the tokens itself, an estimate (x-vidai-token-count: estimated).

What goes through the gateway

Claude Code feature Through the gateway
Sessions in the terminal, VS Code and JetBrains, subagents, background calls Yes
WebFetch's page summaries Yes (a model call); its domain safety check goes to Anthropic directly
GitHub Actions (claude-code-action), the Agent SDK Yes, with the same variables in their environment
Claude desktop app Only through its own third-party inference settings, not these variables
Claude Code on the web, in Slack, Remote Control, voice dictation No
Update checks, telemetry, release notes No: they go to Anthropic; turn them off with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Check it works in a minute

Run /status, send "Reply with exactly: ok", then open Request logs a few seconds later and filter on your key.

Good to know

  • Roll it out to everyone: put ANTHROPIC_BASE_URL in the env block of Claude Code's managed settings, and set allowedProviders to ["customEndpoint"] so Claude Code refuses to run against anything but the gateway. Hand out one Vidai key per developer (or an apiKeyHelper that fetches it), so calls are charged to their team. See Claude Code's rollout guide.
  • While a Vidai key is set, Claude Code doesn't use a developer's claude.ai login for these calls.
  • Claude Code's docs: Connect to an LLM gateway, gateway compatibility, model configuration.