首次运行 No available models / 网关起不来

你会遇到什么

ccr start / ccr serve 提示 No available models. Configure at least one provider...，管理界面没有可用模型。别慌——这是首次运行的正常现象：还没配置任何 provider（~/.claude-code-router/ 下 provider 配置为空），不是故障。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

网关启动时需要一个可用模型列表；配置为空时它如实提示"没有可用模型"，并拒绝提供服务。配置好 provider + 模型后重启网关即可。

网关（gateway）的核心职责是路由：把客户端发来的模型请求转发给真正的模型提供商。路由的前提是知道“有哪些模型可用、各自走哪个 provider”，所以启动时它会读取配置构建一张“模型 → provider”的路由表；表为空时它不能猜，只能如实拒绝（No available models）。

这其实是网关的fail-fast 设计——宁可拒绝服务也不静默转发到错误的 provider，避免“看起来在服务、实际全 502”。

也因此修复路径固定：写配置（路由表有了内容）→ 重启网关（路由表重新加载）→ 再验证。改配置不重启不生效，因为路由表只在启动时构建一次，stop && start 才是完整的重载。

实测环境：ccr --version 输出同样的提示（+ 闭环日志 step 2），符合预期；配置步骤见 站内文档。

一步步来

1. 启动并打开管理界面 — 必做

ccr start

按输出提示在浏览器打开管理界面（默认 localhost 端口）。

2. 添加 provider + 模型 — 必做

在管理界面添加你的 provider（OpenAI/Anthropic/国产模型等）和模型。

3. 或直接编辑配置 — 必做

~/.claude-code-router/（本版为 config.sqlite；见 guide.md 配置节），按格式写入 provider。

4. 重启网关 — 必做

ccr stop && ccr start

配置生效后再启动，不再报 No available models。

怎么确认修好了

ccr start

不再出现 No available models、管理界面能列出模型即成功（实测：未配置时如实提示，配置后正常启动）。

其它环境的表现

症状

ccr start / ccr serve 提示 No available models. Configure at least one provider...；管理界面没有可用模型。

原因

尚未配置任何 provider（~/.claude-code-router/ 下 provider 配置为空）——首次运行正常现象，不是故障。

解法

1. ccr start 后浏览器打开管理界面，添加 provider + 模型。
2. 或直接编辑配置文件（~/.claude-code-router/，本版为 config.sqlite；见 guide.md 配置节）。
3. 添加后重启网关（ccr stop → ccr start）。