把 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 使用教程。
推荐的接入顺序
先在 9Router 内创建一个单一 Provider 的测试路由，再让 Claude Code 指向该路由。确认能完成一次简单对话后，再加入 fallback、多个账号或本地模型。
配置时重点核对：
- Base URL 是否是 9Router 的 OpenAI-compatible endpoint，而不是上游厂商地址；
- API key 是否由当前 9Router 实例签发；
- Claude Code 中填写的模型名，是否与 9Router 的模型或 Combo 名完全一致；
- 改完环境变量或配置后，终端与 Claude Code 是否已经重新启动。
不要把上游 Provider 的 key 直接散落在多个项目配置里。把它留在 9Router 中，Claude Code 只保存本地路由器所需的最小凭据，迁移和撤销会更容易。
常见报错怎么排查
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？
先查看服务日志中的显存不足、上下文超限、并发排队或模型名不匹配。把本地模型作为主路由前，应在真实任务长度下连续验证，而不是只测试一句短提示。