9Router：AI 路由、Token Saver 与故障转移

理解该项目的有效方式是将其视为编程工具与模型账户之间的基础设施。Claude Code、Codex、Cursor、Cline、Copilot 类客户端、Antigravity、OpenClaw 以及其他 OpenAI-compatible 工具都可以指向 `http://localhost:20128/v1`；随后 9Router 会决定如何转换、压缩、路由、重试和记录请求。

Get the latest on AI, LLMs & developer tools

New MCP servers, model updates, and guides like this one — delivered weekly.

观看 9Router 视频

更喜欢阅读？下方的书面指南涵盖了架构、设置、风险和实际结论。

编辑说明

本文基于 2026 年 6 月 3 日研究的 GitHub 仓库、README、包元数据、源码树、npm 元数据、发布/标签、近期 Issue、近期 PR 以及提供商配置文件。README 中关于免费/无限制的表述被视为项目定位，而非经独立验证的配额建议。

1. 一句话解释 9router

9Router 是一个采用 MIT 协议的本地 LLM 网关，专为编程 Agent 设计，集成了 OpenAI-compatible API、提供商转换、多账户故障转移、配额跟踪、RTK 工具输出压缩、仪表板以及 Docker/本地部署功能。

领域	细节	为什么重要
代码仓库	decolua/9router	https://github.com/decolua/9router
主要语言	JavaScript	调研时 GitHub 显示的主要语言。
许可证	MIT	如有相关的打包或二进制许可证，请单独检查。
创建时间	2026 年 1 月 5 日	已检查已发布包：0.4.66（2026 年 5 月 29 日）；已检查 GitHub Releases 最新条目：v0.4.63（2026 年 5 月 26 日）。

2. 为什么重要

该项目之所以重要，是因为 AI 编程工作流不再局限于单一客户端或模型提供商。开发者通常会并行使用 Claude Code、Codex、Cursor、Cline、Antigravity 和 OpenAI-compatible 工具，而模型访问则来自订阅、API 密钥、免费层级、区域提供商和本地兼容端点。

9Router 试图将这种混乱局面标准化为一个端点和一个仪表板。当某个提供商达到配额或更改事件格式时，无需重新配置每个编程工具，只需在路由器中创建提供商账户、模型别名、组合和故障转移链即可。

激进的 Token Saver 策略也非常实用。编程 Agent 会在 diff、grep 输出、日志、文件列表和重复的工具记录上消耗大量上下文。RTK 压缩在格式转换之前运行，因此该项目可以在不要求每个上游客户端了解压缩格式的情况下减小负载大小。

3. 架构与心智模型

9Router 是一个 Next.js 仪表板加上 API 网关，并配有一个单独发布的 CLI 包。该应用将 OpenAI-compatible 路由重写为 Next API 处理程序，将聊天工作委托给 `open-sse` 转换/路由核心，将运行时状态存储在本地数据存储中，并提供用于管理提供商、配额、日志和组合的仪表板。

领域	细节	为什么重要
客户端界面	`http://localhost:20128/v1`	Claude Code、Codex、Cursor、Cline、Antigravity 及类似客户端使用的 OpenAI-compatible 端点。
仪表板	Next.js 应用	提供商设置、组合、别名、配额、使用情况、日志、端点设置、云同步和模型测试。
CLI 包	npm 上的 `9router`	启动本地运行时、启动器、托盘导向的钩子以及打包后的应用行为。
请求处理程序	`src/app/api/v1/*`	用于聊天补全、响应、消息、模型、嵌入、图像、语音、搜索和获取的路由。
翻译核心	`open-sse/*`	格式翻译、提供商执行、流式传输辅助工具、Token 刷新和回退辅助工具。
提供商注册表	`src/shared/constants/providers.js`	OAuth 提供商、API-key 提供商、免费/免费层级提供商、媒体类型、别名和风险元数据。
存储	本地数据目录和 SQLite 适配器	当前源码使用数据库适配器，尽管旧的架构文档仍提到 JSON 存储。

