Claude Code Router: Run Claude Code on Other Models (and When a Gateway Is Simpler)

What Claude Code Router does

musistudio’s Claude Code Router, often shortened to CCR, describes itself as a “local model gateway and control plane for coding agents.” It provides a stable local endpoint for Claude Code and other clients, with provider credentials, routing rules, retries, ordered fallbacks, and request logs.

The v3.1.1 README lists support for OpenAI Chat and Responses, Anthropic Messages, and Gemini Generate Content and Interactions formats. Protocol adaptation is what makes running Claude Code with other models possible through CCR.

CCR is MIT-licensed, with a 2025 musistudio copyright, and supplied “AS IS.” Permission to use the software does not make upstream inference free. Provider charges and allowances remain separate; historical provider prices and OpenCode Go dollar allowances have not been verified for this publication date.

The relevant Claude Code Router 3.1 release

Version 3.1.1 was released on September 16, 2026. It adds first-class OpenCode Go local import, exposes individual failed gateway attempts, and corrects usage pricing for routed models.

The release also accepts --daemon on start and serve, fixes the Docker UI’s log-body worker, and provides macOS Apple Silicon and Intel builds, a Windows installer, and a Linux AppImage. The setup below uses the npm distribution and documentation pinned to v3.1.1.

Install CCR and connect Claude Code

The npm distribution requires Node.js 22 or newer. The pinned CLI guide documents these commands:

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

For startup without opening a browser:

ccr ui --no-open

The management interface and model gateway have separate default addresses:

Keeping these roles clear helps when checking where a connection failed. A working management page does not by itself establish that the model gateway accepted its configuration.

Add a provider and client key

Open Providers → Add Provider, choose a preset or Other / custom API endpoint, and enter the endpoint and API key. CCR detects protocols and models; Advanced settings lets you select a protocol manually.

Use Check Connection to test the provider. This sends a real request, so it may consume tokens or part of the provider’s request allowance.

Create a CCR client key on API Keys for model requests. That key is separate from the management UI/RPC token: treat client access and management access as distinct configuration items.

Create a Claude Code profile

In Agent Config, create an enabled profile for Claude Code, select a model such as Provider/model, and save it. For a profile named “Claude Code - Work,” launch with:

ccr "Claude Code - Work"

Desktop-generated launch commands use ccr-app. The Claude Code profile guide distinguishes two scopes:

• Only opened from CCR applies the configuration to CCR launches.
• System default also affects direct Claude Code launches.

Profiles support Fable, Opus, Sonnet, and Haiku overrides. Verify the active selection with /model, then inspect CCR Request logs to see the requests passing through the gateway. Keep the Claude Code model guide nearby when planning those selections.

Configure routing, retries, and fallbacks

CCR routing rules can inspect request.header and request.body, and can rewrite request.body.model. This gives you control over model selection based on the incoming request, beyond the model chosen in an agent profile.

Fallback configuration uses mode, models, and retryCount. The three modes are off, retry, and model-chain.

The distinction between retry eligibility and fallback eligibility matters. A response that does not qualify for a retry can still qualify for a fallback target.

Check which model actually served the request

A model chain can change the model that ultimately serves a request. CCR logs show the final provider and model, so use those logs when checking unexpected behavior or usage.

Start with a profile whose provider and model you can identify. Add routing rules and fallback targets deliberately, then check the final destination after exercising them. This makes it easier to connect a changed response or cost pattern to the routing configuration.

Version 3.1.1 also exposes individual failed gateway attempts. Those records help distinguish a successful final response from the attempts that preceded it.

Use the OpenCode Go import in v3.1.1

The musistudio Claude Code Router v3.1.1 release adds first-class local import for OpenCode Go. The integration separates Zen, identified as opencode, from Go, identified as opencode-go, including their credentials and overlapping model IDs.

The importer reads OpenCode configuration, auth.json, and cached model metadata. OPENCODE_API_KEY applies to both services; OPENCODE_GO_API_KEY supplies a Go-specific override. Discovery filters models by protocol and reconciles cached metadata with live /models results.

Why the session header matters

The OpenCode Go integration PR records that requests to https://opencode.ai/zen/go/v1 require x-opencode-session. Without it, the endpoint returns 400 MissingSessionID.

CCR selects the session value in this order: explicit configuration, an explicit client header, Claude session headers, metadata.user_id, and finally a stable process fallback. Header injection is restricted to the official Go endpoint.

