DEV Community

Cover image for How to Use Claude Code with OpenRouter — Run Any AI Model for Free or Cheap 🚀
Muhammad Hamid Raza
Muhammad Hamid Raza

Posted on

How to Use Claude Code with OpenRouter — Run Any AI Model for Free or Cheap 🚀

#claude #ai #webdev #tutorial

Ever wished you could use Claude Code with models other than just the official Anthropic ones? Maybe you want to try a powerful free model, cut costs, or experiment with something new like NVIDIA's Nemotron?

Good news — it's totally possible. Claude Code supports custom API base URLs, which means you can point it to OpenRouter and instantly unlock access to dozens of AI models, including free ones. 💡

In this guide, I'll walk you through the complete setup on Windows, macOS, and Linux — step by step, no fluff.

What Is OpenRouter?

OpenRouter is a unified API gateway that gives you access to many AI models — from OpenAI and Anthropic to Google, Meta, Mistral, NVIDIA, and more — all through a single API endpoint.

Think of it like a TV remote that controls every streaming platform. Instead of managing separate API keys for each provider, you get one key that works everywhere.

Some models on OpenRouter are completely free. Others cost a fraction of what you'd pay directly. It's a great way to experiment without burning through credits.

Why Use Claude Code with OpenRouter?

Claude Code is a powerful AI coding assistant that runs in your terminal. By default, it talks directly to Anthropic's API. But since it supports environment variable overrides, you can redirect it to any OpenAI-compatible endpoint — including OpenRouter.

Reasons you might want to do this:

  • 💸 You want to use a free model to save money
  • 🧪 You want to experiment with different models for different tasks
  • 🌐 You already have OpenRouter credits and don't want to maintain two separate accounts
  • ⚡ You want to try newer open-source models like NVIDIA Nemotron, Llama, Qwen, etc.

What You'll Need

Before we start, make sure you have:

  • ✅ Claude Code installed — via npm install -g @anthropic-ai/claude-code
  • ✅ An OpenRouter account — sign up free at openrouter.ai
  • ✅ Your OpenRouter API key — get it from the OpenRouter dashboard under "API Keys"
  • ✅ A model name from OpenRouter you want to use (e.g., nvidia/nemotron-3-super-120b-a12b:free)

Where Is the Settings File?

Claude Code reads its configuration from a settings.json file. Here's where to find it depending on your OS:

Operating System Settings File Path
Windows C:\Users\<YourUsername>\.claude\settings.json
macOS ~/.claude/settings.json
Linux ~/.claude/settings.json

If the file doesn't exist yet, just create it. Claude Code will pick it up automatically.

Step-by-Step Setup

🪟 Windows

Step 1: Open File Explorer and navigate to:

C:\Users\<YourUsername>\.claude\
Enter fullscreen mode Exit fullscreen mode

Replace <YourUsername> with your actual Windows username.

Step 2: If the .claude folder doesn't exist, create it manually.

Step 3: Inside that folder, open or create settings.json using Notepad or VS Code.

Step 4: Paste the following configuration:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "your-openrouter-api-key-here",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "nvidia/nemotron-3-super-120b-a12b:free"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Replace your-openrouter-api-key-here with your actual OpenRouter API key.

Step 6: Save the file and open a new terminal. Run:

claude
Enter fullscreen mode Exit fullscreen mode

You're done! 🎉

🍎 macOS

Step 1: Open Terminal.

Step 2: Navigate to the .claude folder:

cd ~/.claude
Enter fullscreen mode Exit fullscreen mode

If it doesn't exist yet, create it:

mkdir -p ~/.claude
Enter fullscreen mode Exit fullscreen mode

Step 3: Open or create the settings file using your preferred editor:

nano ~/.claude/settings.json
# or
code ~/.claude/settings.json
Enter fullscreen mode Exit fullscreen mode

Step 4: Paste this configuration:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "your-openrouter-api-key-here",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "nvidia/nemotron-3-super-120b-a12b:free"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Replace your-openrouter-api-key-here with your real key.

Step 6: Save and close. Then open a new terminal window and run:

claude
Enter fullscreen mode Exit fullscreen mode

That's it for macOS! 🍏

🐧 Linux

Step 1: Open your terminal.

Step 2: Navigate to (or create) the .claude directory:

mkdir -p ~/.claude && cd ~/.claude
Enter fullscreen mode Exit fullscreen mode

Step 3: Create or edit the settings file:

nano ~/.claude/settings.json
# or
vim ~/.claude/settings.json
Enter fullscreen mode Exit fullscreen mode

Step 4: Paste the configuration:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "your-openrouter-api-key-here",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "nvidia/nemotron-3-super-120b-a12b:free"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Replace the API key placeholder with your real OpenRouter key.

Step 6: Save the file. Open a fresh terminal session and run:

claude
Enter fullscreen mode Exit fullscreen mode

Linux users, you're set! 🐧

Understanding the Configuration Fields

Here's what each field in the config actually does:

Field Purpose
ANTHROPIC_BASE_URL Tells Claude Code to use OpenRouter's API instead of Anthropic's
ANTHROPIC_AUTH_TOKEN Your OpenRouter API key used for authentication
ANTHROPIC_API_KEY Left empty intentionally — OpenRouter handles auth via the token
ANTHROPIC_DEFAULT_SONNET_MODEL The model you want Claude Code to use by default

The ANTHROPIC_DEFAULT_SONNET_MODEL field is where the magic happens. Change this to any model ID from OpenRouter's model list and Claude Code will use it.

How to Find Model IDs on OpenRouter

  1. Go to openrouter.ai/models
  2. Browse or search for the model you want
  3. Click on it to see the model ID
  4. Copy the full model string (e.g., meta-llama/llama-3.3-70b-instruct:free)
  5. Paste it as the value of ANTHROPIC_DEFAULT_SONNET_MODEL

Models with :free at the end are completely free to use — no credits needed. 👀

Pros and Cons

✅ Advantages of Using Claude Code with OpenRouter

  • Access to free models — great for learning and experimenting
  • One API key for many models
  • Flexibility to switch models without reinstalling anything
  • Works with open-source models that Anthropic doesn't offer
  • Useful if you're on a budget but still want powerful coding assistance

⚠️ Things to Be Aware Of

  • Not every OpenRouter model is as capable as Claude Sonnet or Opus
  • Free models sometimes have rate limits or slower response times
  • Some models may not follow Claude Code's system prompts as precisely
  • If the model doesn't support tool use well, Claude Code's agentic features may behave unexpectedly

Best Tips

✅ Do this:

  • Always test your setup with a simple prompt first before using it on a real project
  • Use free models for low-stakes tasks like drafting, explaining code, or answering questions
  • Keep your API key private — never commit settings.json to a public Git repo
  • Check the OpenRouter model card for context window size before using a model on large codebases

❌ Avoid this:

  • Don't leave your real API key in shared machines or public repositories
  • Don't assume every model will behave exactly like Claude — each model has its own strengths and quirks
  • Don't set ANTHROPIC_API_KEY to your actual Anthropic key when using OpenRouter — it's not needed and might cause confusion

Common Mistakes People Make

1. Wrong API base URL format

Some people accidentally set the URL to https://openrouter.ai/api/v1. The correct value is https://openrouter.ai/api — Claude Code appends /v1/messages automatically.

2. Leaving the model name blank or wrong

If ANTHROPIC_DEFAULT_SONNET_MODEL is missing or has a typo, Claude Code may fall back to an unexpected default or throw an error. Always double-check the model ID from OpenRouter's model list.

3. Using an expired or invalid API key

OpenRouter keys are easy to rotate. If Claude Code starts returning auth errors, go to your OpenRouter dashboard and create a fresh API key.

4. Not restarting the terminal

Settings are read when Claude Code starts. If you edit settings.json while Claude Code is running, the changes won't apply until you restart your terminal.

5. Committing the settings file to Git

This one hurts. Your settings.json contains your API key. Add .claude/ to your .gitignore to avoid accidentally pushing it to a public repository.

Conclusion

Setting up Claude Code with OpenRouter is genuinely simple once you know where the settings file lives. A few lines of JSON and you unlock access to a wide range of AI models — including free ones — all from your existing terminal workflow.

Whether you're on Windows, macOS, or Linux, the process is essentially the same: find the settings file, drop in the config, and you're good to go. 🔧

The best part? You can switch models anytime just by changing one line. That kind of flexibility is rare and genuinely useful for anyone who codes with AI tools regularly.

If this guide helped you, I'd love it if you shared it with a fellow developer who's been curious about Claude Code but didn't want to deal with API costs. And if you're looking for more practical dev guides like this, check out 👉 hamidrazadev.com — there's a lot more where this came from.

Happy coding! 😊

Top comments (0)