4. 最小端到端设置

下面的命令来自仓库文档，并已对照当前调研快照检查。请把它们当作起点，在生产环境安装之前先阅读链接中的 README。

# Global install path
npm install -g 9router
9router

# Source development path
git clone https://github.com/decolua/9router.git
cd 9router
cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

# Docker path
docker run -d \
  --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  decolua/9router:latest

在连接关键数据或大型工作区之前，先用一个很小的任务证明集成可用。

# Configure your coding client with the local router
Endpoint: http://localhost:20128/v1
API key: copy from the 9Router dashboard
Model: choose a 9Router model alias or combo, for example kr/claude-sonnet-4.5

# Local URLs
Dashboard: http://localhost:20128/dashboard
OpenAI-compatible API: http://localhost:20128/v1

5. 技术深度解析

5.1 它是一个网关，而非模型提供商

9Router 并不会凭空创造一个新的基础模型。它位于编码客户端和上游提供商之间。该路由器负责转换请求格式、在支持的情况下刷新 Token、管理 API 密钥、路由到账户，并决定在首选提供商失败或达到配置限制时采取何种操作。

这种区别对于风险管理至关重要。如果上游提供商更改了流事件、拒绝了架构、移除了免费层级或限制了账户使用，9Router 必须迅速做出调整。最近的问题恰恰反映了这种提供商的变动。

Claude Code / Codex / Cursor / Cline
  -> http://localhost:20128/v1
  -> 9Router endpoint settings
  -> combo / alias / provider account
  -> upstream model API
  -> translated stream back to client

5.2 组合（Combos）是路由的基本单元

README 将回退描述为三层链：首先是订阅，其次是廉价提供商，最后是免费提供商。在实践中，这在仪表板中表现为组合配置。组合是您编码模型偏好、回退顺序以及允许哪些账户处理请求的地方。

这对长时间的编码工作很有用，因为手动切换提供商会带来阻碍。如果你不了解每个提供商的条款、配额、延迟和模型质量，这也很危险。回退链可以保持工作进度，但也可能在任务中途悄无声息地改变模型行为。

5.3 RTK 在翻译前会压缩 Agent 工具的输出

最具体的工程特性是 RTK Token Saver。编码 Agent 的工具结果通常非常庞大：diff、搜索结果、树状结构、日志、编号读取和 shell 输出。9Router 会检测这些结构，并在请求被翻译为 Claude、OpenAI、Gemini、Vertex、Kiro 或其他目标格式之前应用专门的压缩过滤器。

README 中提到该过滤器在设计上是安全的：如果压缩失败或导致输出变大，则保留原始文本。这是正确的默认设置，因为对 diff 进行有损或错误的压缩可能会导致 Agent 修改错误的代码。

tool_result: git diff / grep / tree / logs
  -> RTK filter selection
  -> compressed or original payload
  -> format translation
  -> upstream provider request

5.4 格式转换是其中的难点

该项目支持 OpenAI 聊天补全、OpenAI Responses、Claude 风格消息、Gemini、Cursor、Kiro、Vertex、Antigravity、Ollama 风格路径、嵌入、图像生成、语音、搜索和 Web 获取路由。这是一个庞大的兼容性覆盖面。

最近的 Bug 显示了其代价：助手预填充行为、Vertex 限制、特定于提供商的 Token 参数、GitHub Gemini 流组装以及媒体模型测试都可能以不同的方式崩溃。9Router 的价值在于吸收这些差异，但这意味着仓库必须不断跟踪上游的变化。

5.5 本地存储和日志是威胁模型的一部分

像这样的路由器会存储或接触提供商凭据、OAuth 会话、请求日志、使用记录、模型别名，甚至可能包括原始提示词。当前的源码包含本地数据库适配器；README 描述了 data 目录下的本地数据。请将运行 9Router 的机器视为承载凭据的基础设施。

