Claude Code settings.json for an LLM Gateway: A Working Setup and What Each Error Means

Claude Code can pick up the same variable from your shell, from up to four settings files and from VS Code's settings. Point it at a gateway in one place, leave an old value in another, and you get a login screen, a model error or a 401 that doesn't match the key you just pasted.

This post is the settings.json that works, how Claude Code decides between competing values, and the exact messages it prints when something is off. Tested on Claude Code 2.1.304 on October 20, 2026, against AIHubMix with a real key; any Anthropic-compatible gateway is set up the same way.

TL;DR

• File: ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json on Windows). Put ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in its env block.
• The base URL is the root (https://aihubmix.com). Claude Code appends /v1/messages itself.
• A settings env value overwrites the same variable exported in your shell. Variables the file doesn't set still come from the shell.
• Don't set both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY: both headers go out, and AIHubMix reads x-api-key first.
• VS Code needs the two variables again in claudeCode.environmentVariables.

Prerequisites

• Claude Code installed, checked here on 2.1.304
• A gateway key; for AIHubMix, from the AIHubMix console

The config

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

The $schema line is optional; it gives you validation in VS Code, Cursor and other editors. AIHubMix uses Anthropic's own model IDs, such as claude-sonnet-5-5, so the sonnet, opus and haiku aliases resolve without extra variables.

Check it

claude -p "1+1, output only the answer"

It should print 2. Then start claude in a project. The header reads something like Sonnet 5.5 · API Usage Billing, and /status shows:

Auth token:          ANTHROPIC_AUTH_TOKEN
Anthropic base URL:  https://aihubmix.com
Model:               claude-sonnet-5-5
Setting sources:     User settings

Setting sources lists every settings file that loaded, which is the fastest way to catch a file you forgot about.

Which value wins

Settings files, highest first, per Anthropic's settings precedence:

1. Managed settings from your organization
2. --settings on the command line, for that session only
3. .claude/settings.local.json (yours, this repo only)
4. .claude/settings.json (shared through git; never put a token here)
5. ~/.claude/settings.json

Environment variables add one rule: a variable in any file's env block overwrites the shell's value. The tests against AIHubMix show where that rule stops:

Setup	Result
Settings token correct; shell base URL and token wrong	Works: the settings values win
Settings token correct; old shell ANTHROPIC_API_KEY wrong	401, showing the old key's last six characters
Settings token wrong; shell ANTHROPIC_API_KEY correct	Works
Shell ANTHROPIC_MODEL set to Haiku; settings model is Sonnet	Haiku runs

The middle rows are the trap. The settings file never mentioned ANTHROPIC_API_KEY, so the shell's copy survived, Claude Code sent it alongside the token, and AIHubMix used it.

AUTH_TOKEN vs API_KEY

Variable	Sent as	Note
ANTHROPIC_AUTH_TOKEN	Authorization: Bearer	Used right away
ANTHROPIC_API_KEY	x-api-key	Asks for approval once in interactive mode

AIHubMix accepts either, and its Claude Code guide uses ANTHROPIC_AUTH_TOKEN. Pick one and remove the other from your shell profile.

Once either variable is set, requests stop using your claude.ai login and the gateway bills per token, as Anthropic's gateway guide describes. The login stays saved. ANTHROPIC_BASE_URL alone, without a credential, keeps using your subscription.

Model selection

From Anthropic's model configuration page, highest first:

1. /model <name> in a session
2. claude --model <name>
3. ANTHROPIC_MODEL
4. The model key

/model saves a new default, but if ANTHROPIC_MODEL is set, every new session starts on it again. Prefer the model key. With nothing set, Claude Code uses Opus 5.5. ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL only remap what an alias sends.

To see which model a run actually used, claude -p "..." --output-format json lists it under modelUsage.

Anthropic doesn't support Claude Code on non-Claude models, even when the gateway serves them on the same address.

When edits apply

Claude Code watches its settings files; most saved edits, including env, reach the running session. The model key, removed variables and shell exports need a restart.

VS Code

The extension checks for a login before it starts, using its own claudeCode.environmentVariables setting, so ~/.claude/settings.json alone can leave VS Code asking you to sign in. In Preferences: Open User Settings (JSON):

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

Then Developer: Reload Window. Details are in Anthropic's VS Code docs. The Claude Desktop app reads neither settings.json nor these variables.

Other variables worth knowing

Variable	Set it when
API_TIMEOUT_MS	Long requests time out (default 10 minutes)
CLAUDE_CODE_MAX_RETRIES	You want errors to show sooner
HTTPS_PROXY	You're behind an HTTP proxy
NODE_EXTRA_CA_CERTS	Your proxy uses its own root certificate

All of them work in the env block. The full list is in Anthropic's environment variables reference.

Failure modes and fixes

Not logged in · Please run /login

No credential reached Claude Code: the variable is missing, the file was skipped (next item), or the token is only in a project file. The login check runs before project settings load, so a fresh install with the token only in .claude/settings.local.json lands on Select login method:. Move it to ~/.claude/settings.json.

These settings files did not load ... Invalid or malformed JSON

A // comment or trailing comma in the named file. Nothing in that file applies, token included.

There's an issue with the selected model (...)

With a model ID that's fine, this is almost always a base URL ending in /v1: the request goes to /v1/v1/messages. Remove the /v1.

API Error: 400 The model ID you entered is: ... This model ID is incorrect

AIHubMix has no model with that ID; the message repeats the ID it received. Copy it from the AIHubMix model list.

Failed to authenticate. API Error: 401 invalid key: XXXXXX

The six characters are the end of the key AIHubMix received. PI_KEY means the placeholder AIHUBMIX_API_KEY was pasted. Anything that isn't the end of your token means another key went out, usually an old ANTHROPIC_API_KEY. If the message is this key is not enabled, check the key's status and credit in the console.

auth may not work as expected

A token variable and a saved claude.ai login are both active. /logout to keep the gateway, or remove the variable to go back to the subscription.

Claude Code doesn't recognize the model ...

A warning, not an error: the request goes out, but Claude Code assumes a 200K-token context window. For a newer Claude model, claude update clears it.

A bad key looks like a hang

Claude Code retries failed requests up to 10 times. With a wrong key, claude -p printed the 401 after 190 seconds. Set CLAUDE_CODE_MAX_RETRIES=0 while debugging and the error comes back in a couple of seconds.

Not verified here

• The VS Code extension and the Desktop app sections follow Anthropic's docs; neither was tested. Reloading the window after the edit is a suggestion, not a documented step.
• this key is not enabled and auth may not work as expected weren't reproduced.
• Tests ran mostly through claude -p in a throwaway HOME, with one AIHubMix key.

Sources

• Settings files and precedence (Anthropic)
• Environment variables (Anthropic)
• Connect Claude Code to an LLM gateway (Anthropic)
• Model configuration (Anthropic)
• Claude Code integration guide (AIHubMix)