Intelligent LLM Routing for Claude Code

How Claude Code connects to an LLM router

Claude Code talks to models in the Anthropic Messages format. By default it calls Anthropic directly, but its ANTHROPIC_BASE_URL environment variable lets you point it at a gateway or router instead. Claude Code then sends its requests to /v1/messages on that address, and the router decides which model answers.

Anthropic's gateway documentation lists what a gateway has to do for Claude Code to work well. It must stream responses as they arrive (a gateway that buffers makes Claude Code stall), pass the cache_control field through so prompt caching keeps working, and forward error bodies unchanged. Air Router takes Claude Code's requests at the bare domain, https://api.airllm.ai/; Claude Code adds /v1/messages itself.

What Anthropic says about gateways

Before you set this up, know Anthropic's stated position. Its LLM gateway documentation says: "Any gateway that exposes a supported API format works. Anthropic doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway."

In practice that gives you two choices with Air Router:

• airllm-anthropic keeps every request inside Anthropic's Claude family while Air Router still picks the appropriate Claude model for each request. This is the closest match to what Anthropic describes.
• airllm-auto routes across supported providers, so some requests may be answered by non-Claude models. It is the setting the Developer Guide uses, and it is outside what Anthropic supports for Claude Code.

Either way, use your AirLLM API key as ANTHROPIC_AUTH_TOKEN. Claude Code sends that token as a bearer credential, so requests are billed to your AirLLM account rather than drawing on a Claude subscription. Don't set only the base URL: Anthropic's terms don't allow routing claude.ai plan credentials through a third party, and AirLLM never needs them.

Set up Claude Code with Air Router

The quickest route is the AirLLM setup script, which writes these settings to ~/.claude/settings.json for you. To do it by hand on macOS or Linux:

1. Check Claude Code is installed

   Run claude --version in a terminal.

2. Add the variables to your shell profile

   Open ~/.zshrc (or ~/.bashrc on most Linux systems) and add the lines below, with your own key.

3. Reload and start Claude Code

   Run source ~/.zshrc, check the address with echo $ANTHROPIC_BASE_URL, then start claude.

export ANTHROPIC_BASE_URL="https://api.airllm.ai/"
export ANTHROPIC_AUTH_TOKEN="your_airllm_api_key"
export ANTHROPIC_MODEL="airllm-auto"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="airllm-auto"
export ANTHROPIC_DEFAULT_SONNET_MODEL="airllm-auto"
export ANTHROPIC_DEFAULT_OPUS_MODEL="airllm-auto"
export ANTHROPIC_DEFAULT_FABLE_MODEL="airllm-auto"
export CLAUDE_CODE_SUBAGENT_MODEL="airllm-auto"
export CLAUDE_CODE_SUBAGENT_MODEL_FORCE="1"
export API_TIMEOUT_MS="3000000"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

On Windows, the Developer Guide's Claude Code section has the PowerShell version, and WSL uses the steps above inside WSL.

Choose airllm-auto or airllm-anthropic

The extra model lines matter. Claude Code uses separate model settings for its background tasks and subagents; if they still name Anthropic models, those requests fail with "model not found". Set every model line to the same routing model.

To use airllm-anthropic, replace airllm-auto in every model line of the snippet. The routing models page describes all six names.

Check that it works

Send a small test prompt, such as "Write a simple Java method to validate an email address." Then open your AirLLM dashboard: the request should appear in your usage logs. If nothing shows up, Claude Code is still talking to another endpoint, usually because the shell was not reloaded or a different terminal is open.

Note. Anthropic's docs say that with a non-Anthropic base URL, Claude Code turns MCP tool search off by default (set ENABLE_TOOL_SEARCH=true to turn it back on) and disables Remote Control.

What changes when Claude Code goes through Air Router

Your commands, slash commands, permissions and workflow stay the same. What changes is where the model requests go. Air Router routes each step of the agent's work to a suitable model, so a file search doesn't need the same model as an architecture decision. It considers existing prompt caches before switching models, reduces repeated file content and completed tool history before a request reaches the model, and is designed to interrupt unproductive agent loops. For the broader idea, see what an AI coding agent router is.

Claude Code cost habits that still matter

Routing helps, but how you use Claude Code still shapes the bill. Anthropic's own advice holds with any backend:

• Use /clear between unrelated tasks, and /compact with a focus instruction when a session gets long.
• Keep CLAUDE.md short; Anthropic suggests under 200 lines, with longer workflows moved into skills.
• Disable MCP servers you aren't using, and write specific prompts.

Our guide on how to reduce Claude Code costs covers these in more detail.

Troubleshooting

• 404 Not Found: the base URL is wrong. Claude Code takes https://api.airllm.ai/ without /v1.
• 401 Unauthorized: the key is missing or wrong. Check ANTHROPIC_AUTH_TOKEN.
• Model not found: one of the model lines still names another model. Set them all to an airllm-* name.
• No request in your AirLLM logs: the variables aren't loaded in this terminal, or you're in Windows instead of WSL (or the reverse).

The full list is in the Developer Guide's troubleshooting section.

Frequently asked questions

Related

Sources

• Claude Code docs — LLM gateway configuration
• Claude Code docs — LLM gateway protocol requirements
• Claude Code docs — environment variables
• Claude Code docs — manage costs effectively
• Claude Code docs — legal and compliance