这并不意味着该项目不可用。这意味着你应该有意识地配置日志记录，尽可能使用最小权限的 API 密钥，避免通过条款不明确的账户路由敏感的客户端数据，并且除非你已特意将其部署在身份验证之后，否则请保持仪表板端口私有。

6. 真实场景：错误 vs 正确

错误做法	正确做法	原因
不要假设 9Router 本身提供无限的模型访问权限。	将其视为真实上游账户、订阅和免费层级的路由器。	提供商条款、配额和模型可用性仍然适用。
不要在未经测试的情况下将所有工具指向同一个回退组合。	为编码、廉价实验、媒体和敏感工作创建单独的组合。	不同的客户端和任务需要不同的延迟、质量和风险配置。
不要永久启用详细日志。	使用请求日志进行调试，然后减少保留时间并保护 data 目录。	日志可能包含提示词、代码、密钥和业务上下文。
不要仅依赖 GitHub 发布页面来获取最新信息。	在调试特定版本行为时，请检查 npm、标签和默认分支。	9Router 的 npm/标签状态已经领先于最新的 GitHub 发布条目。

7. 常见错误和当前问题

Issue tracker 很重要，因为这些仓库还很年轻，而且变化很快。本文把 issues 当作风险信号，而不是项目不可用的证明。

领域	细节	为什么重要
提供商条款	由 OAuth/订阅支持的提供商可能带有账户限制风险。	源代码包含风险提示；请勿盲目路由业务关键流量。
版本差异	在研究时，npm/tag 0.4.66 比 GitHub 上的最新发布条目更新。	报告版本时请务必精确。
流式传输停滞	问题报告包括停滞、空流、占位符以及提示词回显行为。	长推理和提供商适配器需要冒烟测试。
媒体端点	最近的 PR 将图像和 STT 探测路由到真实的媒体端点。	不要假设 chat-completion 测试能验证所有模态。
运行时依赖	有报告指出打包的运行时路径中存在 SQLite 依赖被裁剪的问题。	打包安装需要进行本地启动验证。
过时的文档	旧的架构文档提到了 JSON 存储，而当前源代码包含 SQLite 适配器。	当源代码和 README 与旧的架构说明冲突时，请优先参考源代码和 README。

8. 性能、扩展与成本说明

9Router 的性能主要受两个变量影响：上游提供商的行为以及路由器端的转换/压缩开销。路由器可以通过 RTK 减小提示词大小，但无法让缓慢或过载的上游提供商变快。

只有当回退模型确实能处理任务时，回退机制才能提高可用性。廉价/免费模型或许能保持流式传输，但可能会产生质量较低的代码编辑、较弱的工具调用或不兼容的函数调用结构。

最佳成本模式是显式分段：高风险编辑和审查使用高级组合，探索阶段使用更便宜的组合，广泛搜索和摘要使用本地/免费组合，图像/语音/视频请求使用特定媒体路由。

9. 适合谁

适合使用，如果	不适合，如果
您使用多个 AI 编码客户端并希望拥有一个本地端点。	您仅使用一个提供商，且比起路由灵活性更看重简洁性。
您主动管理配额、订阅、免费层级和廉价 API。	您的组织禁止代理 OAuth/订阅支持的会话。
您的编码代理提示词包含大型 diff、日志和搜索输出。	在路由源代码之前，您需要经过审计的企业级网关控制。
您需要能够自如地调试快速迭代的提供商适配器。	您需要一个发布节奏缓慢且保守的稳定设备。

10. 社区信号

GitHub 上的 issue 和 PR 极其活跃且技术性很强。大部分信号来自用户在 Claude Code、Antigravity、OpenClaw、MiniMax、Xiaomi、GitHub Gemini、Vertex 以及自定义兼容端点之间测试各种提供商组合。

最强烈的积极信号在于其实用性：人们正在将其用于真实的编码客户端，并迅速报告边缘情况。最强烈的警示也源于同一事实：提供商和客户端协议的变化速度极快，以至于路由器必须持续进行补丁更新。

