Claude Code with AIXHUB

Use this guide to connect the Claude Code command-line client to an Anthropic-compatible model routed by AIXHUB. Start with temporary environment variables, make one read-only request, and only then save the configuration at user level.

What you will accomplish

By the end of this guide, you will have:

1. Installed the official Claude Code command-line client.
2. Tested AIXHUB in one terminal without changing permanent settings.
3. Saved a complete user-level settings.json configuration.
4. Confirmed a read-only request in AIXHUB Usage.
5. Kept a clear path to restore the previous configuration.

System requirements

• Windows with PowerShell, or macOS/Linux with Bash or zsh. macOS typically uses zsh as its default interactive shell.
• Permission to install software for your user account and run claude from a terminal.
• An AIXHUB account, an AIXHUB API key, and an Anthropic-compatible model ID copied from Available channels. This guide uses panel-model-id wherever a model ID is needed.
• A backup of an existing Claude Code user settings file before you edit it.

Claude Code reads user settings from these locations:

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

Install

macOS and Linux

Run the official installer:

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

Windows PowerShell

Run the official PowerShell installer:

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

Open a new terminal after installation, then confirm the executable is available:

claude --version

Resolve installation or PATH errors before adding AIXHUB settings. This separates a client installation problem from a provider configuration problem.

AIXHUB configuration

Test in the current terminal

On macOS or Linux, use the block for the shell you are actually running. macOS typically defaults to zsh. Both versions read the key without echoing it or placing the real value in shell history.

Bash

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export ANTHROPIC_BASE_URL="https://api.aixhub.org"
export ANTHROPIC_AUTH_TOKEN="$AIXHUB_KEY"
export ANTHROPIC_API_KEY="$AIXHUB_KEY"
export ANTHROPIC_MODEL="panel-model-id"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export ANTHROPIC_BASE_URL="https://api.aixhub.org"
export ANTHROPIC_AUTH_TOKEN="$AIXHUB_KEY"
export ANTHROPIC_API_KEY="$AIXHUB_KEY"
export ANTHROPIC_MODEL="panel-model-id"
unset AIXHUB_KEY

On Windows PowerShell, read a SecureString, convert it only for the current process environment, and remove the temporary PowerShell variables:

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:ANTHROPIC_BASE_URL = "https://api.aixhub.org"
$env:ANTHROPIC_AUTH_TOKEN = $plainKey
$env:ANTHROPIC_API_KEY = $plainKey
$env:ANTHROPIC_MODEL = "panel-model-id"
Remove-Variable plainKey, secureKey

ANTHROPIC_BASE_URL must be exactly https://api.aixhub.org for Claude Code. Do not append /v1; the client adds the Anthropic API path itself. Both token variables use the same AIXHUB key, while ANTHROPIC_MODEL fixes the route to panel-model-id.

These process environment values last only for the current terminal session. Close that session after the test to clear the key and model variables from its environment.

Save the user-level configuration

After the temporary test succeeds, back up the existing settings file and merge the following env object into it. If the file does not exist, this is the complete file:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aixhub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key",
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_MODEL": "panel-model-id"
  }
}

Use %USERPROFILE%\.claude\settings.json on Windows and ~/.claude/settings.json on macOS or Linux. Preserve any unrelated top-level properties when merging an existing file, keep valid JSON syntax, and restart every Claude Code process after saving.

First run

Change to a small test repository, start the client with an explicit model, and avoid granting write access for the first request:

claude --model panel-model-id

The command-line flag and ANTHROPIC_MODEL now agree on panel-model-id; do not rely on an interactive default. Give Claude Code this bounded task:

Inspect the current directory without changing any file. Reply with OK only.

Review any permission request before approving it. A first run does not need file edits, shell commands that change state, or access outside the test repository.

Verification

A successful response should contain this actual output:

OK

Then open AIXHUB Usage and confirm that a new Anthropic-compatible request appears with panel-model-id. Check that its time matches the test, that the launch command and ANTHROPIC_MODEL selected the same model, and that the request did not go directly to an official Anthropic account.

Troubleshooting

401 or authentication failed

• Confirm that both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY receive the same current AIXHUB key in the terminal or settings.json used to launch Claude Code. Do not print either value while checking.
• Do not use an AIXHUB dashboard password or an official Anthropic account token.
• Restart Claude Code after changing the variables. A running process does not inherit later shell changes.

Model unavailable or model not found

Copy the exact model ID again from Available channels, set ANTHROPIC_MODEL to panel-model-id, launch with claude --model panel-model-id, and confirm that the route supports Anthropic-compatible requests. Do not shorten the ID or guess a version suffix.

Claude Code still uses official Anthropic

Check ANTHROPIC_BASE_URL and ANTHROPIC_MODEL in the terminal that starts Claude Code, but do not print either token variable. Also check the loaded settings.json. The Base URL must be https://api.aixhub.org without /v1. Fully close terminal sessions, editor integrations, and background Claude Code processes before retrying.

A different configuration wins

Temporary shell variables, user settings, managed settings, and editor integrations can provide all four ANTHROPIC_* names. Remove stale values or make them consistent, including ANTHROPIC_MODEL, then start a fresh process. If the response is 403, 429, 502, or 503, use the error code reference to distinguish access, rate, and upstream failures.

Upgrade and restore

Check the current version before and after an upgrade:

claude --version
claude update
claude --version

If claude update is unavailable, rerun the same official installer used above. The installer command does not require changing the AIXHUB settings.

To restore the previous setup, close Claude Code, restore the backup of settings.json, or delete only ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL from its env object. Also remove the four variables from shell profiles if you added them there, and close the temporary terminal session to clear its process environment. Open a new terminal and run claude --version before choosing a different provider.

Security

• Treat sk-your-key as a stand-in for a secret. Never commit the real value, paste it into a prompt, or include it in support logs.
• Keep settings.json in the user profile rather than the repository, and restrict it to the user account where the operating system supports file permissions.
• For temporary tests, enter the key through the non-echoing prompt shown above; never place the real value directly in a command that shell history records.
• Use a dedicated AIXHUB key for Claude Code so it can be revoked without affecting other clients.
• Rotate the key immediately if it appears in terminal history, a screenshot, a patch, or a shared log.
• Review tool permissions on every unfamiliar repository, even after the network route is verified.

Official sources

• Claude Code setup
• Claude Code settings

Last verified: 2026-07-14