🎯 一句话总结：9Router 把多个 AI 账号、API Key 和订阅入口收进一个本地网关，对外统一提供 OpenAI 兼容接口，并负责模型切换、失败回退、额度监控和 Token 压缩。

📌 9Router 适合解决什么问题

同时使用 Claude Code、Codex、Cursor、Cline 或其他 AI 工具时，最麻烦的往往不是模型本身，而是每个客户端都要重复维护地址、密钥和模型名。

9Router 在客户端与上游服务之间增加一层本地网关：客户端只连接一个地址，网关再按规则把请求交给不同账号和模型。

能力	实际作用
OpenAI 兼容入口	支持标准接口的客户端可直接接入
格式转换	在 OpenAI、Anthropic 等请求格式之间转换
多账号管理	同一提供商可保存多个账号或 API Key
自动回退	当前模型失败、限流或额度不足时切换备用路径
额度监控	在面板查看配额、Token 与成本趋势
RTK 压缩	精简工具输出，降低长日志和代码差异占用的输入 Token
自定义组合	把多个模型按优先级组成一个可调用的逻辑模型
它更适合多模型、高频调用和自托管场景。如果只偶尔使用一个固定模型，直接配置官方客户端通常更简单。

🔥 0.5.45 版有哪些变化

当前 npm 最新版为 0.5.45。从较早的 0.5.x 版本升级后，重点不只是模型数量，而是路由链路和管理体验更完整。

更新方向	变化
多模态接口	已扩展到图片、语音、嵌入、网页搜索与抓取等能力
模型发现	可按能力查询模型，减少把聊天模型误用于图片或语音接口的情况
回退控制	支持订阅、低价和免费模型组成分层回退链
Token 管理	RTK 可压缩工具输出，也可按单次请求绕过压缩
账号维护	批量添加 API Key 时避免覆盖已有密钥
模型兼容	改善实时模型目录、Claude 请求头与 OpenAI Responses 转换
启动性能	跳过未启用的后台服务，减少无效初始化

⚠️ 补丁版本会持续发布。升级前先确认当前版本，升级后再检查服务和健康接口，不要只看安装命令是否退出成功。

⚙️ 安装、升级与启动

首次安装

npm install -g 9router@latest
9router
默认管理面板位于：

http://localhost:20128
标准 API 地址是：

http://localhost:20128/v1

从旧版升级

查看 npm 最新版本

npm view 9router version

安装最新版

npm install -g 9router@latest –prefer-online

systemd 部署时重启服务

systemctl restart 9router

快速检查

读取实际安装版本

node -p “require(‘/usr/local/lib/node_modules/9router/package.json’).version”

检查服务与监听端口

systemctl status 9router –no-pager
ss -ltnp ‘( sport = :20128 )’

检查健康状态

curl http://127.0.0.1:20128/api/health
健康接口应返回：

{“ok”:true}
如果使用 NVM，先确认 npm prefix -g。NVM 的全局目录和 /usr/local/lib/node_modules 可能不是同一处，装进错误目录后，systemd 仍会启动旧版本。

🔌 添加提供商与调用模型

在管理面板中进入 Providers，连接订阅账号或填写 API Key。完成后再进入 Keys 创建 9Router 自己的访问密钥，客户端不应直接持有所有上游密钥。

模型列表按能力拆分：

curl http://127.0.0.1:20128/v1/models
curl http://127.0.0.1:20128/v1/models/image
curl http://127.0.0.1:20128/v1/models/tts
curl http://127.0.0.1:20128/v1/models/stt
curl http://127.0.0.1:20128/v1/models/embedding
curl http://127.0.0.1:20128/v1/models/web
聊天请求示例：

curl http://127.0.0.1:20128/v1/chat/completions
-H “Authorization: Bearer YOUR_9ROUTER_KEY”
-H “Content-Type: application/json”
-d ‘{
“model”: “provider/model-name”,
“messages”: [
{“role”: “user”, “content”: “用三句话解释反向代理”}
]
}’
模型 ID 必须以 /v1/models 返回结果为准。不要凭印象填写名称，否则常见结果是 Invalid model format 或 model_not_found。

需要频繁测试多家 AI 服务时，可以通过 APIMart API 聚合平台补充独立上游，再把对应 API Key 接入 9Router。生产任务仍应准备至少一条稳定的官方或自托管线路。

🧩 组合模型与自动回退

组合模型的价值在于把“选哪个模型”变成网关规则，而不是让每个客户端各自维护一套设置。

建议按任务价值配置三层：

主线路：质量稳定、上下文足够的订阅或付费模型。- 备用线路：成本较低、速度较快的模型。- 应急线路：免费模型或本地模型，仅用于保持基础可用性。

场景	主线路	备用线路	应急线路
编程代理	强代码模型	通用快速模型	免费代码模型
内容整理	长上下文模型	低价通用模型	本地模型
图片生成	主图像模型	第二家图像服务	不自动降级到聊天模型
网页研究	搜索服务	备用搜索服务	只抓取指定网页
回退链不能只按价格排序。上下文长度、工具调用、结构化输出和图片能力不兼容时，即使请求成功，结果也可能不可用。

🛡️ 安全与稳定性

9Router 保存上游账号、密钥和请求记录，部署方式直接决定风险大小。

默认仅监听本机：个人使用时绑定 127.0.0.1，不要无认证暴露到公网。- 启用独立访问密钥：客户端只使用 9Router Key，不下发上游密钥。- 远程访问走加密通道：优先使用 VPN、SSH 隧道或带身份认证的反向代理。- 限制日志内容：处理代码、合同或客户数据时，确认请求日志的保存范围和保留时间。- 保留备用路径：网关是统一入口，也会成为单点故障；关键任务应准备可直接切换的备用端点。- 更新前保存数据目录：升级通常保留配置，但数据库和密钥文件仍应纳入备份。

⚠️ 自动回退只解决“当前账号不可用”，不能保证备用模型具有同等质量、上下文长度或工具能力。

❓ FAQ

Q：升级后端口还应该是 8080 吗？
A：当前默认端口是 20128。旧教程中的 8080 配置已经过时，客户端地址应改为 http://localhost:20128/v1。

Q：安装最新版后为什么仍显示旧版本？
A：先检查 npm prefix -g、command -v 9router 和 systemd 的 ExecStart。NVM 与系统级 npm 可能分别安装了一份 9Router。

Q：为什么 /v1/models 有模型，调用仍失败？
A：常见原因包括账号被限流、模型锁定、上游无可用账号或请求超过上下文长度。查看 9Router 错误日志能区分格式错误和上游故障。

Q：RTK 会不会改坏代码？
A：RTK 主要压缩发送给模型的工具结果，例如日志、目录列表和代码差异，不会直接改写本地文件。对需要完整原始输出的请求，可以临时绕过压缩。

Q：能否在多台设备上共用？
A：可以部署到局域网或 VPS，但必须加访问密钥和加密通道。公开暴露管理面板或无认证 API 风险很高。

Q：适合生产环境吗？
A：可以作为统一接入层，但要补齐备份、监控、访问控制和备用端点。不要把免费模型回退当成生产稳定性保证。