Connect Claude Code to 9Router

Point Claude Code at your running 9Router instance and choose a model ID that the router can actually serve. The current 9Router settings writer uses ANTHROPIC_BASE_URL with a /v1 suffix. A compatible endpoint is only part of the setup: authentication, model mapping, and tool-call behavior also need to work.

This guide describes routing a Claude Code client. Connecting a Claude subscription as an upstream provider is a different operation. Do not assume that configuring the client automatically connects or authorizes a provider account.

Before changing settings

Complete the installation checks. You should have a reachable dashboard, a working provider connection, and an exact model ID or a combo name. Also confirm that Claude Code already starts successfully with its current configuration.

Close active coding sessions before applying configuration changes. Back up your existing settings file, commonly ~/.claude/settings.json, using a new backup filename. Preserve its existing permissions, hooks, environment settings, and other integrations. Replacing the whole file with a short example can silently remove unrelated configuration.

If Claude Code runs on a different machine from 9Router, determine the address that it can reach. A Docker dashboard changing a file inside its container does not necessarily change the client configuration on your host.

Use the router’s client setup

Open the 9Router dashboard, find its CLI tools setup, and choose Claude Code. Select your local endpoint and a currently available model or combo. Review the generated values before applying them.

The settings writer reviewed for this guide merges an env object into the existing Claude settings and normalizes the base URL to end in /v1. The following is a structural example of the relevant part of that file:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_ROUTER_KEY",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "YOUR_EXACT_MODEL_ID"
  }
}

Replace both uppercase placeholders locally. They are not usable credentials or model names. Never paste your real key into this Wiki, a search engine, or a public issue. If you use the dashboard’s generated configuration, prefer its values for your installed version over a static example.

The current settings writer preserves an existing ANTHROPIC_AUTH_TOKEN instead of automatically replacing it. If a change appears to succeed but authentication still fails, inspect which token remains in the file. Do not assume that every Apply operation replaced the old value.

Pick one model mapping first

Claude Code has model aliases such as sonnet, opus, and haiku. The router may use provider-prefixed model IDs. These are different naming layers.

For an initial test, map one alias to one known working model. You can then select that alias in Claude Code. If you instead use a combo, ensure that the combo name exactly matches what the client sends. The fallback guide explains this mapping.

Avoid copying a dated model ID from an old article. Model availability depends on the connected provider and account. A model name that looks plausible may produce a model-not-found error, or it may refer to a route whose provider is currently unavailable.

The upstream combo interface also documents default Claude combos. Inspect any generated mappings before relying on them. A generated combo is a configuration convenience, not a test that all of its model routes work.

Run a small verification

Restart Claude Code so that it loads the changed configuration. In an empty scratch directory, ask a short question that does not contain private code, such as asking for a one-line explanation of a loop.

Confirm three things:

1. Claude Code receives a complete response rather than hanging during streaming.
2. Your 9Router instance records the corresponding request.
3. The selected provider and model match the route you intended to use.

A successful text reply proves only that text request. For coding use, follow with a harmless task in the scratch directory, such as asking the client to read a file you created for testing. Keep normal tool approvals enabled. If text works but tool use fails, investigate model capability and protocol translation rather than repeatedly changing the API key.

Do not measure cost savings from one short request. Token reporting, cached input, retries, and provider billing can differ. If cost is your goal, compare the same task under controlled settings and use the provider’s actual usage records.

Diagnose the common failures

Connection refused: the client cannot reach the local server. Recheck the host, port, process, and whether the client runs in a container or WSL.

Authentication rejected: distinguish the key used by Claude Code to reach 9Router from the credentials 9Router uses upstream. Inspect the request log to see which boundary rejected the request.

Model not found: inspect the exact ID or alias received by the router. Correct the mapping before adding fallbacks.

Text works, tools fail: use a model that supports the required tool behavior and inspect the installed router’s compatibility notes. A response-format failure is not evidence that the entire provider is offline.

Restore the previous route

Close the client, restore your saved settings, and remove any temporary environment overrides from the shell session. Restart the client and confirm that it reaches the original provider again. Keep router data until you are sure you no longer need its configuration.

If you use the dashboard’s reset function, inspect its scope first. A reset may remove router-related fields without reconstructing every original value. Your own backup is the reliable record of the setup you had before this change.

Does a Claude Code route guarantee a Claude response?

No. The client name identifies the application; the configured model mapping and provider determine inference. A combo can fall back to another model family if you allow it. Inspect the selected route and provider usage rather than asking the model to identify itself. The Claude account and model guide explains the separate layers.

Why is cached-token usage missing?

Missing dashboard data does not by itself prove that no caching occurred. Issue #5114 raises this question for a Claude Code route through Kiro. Compare upstream usage fields with the router’s displayed statistics and preserve the version and model ID in a redacted reproduction. Do not derive a savings percentage from an absent counter.