Using OpenRouter (or a Gateway) with Claude Code

If you have used Claude Code — Anthropic's official CLI coding agent — you have probably wondered whether you can point it at a different model or provider without losing the tool-calling and context features that make it useful. Developers searching for claude code openrouter are typically asking the same question: how do I route Claude Code through a gateway or aggregator so I can use cheaper models, avoid rate limits, or avoid paying separately for each provider? This guide covers the general approach, the trade-offs you should know about, and a configuration sketch to get you started.

What Claude Code actually is

Claude Code is Anthropic's command-line agent for software development. You install it, point it at a codebase, and interact with it through natural-language instructions. Under the hood it drives the Anthropic Messages API — tool use, multi-turn context, long-context windows, and streaming are all part of how it operates. That API contract is important because it defines what any gateway sitting in front of Claude Code must support faithfully.

Out of the box Claude Code talks directly to Anthropic's API. By design, that is where the models that support its full feature set live. But developers often want to explore alternatives: a different Anthropic-compatible model from a third-party host, a gateway that provides fallback and cost accounting, or a way to route traffic without managing multiple credentials.

How to use OpenRouter with Claude Code (the general approach)

Claude Code respects environment variables and configuration that override the default API endpoint. The typical approach to use OpenRouter with Claude Code — or to point it at any compatible gateway — involves two things:

• Setting the base URL to the gateway's endpoint instead of Anthropic's default.
• Providing an API key for that gateway.

The environment variable most commonly used is ANTHROPIC_BASE_URL, which tells the underlying Anthropic SDK where to send requests. You may also need to set the model name explicitly so Claude Code does not default to a model string the gateway does not recognize. Claude Code's configuration also has settings for the model and API key.

Check Claude Code's current documentation before relying on any specific flag or config key name — the CLI is actively developed and the exact mechanism for overriding the endpoint and model can change between releases. The Anthropic Claude Code docs at docs.anthropic.com/claude/claude-code are the authoritative source for the current configuration interface.

A basic environment-variable configuration

Below is a representative shell snippet showing the pattern. Substitute the gateway URL, your key, and a model string your gateway supports:

# Point Claude Code at a gateway that speaks the Anthropic Messages API
export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_API_KEY="your-gateway-api-key"

# Optionally set the model explicitly if the gateway requires it
# (exact flag name — verify in current Claude Code docs)
# export CLAUDE_MODEL="anthropic/claude-sonnet-4-5"

claude  # or however you launch Claude Code

This pattern applies regardless of which gateway you use — OpenRouter, flo2, or any other proxy that understands the Anthropic Messages API.

The compatibility constraint that matters most

Claude Code is built on Anthropic's Messages API, not the OpenAI Chat Completions API. This distinction matters when you evaluate gateways and aggregators.

OpenRouter is primarily an OpenAI-compatible endpoint. Many clients that call it use the OpenAI format. For what is OpenRouter, the short answer is that it is a unified LLM aggregator with an OpenAI-compatible interface that routes to many models. Whether OpenRouter's Anthropic-format compatibility is complete enough for Claude Code's tool-use and streaming requirements — check OpenRouter's documentation for their current Anthropic-compatible endpoint status. Partial compatibility can cause subtle failures in agentic use cases where tool-calling schemas, streaming event formats, and stop-reason fields must all match exactly.

This is not a knock on OpenRouter. It is a practical constraint: Claude Code uses a specific slice of the Anthropic Messages API surface area, and a gateway that only approximates it may drop features silently. Always test with a real Claude Code session, not just a basic text-completion call, before relying on a gateway in production.

Why people route Claude Code through a gateway at all

Before diving further into configuration, it is worth naming the actual use cases, because they vary:

• Using a cheaper or alternative model. Claude 3 Haiku, open-weight models hosted on third-party inference providers, or experimental models not directly on Anthropic's API.
• Rate limit management. A gateway can fan requests across multiple keys or providers and retry on failure, smoothing over the TPM/RPM limits a single direct API key hits.
• Cost accounting. Routing through a gateway lets you log every request with model, token count, and cost — useful for teams tracking AI spend per project or per developer.
• Fallback. If a provider is degraded, a gateway can retry automatically on another, keeping Claude Code responsive.
• One credential for many providers. Developers who want Claude Code to route to different models at different times without manually swapping keys or config.

Claude Code custom model and base URL: key trade-offs

When you override the claude code base url or point to a claude code alternative model, you are trading off the guarantee that the full feature set works correctly. Here is what to weigh:

• Tool-use schema compatibility. Claude Code relies heavily on tool definitions and the structured JSON that comes back from the model. A gateway that modifies these schemas in transit — even subtly — can break code-editing operations.
• Streaming event format. Claude Code streams responses and parses specific event types. A gateway must pass these through faithfully, not reformat them.
• Model capability. Pointing Claude Code at a model that does not support multi-turn tool use at all — even via a gateway — will produce failures or degraded output.
• Context window. Some tasks Claude Code takes on assume a long context window. A cheaper model with a smaller window may silently truncate.

None of these are reasons to avoid gateways. They are reasons to test carefully and to choose a gateway that handles the Anthropic Messages API faithfully.

Where flo2 fits in this picture

flo2 is an LLM gateway that speaks the Anthropic Messages API natively — not a translation layer from OpenAI format. That means when Claude Code sends a request to flo2, the tool-use schema, streaming events, and message structure pass through without modification. flo2 then routes the request to whichever backend you have configured: Anthropic directly, a third-party Anthropic-compatible host, or other providers you have added.

The practical benefit for Claude Code users: you get one API key (from flo2) that can route to many models and providers, with fallback and cost accounting, while preserving the Anthropic Messages API contract that Claude Code depends on. flo2 is a OpenRouter alternative for teams who want to bring their own provider keys and pay zero markup on top of what providers charge. During Beta, flo2 is free to use — worth verifying the current terms at flo2 since beta conditions can change.

To use flo2 with Claude Code, the configuration follows the same pattern as above: set ANTHROPIC_BASE_URL to flo2's endpoint, provide your flo2 API key as ANTHROPIC_API_KEY, and you are routing through flo2 without touching the rest of your Claude Code setup.

Practical checklist before you switch base URLs

Before relying on a gateway-routed Claude Code setup in real work:

• Read Claude Code's current docs to confirm the exact env vars and config options for your version.
• Test tool use explicitly — ask Claude Code to edit a file and verify it succeeds end-to-end.
• Test streaming — a stalled or reformatted stream will make Claude Code feel broken even if text eventually arrives.
• Check whether the model you are routing to actually supports the tool-use schema Anthropic defines. Not all models do, even if they appear in a gateway's catalog.
• Verify cost accounting is working if that is part of your reason for using the gateway.

Routing Claude Code through a gateway is a real and useful pattern — it just requires a gateway that takes the Anthropic Messages API compatibility seriously. With that in place, you get the routing, fallback, and cost-visibility benefits without sacrificing the features that make Claude Code worth using in the first place.