When such a request reaches CCR, the tag is extracted and removed, and the request goes to the model named in it.
The key to all of it is the description field on the models page. It acts as both the switch and the guide: if no model has a description, CCR injects nothing, so as not to write an empty model list into tool descriptions. The documentation advises describing models by the tasks they suit, and gives sample wordings - fast and cheap for code search and small edits, strong for architecture and high-risk review, long-context for large logs and documents.
So picking a cheap model for a cheap step is not done by a rule but by a description the agent chooses from itself.
Codex and Patches
A second mechanism of the same kind, but about compatibility.
Codex has its own file-editing tool built unusually: it takes not function arguments but raw patch text. Many third-party OpenAI-compatible models handle such tools worse than they handle ordinary functions.
CCR substitutes the tool: outward it exposes an ordinary function with a patch field, and embeds the full grammar of the format in its description. When the model answers, CCR rewrites the response back into the shape Codex expects.
The caveat is honest and important: files are still edited by Codex, not by CCR. For models with GPT-style names the substitution does not apply - they go the native route. And it is enabled not by a routing switch but automatically, by the model's name.
Observability
This section is why the tool belongs in the spending topic.
For every request you can see which provider, which model and which credential were finally chosen, how it ended, how long it took, how many tokens went out, what it is estimated to have cost, and which tool calls happened inside. There is a separate trace of the agent's work.
That is exactly what is missing in ordinary work: not a single figure for the month, but a breakdown of one request - why it went where it went, and what it cost.
Secure by Default
One setting is worth knowing.
If no access key for the gateway itself is set, the host is forced to 127.0.0.1 - so that nobody else connects to your gateway holding other people's keys. It is written into the README in plain words.
Separately there are client keys for CCR itself: with their own expiry and local limits on request, token and image counts. So the gateway can be handed to a colleague without handing over the provider keys.
What to Know in Advance
Versions move very fast. Three releases in August 2026, the last of them - 3.0.22 - shipped the day before I wrote this. Any instruction goes stale within weeks.
There are more than a thousand open issues. As of 25 August 2026 there are 1,091. For a project standing between your agent and your money, that number is worth noticing.
The Node requirement is stricter than it looks. The package metadata says Node 22 or newer, and the CLI documentation repeats it.
Windows builds only happen on Windows. The project carries a native module, so packaging the desktop app for Windows requires Windows x64.
The project lives on sponsors. The top of the README is a sponsor banner, and that sponsor's models ship as a built-in provider preset. It does not affect how it works, but when choosing a provider it is worth remembering whose banner you are reading.
The scope keeps growing. Beyond routing, version three added model fusion adding vision and web search, a tool hub, built-in browser automation, Chrome login-state import, and agent relay through messengers - from Slack and Telegram to Feishu and DingTalk. Some will call that development, others sprawl.
First-Encounter Mistakes
Looking for a Router section in a config file. That is version two. In version three configuration happens in the UI, and the desktop config lives in a SQLite database.
Mixing up the ports. The model gateway is on 3456, the management UI on 3458.
Exposing the gateway outward without setting a key. Without a key the host is forced local - and that is protection, not an obstacle.
Expecting subagents to pick the cheap model on their own. They will not until model descriptions are filled in: without them the tag mechanism simply does not engage.
Installing through npm on Node 20. Node 22 or newer is required.
Assuming CCR edits files for Codex. It does not: it only translates the tool call in both directions.
Building the desktop app for Windows on another system. The native module will not allow it.
Taking instructions from an article six months old. In that time the major version and the whole configuration method changed.
To put it in one sentence: this is no longer a router but a control panel - and its main value is that the decision of which model goes on which step stops being scattered across every agent's config and becomes one visible place with a meter attached.
Sources
This article was checked against the musistudio/claude-code-router repository (branch main) on 25 August 2026: the README, package.json, docs/src/content/docs/en/configuration.md, docs/src/content/docs/en/configuration/routing.md and the repository tree. Version, stars, forks, open-issue count and the last commit date were taken the same day through the GitHub API and the npm registry. The project recently changed major version: descriptions of version two, with its JSON file edits and custom JavaScript router, no longer apply to the current one.
