Claude Code + TheRouter.ai: Environment Variable Setup

Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN to route all Claude Code traffic through TheRouter in four steps

Claude Code uses Anthropic's native Messages API. TheRouter.ai provides a fully compatible /v1/messages endpoint, so you only need to override a few environment variables to route all Claude Code traffic through TheRouter. This guide walks you through setup in four steps.

Key difference from other tools

Claude Code uses the Anthropic SDK internally, so its base URL should point to https://api.therouter.ai (the root domain), not https://api.therouter.ai/v1. This is different from OpenAI-compatible tools like Cursor.

Step 1 — Install Claude Code

If you haven't installed Claude Code yet:

install.sh

npm install -g @anthropic-ai/claude-code

Step 2 — Configure environment variables

Claude Code reads model and endpoint settings from environment variables or from ~/.claude/settings.json. Set the gateway URL, your API key, and the model aliases for all three tiers that Claude Code uses.

Use Anthropic-native model names

Claude Code validates the ANTHROPIC_MODEL variable against its internal list of known Anthropic models. Use the Anthropic-native format (e.g. claude-sonnet-4-6), not TheRouter's brand/model-name format. TheRouter automatically resolves these names when the request arrives.

Shell

export THEROUTER_API_KEY="sk-..."

# Point Claude Code at TheRouter
export ANTHROPIC_BASE_URL="https://api.therouter.ai"
export ANTHROPIC_AUTH_TOKEN="$THEROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

# Model names (all three tiers — use Anthropic-native format)
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

What each variable does

ANTHROPIC_BASE_URL — redirect all Anthropic SDK requests to TheRouter
ANTHROPIC_AUTH_TOKEN — your TheRouter API key (used as the Bearer token)
ANTHROPIC_API_KEY — set to empty string to prevent fallback to a direct Anthropic account
ANTHROPIC_MODEL — the default model for normal tasks (Sonnet tier)
ANTHROPIC_DEFAULT_HAIKU_MODEL — the model for lightweight/fast tasks (Haiku tier)
ANTHROPIC_DEFAULT_OPUS_MODEL — the model for complex reasoning tasks (Opus tier)

Step 3 — Verify the configuration

Open a new terminal window (so the env vars take effect), launch Claude Code, and type /status to confirm everything is connected:

bash

claude
# inside Claude Code, type:
/status

What success looks like

The status panel should show your TheRouter base URL and the model aliases you configured:

StatusConfigUsage

Model: claude-sonnet-4-6

Small/fast model: claude-haiku-4-5

Opus model: claude-opus-4-6

API base: https://api.therouter.ai

If the model names don't match

If the status shows date-suffixed names like claude-sonnet-4-5-20250514 instead of your configured model names, the override variables did not take effect. Make sure you opened a new terminal after setting them, or verify the settings.json path is correct (~/.claude/settings.json).

Step 4 — Install TheRouter Skill (optional)

Install the TheRouter skill so Claude Code understands the full API surface — model catalog, routing strategies, fallbacks, debugging, and more. This is a local reference file, no data is sent externally.

Install

curl -fsSL https://www.therouter.ai/ai/skill/install.sh | bash

After installation, try asking Claude Code:

text

> Help me integrate with TheRouter API
> Which model is cheapest for summarization?
> Debug my TheRouter 429 error
> Set up model fallbacks for my chatbot

Managing multiple local coding clients?

If Claude Code is only one client in a broader local workflow, open the cc-switch guide and use TheRouter presets there instead of hand-editing every client config.

Troubleshooting

/status still shows the original Anthropic model

Environment variables are read at launch time. You must open a new terminal after exporting them, then run claude again. If using settings.json, verify the file is at ~/.claude/settings.json (not inside a project directory).

Requests work but aren't going through TheRouter

If you forgot to set ANTHROPIC_API_KEY="", Claude Code may silently fall back to a direct Anthropic connection using any existing key on your system. Always set it to an empty string explicitly.

Error: "There's an issue with the selected model"

Claude Code validates ANTHROPIC_MODEL against its internal list of known Anthropic models. If you use TheRouter's brand/model-name format (e.g. anthropic/claude-sonnet-4.6), Claude Code will reject it. Use the Anthropic-native format instead: claude-sonnet-4-6. TheRouter resolves these names automatically.

Error: "model not found" or 404

Verify the model is available on TheRouter by running curl https://api.therouter.ai/v1/models -H "Authorization: Bearer $THEROUTER_API_KEY". Avoid using date-suffixed upstream names like claude-sonnet-4-6-20250514 — use the base name without dates (e.g. claude-sonnet-4-6).

Base URL confusion with other tools

Claude Code (Anthropic SDK) uses https://api.therouter.ai as the base URL. OpenAI-compatible tools (Cursor, Windsurf, Cline) use https://api.therouter.ai/v1. Mixing these up will cause connection failures.

Caveats

Use the root base URL only for Anthropic-native clients such as Claude Code and the Anthropic SDK. Raw HTTP integrations can call /v1/messages directly, and Anthropic SDKs should keep using https://api.therouter.ai as the base URL.

Coding Tools Setup

cc-switch Integration