9Router 故障排查完全指南配额、限流、OAuth 与连接问题的一线实战手册【免费下载链接】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/9router9Router 是一个把 Claude Code、Codex、Cursor、Cline、Copilot 等编码工具统一接入 40 免费/付费模型提供商的本地网关其核心价值在于通过 Combo 回退链实现订阅优先、便宜兜底、免费救急的路由策略。本文以官方 troubleshooting.md西班牙语版与 英文版 内容一致为主线逐项拆解 8 类高频报错空响应、限流、Token 过期、成本失控、连接拒绝、Dashboard 打不开、模型找不到、响应慢、API Key 无效并深入仓库源码验证每一项的底层实现原理。读完本文你将能在 5 分钟内定位 9Router 日常使用中的绝大多数故障并掌握组合回退 配额追踪 Token 自愈这套开箱即用的自救体系。0. 前置知识9Router 的两个端口与三类端点排查前先记住 9Router 的网络布局后续所有诊断命令都围绕它们展开端点地址用途Dashboardhttp://localhost:3000图形化管理界面提供商、Combo、配额、用量统计OpenAI 兼容网关http://localhost:20128/v1供 Cursor、Cline、Codex 等工具接入的 API 端点内部管理 APIhttp://localhost:20128/api/*CLI 与 Dashboard 调用的管理接口端口20128与http://localhost:20128/v1在 README.md 中作为标准接入方式反复出现CLI 客户端的默认配置也是host: localhost, port: 20128见 cli/src/cli/api/client.js。Dashboard 则默认运行在http://localhost:3000。记住网关看 20128、界面看 3000这条准则以下所有排查思路都会更快落地。1. Language model did not provide messages空响应与配额耗尽1.1 症状与成因症状请求返回空响应或报错典型如 Claude 系工具提示模型没有返回任何消息内容。官方列出的三类成因提供商配额已耗尽subscription quota exhaustedAPI key 无效或已过期模型当前不可用。其中配额耗尽是最常见原因——订阅类提供商Claude Code、Codex普遍采用 5 小时滚动窗口配额免费提供商则常带每日请求数或每月 token 上限。1.2 标准处置流程查看配额状态Dashboard → Providers → 查看配额追踪器若配额耗尽等待重置或切换提供商配置 Combo 回退链Dashboard → Combos → 创建回退链例如cc/claude-opus → glm/glm-4.7 → if/kimi-k2订阅 → 便宜 → 免费验证提供商连接Dashboard → Providers → 必要时重新连接。1.3 源码纵深Combo 回退链是如何接力的Combo 回退不是简单的失败重试而是按顺序逐个尝试、遇错即换的串行路由。核心实现在 open-sse/services/combo.js 的handleComboChat依次调用handleSingleModel(body, modelStr)只要返回 2xx 成功即立即返回结果result.ok判断见 combo.js失败时解析错误体error.message、retryAfter交给checkFallbackError判定是否应回退到下一个模型对 503/502/504 这类瞬时错误会先等待冷却cooldown再继续避免一抖就跳见 combo.js全部模型失败时返回 503并附带最早的重试时间formatRetryAfter让客户端可以精确等待。这也解释了官方建议在 Combo 末尾永远挂一个免费档如if/kimi-k2-thinking的原因即使前序模型全部配额耗尽链路也不会中断而是平滑落到免费兜底模型上。更完整的 Combo 设计预算限制、模型启用/禁用、配额重置时间编排可参考 combos.md。2. Rate Limiting429 与 Too many requests2.1 症状与成因症状返回Rate limit exceeded或Too many requestsHTTP 429。成因订阅配额耗尽5 小时 / 每日 / 每周窗口触达 API 速率限制并发请求过多。2.2 标准处置流程查看重置倒计时Dashboard → Quota Tracking → 查看重置倒计时明确何时能恢复切到便宜档改用glm/glm-4.7$0.6/1M tokens或minimax/MiniMax-M2.1$0.20/1M tokens增加回退 Combo主模型用订阅如cc/claude-opus备份用便宜模型紧急用免费模型if/kimi-k2。2.3 源码纵深指数退避与错误规则引擎9Router 对限流有一套配置驱动的错误分类引擎见 open-sse/config/errorConfig.js文本规则优先匹配rate limit、too many requests、quota exceeded、capacity、overloaded等关键词→ 触发指数退避状态码规则兜底401/402/403/404 固定冷却 2 分钟429 走退避退避基准base: 2000ms、上限max: 5 * 60 * 10005 分钟、最大等级 15errorConfig.js即 2s → 4s → 8s 逐级翻倍未匹配的瞬时错误统一走 30 秒冷却TRANSIENT_COOLDOWN_MS。配额追踪的完整能力实时 token 消耗、重置倒计时、成本估算、预算告警、免费档自动切换以及GET http://localhost:20128/api/quota的查询方式见 quota-tracking.md。此外账户级冷却状态rateLimitedUntil、backoffLevel会持久化在连接记录上applyErrorState/resetAccountState负责写入与成功后的复位open-sse/services/accountFallback.js请求成功时自动清零冷却状态。3. OAuth Token 过期Unauthorized / Token expired3.1 症状与成因症状返回Unauthorized或Token expired。成因OAuth token 过期自动刷新失败提供商会话被服务端失效刷新期间网络异常。3.2 标准处置流程等待自动刷新默认行为9Router 默认自动刷新 token等 30 秒后重试即可手动重连Dashboard → Providers → [提供商名] → Reconnect → 重新走一遍 OAuth 授权流检查提供商服务状态确认 Claude Code、Codex 等服务本身在线。3.3 源码纵深Token 刷新是怎么自愈的自动刷新由 open-sse/services/tokenRefresh.js 统一调度REFRESH_HANDLERS为每个提供商注册专用刷新函数Claude、Codex、Gemini CLI、Antigravity、Kimi、iFlow、Kiro、GitHub、Copilot、Trae、Zed、Windsurf 等见 tokenRefresh.jsrefreshWithRetry默认最多重试 3 次每次间隔递增1s、2s见 tokenRefresh.js令牌到期前有 5 分钟缓冲TOKEN_EXPIRY_BUFFER_MS提前刷新以规避竞态见 tokenRefresh.jsisUnrecoverableRefreshError会识别invalid_grant、refresh_token_reused等不可恢复错误tokenRefresh.js——这类情况等再久也没用必须走手动重连重新授权。所以官方建议等 30 秒重试是有依据的重试窗口覆盖了刷新请求的网络往返与重试机制但如果持续报Unauthorized应直接手动重连而不是反复空等。4. Costos altos成本失控的止血方案4.1 症状与成因症状使用量或账单金额异常升高。成因无谓地使用昂贵模型没有配置便宜档回退上下文窗口过大导致 token 消耗飙升。4.2 标准处置流程查看用量统计Dashboard → Usage Stats → 查看 token 消耗定位高成本模型换便宜模型把cc/claude-opus订阅约 $20–100/月替换为glm/glm-4.7$0.6/1M tokens或minimax/MiniMax-M2.1$0.20/1M tokens启用免费档if/kimi-k2-thinking免费qw/qwen3-coder-plus免费kr/claude-sonnet-4.5免费gc/gemini-3-flash-preview免费180K/月优化提示词压缩上下文、长回复改用流式输出、对高频提示词做缓存。4.3 源码纵深成本为什么能被看住成本控制依赖两套机制协同配额与成本追踪quota-tracking.md展示了按提供商订阅/便宜/免费分类的成本明细、成本预估Dashboard → Costs → Projections以及预算告警80%/90%/100% 触发、超额自动切免费档。底层 API 为GET /api/usage?periodtoday返回按模型拆分的 token 与成本Combo 预算限制在 Combo 编辑页可设每日/每月预算上限达到上限后 9Router 会跳过付费模型、只用免费档见 combos.md 的 Advanced Configuration 一节。实践中订阅 → 便宜 → 免费三段式 Combo 是把成本压到最低的标准姿势订阅档吃掉 80% 流量零边际成本便宜档负责余量免费档兜底。5. Connection Refused连不上 localhost:201285.1 症状与成因症状ECONNREFUSED或Cannot connect to localhost:20128。成因9Router 没有运行端口 20128 被占用或未监听防火墙拦截了连接。5.2 标准处置流程启动 9Router9routerDashboard 应随之打开在http://localhost:3000检查端口 20128 是否在监听# macOS / Linux lsof -i :20128 # Windows netstat -ano | findstr :20128检查防火墙macOSSystem Settings → Network → FirewallWindowsWindows Defender 防火墙 → 允许应用Linuxsudo ufw allow 20128改用云端端点本地网关不可用时例如 Cursor IDE 部署在其他机器/容器可将 Endpoint 配置为https://9router.com/v1。5.3 源码纵深CLI 客户端默认就连这个端口CLI 工具9router命令本身通过 cli/src/cli/api/client.js 的makeRequest与网关通信默认即指向localhost:20128并通过x-9r-cli-token头完成本机鉴权。因此ECONNREFUSED几乎总是服务没起来或端口被占用/防火墙拦截两类原因——先lsof -i :20128确认监听比反复重启客户端更高效。若服务正常但工具仍连不上再检查防火墙放行规则。6. El dashboard no abreDashboard 打不开6.1 症状与成因症状http://localhost:3000无法加载。成因端口 3000 已被其他程序占用9Router 进程崩溃浏览器缓存问题。6.2 标准处置流程确认 9Router 是否在运行# 查看进程 ps aux | grep 9router # 查看端口 3000 lsof -i :3000杀掉占用端口的进程# macOS / Linux lsof -ti:3000 | xargs kill -9 # Windows netstat -ano | findstr :3000 taskkill /PID PID /F重启 9Router# 停止 pkill -f 9router # 启动 9router清理浏览器缓存Chrome 用CtrlShiftDelete → 清理缓存或直接开无痕窗口验证复查防火墙确保 3000 端口未被拦截。注意Dashboard3000与网关20128是两个独立端口。出现工具能连、Dashboard 打不开时问题几乎必然出在 3000 端口的占用或前端缓存上与网关无关反之亦然。7. Modelo no encontrado模型 ID 与提供商前缀7.1 症状与成因症状返回Model not found或Invalid modelHTTP 404错误码model_not_found。成因提供商未连接模型 ID 拼写错误最常见是漏掉提供商前缀提供商处于非活跃状态。7.2 标准处置流程验证提供商连接Dashboard → Providers → 查看状态绿色 活跃检查模型 ID 格式正确cc/claude-opus-4-5-20251101 错误claude-opus-4-5-20251101 标准格式[provider-prefix]/[model-name]列出当前可用模型curl http://localhost:20128/v1/models \ -H Authorization: Bearer your-api-key重新连接提供商Dashboard → Providers → [提供商] → Reconnect。7.3 源码纵深前缀为什么不能省模型 ID 的provider-prefix是 9Router 路由的关键请求进入后网关靠斜杠左侧的短前缀如cc、glm、if、cx、gc、kr把请求分发到对应提供商的执行器与凭据。这一设计在源码中处处可见Combo 判定逻辑getComboModelsFromData直接以modelStr.includes(/)区分单模型与Combo 名open-sse/services/combo.js提供商注册表为每个提供商定义短前缀如 CodeBuddy CN 使用cbcn/glm-5.2open-sse/providers/registry/codebuddy-cn.js价格归一化时也会剥掉厂商前缀deepseek/deepseek-chat → deepseek-chat以匹配基准价open-sse/providers/pricing.js。因此漏写前缀不仅会 404还会让价格与能力视觉/PDF/搜索判定全部失准。拿到 404 时第一件事就是用curl /v1/models拉取真实 ID 列表对照而不是凭记忆拼模型名。8. Respuesta lenta慢响应与超时8.1 症状与成因症状请求耗时过长或超时504 Gateway Timeout。成因提供商端延迟高网络问题上下文/回复体量过大提供商侧限流。8.2 标准处置流程查看提供商延迟Dashboard → Providers → 查看延迟统计换更快的模型快速档cc/claude-haiku-4-5Haiku 比 Opus 快 gc/gemini-3-flash-preview qw/qwen3-coder-flash启用流式输出首 token 更快到达体验上显著变快{ model: cc/claude-opus-4-5, messages: [], stream: true }检查网络延迟ping api.anthropic.com ping api.openai.com压缩上下文裁剪历史消息、缩小提示词、在 CLI 工具中启用 context pruning。8.3 源码纵深慢请求会怎样被对待流式支持stream: true走 SSE 流式通道9Router 的 streaming handler 逐块转发相关实现见 open-sse/handlers/chatCore/streamingHandler.js 与 open-sse/utils/sse.js客户端可在首个 token 到达后立刻开始渲染超时兜底CLI 客户端makeRequest内置 30 秒超时cli/src/cli/api/client.js超过即返回Request timeout错误码语义网关将上游 502/503/504 分别映射为bad_gateway、service_unavailable、gateway_timeoutopen-sse/config/errorConfig.js方便客户端区分上游故障与请求本身问题。9. API Key inválida鉴权失败排查9.1 症状与成因症状返回Invalid API key或Authentication failedHTTP 401错误码invalid_api_key。成因复制了错误的 keykey 已过期或被删除key 根本没有生成。9.2 标准处置流程重新生成 keyDashboard → Settings → API Keys → Generate New Key → 复制使用核对 key 格式正确9r_xxxxxxxxxxxxxxxxxxxxxxxx 错误缺少 9r_ 前缀检查 CLI 工具中的配置# Cursor Settings → Models → OpenAI API Key # Cline Settings → API Key # 环境变量方式 export OPENAI_API_KEY9r_your_key用 curl 直接验证 keycurl http://localhost:20128/v1/models \ -H Authorization: Bearer 9r_your_key9.3 源码纵深key 的校验发生在哪一层本地部署默认宽松但面向公网暴露时可通过环境变量REQUIRE_API_KEYtrue强制所有/v1/*路由校验 Bearer key见 README.md——这正是云端点必须配 key的场景key 的管理走/api/keys接口创建/删除由 Dashboard 的 Settings → API Keys 面板调用cli/src/cli/api/client.js401 错误在错误分类中属于固定 2 分钟冷却档errorConfig.js即换了新 key 后仍可能短暂报 401稍等冷却或重启工具即可无需反复更换。10. 仍然解决不了—— 自检清单与下一步若上述方案都无效按此顺序做一次系统性自检进程与端口ps aux | grep 9router、lsof -i :20128、lsof -i :3000三项全部确认配额与冷却Dashboard → Quota Tracking查看是否有账户处于冷却cooldown状态——存在rateLimitedUntil时请求会直接短路见 open-sse/services/accountFallback.jsToken 状态确认自动刷新是否持续失败必要时手动 Reconnect模型 ID用curl /v1/models拉取真实 ID 逐一比对升级排障查阅仓库内相关主题文档 faq.md、combos.md、quota-tracking.md或到 GitHub Issues 提交包含上述诊断信息的报告。最后一条经验法则9Router 的故障绝大多数不是坏了而是配额没了或路由链断了。把订阅 → 便宜 → 免费的 Combo 回退链配好、养成每天看一次配额面板的习惯你遇到的 90% 的报错都会在下次请求时自动消失——这正是它被设计出来的目的。【免费下载链接】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），仅供参考
