Claude Code Router Guide (2026): Use Claude Code With DeepSeek, OpenRouter, Gemini and Ollama

Claude Code is one of the best coding agents around, but it normally talks only to Anthropic’s own models. Claude Code Router (CCR) is the free tool people use to point it at DeepSeek, OpenRouter, Gemini or a local model instead.

CCR has changed a lot in 2026. Version 3 replaced the old hand-edited config.json with a web UI, a desktop app and “Agent Config” profiles, so many older tutorials no longer match what you see.

This guide walks through the current version step by step, shows when you do not need CCR at all, and covers the errors people hit most.

What Is Claude Code Router?

Claude Code Router is an open-source project by musistudio. It runs a small local gateway that receives Claude Code’s requests and forwards them to whichever model you choose.

Because it translates between API formats, the upstream does not need to speak Anthropic’s protocol. Presets cover a long list of providers:

• Protocols: OpenAI Chat and Responses, Anthropic Messages, Gemini Generate Content.
• Named providers: OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI and Bailian.
• Custom endpoints: any compatible URL, which is how you add Ollama, llama.cpp or LM Studio.

Version 3 also routes other agents, including Codex, Grok CLI, Kimi CLI, OpenCode and Kilo Code. This guide sticks to Claude Code.

Do You Even Need It? Direct Options in 2026

Ollama without CCR

Ollama now exposes an Anthropic-compatible API. The quickest route is one command:

ollama launch claude

Or set the variables yourself (macOS/Linux):

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5

Ollama’s docs say to pick a model that supports tools and to give it a context window of 64k tokens or more.

DeepSeek without CCR

DeepSeek’s API has an Anthropic endpoint at https://api.deepseek.com/anthropic. It maps Claude names automatically: claude-opus* goes to deepseek-v4-pro, and claude-sonnet* or claude-haiku* go to deepseek-flash.

How to Install Claude Code Router

You need Claude Code installed first, and Node.js 22 or newer for the CLI. Check with node -v.

Option 1: npm CLI

npm install -g @musistudio/claude-code-router
ccr ui

ccr ui starts the background service and opens the management page at http://127.0.0.1:3458. On a headless server use ccr ui --no-open.

Option 2: Desktop app

The GitHub releases page has the desktop app (v3.1.3) for Windows, macOS (Apple Silicon and Intel) and Linux AppImage. It adds a tray icon and a launcher called ccr-app.

Option 3: Docker

From a clone of the repo, run npm run docker:compose:up. The UI and gateway are exposed on 127.0.0.1:3458 by default.

Tip: to upgrade later, run npm install -g @musistudio/claude-code-router@latest. Uninstalling with npm keeps your local config and databases.

Set Up Your First Provider and Profile

1. Open the UI with ccr ui.
2. Add a provider. On the Providers page, pick a preset (DeepSeek, OpenRouter and so on) or “Other / custom API endpoint”. Paste your API key.
3. Load models. Select the models CCR discovered, or type IDs under Custom models if the endpoint has no /models list.
4. Click Check Connection. It sends real test requests, so it may use a few tokens.
5. Start the server on the Server page if it is not already running.
6. Create a client key on the API Keys page. This is CCR’s own key, separate from your provider keys.
7. Create a Claude Code profile. Agent Config > Add profile > Claude Code. Set a name, entry mode (CLI, App or both), a default model and, optionally, overrides for the Opus, Sonnet and Haiku tiers.
8. Launch it from a terminal in your project folder:

   ccr "my-deepseek"

9. Verify. Inside Claude Code, run /model to see CCR’s models, send a test message and check the Logs page.

Note: a profile’s scope can be “only when opened from CCR” or “system default”. Start with the first so your normal claude command still uses Anthropic.

Claude Code Router With Ollama (Local Models)

CCR’s docs do not have an Ollama page, but Ollama works as a custom endpoint. Here is the setup I recommend.

1. Install Ollama and pull a tool-capable model. See my Ollama install guide and best Ollama models by VRAM.
2. Raise the context window to 64k. Set OLLAMA_CONTEXT_LENGTH=65536 before starting ollama serve. The default is far too small for an agent.
3. Add a custom provider in CCR named Ollama with the endpoint http://localhost:11434. Use any placeholder as the key, such as ollama.
4. Add model IDs exactly as ollama list shows them, for example qwen3.8:27b.
5. Set local pricing to zero. In the model’s pricing metadata, set inputUsdPerMillionTokens and outputUsdPerMillionTokens to 0 so the cost dashboard stays honest.
6. Use it as a fallback or for cheap subagents, and keep a stronger cloud model as the main route.

How big a model can you run? On a 16 GB card, a 27B model at Q4 is about the ceiling with a 64k context; my Qwen3.8-27B on 16 GB guide has exact settings. For VRAM planning in general, see how much VRAM you need.

Warning: small local models often fail at Claude Code’s tool calls. If edits loop or files are not written, the model is the problem, not CCR. Try a larger coder model before blaming the router.

Using DeepSeek and OpenRouter

A sensible cheap setup: DeepSeek Flash as the default, DeepSeek V4 Pro for the Opus tier, and a local Ollama model as the fallback when the API is busy.

