9Router Claude Code 配置教程：API Base URL、模型路由与常见报错

Sat, 11 Jul 2026 11:00:00 +0800

把 Claude Code 接到 9Router，关键不是复制一段配置就结束，而是让客户端、9Router Provider 和目标模型的名称保持一致。出现 401、404 或“模型不可用”时，也应先分层定位，而不是反复更换 API key。

配置前先确认三件事

9Router 服务已启动，并能打开本地管理界面。
已在 9Router 中添加 Provider，且 Provider 的密钥和连通性正常。
记下 9Router 提供给 OpenAI-compatible 客户端的 Base URL、API key，以及可用的模型或 Combo 名称。

Claude Code 只应请求 9Router 的 Base URL；具体把请求发往哪个 Provider、哪个模型，则交给 9Router 的路由规则处理。完整定位和安装背景可先看 9Router 使用教程。

常见报错怎么排查

401 或 Unauthorized

先确认请求是否真的到达本地 9Router，再检查 API key。若管理面板能登录但客户端仍然 401，通常是客户端用错了 key，或 Base URL 指向了另一台实例。

404 或 endpoint not found

多数情况是 Base URL 多写或少写了路径。不要凭感觉拼接 /v1；以当前 9Router 页面或文档展示的 OpenAI-compatible 地址为准，并用一次最简单的请求验证。

model not found

先在 9Router 查看模型列表。Provider 的原始模型名、你定义的别名和 Combo 名可能并不相同；Claude Code 应填写路由器暴露出来的那个名称。

请求能发出但总是 fallback

查看第一优先 Provider 的状态、余额/配额、模型权限和请求日志。fallback 是兜底机制，不应替代对首选模型失败原因的修复。

建议保留一个最小测试配置

复杂路由上线前，保存一份“一个 Provider、一个模型、无 fallback”的测试配置。日后遇到问题时，先回到这份基线：基线正常说明故障在路由规则；基线也失败则继续检查网络、凭据或 Provider。

若你的问题发生在 Claude Code 本身的安装、权限或项目环境，可继续看 Claude Code 多项目记忆与 Hooks。

总结

9Router 与 Claude Code 的接入核心是：Base URL 指向路由器、模型名匹配路由器、上游逻辑留在路由器。按“连通性—鉴权—模型名—路由规则”的顺序检查，通常能避免大多数配置问题。

一套便于排错的配置模型

可以把整条调用链画成四层：Claude Code → 9Router endpoint → Provider → 实际模型。每一层只回答一个问题：客户端是否把请求交给路由器、路由器是否接受凭据、规则是否选中 Provider、Provider 是否能调用模型。日志和测试也应按这四层分开保存。

例如，先在 Claude Code 中使用一个固定模型名；随后在 9Router 中让该名称只对应一个 Provider。这样当请求失败时，能快速判断是客户端配置还是上游服务问题。等稳定后，再把这个模型名改为 Combo，并为它添加第二个 Provider。不要让 Claude Code 直接感知多个上游名称，否则每个项目又会积累一套难以维护的配置。

用最小请求验证，而不是直接跑长任务

每完成一层设置，就做一次低成本验证：

用 9Router 自己的健康检查或管理界面确认服务在监听。
用一个简单、无工具调用的请求确认 API key 和模型名。
在 Claude Code 中让它解释当前目录的一小段文本，验证客户端能收到响应。
最后才测试读文件、运行测试、长上下文或并行 Agent。

长任务会混入网络、工具权限、上下文和重试等变量；它失败时很难知道是路由问题还是任务本身的问题。把最小请求保存在自己的排障笔记中，换电脑或升级后也能复用。

路由规则怎样设计更稳

将“默认模型”和“高成本模型”分开。默认模型承担常规问答、格式整理和低风险改动；只有需要复杂推理、代码审查或长上下文时，再显式选择更强模型。这样既避免不必要的费用，也便于从日志中观察哪个任务真正需要升级。

fallback 的触发条件也应保守：网络错误、明确的限额错误或 Provider 不可用可以切换；模型返回了不理想答案不应立即自动重试多个 Provider。后者会放大 token 消耗，并让结果难以复现。

部署与凭据安全清单

9Router 不应暴露在没有访问控制的公网地址上。
DATA_DIR、备份和日志可能包含 Provider 信息，应按敏感配置处理。
不把上游密钥写入仓库、截图或 Claude Code 项目说明文件。
升级前备份配置；升级后先以最小请求测试，再恢复生产路由。

FAQ：是否要在每个项目都配置 9Router？

通常不需要。客户端级环境变量或统一管理工具可以为多个项目复用 endpoint；项目级配置只在某个仓库确实需要专用模型、专用权限或隔离账单时才有价值。

FAQ：本地模型为什么经常 fallback？

先查看服务日志中的显存不足、上下文超限、并发排队或模型名不匹配。把本地模型作为主路由前，应在真实任务长度下连续验证，而不是只测试一句短提示。

模型路由 on KnightLi的博客