本地模型 api_base_url 配置错误（Ollama 等）

你会遇到什么

你按教程把网关切到本地模型（比如 Ollama），配置里填了 api_base_url，结果一发请求就报错：找不到模型（model not found）、连接被拒（connection refused），或者网关直接弹路由错误。教程里"把地址填进去"看着很简单，但地址填法差一点就完全不通。

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

为什么会这样

网关（claude-code-router）请求模型时不是直接请求 base 地址，而是请求一个完整 URL：base + /v1/chat/completions。只填 http://localhost:11434 这种 base 地址，网关拼不出完整路径，服务端要么 404、要么报连接拒绝；漏掉 /v1 段也一样，OpenAI 兼容端点通常挂在 /v1 下（上游 Issue #239 场景）。

• 模型名必须和 ollama list 输出逐字一致（含 :8b 之类 tag，大小写也算）。
• 改完配置必须重启网关才生效，改完不重启 = 看起来没改。

网关调用模型走的是标准 OpenAI 兼容协议：客户端 → 网关 → 模型服务，最后一段请求是“POST 到模型服务的某个 URL”。这个 URL 不是随便填的，它由协议规定：OpenAI 兼容端点固定挂在 {base}/v1/chat/completions，base 是服务地址（含端口），/v1/chat/completions 是协议路径。

网关配置里的 api_base_url 是“base + 路径”的合体——只填 base 等于告诉网关“端点不存在”，它拼不出协议要求的完整路径；漏 /v1 等于告诉它“端点在一个不存在的位置”。这就是“填法差一点，结果完全不通”的机制原因。模型名是第二道精确匹配：服务端按名字索引模型，名字对不上就是 model not found（含 tag、大小写）。

还有一层容易被忽略：配置是启动时加载的，改完不重启，网关内存里还是旧配置——“看起来没改”其实是“没重载”。

一步步来

1. 确认模型真在 — 必做

ollama list

输出里要有你要用的模型名，比如 qwen3:8b。没有就先 ollama pull <模型名> 拉下来。

2. 填完整 URL — 必做

把配置里的 api_base_url 改成（Ollama 例）：

http://localhost:11434/v1/chat/completions

关键点：含端口、含 /v1/chat/completions 完整路径，不要只填 base。

3. 模型名逐字对齐 — 必做

配置里的模型名必须和 ollama list 输出逐字一致（含 tag）。拿不准就把 ollama list 第一列复制过去。

4. 重启网关再测 — 必做

ccr restart

重启后发一条测试请求，确认不再报错。

怎么确认修好了

用 curl 直接打完整地址能拿到正常响应（实测可用形态）：

curl http://localhost:11434/v1/chat/completions -d '{"model":"<你的模型名>","messages":[{"role":"user","content":"hi"}]}' -H 'Content-Type: application/json'
→ HTTP 200 + JSON 响应（含 choices）

网关侧再发同样请求，不再出现 model not found / connection refused。

其它环境的表现

症状

配置本地模型（Ollama 等）后请求失败：找不到模型 / 连接拒绝 / 路由报错。

原因

api_base_url 必须写完整 URL（含 /v1/chat/completions 路径）；只写 base（如 http://localhost:11434）或漏 /v1 都会失败（上游 Issue #239 场景）。

解法

1. 写完整 URL：http://localhost:11434/v1/chat/completions（Ollama 例）。
2. 模型名与 ollama list 输出一致。
3. 保存后重启网关再测。