Claude Code settings.json and Environment Variables: Base URL, Auth Token and Model

Claude Code takes its configuration from JSON settings files and from environment variables. To run it through a gateway instead of Anthropic's API, you need two variables, ANTHROPIC_BASE_URL and a token, and usually a model. The variables are simple. What confuses people is where to put them, because the same variable can sit in your shell profile, in several settings.json files and in VS Code's settings.

This guide starts with a setup that works, then explains where the files live, which value wins, and the errors you're likely to see. It was checked against Anthropic's docs and tested with AIHubMix on Claude Code 2.1.304 on October 20, 2026. The examples use AIHubMix as the gateway; any Anthropic-compatible endpoint is set up the same way.

The short version

• Your personal settings file is ~/.claude/settings.json, or %USERPROFILE%\.claude\settings.json on Windows.
• For a gateway, put ANTHROPIC_BASE_URL (without /v1) and ANTHROPIC_AUTH_TOKEN in that file's env block.
• A value in a settings file's env block overrides the same variable exported in your shell.
• Once a token is set, requests stop using your Claude subscription and are billed by the gateway.
• The VS Code extension needs the same variables in its own claudeCode.environmentVariables setting.

A working AIHubMix setup

1. Create a key in the AIHubMix console.
2. Put this in ~/.claude/settings.json. Create the file if it doesn't exist.

{
  "$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"
}

3. Run a quick test:

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

4. Start claude in a project. The header under the logo should read something like Sonnet 5.5 · API Usage Billing, and /status shows your gateway on the Anthropic base URL line.

Two details matter. The base URL is the root address: Claude Code adds /v1/messages itself, so a URL ending in /v1 breaks every request. And AIHubMix uses Anthropic's own model IDs, such as claude-sonnet-5-5, so the sonnet, opus and haiku shortcuts work without extra setup.

The $schema line is optional. It lets VS Code, Cursor and other editors flag mistakes in the file as you type.

You can export the same two variables in your shell instead, but a settings file is the better home: every terminal, the IDE extensions and background agents read it.

Where the settings files live

Never put a token in the project's .claude/settings.json, since it's committed to git. Use your user file or .claude/settings.local.json.

Settings files must be valid JSON. A // comment or a trailing comma makes Claude Code skip the whole file, token included, and you'll see the login screen instead of your gateway.

Don't confuse these with ~/.claude.json, a single file in your home folder. That one stores Claude Code's own state, such as your login and MCP servers, and you rarely need to edit it.

Which value wins

When several files set the same thing, Anthropic's settings precedence applies, highest first:

1. Managed settings from your organization
2. --settings on the command line, for that session only
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

For environment variables, one more rule: a variable in a settings file's env block overwrites the same variable from your shell. So an export ANTHROPIC_BASE_URL=... in ~/.zshrc does nothing while a settings file sets it too. Provider-switching tools usually write to ~/.claude/settings.json, which is why they win over your shell.

Inside Claude Code, /status lists the files it loaded on its Setting sources line.

ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY

Use the one your gateway reads. AIHubMix accepts both, and its Claude Code guide uses ANTHROPIC_AUTH_TOKEN, which is also the simpler choice. Don't leave both set. Claude Code then sends both headers, and AIHubMix checks x-api-key first: in our test, a correct token in settings.json still got a 401 because an old ANTHROPIC_API_KEY was exported in the shell. The env block only overrides the variables it sets, so remove the old key from your shell profile when you switch.

What about your Claude subscription? According to Anthropic's gateway guide, once a token or API key variable is set, requests use it instead of your claude.ai login, and the gateway bills per token. Your login stays saved and comes back when you remove the variable. Setting only ANTHROPIC_BASE_URL, with no token, keeps using your subscription.

Choosing the model

Anthropic's model configuration page gives this order, highest first:

1. /model <name> during a session
2. claude --model <name> at startup
3. The ANTHROPIC_MODEL variable
4. The model key in a settings file

/model saves your choice as the new default. If ANTHROPIC_MODEL is set, though, every new session starts on it again. If you switch models often, set the model key and leave ANTHROPIC_MODEL out. With no model set anywhere, Claude Code uses Opus 5.5.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL change which model each shortcut sends. You only need them if you want a shortcut to point somewhere else, for example to keep sonnet on an older version.

