Claude Code Router v3 Setup on Windows

Claude Code Router (CCR) is a local gateway for coding agents. It accepts requests from Claude Code and forwards them to a model provider you choose. It can also apply routing and fallback rules when one model should not handle every task.

CCR v3 is different from older releases. The old setup guides told you to edit ~/.claude-code-router/config.json and launch with ccr code. The current release has a management UI, provider checks, Agent Profiles, request logs, and a SQLite configuration database. Following the old workflow can leave you editing a file that the running service no longer uses.

This guide follows the current v3 setup on Windows.

Choose the desktop app or CLI#

Windows users have two practical options:

Download the Windows desktop installer from the project’s GitHub releases page. The release is distributed as a Windows .exe.

For the CLI, install Node.js 22 or newer first. Confirm the version in PowerShell:

node --version

Then install or upgrade CCR:

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

ccr ui starts the background service and opens the management page. If the command is missing after installation, close PowerShell, open it again, and run npm prefix -g to check where npm installed the global package.

Understand the two local ports#

The CLI uses separate addresses for management and model traffic:

CCR can select another management port if 3458 is busy. Use the address printed by the command. The gateway remains a separate service, so an open management page does not prove that model requests can pass through it.

Add a provider and model#

Open Providers, choose Add Provider, and select a built-in preset when one exists. For an unlisted service, choose the custom API option.

Enter the provider’s base URL, protocol, API key, and model IDs. CCR supports OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini Generate Content protocols. Choose the protocol the provider documents instead of guessing from the URL.

Before saving:

1. Run protocol probing if you are unsure which format the endpoint accepts.
2. Run the connection check for one or two models.
3. Read the returned diagnostic if the key, endpoint, or model ID fails.

Connection checks send real requests and may use billable tokens. There is little value in testing every model at once.

Create a client key and start the gateway#

Open API Keys and create a CCR client key. This key authenticates requests sent to the local gateway. It is separate from the provider key and from the private token that protects the management interface.

Next, open Server and start the gateway. Its default address is http://127.0.0.1:3456.

You can verify the service from PowerShell:

Invoke-WebRequest http://127.0.0.1:3456/health

A healthy response confirms that the gateway is running. It does not prove that a provider model works, which is why the provider connection check still matters.

Connect Claude Code with Agent Profiles#

Open Agent Profiles, select Claude Code, and create a profile. Choose the main model, a small fast model if you want one, and the Claude Code settings file CCR should manage.

During testing, use the option that applies the profile only when Claude Code is opened from CCR. This keeps your normal Claude Code configuration unchanged. After the test passes, you can decide whether CCR should become the system default.

Apply and enable the profile, then launch it from CCR. With the npm CLI, enabled profiles can also be opened by name:

ccr "Claude - Work"

Use your own profile name in that command. Send a short request, then check Logs. The log should show the requested model, resolved model, provider, response status, and latency.

Configure routing and fallback#

The Claude Code profile’s selected model handles ordinary requests. Keep Use enhanced route enabled if you want CCR to help subagents and workflows choose other configured models.

For automatic subagent selection, open Models and write useful descriptions for the models CCR may choose. Describe what each model is good at, such as quick repository searches, difficult refactor planning, or long document review. A model without a description is not offered to this selection mechanism.

Global custom routes live under Routing. Rules are evaluated in order, and the first enabled match rewrites the request. Use fallback settings for failures:

Start with one provider and one model. Add routing after the basic request path works. This makes authentication and protocol errors much easier to isolate.

Common problems#

• ccr is not recognized: reopen PowerShell and check npm prefix -g. Confirm that npm’s global executable directory is on PATH.
• The UI opens but requests fail: confirm the gateway is running under Server, not just the management service.
• Requests go to port 3458: change the client to the gateway address on port 3456.
• A provider check returns 401 or 403: verify that the API key belongs to the endpoint you entered and has access to the selected model.
• A model returns 404: copy the exact current model ID from the provider. Do not use the product’s display name.
• A profile cannot be launched: make sure the profile is enabled, save it again, and use its unambiguous name or ID.
• An old service keeps old options: run ccr stop, then start it again with ccr ui.

The safest setup order is provider, connection check, client key, gateway, and Agent Profile. Once one Claude Code request appears correctly in the logs, add routing and fallback rules one at a time.