Claude Code Router 3.1.1: Install, Route, and Troubleshoot

You want Claude Code to use DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM, or another compatible endpoint, but the guide in front of you still talks about config.json and ccr code—or the gateway at 127.0.0.1:3456 never starts. This guide follows the current 3.1.1 workflow and takes you from installation to a verified Claude Code profile, with a troubleshooting path for each common failure.

Start with the version: 3.1.1 is no longer centered on a hand-written config.json

Use the web UI for providers, routing, and Agent Profiles instead of copying an old JSON block. As of September 26, 2026, the npm latest tag points to 3.1.1. The current package stores its primary configuration in config.sqlite and generates gateway.config.json for the running gateway, according to the npm registry metadata and the current project README.

The same version difference explains two frequent dead ends. The current CLI reference launches an agent with ccr <profile-name-or-id>; it does not list ccr code. The generated gateway.config.json is also not the file you should maintain by hand. When a tutorial asks for config.json or ccr code, check which CCR generation it targets before treating the resulting error as an installation problem.

Prepare Node.js, an upstream provider, and Claude Code

You need Node.js 22 or newer, an upstream model service, and a locally installed Claude Code executable. CCR routes requests; it does not install Claude Code for you, and API access is not the same product as a Claude.ai or Claude Max subscription.

Check Node.js first:

node --version

Upgrade Node.js before continuing if the major version is below 22. Your upstream can be a built-in preset such as OpenRouter, DeepSeek, Gemini, Moonshot/Kimi, or Z.AI, or a custom endpoint that implements a supported OpenAI-compatible or Anthropic-compatible protocol.

Install the npm CLI and verify the command before configuring anything

Run the help command immediately after the global install. That separates an npm or PATH problem from a provider or routing problem.

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

Use these commands to upgrade or remove the package:

npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-router

Removing the npm package does not delete CCR’s local configuration or databases. The data directory is ~/.claude-code-router on macOS/Linux and %APPDATA%\claude-code-router on Windows.

Configure in this order: Provider → Check Connection → Client Key → Routing → Server → Profile → end-to-end test

Get one default route working before you add conditions or fallback models. If you configure multiple providers, rewrites, retries, and fallbacks at once, a 401, an invalid model ID, and a protocol mismatch become difficult to distinguish.

Open the management UI:

ccr ui

The management UI defaults to http://127.0.0.1:3458, while the model gateway defaults to http://127.0.0.1:3456. Use the authenticated URL printed or opened by CCR. If 3458 is occupied, CCR may choose a later management port and print the actual address.

1. Add the upstream under Providers

Choose a preset when one exists; use a custom endpoint only when necessary. In Providers → Add Provider, select the provider, enter that provider’s own API key, choose the correct protocol, and add model IDs that are actually available to your account.

Do not infer the protocol from the model’s marketing name. Anthropic Messages, OpenAI Chat/Responses, and Gemini request formats are different. The base URL, protocol, and model ID must match the current documentation of the upstream service.

After saving the provider, run Check Connection. Treat this as an upstream-only check; it does not prove the Claude Code → CCR gateway → Routing → provider path.

2. Create a CCR client key under API Keys

A CCR client key is not the management token. The management token protects the browser UI and RPC API; the client key authenticates model requests that Claude Code sends to the gateway. Treat a management URL containing ccr_web_token like a password and do not paste it into logs, tickets, or chat messages.

3. Add a default route before conditions and fallback

Point the default route to one provider entry that passed Check Connection and one model from that provider. Save the route, but do not send the Claude Code request yet; start the gateway and create the Agent Profile first.

After the end-to-end request in step 6 succeeds, add conditions, retries, request rewrites, or ordered fallback models under Routing. Add one behavior at a time and test again. A fallback model also needs to support the tools, context, and protocol your task requires; two models are not interchangeable merely because both can chat.

4. Start and verify the gateway under Server

An open UI does not prove that the gateway on 3456 is usable. Open Server, start the gateway, and record the client-facing URL shown there. The default is http://127.0.0.1:3456; use the actual URL displayed by CCR. When startup fails, run CCR in the foreground to expose the error:

ccr serve

Foreground output makes it easier to separate a port conflict from an incomplete provider, a missing model, or a local file-permission problem.

5. Create and enable a Claude Code Agent Profile

