Claude Code CLI natively supports routing through OpenRouter, giving you access to a wide variety of models beyond Anthropic's own — including free-tier models, community models, and alternative providers.
How It Works
Claude Code uses the Anthropic SDK under the hood. By overriding the base URL and authentication token, you can point it at OpenRouter's API endpoint. The CLI then uses whatever model you specify via the ANTHROPIC_MODEL environment variable.
Required Configuration
All configuration lives in .claude/settings.json (project-level) or settings.local.json (user-level, gitignored). Below are the parameters you need:
1. ANTHROPIC_BASE_URL
Set to OpenRouter's API endpoint:
https://openrouter.ai/apiOpenRouter's official base URL for OpenAI SDK compatibility is
https://openrouter.ai/api/v1, but Claude Code's Anthropic SDK routes to/api(which resolves to the same endpoint internally).
2. OPENROUTER_API_KEY
Your OpenRouter API key. Get one from openrouter.ai/keys.
Format: sk-or-v1-xxxxxxxxxxxx
3. ANTHROPIC_AUTH_TOKEN
Same as your OpenRouter API key. Claude Code uses this for authentication when talking to the configured base URL.
4. ANTHROPIC_API_KEY
Leave this empty. When routing through OpenRouter, the standard Anthropic API key is not needed.
5. ANTHROPIC_MODEL
The model identifier as used on OpenRouter, in the format provider/model-name. Examples:
| Model | Identifier |
|---|---|
| DeepSeek V4 Flash (free) | deepseek/deepseek-v4-flash:fre |
| DeepSeek V3 | deepseek/deepseek-chat |
| Claude Opus 4.7 | anthropic/claude-opus-4-7 |
| Claude Sonnet 4.6 | anthropic/claude-sonnet-4-6 |
| Gemini 2.5 Pro | google/gemini-2.5-pro |
| GPT-4o | openai/gpt-4o |
Free model suffix: OpenRouter uses
:fresuffix for free/no-rate-limit models. Without it, a model may require a paid account or credits.Tilde prefix: You can use
~as a prefix (e.g.,~openai/gpt-latest) to let OpenRouter resolve to the latest version of a model family.
Example Configuration
.claude/settings.json:
{
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-v1-your-key-here",
"ANTHROPIC_API_KEY": "",
"ANTHROPIC_MODEL": "deepseek/deepseek-v4-flash:fre"
}
}Step-by-Step Setup
- Get an OpenRouter key — Sign up at openrouter.ai and create an API key.
- Find a model — Browse openrouter.ai/models to pick one. Copy its slug (e.g.,
deepseek/deepseek-v4-flash:fre). - Create or edit settings — Open
.claude/settings.jsonin your project (or~/.claude/settings.jsonfor global config). - Add the environment variables — Use the template above, replacing the key and model.
- Run Claude Code — Start the CLI as usual:
claude
Where to Put Settings
| Scope | File | Git-tracked? | Use Case |
|---|---|---|---|
| Project | .claude/settings.json |
Yes | Team-wide model config |
| Local override | .claude/settings.local.json |
No (gitignored) | Personal keys, local overrides |
| Global | ~/.claude/settings.json |
No | User-wide default for all projects |
Settings are merged in order: global → project → local. Local overrides take highest priority.
App Identification (OpenRouter Headers)
When making direct API calls to OpenRouter, you can identify your app using these optional headers. They help your app appear on openrouter.ai/rankings leaderboards.
| Header | Purpose | Example |
|---|---|---|
HTTP-Referer |
Your site/app URL for rankings | https://myapp.com |
X-Title (or X-OpenRouter-Title) |
Your site/app display name | My CLI App |
These headers are not directly configurable in Claude Code's settings.json, but they're useful if you're building tools or scripts on top of OpenRouter directly.
OpenRouter API Features
Model Fallbacks
OpenRouter supports specifying multiple models as fallbacks. If the primary model fails or is unavailable, it automatically tries the next one in the list. This is available via the OpenRouter SDK but not directly in Claude Code's config — useful for custom integrations.
Provider Routing
OpenRouter routes requests across multiple infrastructure providers. You can control this with the following options:
| Option | Values | Description |
|---|---|---|
sort | price (default), throughput, latency | How to select provider |
only | ["anthropic"], ["google"], etc. | Restrict to specific providers |
ignore | ["deepinfra"], etc. | Skip specific providers |
order | ["anthropic", "google"] | Try providers in priority order |
data_collection | deny | Exclude providers that may train on your data |
Listing Available Models
curl https://openrouter.ai/api/v1/models \
-H "Authorization: Bearer $OPENROUTER_API_KEY"Checking Credits
curl https://openrouter.ai/api/v1/credits \
-H "Authorization: Bearer $OPENROUTER_API_KEY"Response Headers
| Header | Description |
|---|---|
X-Generation-Id | Unique ID for each generation (present on all responses) |
X-OpenRouter-Cache-Status | HIT or MISS for cached responses |
X-OpenRouter-Cache-Age | How long the response was cached |
X-OpenRouter-Cache-TTL | Remaining TTL on a cache hit |
Common HTTP Error Codes
| Code | Meaning |
|---|---|
| 400 | Bad request (malformed payload) |
| 401 | Invalid API key |
| 402 | Insufficient credits |
| 403 | Forbidden or moderation flag |
| 408 | Request timeout |
| 429 | Rate limited |
| 502 | Bad gateway (upstream provider issue) |
| 503 | No suitable model provider available |
Standard Generation Parameters
| Parameter | Range | Description |
|---|---|---|
temperature | 0–2 | Controls randomness. 0 = deterministic |
max_tokens | 1 to context length | Max tokens in the response |
top_p | 0–1 | Nucleus sampling threshold |
top_k | integer | Limit to top K tokens |
frequency_penalty | -2 to 2 | Penalize frequent tokens |
presence_penalty | -2 to 2 | Penalize repeated tokens |
Limitations with Non-Anthropic Models
Claude Code is designed to work with Anthropic's API and models. When routing through OpenRouter to non-Anthropic models, some features may not work as expected:
- Tool use / function calling — Not all models support this. DeepSeek models generally have good tool-use support; others may vary.
- Extended thinking — Only supported on Anthropic Claude models.
- Prompt caching — OpenRouter may support this, but behavior varies by model.
- Streaming — Generally works, but implementation details vary by provider.
- Context window — OpenRouter reports context limits per model; actual limits depend on the upstream provider.
Notes
- OpenRouter must be accessible — If you're behind a corporate proxy or firewall, ensure
openrouter.aiis reachable. - Model availability — Free models (
:fre) may have rate limits or downtime. Check openrouter.ai/status for availability. - Cost varies by model — OpenRouter passes through provider pricing. Always check the model page for current rates.
- Token limits — OpenRouter may enforce different context window limits per model. Check the model's OpenRouter page for specifics.
- Key security — Never commit your API key to version control. Use
.claude/settings.local.json(gitignored) or environment variables.
💬 Comments & Reactions