Claude Code is an agentic coding tool that can read your codebase, edit files, and run commands directly from your terminal, IDE, or desktop app. It normally requires a paid Anthropic plan, but you can configure it to use free models instead, mainly for testing and experimenting before committing to a subscription.

This guide covers setup on macOS. The process is similar on Windows.

What this covers:

• Installing Claude Code

• Getting a free API key from OpenRouter

• Configuring Claude Code to use OpenRouter globally

• Choosing a free model

• Optional project-level configuration

Step 1: Install Claude Code

Install via npm:

npm install -g @anthropic-ai/claude-code

After installation, run:

claude

This starts the onboarding process. Choose your preferred theme, then press Ctrl + C twice to exit. Full setup happens in the next steps.

Step 2: Get a Free API Key

Go to openrouter.ai, sign up, and generate a free API key.

Copy it immediately and save it somewhere safe. API keys are typically only shown once at creation. If you miss it, you can always generate a new one from the dashboard.

Step 3: Configure Claude Code to Use OpenRouter

There are three ways to configure Claude Code:

• Shell profile (environment variables in .zshrc or .bashrc)

• Global settings file (applies to all projects)

• Project settings file (applies to one project)

This guide uses the global settings file, which is the most practical option for general use.

Step 4: Find the Claude Config Folder

Navigate to your home directory:

/Users/your-username

Hidden folders are not shown by default in Finder. To reveal them, press:

Command + Shift + .

Look for a folder named .claude. Inside it, find or create a file named settings.json.

If the .claude folder does not exist, create it. If settings.json does not exist inside it, create that too. Open the file in any text editor or code editor.

Step 5: Add the Configuration

Paste the following into settings.json:

{
    "env": {
        "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
        "ANTHROPIC_AUTH_TOKEN": "<your-openrouter-api-key>",
        "ANTHROPIC_API_KEY": "",
        "ANTHROPIC_MODEL": "<model-id>"
    }
}

Replace <your-openrouter-api-key> with the key you copied in Step 2, and replace <model-id> with the model you want to use (covered in the next step).

Step 6: Choose a Free Model

Browse the available free models at:

openrouter.ai/models?order=newest&q=free

Each listing shows the model ID in the format provider/model-name (for example, google/gemma-3-27b-it:free). Copy the model ID and replace <model-id> in your settings.json.

Step 7: Start Using Claude Code

Run claude in any project directory. Claude Code will now route requests through OpenRouter using the free model you configured.

Optional: Project-Level Configuration

If you want a specific project to use a different model or configuration from the global default, set it up at the project level:

1. Create a .claude folder in the project root

2. Inside it, create a file named settings.local.json

3. Add the same configuration structure from Step 5 with the project-specific values

Project-level settings take precedence over the global settings file, so only that project will use the override.

Note: Add .claude/settings.local.json to your .gitignore file if the project is in a shared repository. The file may contain your API key and should not be committed.

A Note on Permissions

When Claude Code needs to run a command (installing a package, modifying a file, executing a script) it will ask for your approval before proceeding. The options are:

• Yes: allow this one command

• Yes, don't ask again: allow this and skip future prompts for similar commands

• No: decline

Choosing "Yes, don't ask again" is convenient but means commands run without confirmation. For testing and experimentation, approving each command individually is the safer habit. It also helps you understand what Claude Code is actually doing as you get familiar with the tool.

Key Takeaways

• Claude Code can be configured to use third-party model providers by pointing ANTHROPIC_BASE_URL at a compatible API and setting ANTHROPIC_MODEL to the desired model ID.

• OpenRouter provides access to a range of free models suitable for testing.

• The global ~/.claude/settings.json file applies configuration across all projects. A settings.local.json inside a project's .claude folder overrides it for that project only.

• Never commit API keys to version control. Add settings.local.json to .gitignore for shared repositories.

• Approve commands individually when testing so you can see exactly what Claude Code is executing.

Conclusion

Configuring Claude Code to use free models via OpenRouter takes about five minutes and gives you a working environment to explore what the tool can do before subscribing. The same configuration approach works for any OpenAI-compatible API endpoint, so the pattern extends beyond OpenRouter if you want to experiment with other providers.

Using Claude Code with a specific model or workflow that has worked well? Share it in the comments.