该仓库的 README 使用了强烈的“免费/无限制”措辞，但 issue 追踪器反映了更符合工程实际的情况：模型 ID 会变，流式传输格式各异，OAuth 路径会中断，且仪表盘测试必须具备模态感知能力。

11. 结论：值得使用吗？

我们的判断

如果您想要一个本地的、可手动操作的网关，以便在多个提供商之间路由 AI 编码工具，并且愿意谨慎管理提供商风险，请使用 9Router。在根据您自己的策略审查凭据存储、日志记录、提供商条款和回退行为之前，请勿将其用于受监管的生产代码路径。

12. 更大的图景

9Router 是从单模型客户端向本地 AI 基础设施转型的一部分。开发者越来越希望在不更改每个编辑器或终端 Agent 的情况下，实现模型路由、预算控制、配额可见性、代理兼容性和提供商抽象。

尚未解决的问题是信任。路由演示起来很容易，但安全的路由则更难。下一代工具将需要明确的策略控制、凭据隔离、审计日志、脱敏处理以及可复现的模型路由决策。

13. 常见问题

问： 9Router 是 AI 模型提供商吗？

不是。它是一个本地路由器和仪表盘，用于将请求发送到您配置的上游提供商、账户、免费层级、订阅或兼容端点。

问：我在编码工具中应该配置什么端点？

使用 `http://localhost:20128/v1` 和 9Router 仪表盘显示的 API 密钥，然后选择在 9Router 内部定义的模型别名或组合。

问：什么是 RTK Token Saver？

RTK 在负载被转换并发送到上游之前，会压缩常见的编码 Agent 工具输出，例如 diff、grep 结果、文件树、日志和编号读取内容。

问：为什么 npm 和 GitHub Releases 之间的版本不一致？

在研究时，npm/tags 的版本领先于最新的 GitHub 发布条目。如需调试，请结合查看 npm 元数据、标签、发布版本和默认分支。

问：通过路由器使用 OAuth/订阅账户安全吗？

这取决于提供商的条款和您的风险承受能力。该项目包含针对某些提供商的风险提示，因此请将其视为一项策略决策，而非纯粹的技术设置步骤。

问：本地数据存储在哪里？

README 描述了配置的数据目录下的本地数据，目前的源代码包含 SQLite 适配器。请保护好该目录，因为它可能包含凭据、使用记录和日志。

问：什么最容易出问题？

最近的 issue 指出上游提供商的模式变更、流式组装、模型 ID、Token 参数、媒体端点测试以及打包的运行时依赖项最容易出现问题。

14. 术语表

领域	细节	为什么重要
网关	一个接收模型请求并将其转发到其他地方的本地服务。	9Router 的核心角色。
组合	一个已配置的路由/回退链。	用于选择订阅、廉价或免费路由。
RTK	工具输出压缩层。	在提供商转换之前减少大型 Agent 工具的结果。
OpenAI-compatible	许多工具可以指向的 API 形状。	9Router 暴露了兼容的 `/v1` 端点。
OAuth 提供商	通过用户会话进行身份验证的提供商。	可能带有额外的账户策略风险。
媒体端点	图像、语音、视频或 STT 路径。	不应仅通过聊天补全进行测试。
回退	当第一个提供商/账户失败时路由到下一个。	有用但可能会改变模型行为。

15. 所有来源和链接

主要来源

Issues 和 PRs

发布源

内部链接

16. 来源归属表

领域	细节	为什么重要
README	定位、快速入门、端点、提供商层级、RTK、Docker、仪表板界面。	主要来源。
包元数据	CLI package、版本细微差别、Node 要求、可执行文件入口。	主要来源。
源码树	Next 路由、翻译核心、提供商注册表、数据库适配器。	架构来源。
Issues/PRs	提供商流失、流媒体停滞、媒体探测、运行时依赖项注意事项。	新鲜度信号。
npm 和发布	已发布包、标签和发布条目之间的版本差异。	新鲜度来源。

Related Guides

Guides & Features