9Router 排坑实录：模型未找到、认证失败、连接超时一个都别漏

9Router 排坑实录模型未找到、认证失败、连接超时一个都别漏【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router把 Claude Code、Codex、Cursor、Cline 这些 CLI 工具统一接到 9Router本质上就是改两样东西一个BASE_URL、一个 API Key然后祈祷一次通过。但现实往往是——模型名照着文档抄了还是 404Key 明明复制对了却报 401请求偶尔能发出去、偶尔直接卡死超时。这类问题在 GitHub Issues 和社区教程里反复出现几乎成了每个 9Router 新用户的第一道坎。这篇文章不再停留在重新连一下就好的层面而是直接钻进仓库源码把模型未找到、认证失败、连接超时这三类高频故障的根因逐一拆开并给出可复现的排查路径。模型未找到别名与模型列表对不上的真相Model not found404是出现频率最高的报错。在 9Router 中这个错误码来自统一错误映射表 errorConfig.js上游返回 404 时客户端收到的是{ type: invalid_request_error, code: model_not_found }。也就是说只要你请求的模型 ID 不在路由器的可解析范围内就会得到这个结果。根因一模型 ID 的别名前缀没对上9Router 的所有模型 ID 都带别名前缀格式是别名/模型名例如cc/claude-opus-4-6、kr/claude-sonnet-4.5、glm/glm-5。前缀不是随便写的它来自 providers.js 中定义的PROVIDER_ID_TO_ALIAS映射并在 models 路由 里通过ALIAS_TO_PROVIDER_ID反查、按outputAlias生成对外模型 ID。这就带来第一个坑同一个模型在文档、Dashboard、CLI 工具三处的写法可能不同。源码里有一段专门的前缀剥离逻辑见 models/route.js 第 496-509 行从/v1/models拉回的模型 ID 如果已经带了outputAlias/、staticAlias/或providerId/前缀会被逐一尝试剥掉再合并去重最后统一重新拼成outputAlias/模型名。如果你在 CLI 里配的模型名是claude-sonnet-4.5漏了kr/或者写成了kiro/claude-sonnet-4.5真实前缀是kr/路由器就找不到这条记录直接 404。判断方法很简单请求GET http://localhost:20128/v1/models把响应里真实存在的 ID 原样复制进配置不要凭记忆手敲。根因二模型列表是动态拉取的文档只是基线很多用户对着 README 里的模型清单配置却发现kr/deepseek-3.2这种 ID 在GET /v1/models里根本不存在。这是因为 9Router 的模型列表是动态构建的有活跃连接时buildModelsList 会优先走LIVE_MODEL_RESOLVERSKiro、Qoder、Kimchi、GitHub Copilot、ClinePass、Grok CLI、Cursor、Zed 都在其中用你的账号 Token 实时拉取上游目录只有数据库不可用时才回退到PROVIDER_MODELS静态表。resolveKiroModels这类解析器一旦失败Token 过期、接口变更代码会静默降级到静态列表——你看到的是可用列表实际请求时却可能因为模型 ID 与上游不一致而 404。这也是为什么社区教程里反复强调先跑一次 health check 和 model list 再下结论/v1/models的实时输出才是唯一可信的模型清单README 里的表格只代表基线能力。根因三Combo 座位写错或嵌套循环9Router 的 Combocc/claude-opus-4-6 → glm/glm-5 → kr/claude-sonnet-4.5会把整条链作为一个模型 ID 暴露。源码中 comboSeatLimits 对无斜杠的座位名会当作嵌套 Combo 递归解析且带了循环守卫visiting集合。如果你在 Combo 里把某个座位名写成了不存在的别名聚合能力计算aggregateComboCapabilities虽然不会崩但发布出去的 ID 和实际可路由的座位对不上同样会 404。排查清单GET /v1/models核对真实 ID禁止凭文档手写确认别名前缀cc/、cx/、gh/、cu/、glm/、kr/、oc/等大小写敏感Combo 座位逐个验证存在性避免嵌套死循环若用了自定义模型检查providerAlias是否正确——aliasRepo.js中自定义模型的 key 是providerAlias|id|type前缀不一致同样查不到。认证失败Key 配置的五个易错点401authentication_error的语义是这个 Key 不被接受。但 9Router 的认证链路分两层外层是9Router 自己的 Key内层是上游提供商的 Key/Token。两层混在一起是绝大多数认证排查走弯路的原因。易错点 1把sk_9router当成了真实 Key这是最隐蔽的坑。UI 在未配置云 Key 时默认展示占位符sk_9router见 DefaultToolCard.js/dashboard/cli-tools/components/DefaultToolCard.js) 第 23 行。但源码注释写得很清楚这个占位符从来不是真实 Key。resolveApiKey.js 专门做了修正——过去 CLI 配置路由会把这个占位符写进Authorization头导致所有开启requireApiKey的部署一律 401对应 issue #4399现在解析逻辑明确占位符永不写入。所以Dashboard 里显示的sk_9router只是示例真正的 Key 要在 Endpoint 页面的 API Keys 卡片里创建或直接复用 Dashboard 登录凭证。易错点 2requireApiKey开启后Key 校验是可选即 4019Router 默认REQUIRE_API_KEYfalse/v1/*路由不做 Bearer 校验但一旦你在 Endpoint 设置里打开 Require API key生产环境强烈建议校验就变成硬性要求。v1beta/models 路由 展示了统一模式settings.requireApiKey为真时缺失 Key 直接回 401 Missing API key无效 Key 回 401 Invalid API key。注意Dashboard 登录密码和 API Key 是两套体系。CLI 工具用的是 API KeyDashboard 用的是INITIAL_PASSWORD默认123456。拿登录密码当 API Key 填必然 401。易错点 3上游 Key 过期 vs 外层 Key 错误要分清楚外层 Key 正确的情况下401 往往来自上游。错误映射表里 errorConfig.js 对 401 统一归类为invalid_api_key但实际来源可能是Kiro/Perplexity 等cookie/Token 型提供商凭证过期后executor 层会明确提示re-paste your SSO cookie如 grok-web.js、perplexity-web.jsQoder 无用户 ID 时无法签名qoder.js 会主动回 401 以便 Dashboard 提示重新连接OAuth 型提供商 Token 过期9Router 有自动刷新机制tokenRefresh刷新失败时表现为间歇性 401。判断技巧看错误消息文本。外层 Key 问题消息是 Invalid API key provided / Missing API key上游问题往往带着提供商名Grok auth failed、Perplexity auth failed或提示重新连接。易错点 4Bearer 头与 x-api-key 头混用9Router 兼容 OpenAI 和 Anthropic 两类客户端。OpenAI 系走Authorization: Bearer keyAnthropic 系Claude Code走x-api-keyanthropic-version头——这在 models/route.js 的fetchCompatibleModelIds里体现得很清楚Anthropic 兼容提供商同时带x-api-key和Authorization并且自动把/messages路径改写为/models再探测。如果客户端是 Claude Code 但你在配置里手动填了Authorization: Bearer或者反过来上游探测就可能失败。正确姿势是让 CLI 工具使用各自的官方配置方式Claude Code 用ANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN让 9Router 自己处理头格式。易错点 5多实例互联时的递归环9Router 支持实例互相连接A 实例把 B 实例当上游。源码里专门定义了内部头x-9r-internal-models-fetchmodels/route.js 第 168 行用于识别跨实例的/models抓取并打断递归环。如果两台实例互指且没有这个保护模型探测会无限循环。排查时如果发现fetchCompatibleModelIds反复触发且响应缓慢先检查是否存在循环连接。排查清单在 Dashboard 创建真实 API Key替换sk_9router占位符确认requireApiKey状态与你的客户端行为一致区分错误消息来源外层 vs 上游上游过期去 Dashboard 重新连接OpenAI 系用BearerClaude Code 用官方环境变量检查多实例互联是否成环。连接超时与网络层的排查路径超时问题在 9Router 里分三个层面客户端到 9Router、9Router 到上游、上游自身的可用性。三者症状相似卡住、超时、502/504但排查路径完全不同。超时可能在 9Router 内部上游探测有 5 秒硬超时models/route.js 的fetchCompatibleModelIds给上游/models探测挂了AbortController 5 秒超时失败静默返回空数组。也就是说如果上游慢GET /v1/models会成功但缺模型而不是报错。你看到的现象是模型列表忽多忽少本质是上游探测超时后降级到了静态表。代理配置是超时的头号来源9Router 的出站请求统一走 proxyFetch.js代理解析优先级明确HTTPS_PROXY ALL_PROXYhttps 目标、HTTP_PROXY ALL_PROXYhttp 目标并支持大小写变体。以下几个坑是社区反馈里最集中的NO_PROXY写错导致该直连的被代理shouldBypassByNoProxy的匹配规则是hostname pattern || hostname.endsWith(.pattern)且支持*通配。如果你把NO_PROXY写成localhost而目标是127.0.0.1匹配不上请求就会被错误地送进代理代理 URL 忘记协议normalizeProxyUrl会宽容地把127.0.0.1:7890自动补成http://127.0.0.1:7890但如果你填的地址本身不可达表现就是持续超时企业 MITM 证书导致 TLS 握手失败fetchWithTlsFallback在非STRICT_SSL模式下遇到证书错误会自动用rejectUnauthorized: false重试——如果你把STRICT_SSL设成了true这个兜底被关闭自签名证书场景直接握手失败。端口与监听地址问题9Router 默认端口是20128。README 的 Troubleshooting 明确提示Dashboard 打开在错误端口时需要同时设置PORT20128和NEXT_PUBLIC_BASE_URLhttp://localhost:20128。如果NEXT_PUBLIC_BASE_URL与PORT不一致CLI 客户端拿到的回调地址就是错的表现同样接近连不上。另外localhost与127.0.0.1在某些环境IPv6 优先、防火墙策略下行为不同。CLI 配置端点时建议统一用http://127.0.0.1:20128避免 DNS/回环解析差异。把连接超时当作诊断信号而不是终点在 9Router 的错误分类里errorConfig.js502/504 都被标记为server_error类并配有upstream provider error的默认消息。这意味着当 CLI 报超时/网关错误时问题大概率不在 9Router 本体而在上游链路。此时应逐层验证curl http://127.0.0.1:20128/v1/models确认 9Router 本身活着检查上游提供商状态与配额Dashboard 的 Quota 追踪器确认HTTP_PROXY/HTTPS_PROXY/NO_PROXY环境变量是否符合预期开启ENABLE_REQUEST_LOGStrue在logs/目录里看请求实际发出去了没有、上游响应了什么确认requireApiKey等安全设置没有挡住 CLI 的请求401 与超时在客户端表现可能混淆。一张图看懂 9Router 的请求链路9Router 的完整架构可以从 README 的架构图直观理解CLI 工具请求打到http://localhost:20128/v19Router 完成 RTK 压缩、格式翻译OpenAI ↔ Claude、配额追踪后按订阅 → 便宜 → 免费三级回退路由到上游。这张图解释了为什么同一个请求在不同时刻可能命中完全不同的上游——模型未找到、认证失败、超时都可能在回退切换的瞬间出现排坑的核心心法就是时刻记住这条链路的每一跳都有独立的身份与网络模型 ID 要匹配 9Router 的别名空间Key 要区分外层/上游两层超时要先定位是哪个环节掉链子。把这三件事拆开绝大多数 404、401、超时问题都能在五分钟内定位到根因。结语模型未找到、认证失败、连接超时表面上是三类孤立的报错实际上共享同一个底层逻辑9Router 是一个翻译 路由代理不是简单的端口转发。它的模型命名空间、双层认证、动态模型探测、代理链路都意味着你不能用直连 OpenAI的思维去排查。记住三个铁律以/v1/models的真实输出为准、以错误消息的文本区分认证层级、以请求日志定位超时环节——这三条能覆盖社区反馈中绝大多数的翻车场景。剩下的就是让自动回退和 RTK 帮你把编码节奏拉满。【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考