How to Use Claude Code with a Custom API Base URL (and Why You Would)

In short:

• Claude Code reads two environment variables to talk to any Anthropic-compatible endpoint: ANTHROPIC_BASE_URL (where to send requests) and a credential variable, usually ANTHROPIC_AUTH_TOKEN.
• Test the key with one curl call first, then start claude and run /status to see which base URL and credential it is actually using.
• Make it permanent through the env block in ~/.claude/settings.json, never in a project’s committed .claude/settings.json.
• Pin the opus, sonnet and haiku aliases to exact model IDs so you always know which model, and which rate, a request uses.

Claude Code is usually installed and signed in with a claude.ai account or an Anthropic Console key. But it is also built to run behind a gateway: a server that speaks the same Anthropic Messages API and forwards requests upstream. Anthropic’s own documentation describes this setup in detail, and it is how Relaykit works for Claude Code users. This post walks through the setup step by step, explains what changes when you do it, and lists the errors you are most likely to see.

Why point Claude Code somewhere else?

There are a few practical reasons developers route Claude Code through a gateway instead of a direct subscription or Console key:

• Prepaid, pay-per-token billing. With a prepaid balance you cannot overspend: when the balance runs out, requests stop. That is a useful property when an agent is running unattended in a loop.
• One balance across tools and models. The same key and balance can drive Claude Code, an OpenAI-format tool like Codex CLI, and your own scripts, so you are not juggling several vendor accounts.
• Per-project keys and usage logs. Creating a separate key per project or per machine makes it obvious where tokens went and lets you revoke one key without touching the others.
• Organisational control. Teams use gateways to keep upstream credentials server-side and hand each developer a key that can be revoked on offboarding.

There are trade-offs, and you should know them before you switch:

• Features tied to a claude.ai identity, such as Remote Control and voice dictation, are unavailable while a gateway credential is active. Claude Code’s docs also note that Remote Control is disabled when ANTHROPIC_BASE_URL points at a non-Anthropic host.
• Anthropic does not support routing Claude Code to non-Claude models through any gateway. Use Claude models with Claude Code. If you want GPT, Grok or DeepSeek in an agent, use a tool built for the OpenAI format, such as those in our setup guides.
• Relaykit is an independent service. It is not affiliated with, or endorsed by, Anthropic.

What you need

1. Claude Code installed (claude --version should print a version).
2. An API key from the console. Our keys start with sk-. If you have not signed up yet, the quickstart covers it in a couple of minutes.
3. The base URL: https://api.oneaiapikey.com. Note there is no /v1 on the end. Claude Code appends /v1/messages itself.

Step 1: set the variables for one terminal session

Start with temporary shell variables. If something is wrong you can close the terminal and nothing persists.

export ANTHROPIC_BASE_URL=https://api.oneaiapikey.com
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here

$env:ANTHROPIC_BASE_URL = "https://api.oneaiapikey.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-key-here"

Which credential variable?

Claude Code supports two credential variables, and each one sends the key in a different HTTP header:

Our gateway accepts either header, so we recommend ANTHROPIC_AUTH_TOKEN: it works without the one-time approval prompt. Do not set both. Claude Code warns about conflicting credential sources at startup, and it is easy to forget which one is in effect.

Step 2: test the key before opening Claude Code

A single small request tells you whether the URL and key work, independently of Claude Code. If this fails, the problem is the key or the network, not your Claude Code configuration.

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-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with: ok"}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with: ok"}]}'

A JSON body that starts with {"id":"msg_ and contains a content array means everything works. A 401 means the key was rejected: check for a stray space or a missing character, and confirm the key is still enabled in the console. An error about an unknown model still proves the URL and key are correct, because authentication happened first.

Step 3: start Claude Code and check /status

From the same terminal, so it inherits the variables, run claude and send any short prompt. Then run /status. On the Status tab, look at two lines:

• Anthropic base URL should show https://api.oneaiapikey.com. If the line is missing, the variable did not reach the session.
• Auth token should name ANTHROPIC_AUTH_TOKEN. If you see a Login method line naming a claude.ai account instead, Claude Code is still using your subscription login.

If both lines look right and your prompt got an answer, you are done with the basic setup.

Step 4: make it permanent with settings.json

Shell variables vanish when the terminal closes, and editors started from the Start menu or dock never see them. To make the configuration apply everywhere Claude Code runs, put it in the env block of your user settings file:

• macOS and Linux: ~/.claude/settings.json
• Windows: %USERPROFILE%\.claude\settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.oneaiapikey.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key-here",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

If the file already exists, merge the env block into it rather than replacing the whole file. When a shell export and the settings file both set the same variable, the settings-file value wins, so remove the old exports from your shell profile to avoid confusion later.

Do not put your key in a project’s .claude/settings.json. That file is meant to be committed and shared with everyone who clones the repository. If you want a per-project key, use .claude/settings.local.json and make sure it is in your .gitignore before you save the key there.

Pin the model aliases

Inside Claude Code you switch models with /model opus, /model sonnet or /model haiku, or with claude --model ... at startup. Those aliases resolve to model IDs, and the defaults change as Anthropic ships new versions. Pinning them with the three ANTHROPIC_DEFAULT_*_MODEL variables shown above does two things:

1. You always know exactly which model ID is sent, which means you know the rate. On our catalogue, Claude Opus 5.5, Claude Sonnet 5 and Claude Haiku 4.5 are priced separately; see the models page for current per-token rates.
2. Requests never ask for a model ID the gateway does not serve.

Two more model variables are worth knowing:

• ANTHROPIC_MODEL overrides the model setting for the session, if you want a fixed default without using /model.
• CLAUDE_CODE_SUBAGENT_MODEL sets the default model for sub-agents. Pointing it at a cheaper tier can cut costs noticeably on long agentic tasks, because sub-agents often do high-volume reading and searching.

Also note that the haiku alias is used for some background work, such as generating session titles. Pinning it to a fast, inexpensive model keeps that overhead small. Our post on choosing a model for coding agents goes deeper on which tier to use where.

Using the VS Code extension

The Claude Code VS Code extension checks credentials before it launches, so set the variables in VS Code’s own user settings (run Preferences: Open User Settings (JSON)):

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.oneaiapikey.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-key-here" }
  ]
}

Values in ~/.claude/settings.json still reach the spawned Claude Code process, but this setting is what the extension’s own login check reads.

Optional settings that help behind a gateway

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 turns off traffic that does not go through the gateway, such as telemetry, error reporting and auto-update checks. Useful on locked-down networks. Because it also disables auto-updates, update Claude Code yourself from time to time.
• API_TIMEOUT_MS controls how long Claude Code waits for a response. The default is 600,000 ms (10 minutes). You rarely need to change it, because Claude Code streams its responses, which keeps the connection active.

Troubleshooting

Switching back

To return to your subscription, remove the variables from ~/.claude/settings.json (and your shell profile), open a new terminal and run /status. Your claude.ai login stays saved while a gateway variable is set; it is simply not used until you remove the variable.

Where to go next

• The step-by-step Claude Code setup guide in our docs, kept up to date as Claude Code changes.
• Estimating your monthly LLM API cost, including how prompt caching changes the maths for agent sessions.
• API key security for AI apps, because a key in settings.json is still a secret on disk.