DataLLM LabClaude Code Router: Single-Provider Setup and Verification
Claude Code Router can translate and route an Agent's model requests, but a proxy accepting a request is not proof that the Agent works. Start with one provider, one model, and observable checks before enabling fallbacks or pools. This guide follows the current 3.x workflow and gives explicit rollback steps. It does not claim a successful CCR Agent run or a measured saving.
Use a versioned guide, not a legacy configuration
The canonical project is musistudio/claude-code-router. For this revision we checked its v3.1.3 source, at commit 3b0aebf3701406dc774f9fdd6c2160622376a626, and the linked current documentation. That is a documentation version, not software installed or executed for this article.
Current CCR separates a management UI, a model gateway, and Agent Config profiles. Older Router and Providers JSON tutorials may describe a different version. Do not paste that schema into a live configuration or invent a migration step from this page. Use the versioned README and your installed command help together.
Before testing, record the CCR version, Node version if using the CLI, Agent version, working directory, and previous provider configuration. Use a throwaway repository without production secrets. Installation and connection checks below are proposed reader actions; none were performed for this revision.
Start the current CLI without exposing it to the network
The CLI reference specifies Node.js 22 or newer. Verify the package version you intend to install rather than silently inheriting a future release:
node --version
npm view @musistudio/claude-code-router@3.1.3 version
npm install -g @musistudio/claude-code-router@3.1.3
ccr --help
ccr ui --host 127.0.0.1
Stop if the expected package version is unavailable or the installed help does not match this workflow. Do not downgrade or overwrite an existing installation merely to match the article.
The management UI normally uses port 3458; the model gateway normally uses 3456. Trust the addresses reported by the running instance, because an occupied management port can shift. A UI opening in a browser does not establish that the gateway or upstream model is usable.
The management URL may contain a private token. Treat the entire URL as a credential. Keep both listeners local for this check; do not bind to 0.0.0.0 or publish the panel simply to make a local test convenient.
Configure one provider and one model
The current provider guide uses Providers > Add Provider, with a preset or custom endpoint, credentials, protocol detection, model selection, and a connection check. Configure the following record before expanding the route:
| Setting | First-test value or rule |
|---|---|
| Provider | One approved account, not a rotating credential pool |
| Upstream endpoint | The provider's documented endpoint for the selected protocol |
| Protocol | The detected protocol, confirmed against provider documentation |
| Model | One exact provider-supported ID, not a guessed family name |
| Credentials | Enter through the local credential controls; never in a screenshot or committed file |
| Routing | An explicit selected model, with no silent fallback during diagnosis |
| Budget | A small provider-side allowance and a declared stopping rule |
Do not mix a Chat Completions endpoint with a Responses or Messages protocol merely because each service is called "compatible." If detection is incorrect, use the provider guide's manual protocol controls rather than adding unrelated transformers from an older tutorial.
Check Connection sends a real upstream request. It may consume tokens or quota. Approve that cost and data route before running it, select only the intended model, and save the sanitized result. A positive connection check establishes that path, not a complete Agent loop.
Keep three credential roles separate
The upstream provider key pays for and authorizes model access. A CCR client key authenticates model requests to the local gateway. The management token protects the UI and management RPC. They are different credentials; do not substitute a dummy API key from an old proxy recipe without checking the current configuration.
Create the CCR client key using the current API Keys controls, then configure the Agent profile with the gateway address and selected model. During the trial, keep the profile scoped to agents opened from CCR rather than making it the system default. The Agent Config guide documents that scope and the installed profile workflow. Keep a private export of the previous settings so restoration does not depend on remembering which fields changed.
Verify the resolved route before asking it to edit code
In Settings > Logs & Observability, current documentation provides request logs and Agent observability. Enable only the information needed for a non-sensitive test, and protect the resulting local data. Logs can contain prompts and responses, not just timing. Logging guide
Send a short test through the configured Agent and compare the requested model with the resolved provider and model. Retain the status, request ID, latency, and usage where available. A response that silently used a fallback is not proof that the intended provider worked.
Ordinary logs are documented as same-day diagnostic records, not a durable experiment archive. Export a sanitized record promptly when you need to preserve evidence, rather than assuming it will be there the following week.
Separate the panel, gateway and upstream before retrying
| Observed result | What it establishes | Next unresolved check |
|---|---|---|
| Management panel opens at the reported address | The local management service is reachable | Gateway client authentication |
| Gateway accepts the configured client key | One local request reached the gateway | Upstream provider and exact resolved model |
| One upstream text response completes | A model request path worked | Actual tool-call and tool-result return |
Keep these outcomes in separate log fields. For example, a successful 3458 panel check with a failed 3456 gateway request is not a reason to rotate upstream accounts. Use the reported ports rather than assuming defaults, and retain the resolved route before enabling fallback. This is a diagnostic decision table, not an executed CCR test.
A tool-loop check is a separate test
Create a harmless file with a known marker in the throwaway repository. Ask the configured Agent to read it and report that marker without edits, shell commands, or external access. Grant only the intended read operation.
Inspect the trace for the tool call, returned tool result, and final answer. If the model merely describes a possible read or guesses the marker, tool execution has not been established. Stop if it asks for broader permissions or performs a disallowed action.
A successful read-only check would establish only that path on that version. Multi-file edits, test execution, long context, and error recovery each need further approved checks. The general coding benchmark is not a CCR test: its short function tasks did not exercise this proxy, profile, or Agent tool loop.
Diagnose a failure at the correct layer
| Observation | Check next | Do not infer |
|---|---|---|
| UI loads, model requests fail | Gateway running, client key, provider configuration | The provider is working because the UI opened |
| Upstream rejects access | Key scope, account quota, exact endpoint | A different model will fix the credential |
| Text returns but no tool is called | Selected mode, model tool support, protocol translation | Chat success proves Agent compatibility |
| A different model appears in logs | Routing conditions and fallback policy | The requested model completed the job |
| Cost rises unexpectedly | Retries, context, tool returns, and all resolved routes | A lower token rate guarantees lower task cost |
Do not rotate through accounts to bypass a restriction. Fallback needs an authorized data route, a tested capability contract, and a budget. The routing and failover guide covers that independent decision.
Roll back before uninstalling
End the test Agent session. Restore its previous endpoint, model, profile, and any environment settings that CCR changed. If the service came from ccr ui or ccr start, use ccr stop; a foreground ccr serve must instead be stopped in its terminal or process manager. Confirm a small request uses the restored route before sending real repository work.
The CLI guide states that uninstalling the npm package does not delete local configuration and databases. Preserve required records and revoke test credentials separately; do not delete live SQLite files or private backups while services are running. Prefer the documented export controls for configuration backups.
Conclusion: route evidence precedes a savings claim
Claude Code Router is useful when you need an observable model route, not as proof that every cheaper model is a safe Agent replacement. Establish one provider and a read-only tool loop first. Measure complete workflow cost, retries, and review effort before publishing any savings percentage.
FAQ
Is this an executed CCR setup report?
No. It is a versioned documentation guide and proposed verification procedure. No CCR installation, provider connection, Agent run, or paid model request was performed for this revision.
Does a successful connection check prove Claude Code works?
No. It establishes a model-request path. The selected Agent must separately demonstrate an actual tool call, returned result, and completed task.
Do the management token and provider key have the same purpose?
No. The management token protects the panel, the CCR client key authenticates gateway calls, and the provider key authorizes upstream model access.