Routing, Subagents and Fallbacks

This is where CCR beats the direct options.

• Main route: requests use the model Claude Code selects if CCR knows it, otherwise the profile’s default model.
• Subagents: give your models a Description. CCR lists them in Claude Code’s Task tool instructions, and Claude Code can pick a model per subagent with a <CCR-SUBAGENT-MODEL> tag.
• Custom rules: match on request headers or body fields, checked in order. The first enabled match wins.
• Script rules: a Node.js script can pick the model (2,000 ms default timeout). Only run scripts you trust.

Delays follow the provider’s Retry-After header or exponential backoff, capped at 30 seconds.

Tip: have several API keys for one provider? Add them to the provider’s credential pool with limits such as {"rpm": 60, "tpm": 100000}. CCR skips a key that would go over its limit.

CCR Commands and File Locations

Useful flags: --host (default 127.0.0.1), --port (default 3458; CCR tries the next port if busy) and --no-gateway to run only the management UI.

• macOS / Linux data folder: ~/.claude-code-router
• Windows data folder: %APPDATA%\claude-code-router
• Inside it: config.sqlite, gateway.config.json, service.json, profiles/, app-data/, bin/
• Environment variables: CCR_WEB_HOST, CCR_WEB_PORT, CCR_WEB_AUTH_TOKEN (a fixed UI token; random if unset)

Old config.json Guides vs Version 3

Many 2025 tutorials tell you to hand-edit ~/.claude-code-router/config.json with a Router block and start Claude Code with ccr code. The current docs describe a different setup:

• Settings live in config.sqlite and are edited in the UI.
• Claude Code launches through an Agent Config profile with ccr "<profile>".
• Routing uses ordered rules, subagent tags and fallback modes.

If a guide’s commands do not exist on your install, check which major version it was written for before you debug anything else.

Troubleshooting

Claude Code ignores CCR and still uses Anthropic

Check that the CCR service is running, that you launched with ccr "<profile>" rather than plain claude, and that the profile is enabled and its scope covers this project. Claude Code’s own settings file can also override environment variables; run /status to see the active base URL.

401 or 403 from the provider

A credential problem. Confirm the API key is correct and enabled, and that the endpoint URL and protocol match the provider. Then run Check Connection on the provider page.

“model not found”

The routed model name is not in the provider’s model list. Compare the exact ID in the provider list, the routing rule and the Agent Config profile, and fix the one that differs.

No models in /model

The profile is disabled or has no default model, or the provider’s models were never saved. Remember Check Connection does not save models; select them in the main list.

Requests time out

Open the request logs and see which stage was slow. Local models on big contexts can take minutes for the first reply; raise the timeout or use a smaller model.

The UI does not open on 3458

Another app holds the port. CCR tries the next port, so read the URL it prints, or start it with ccr ui --port 3500.

Ollama works in chat but fails in Claude Code

Usually context or tools. Raise OLLAMA_CONTEXT_LENGTH to 65536 and use a model that supports tool calling.

My Take

For most people starting today, I would try the direct routes first. ollama launch claude or DeepSeek’s Anthropic endpoint gets you running in two minutes with nothing extra to maintain.

Move to Claude Code Router when you want a smart mix: a cheap cloud model for routine work, a strong one for hard tasks, a local model when the API is down, and a log of what it all costs. Version 3’s UI makes that far easier than the old JSON file.

If you are choosing between agents in the first place, my Cursor vs Windsurf vs Claude Code vs Cline comparison and Claude Code commands cheat sheet are good next reads.

FAQ

What is Claude Code Router?

A free, MIT-licensed local gateway that lets Claude Code use models from DeepSeek, OpenRouter, Gemini, Moonshot, local servers and others instead of only Anthropic’s.

Is Claude Code Router free?

Yes, the software is free and open source. You still pay your model provider, unless you route to a local model.

How do I install Claude Code Router?

Install Node.js 22+, run npm install -g @musistudio/claude-code-router, then ccr ui. A desktop app is also available on GitHub.

Can I use Claude Code with Ollama without the router?

Yes. Run ollama launch claude, or set ANTHROPIC_BASE_URL=http://localhost:11434 and ANTHROPIC_AUTH_TOKEN=ollama, then start claude --model <model>.

Does “ccr code” still work?

The current CLI docs do not list it. Version 3 launches Claude Code through an Agent Config profile with ccr "<profile name>".

Where is the Claude Code Router config file?

In ~/.claude-code-router on macOS and Linux, or %APPDATA%\claude-code-router on Windows. Version 3 stores settings in config.sqlite and you edit them in the UI.

Which ports does Claude Code Router use?

The management UI uses 3458 and the model gateway uses 3456, both on 127.0.0.1 by default.

Is it against Anthropic’s terms?

CCR routes Claude Code to other providers’ APIs, so you follow those providers’ terms. Using a Claude subscription through third-party tools is a separate question; check Anthropic’s current terms.

Sources

• GitHub: musistudio/claude-code-router
• CCR docs: CLI reference, Provider config, Routing, Q&A
• CCR docs: Claude Code agent profile
• Ollama docs: Claude Code integration and Anthropic compatibility
• DeepSeek API docs: Using the Anthropic API