AIHubMix also serves other vendors' models on the same address, but Anthropic doesn't support Claude Code on non-Claude models, so some features may not work with them.

When changes take effect

Claude Code watches its settings files, and most saved edits, including the env block, apply to the running session. The model key, removed variables and shell exports need a restart. When in doubt, restart Claude Code.

The VS Code extension

The extension reads the same settings files, but it checks for a login before it starts, using its own claudeCode.environmentVariables setting. That's why VS Code can ask you to sign in while the CLI works. Open Preferences: Open User Settings (JSON) from the Command Palette and add:

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

Then run Developer: Reload Window. More options are in Anthropic's VS Code docs. The Claude Desktop app is separate: it reads neither settings.json nor these variables.

Other useful variables

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

Common errors and what they mean

Not logged in · Please run /login, or the login screen on first launch
Claude Code found no token. Check three things: a JSON mistake that made it skip the file, a missing ANTHROPIC_AUTH_TOKEN, or a token that's only in a project file. The login step runs before project settings load, so move the token to ~/.claude/settings.json.

Invalid or malformed JSON
The file named in the message has a comment, a trailing comma or another syntax error, and none of its settings were applied.

There's an issue with the selected model (...)
Either the model ID is wrong, or the base URL ends in /v1 and the request went to /v1/v1/messages. Check the URL first if the model ID looks right.

API Error: 400 with This model ID is incorrect
AIHubMix has no model with that ID, and the message repeats the ID it received. Usually it's a typo. Copy the ID from the AIHubMix model list again.

Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix doesn't accept the key. The message ends with the last six characters of the key it received, so compare them with the end of your token. PI_KEY means the placeholder AIHUBMIX_API_KEY was pasted instead of a real key. Anything else usually means an old ANTHROPIC_API_KEY from your shell went out. If the message says this key is not enabled instead, check in the AIHubMix console that the key is enabled and has credit.

auth may not work as expected
A token variable and a saved claude.ai login are both active. Run /logout to keep the gateway, or remove the variable to go back to your subscription.

Claude Code doesn't recognize the model ...
A warning, not an error: the request still goes out, but Claude Code assumes a 200K-token context window. If the ID is a newer Claude model, claude update clears it.

It seems to hang with a bad key
Claude Code retries failed requests up to 10 times. In a test with a key that always failed, claude -p kept retrying for about three minutes. Lower CLAUDE_CODE_MAX_RETRIES to see the error sooner.

If you want one key for Claude in Claude Code, and for OpenAI, Google and other vendors in your other tools, AIHubMix serves the Anthropic API at https://aihubmix.com. The settings file above is all Claude Code needs.

FAQ

Where is Claude Code's settings.json?
Your personal file is ~/.claude/settings.json, or %USERPROFILE%.claude\settings.json on Windows. A project can also have .claude/settings.json, shared through git, and .claude/settings.local.json, which is only yours. Claude Code doesn't create them on install.

Does settings.json override environment variables?
Yes. A value in a settings file's env block overwrites the same variable exported in your shell. Variables the file doesn't set, such as an old ANTHROPIC_API_KEY, still come from the shell.

Should I use ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY?
Use the one your gateway reads. ANTHROPIC_AUTH_TOKEN sends a Bearer token and needs no approval. For AIHubMix, ANTHROPIC_AUTH_TOKEN is the documented choice. Don't set both: AIHubMix reads x-api-key first, so a stale ANTHROPIC_API_KEY causes a 401.

Should ANTHROPIC_BASE_URL end with /v1?
No. Claude Code adds /v1/messages itself. For AIHubMix, use https://aihubmix.com.

Do I need to restart Claude Code after editing settings.json?
Most edits, including env changes, apply when you save. The model key and shell exports need a restart. Restarting is the safe choice.

Why does VS Code ask me to sign in when the CLI works?
Before it starts, the extension checks for a login using its claudeCode.environmentVariables setting, and values in ~/.claude/settings.json don't reach that check. Add the base URL and token there and reload the window.

Does setting ANTHROPIC_BASE_URL use my Claude subscription?
Only if no token is set. With ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY set, requests use that key and the gateway bills per token.

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