Claude Code

Claude Code is Anthropic’s coding agent. It runs in your terminal (and in IDEs such as VS Code), reads and edits your code and runs commands. It calls models over the Anthropic Messages protocol; point it at NoviaHub and it uses your NoviaHub balance.

Rather not edit config files?

Once Claude Code is installed, CC Switch can import the settings from NoviaHub’s API Keys page in one click, and you can skip “Configure NoviaHub” below.

Prerequisites

• A NoviaHub API key (see API Keys) and some balance (see Wallet and top-ups).
• macOS 13+, Windows 10 1809+ or Windows Server 2019+, Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+, with 4 GB of RAM or more.

Install

The native installer is the recommended method (it updates itself):

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Other official methods (these do not update themselves):

• Homebrew: brew install --cask claude-code
• WinGet: winget install Anthropic.ClaudeCode
• npm: npm install -g @anthropic-ai/claude-code (needs Node.js 22 or later; the docs advise against sudo)

Check the installation with:

claude --version
claude doctor

Configure NoviaHub

Claude Code appends /v1/messages to the address itself, so use https://noviahub.com without /v1.

Option 1: settings.json (recommended, permanent)

1. Open (or create) your user settings file:

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

2. Add the following, replacing sk-... with your NoviaHub key. If the file already has other settings, merge these keys into its env block:

   ~/.claude/settings.json

   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://noviahub.com",
       "ANTHROPIC_AUTH_TOKEN": "sk-...",
       "ANTHROPIC_MODEL": "claude-sonnet-5",
       "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
       "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
       "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
     }
   }

   Setting	Purpose
   ANTHROPIC_BASE_URL	The API address: https://noviahub.com.
   ANTHROPIC_AUTH_TOKEN	Your NoviaHub key, sent as an Authorization: Bearer header; takes effect immediately.
   ANTHROPIC_MODEL	The default model.
   ANTHROPIC_DEFAULT_OPUS_MODEL / _SONNET_MODEL / _HAIKU_MODEL	Optional. Which model the opus / sonnet / haiku aliases map to; the haiku tier is also used for background tasks.

3. Save the file, open a new terminal and run claude.

Caution

• Values in settings.json are used literally; you cannot write an environment variable reference such as $NOVIAHUB_API_KEY.
• Only put the key in this user-level file, never in a project’s .claude/settings.json, which may end up in a repository.
• According to the docs, values in settings.json take precedence over variables of the same name exported in your shell.

Keep the key out of the file

Store the key in the environment variable NOVIAHUB_API_KEY (see the start of Option 2), then let settings.json read it with apiKeyHelper instead of ANTHROPIC_AUTH_TOKEN:

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://noviahub.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  },
  "apiKeyHelper": "printenv NOVIAHUB_API_KEY"
}

apiKeyHelper is a command whose output is used as the key and sent in both the Authorization and x-api-key headers; since Claude Code v2.1.227 it must print only the key. The Claude Code config generated under API access on NoviaHub’s model pages uses this form, but names the variable NEW_API_KEY. The two differ only in name; pick one and use it consistently.

Option 2: set variables in the terminal

Good for a quick try. First store the key permanently in NOVIAHUB_API_KEY, then set the ANTHROPIC_* variables, which only last for the current terminal window:

macOS / Linux / WSL

# macOS uses zsh by default; with bash on Linux, use ~/.bashrc instead of ~/.zshrc
echo 'export NOVIAHUB_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

export ANTHROPIC_BASE_URL="https://noviahub.com"
export ANTHROPIC_AUTH_TOKEN="$NOVIAHUB_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

Windows PowerShell

# Stores the key permanently; setx does not affect the current window, so open a new PowerShell window
setx NOVIAHUB_API_KEY "sk-..."

# In the new window:
$env:ANTHROPIC_BASE_URL = "https://noviahub.com"
$env:ANTHROPIC_AUTH_TOKEN = $env:NOVIAHUB_API_KEY
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
claude

Verify

1. Run claude, type /status and press Enter.

2. On the Status tab you should see an Anthropic base URL line showing https://noviahub.com, and a line naming the variable the key comes from (for example ANTHROPIC_AUTH_TOKEN).

3. Ask anything. A normal answer means it works; the call and its cost appear under Usage Logs in the NoviaHub console.

Switch models

Claude Code picks the model in this order (highest first):

1. /model <model ID> typed in a session, for example /model claude-opus-5;
2. the launch option claude --model <model ID>;
3. the environment variable ANTHROPIC_MODEL;
4. the model setting in settings.json.

The model must support Anthropic Messages: open it under Models & Pricing and check that its endpoint labels include Anthropic. On 2026-09-28 the Claude models with that label on NoviaHub were claude-opus-5-5, claude-opus-5, claude-sonnet-5, claude-haiku-4-5, claude-fable-5-1, claude-fable-5 and claude-opus-4-8. Models change; the model page is authoritative.

The docs say that with a custom gateway address, Claude Code sends whatever model ID you give it without checking it. Some non-Claude models on NoviaHub (for example gpt-6-sol and deepseek-v4-flash) also carry the Anthropic label and can be called over this protocol, but Claude Code’s docs say nothing about how well non-Claude models work, so test features such as tool use yourself.

By default the /model picker does not load models from the gateway. With CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, Claude Code requests NoviaHub’s /v1/models, but keeps only IDs that contain claude or anthropic.

Troubleshooting

An auth conflict warning This appears if you signed in to Claude Code with a claude.ai account before. Run /logout in Claude Code to sign out of it.

400 errors about unknown fields Add "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1" to the env block in settings.json to turn off experimental features, then try again.

401 Invalid token The key is wrong, or it is disabled, expired or out of quota. Check its status on the API Keys page; see API Keys.

403 insufficient_user_quota Your account balance has run out. Top up first.

Some features are unavailable According to the docs, Remote Control and voice dictation are unavailable with gateway credentials, and Slack and cloud sessions always use Anthropic.

Using the VS Code extension According to the docs, the VS Code extension takes these variables from claudeCode.environmentVariables in VS Code’s user settings; see the official page under References for the format.

References

Checked on 2026-09-28:

• Setup and requirements: https://code.claude.com/docs/en/setup
• Connecting to an LLM gateway: https://code.claude.com/docs/en/llm-gateway-connect
• Gateway protocol requirements: https://code.claude.com/docs/en/llm-gateway-protocol
• Model configuration: https://code.claude.com/docs/en/model-config
• setx (Windows): https://learn.microsoft.com/windows-server/administration/windows-commands/setx