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¶
- Set the two variables and start
claude. - Run
/status: the Anthropic base URL line shows your gateway, and Auth token namesANTHROPIC_AUTH_TOKEN. - 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_tokenscalls 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_URLin theenvblock of Claude Code's managed settings, and setallowedProvidersto["customEndpoint"]so Claude Code refuses to run against anything but the gateway. Hand out one Vidai key per developer (or anapiKeyHelperthat 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.