Problem: First run shows No available models / gateway won't start —— Trove problem library

What you will run into

ccr start / ccr serve says No available models. Configure at least one provider... and the management UI shows no available models.

Don't panic - this is normal on first run: no provider is configured yet (the provider config under ~/.claude-code-router/ is empty), not a fault.

Why this happens

The gateway needs a list of available models at startup; when the config is empty it honestly reports "no available models" and refuses to serve. Configure a provider + model, then restart the gateway.

A gateway's core job is routing: forwarding model requests from the client to the real model provider.

Routing presupposes knowing "which models exist and which provider each goes through", so at startup it reads the config and builds a "model -> provider" routing table; when the table is empty it cannot guess and honestly refuses (No available models).

This is the gateway's fail-fast design — it would rather refuse to serve than silently forward to the wrong provider and produce "looks like it's serving, but everything 502s".

That fixes the repair path: write the config (the table now has content) -> restart the gateway (the table reloads) -> verify again.

Editing config without restarting has no effect, because the routing table is built once at startup; stop && start is the complete reload.

Step by step

1. Start and open the management UI — Required

ccr start

Open the management UI in a browser per the output hint (default localhost port).

2. Add provider + model — Required

Add your provider (OpenAI/Anthropic/domestic models etc.) and a model in the management UI.

3. Or edit the config directly — Required

~/.claude-code-router/ (this version uses config.sqlite; see the config section in guide.md), write the provider in the expected format.

4. Restart the gateway — Required

ccr stop && ccr start

After the config takes effect, starting no longer reports No available models.

How to confirm it works

ccr start

No more No available models and the management UI lists models = success (measured: honestly prompts when unconfigured, starts normally after configuring).

Other environments

Symptom

ccr start / ccr serve says No available models. Configure at least one provider...; the management UI shows no available models.

Cause

No provider configured yet (the provider config under ~/.claude-code-router/ is empty) - normal on first run, not a fault.

Solution

1. After ccr start, open the management UI in a browser and add a provider + model.
2. Or edit the config file directly (~/.claude-code-router/, this version uses config.sqlite; see the config section in guide.md).
3. Restart the gateway after adding (ccr stop -> ccr start).