Connecting Claude Code to 9Router is not just a matter of pasting a configuration snippet. The client, 9Router Provider, and target model names must agree. When you see a 401, 404, or “model unavailable” error, isolate the layer first instead of repeatedly changing API keys.
Confirm three things before configuring
- The 9Router service is running and its local management UI opens.
- A Provider has been added in 9Router, with a working key and connectivity.
- You have the OpenAI-compatible Base URL, API key, and available model or Combo names exposed by 9Router.
Claude Code should call only 9Router’s Base URL. 9Router should decide the Provider and model through its routing rules. For installation and background, see the 9Router guide.
Recommended connection order
Create a test route in 9Router with one Provider only, then point Claude Code at it. After a simple conversation works, add fallback, multiple accounts, or local models.
Check these details:
- The Base URL is 9Router’s OpenAI-compatible endpoint, not an upstream vendor URL.
- The API key was issued by the current 9Router instance.
- The model name in Claude Code exactly matches a model or Combo exposed by 9Router.
- Terminals and Claude Code have been restarted after changing environment variables or configuration.
Do not scatter upstream Provider keys across project configurations. Keep them in 9Router and let Claude Code store only the minimum credentials needed for the local router; revocation and migration become easier.
Troubleshooting common errors
401 or Unauthorized
First verify that the request reaches local 9Router, then check the API key. If the management UI works but the client still gets a 401, the client is often using the wrong key or pointing at another instance.
404 or endpoint not found
This usually means the Base URL has an extra or missing path segment. Do not guess whether to append /v1; use the OpenAI-compatible address currently shown by 9Router and verify it with the simplest possible request.
model not found
Check the model list in 9Router. An upstream model name, a custom alias, and a Combo name may all differ. Claude Code must use the name exposed by the router.
Requests work but always fall back
Check the first-choice Provider’s status, balance or quota, model permission, and request logs. Fallback is a safety net, not a replacement for fixing why the preferred model fails.
Keep a minimal test configuration
Before deploying complex routing, keep a baseline with one Provider, one model, and no fallback. When something breaks, return to it first: a working baseline points to routing rules; a failing baseline points to networking, credentials, or the Provider.
For Claude Code installation, permissions, or project-environment issues, see Claude Code project memory and Hooks.
Summary
The core setup is simple: point the Base URL at the router, match the router’s model name, and keep upstream logic in the router. Check connectivity, authentication, model name, and routing rules in that order.
A configuration model that is easy to debug
Think of the request chain as four layers: Claude Code → 9Router endpoint → Provider → actual model. Each layer answers one question: did the client reach the router, did the router accept credentials, did a rule select a Provider, and can that Provider call the model? Keep tests and logs separated by these layers.
For example, begin with one fixed model name in Claude Code and map it to a single Provider in 9Router. Once that is stable, turn the name into a Combo and add a second Provider. Avoid exposing many upstream names directly to Claude Code, or every project will accumulate its own hard-to-maintain configuration.
Validate with a minimal request, not a long task
After each layer is configured, run a low-cost test:
- Use 9Router health information or its management UI to confirm the service is listening.
- Send a simple request without tool calls to verify the API key and model name.
- Ask Claude Code to explain a small piece of text in the current directory.
- Only then test file access, test execution, long contexts, or parallel Agents.
Long tasks add networking, tool permissions, context, and retry variables. Save a minimal request in your troubleshooting notes so it can be reused after an upgrade or on another machine.
Designing stable routing rules
Separate a default model from a high-cost model. Use the default for routine questions, formatting, and low-risk changes; explicitly choose the stronger model for complex reasoning, code review, or long context. This makes spending easier to understand and shows which work actually merits an upgrade.
Be conservative about fallback triggers. Network errors, explicit quota errors, and Provider outages can justify a switch; an unsatisfying answer should not automatically retry several Providers. That multiplies token use and makes output hard to reproduce.
Deployment and credential security checklist
- Do not expose 9Router on a public address without access controls.
- Treat
DATA_DIR, backups, and logs as sensitive because they may contain Provider information. - Never put upstream keys in repositories, screenshots, or Claude Code project instructions.
- Back up before upgrading; test with a minimal request before restoring production routes.
FAQ: Do I need to configure 9Router in every project?
Usually no. A client-level environment variable or management tool can reuse one endpoint across projects. Project-level configuration is useful only when a repository truly requires a dedicated model, permissions, or billing isolation.
FAQ: Why does a local model fall back so often?
Check service logs for out-of-memory conditions, context limits, concurrency queues, or a model-name mismatch. Validate a local model repeatedly with real task lengths before making it the primary route.