This explains why entering an endpoint and credential alone may be insufficient for Go. Its session requirement is part of the provider integration.

Refresh discovery and read usage limits

If Go import is unavailable, connect OpenCode Go in OpenCode, refresh its local model cache, and rescan in CCR.

CCR fetches usage from GET https://opencode.ai/zen/go/v1/usage and displays remaining percentages for five-hour, weekly, and monthly windows. The pinned documentation does not specify dollar allowances. Read those values as remaining percentages for the named windows; they do not establish a monetary balance.

Troubleshoot the connection in stages

CCR’s troubleshooting material covers bypassed routing, authentication failures, missing models, unexpected model selection, cost spikes, timeouts, and missing agent traces. A useful diagnostic sequence follows the request from launch configuration to its final provider.

Claude Code bypasses CCR

Check that the intended Agent Config profile is enabled and that you launched through it. A profile set to Only opened from CCR limits its configuration to CCR launches; direct launches are affected when System default is selected.

Use /model and CCR Request logs together to verify the setup. The Claude Code CLI reference provides a broader reference for working with the client.

Authentication errors or missing models

For 401/403 errors, review the credentials at each relevant layer: the provider API key, the CCR client key for model requests, and the separate management token. These credentials serve different roles.

For model not found, review the detected models, selected protocol, and profile’s provider/model selection. With OpenCode Go, refresh the local cache and rescan if import is unavailable.

Startup and timeout failures

Version 3.1.1 increases gateway configuration acceptance time from five seconds to 30 seconds. This addresses cases where the management UI starts but the gateway fails under host load, particularly on Windows.

CCR_GATEWAY_CONFIG_TIMEOUT_MS overrides the timeout. Invalid values or values below 1,000 milliseconds fall back to the default.

Configuration lives in ~/.claude-code-router on macOS/Linux and %APPDATA%\claude-code-router on Windows. Relevant files include config.sqlite, generated gateway.config.json, and service.json. Service commands include ccr start, ccr stop, and foreground ccr serve.

When a hosted gateway is simpler

CCR fits workflows that need local provider management, request-based routing, credential pools, or explicit fallback chains. A hosted gateway can offer fewer local setup steps when your immediate goal is connecting Claude Code to an upstream service.

OpenRouter’s August 4, 2026 announcement documents these connection settings:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<openrouter-api-key>
ANTHROPIC_API_KEY=

The announcement also specifies additional model and feature settings. These three variables are the connection settings, not a complete configuration for every model. OpenRouter cautions that most open models do not support tool search, so settings differ by model.

Its Ori CLI automates setup through:

ori login
ori claude

The same workflows can also run through an API gateway such as AI Prime Tech, an independent service unaffiliated with Anthropic or OpenAI; see the guide to using Claude Code with an API key.

Choose based on the controls you need. CCR provides a local place to manage routes, inspect attempts, and configure fallbacks; the documented hosted approach removes the need to operate CCR locally.

Key takeaways

• Claude Code Router connects Claude Code and other clients to providers through a stable local endpoint with protocol adaptation.
• The npm distribution requires Node.js 22+, and the management UI and model gateway use separate default ports.
• Agent Config scope determines whether a profile applies only to CCR launches or also to direct launches.
• Fallbacks can change the serving model; inspect Request logs for the final provider and model.
• v3.1.1 adds OpenCode Go import with separate credentials and required session-header handling.
• A hosted gateway can reduce local setup when you do not need CCR’s local routing controls.

FAQ

Is Claude Code Router free?

Claude Code Router is MIT-licensed, granting permission to use the software. That does not establish free upstream inference, and historical provider prices or OpenCode Go dollar allowances are not verified here.

Can I use Claude Code with other models through CCR?

Yes. CCR provides protocol adaptation and provider/model selection, and its Claude Code profiles let you select a model such as Provider/model. Supported upstream formats include OpenAI Chat/Responses, Anthropic Messages, and Gemini Generate Content/Interactions.

What changed in Claude Code Router 3.1.1?

Released September 16, 2026, v3.1.1 adds first-class OpenCode Go local import, individual failed-attempt visibility, and corrected usage pricing for routed models. It also increases gateway configuration acceptance time to 30 seconds and accepts --daemon on start and serve.

Why does OpenCode Go return MissingSessionID?

The official OpenCode Go endpoint requires the x-opencode-session header and returns 400 MissingSessionID when it is absent. CCR’s Go integration selects a session value through a defined precedence order and injects the header only for the official Go endpoint.