Integration Guide: Connecting Claude Code to RouterHub

This guide explains how to configure Claude Code to use the RouterHub API gateway as its backend. RouterHub is fully compatible with the Anthropic Messages API, making it a drop-in replacement for the official API endpoint.

Below are three configuration methods, from the most stable to the most convenient. Choose the one that best fits your workflow.

Prerequisites

1. A RouterHub Account: You need an active account with a valid API key.
2. Your API Key: Locate your unique API key in the RouterHub dashboard.
3. Claude Code Installed: Ensure you have Claude Code (claude CLI) installed and accessible in your terminal.

Method 1: JSON Configuration File

This is the most stable method, ideal for long-term use. It directly modifies Claude Code's persistent settings, effectively preventing configuration loss after restarts.

File Path

vim ~/.claude/settings.json

Configuration Template

Copy the following template and replace the placeholder values with your actual RouterHub credentials:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-xxxx your RouterHub API Key",
    "ANTHROPIC_BASE_URL": "https://api.routerhub.ai",
    "ANTHROPIC_MODEL": "anthropic/claude-opus-4.6"
  },
  "apiKeyHelper": "echo 'sk-xxxx your RouterHub API Key'",
  "primaryModel": "anthropic/claude-opus-4.6"
}

Key Details

Method 2: Environment Variables

Environment variables override the JSON configuration file. This is the best choice for CI/CD pipelines or quick testing without modifying files.

Run in Terminal (macOS / Linux)

# Set your RouterHub API key, base URL and model
export ANTHROPIC_API_KEY="your_RouterHub_API_KEY"
export ANTHROPIC_BASE_URL="https://api.routerhub.ai"
export ANTHROPIC_MODEL="anthropic/claude-opus-4.6"

# Launch Claude Code
claude

Persist Across Sessions

To make these variables permanent, add the export statements to the end of your shell configuration file:

# Add to ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your_RouterHub_API_KEY"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.routerhub.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="anthropic/claude-opus-4.6"' >> ~/.zshrc

# Reload the configuration
source ~/.zshrc

# Add to ~/.bashrc
echo 'export ANTHROPIC_API_KEY="your_RouterHub_API_KEY"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.routerhub.ai"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="anthropic/claude-opus-4.6"' >> ~/.bashrc

# Reload the configuration
source ~/.bashrc

Method 3: Interactive Commands

If you are already inside the claude interface, you can inspect and adjust the configuration using built-in slash commands. This is ideal for quick adjustments without leaving the session.

Available Commands

Quick Verification Flow

1. Launch claude in your terminal.
2. Type /status — verify it shows your RouterHub API key, not an OAuth account.
3. If not, type /config and enable "Use custom API key".
4. If still stuck, type /logout, close the session, re-export your environment variables, and restart.

Verifying the Configuration

After completing any of the methods above, verify that Claude Code is properly routed through RouterHub:

1. Start a new claude session in your terminal.
2. Type /status to confirm the API key and base URL point to RouterHub.
3. Run a simple prompt (e.g., "Hello, which model are you?") and confirm a successful response.

A successful /status output should look like this:

Troubleshooting

Claude Code Keeps Falling Back to OAuth Login

This usually means the API key is not being picked up. Ensure you have set apiKeyHelper in ~/.claude/settings.json as shown in Method 1. This is the most reliable fix.

Configuration Lost After Restart

If you only set environment variables in the current terminal session, they will be lost when you close it. Either use the JSON file method (Method 1) or persist the variables in your shell configuration file (Method 2).

Error: "Invalid API Key"

Double-check that your RouterHub API key is correct and active. You can verify it in the RouterHub dashboard.

Error: "Connection Refused" or "Timeout"

Ensure that ANTHROPIC_BASE_URL is set to https://api.routerhub.ai and that your network allows outbound connections to this endpoint.

Model Not Found

Verify that the model name in your configuration matches a model available through RouterHub. Check the Models page for the full list of supported models.