The current CLI launches Claude Code through an enabled Agent Profile. Under Agent Profiles, create a Claude Code profile, select the model used by the default route from the provider entry that passed Check Connection, save it, and enable it. In CCR mode, Claude Code connects to the CCR gateway shown under Server (default http://127.0.0.1:3456), not to the upstream provider URL. You can choose any profile name, such as Claude - Review.

Launch it by name or ID:

ccr "Claude - Review"

Put Claude Code-specific arguments after -- so CCR does not parse them as its own options:

ccr "Claude - Review" cli -- --model sonnet

Replace Claude - Review with the profile name or ID you actually created.

6. Send a Claude Code request, then inspect Logs

This is the first true end-to-end test. From the launched profile, send a simple request in Claude Code, then use Logs to confirm the expected provider and model were selected and the request completed successfully.

Provider Check Connection covers only the upstream connection. This request also validates the CCR client key, gateway, Routing, Agent Profile, and actual model call.

Know what ccr start, ui, serve, and stop do

Use ccr ui or ccr start for normal operation and ccr serve for diagnosis. The four service commands have different jobs.

Command	Best use	What it does
ccr start	Persistent background use	Starts the detached management service and gateway, then prints an authenticated management URL
ccr ui	Local interactive setup	Reuses or starts the background service and opens the UI
ccr serve	Troubleshooting or a supervisor	Runs in the foreground so startup and request errors stay visible; ccr web is an alias
ccr stop	Recreating background settings	Stops the detached service started by start or ui

start, ui, and serve accept --host, --port, --open/--no-open, and --gateway/--no-gateway. Their --port option is the preferred management port, not automatically the model gateway port at 3456.

Fix “ccr: command not found” by checking Node and npm’s global bin path

Verify the runtime and global prefix before reinstalling repeatedly. Run:

node --version
npm prefix -g

Confirm that Node.js is at least version 22 and that npm’s global executable directory is present in the current shell’s PATH. Open a new terminal after installation because some shells cache command locations.

If you have also installed the desktop app, note that it provides a related ccr-app command. The npm package documented here installs ccr; the presence of ccr-app does not prove that the npm CLI is on your PATH.

Fix a gateway that is not listening on 127.0.0.1:3456

First determine whether the gateway failed to start or another process already owns the port. A healthy UI on 3458 says nothing about 3456.

On macOS/Linux:

lsof -nP -iTCP:3456 -sTCP:LISTEN

On Windows:

netstat -ano | findstr :3456

If a stale CCR process or another program owns the port, identify the PID before stopping it. Then run ccr serve, return to Server, and verify that a provider, a model, and a client key exist before starting the gateway again.

Fix 401, model-not-found, and protocol errors by checking three mappings

Check credentials, protocol, and model ID in that order. Frequent mistakes include using the management token as the client key, putting a CCR client key into the upstream provider, or calling an Anthropic-compatible endpoint with an OpenAI-compatible route.

Use this sequence:

1. Claude Code authenticates to CCR with a CCR client key, not ccr_web_token.
2. The Provider entry stores the upstream service’s own API key.
3. The selected protocol matches the endpoint.
4. The routed model ID exists for that provider and account.
5. Logs resolves to the provider and model you intended.

Do not rely only on Claude Code’s final error message. CCR Logs can show whether the failure occurred during client authentication, route resolution, upstream authentication, or the model request itself.

Fix missing profiles and background services that keep old options

Only enabled Agent Profiles can be launched. Name matching is case-insensitive and sanitized names are accepted, but an ambiguous name requires the profile ID. Re-save the profile if its generated launcher is missing.

A reused background process does not adopt new host, port, or gateway options. Stop and recreate it:

ccr stop
ccr start --host 127.0.0.1 --port 3458

This behavior explains why a command can appear to run successfully while the service still uses yesterday’s settings.

Use ANTHROPIC_BASE_URL directly when you only need one endpoint

A direct setup is usually simpler when you have one Anthropic-compatible endpoint, one main model, and no need for conditional routing, fallback, shared logs, or multiple profiles. Follow that provider’s Claude Code documentation for ANTHROPIC_BASE_URL, its authentication variable, and model mapping, without adding a local gateway.

CCR becomes the better fit when any of these are true:

• you switch among DeepSeek, OpenRouter, Gemini, Kimi, Z.AI, or custom endpoints;
• different tasks or profiles should use different models;
• you need retries, conditional routing, rewrites, or ordered fallback;
• you need one place to inspect resolved routes, status, tokens, latency, and errors;
• several clients should share one local gateway.

Situation	Prefer
One stable Anthropic-compatible endpoint	Direct ANTHROPIC_BASE_URL
Multiple providers, models, or profiles	CCR
You need request-level route visibility	CCR
You only want the fastest path to one service	Start direct; move to CCR when the workflow grows

Example compatible endpoint: add BetterToken to CCR

BetterToken is one possible custom Anthropic-compatible provider, not the only answer. In CCR Providers, enter https://bettertoken.ai in the upstream API endpoint/Base URL field—not the Claude Code base URL—and do not append /v1. Explicitly select Anthropic Messages, then enter your own BetterToken API key and a currently available model ID. Save the provider and run Check Connection.

When using CCR, Claude Code connects to the CCR gateway shown under Server, normally http://127.0.0.1:3456. Launch the Agent Profile, send a request, and use Logs to confirm that it routed to the intended BetterToken model. Do not point Claude Code directly at https://bettertoken.ai in this mode, or the request will bypass CCR.

Only when you intentionally skip CCR and connect directly to this single endpoint should you follow the BetterToken Claude Code documentation and set the base URL on macOS/Linux:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

PowerShell:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

In that direct mode, the authentication variable and model mapping still come from the current provider documentation. Do not reuse the OpenAI-compatible https://www.bettertoken.ai/v1 base URL for Claude Code.

Protect local credentials and back up the data directory safely

Keep the management listener on 127.0.0.1 unless remote access is intentional. For remote access, use a firewall or private network and TLS at a trusted reverse proxy. Do not expose the gateway externally without CCR client keys.

Upstream credentials, logs, and runtime databases live in CCR’s local data directory. Do not edit or copy config.sqlite while CCR is writing to it. Use the UI export function, or stop CCR before taking a filesystem backup.

Verify the whole path, not just the UI

Success means a Claude Code request used the intended route and returned normally. Check each item:

• node --version reports 22 or newer;
• ccr --help runs;
• Providers contains at least one upstream that passed Check Connection;
• API Keys contains a CCR client key;
• Server shows a running gateway and its client-facing URL (default http://127.0.0.1:3456);
• the Agent Profile is saved and enabled;
• ccr <profile-name-or-id> launches Claude Code;
• an actual Claude Code request was sent, and Logs shows the expected provider, model, and successful status;
• every new route or fallback has been tested again.

Following this order keeps installation, authentication, routing, and agent launch as separate layers. When something fails, you can fix the responsible layer instead of reinstalling CCR or editing an obsolete config.json at random.