如何使用 9router 运行你自己的 AI 模型路由器

9router 是一款基于 MIT 许可证的开源路由代理，可运行在你自己的机器或服务器上，将你接入的所有 AI 提供商统一置于一个 OpenAI 兼容端点 http://localhost:20128/v1 之后。

如果你在一个终端里用 Claude Code，在编辑器里用 Cline，又在某个副业项目中用 OpenAI SDK，那么你很可能同时维护着三套密钥和三个 base URL，而且每次切换模型时，每个工具都需要单独修改配置。9router 用一个本地端点取代了这一切。本指南将介绍如何通过 npm 或 Docker 安装它、用 curl 进行验证、将你的工具指向它，以及在 localhost 之外的任何访问到达之前做好安全加固。

什么是 9router？

9router 是一款自托管代理，它接收 OpenAI 格式的请求，将其路由到你所配置的上游提供商，并按需在 OpenAI、Claude 和 Gemini 请求格式之间进行转换。项目 README 列出了 40 多个受支持的提供商，CLI 以 9router npm 包的形式发布。

9router 与 OpenRouter 的主要区别在于路由器的运行位置。OpenRouter 是一项托管服务，你需要将请求发送给它；而 9router 是由你自己运行的软件。OpenRouter 本身也出现在 9router 的提供商列表中，因此你可以把 OpenRouter 账户接入到你自己的路由器之后。

为什么要运行自托管模型路由器

本地路由器为所有工具提供同一个端点，并将提供商凭据集中管理，这样你无需改动工具配置或应用代码就能切换模型。

• 统一端点。 所有 OpenAI 兼容客户端都使用同一个 base URL。
• 密钥集中管理。 只需在仪表盘中添加一次提供商账户，每个工具只需要一个 9router API 密钥。
• 通过字符串切换模型。 切换模型只需修改 model 的值，别无其他。
• 组合（Combo）。 组合是一个具名的有序模型列表，可直接用作模型名称。当第一个模型配额耗尽、被限流（429）或返回错误时，路由器会尝试下一个模型。

常见做法是把首选模型放在最前面，后面跟上更便宜的模型。在选择备用模型之前，可以使用 LLM API 成本计算器比较各模型的每 token 价格。

如何安装并运行 9router

9router 以全局 npm CLI 的形式安装，使用 npm install -g 9router 安装，并通过 9router 命令启动。服务器监听 20128 端口。

npm install -g 9router
9router
# Dashboard: http://localhost:20128
# API:       http://localhost:20128/v1

如果不想全局安装，可以使用 npx 9router 一次性运行。

如需在 Docker 中运行，请使用官方 decolua/9router 镜像，该镜像同时发布在 ghcr.io/decolua/9router：

docker run -d --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD='change-me' \
  decolua/9router:latest

卷挂载可确保容器重启后 SQLite 数据库（容器内路径为 /app/data/db/data.sqlite）得以保留。新版本发布频繁，latest 标签也会随之更新，因此如果你需要可复现的部署，请固定使用具体的版本标签。

9router 启动后，在仪表盘中完成设置：

1. 打开 http://localhost:20128 并登录仪表盘。
2. 添加至少一个提供商账户。
3. 为你的工具创建一个 API 密钥。

使用 curl 验证路由器

验证 9router 是否正常工作的最快方式，是在配置任何工具之前，向 /v1/models 发送一个 GET 请求。响应是一个 JSON 列表，以标准 OpenAI 列表格式列出路由器可提供的所有模型和组合。

curl http://localhost:20128/v1/models

模型列表接口无需密钥即可响应。但聊天请求则不同：仪表盘中的“Require API key”设置默认开启，因此聊天请求需要使用仪表盘中创建的密钥。在请求模型列表时也附带密钥是个好习惯，因为限定了特定模型的密钥只能看到这些模型：

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_API_KEY"

如果列表中出现了来自你的提供商的模型 ID，说明路由正常工作。如果列表为空，则说明提供商尚未连接。

将你的工具指向 9router

任何支持自定义 OpenAI base URL 的客户端都可以使用 9router。将 base URL 设置为 http://localhost:20128/v1，并提供在仪表盘中创建的 API 密钥即可。

OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:20128/v1",
  apiKey: process.env.NINE_ROUTER_API_KEY, // created in the 9router dashboard
});

const res = await client.chat.completions.create({
  model: "<an id or combo name from /v1/models>",
  messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);

如需切换到其他模型或组合，只需修改 model 字符串，代码的其他部分无需任何改动。

编程智能体

在 Cline 中，选择 OpenAI Compatible 作为 API provider，并填写三项值：base URL http://localhost:20128/v1、仪表盘中的 API 密钥，以及从 /v1/models 复制的模型 ID。支持自带提供商的终端智能体（例如 OpenCode）也使用同样的三项值。

通过 pi-9router-ext 使用 Pi

pi-9router-ext 扩展通过两个环境变量将 Pi 编程智能体连接到 9router：

pi install npm:pi-9router-ext
NINE_ROUTER_BASE_URL=http://localhost:20128 NINE_ROUTER_API_KEY=<key> pi
# inside Pi:
/9router-models

该扩展启动时会从 /v1/models 读取聊天模型。在 0.2.4 版本中，它还会查询 /v1/models/web，以发现 9router 的网页搜索和网页抓取路由。在 Pi 中运行 /9router-models 即可查看它发现的内容。

在对外暴露 9router 之前如何进行安全加固？

在其他机器能够访问 9router 之前，请设置仪表盘密码以及 JWT 和 API 密钥的 secret，并保持“Require API key”处于开启状态。默认配置在 localhost 上没有问题，但超出 localhost 范围则不再安全。如果未设置 INITIAL_PASSWORD，在保存密码之前，首次登录仪表盘将使用 123456。在开放端口或部署到公网主机之前，请参照官方 .env.example 设置以下值：

INITIAL_PASSWORD=<long-random-string>   # first login otherwise uses 123456
JWT_SECRET=<long-random-string>         # listed under "Required" in .env.example
API_KEY_SECRET=<long-random-string>     # the example default is publicly known
AUTH_COOKIE_SECURE=true                 # set when serving behind an HTTPS reverse proxy

API 密钥校验本身是一项仪表盘设置。打开 Endpoint 页面，确认 Require API key 已开启，这样没有有效密钥的请求都会被拒绝。该设置默认开启，如果端点在未开启该设置的情况下可被远程主机访问，仪表盘会显示警告。

只有在 9router 前端进行 TLS 终止时，才应设置 AUTH_COOKIE_SECURE=true。如果使用纯 HTTP，浏览器将不会回传认证 cookie。

总结

像 9router 这样的自托管路由器能让你的所有工具共用一个端点和一套凭据，切换模型只需修改 model 字符串。安装 9router，确认 /v1/models 列出了你的提供商的模型，然后将一个工具指向 http://localhost:20128/v1。在路由器对 localhost 之外开放之前，务必设置好密码和各项 secret，并保持“Require API key”处于开启状态。

常见问题

如何在 20128 以外的端口上运行 9router？

使用 9router --port 8080 启动 npm CLI 即可使用自定义端口。如果从源码运行，请设置 PORT 环境变量，同时将 NEXT_PUBLIC_BASE_URL 指向同一端口。在 Docker 中，修改端口映射的宿主机一侧即可，例如 -p 8080:20128。之后每个工具都需要使用新的 base URL，例如 http://localhost:8080/v1。

9router 将配置和数据存储在哪里？

9router 将数据存储在 DATA_DIR 指定的目录中，默认为 ~/.9router，其 SQLite 数据库位于该目录下的 db/data.sqlite。如果未设置 JWT_SECRET，自动生成的签名 secret 也会存储在该目录下，路径为 ~/.9router/jwt-secret。官方 Docker 镜像将 DATA_DIR 设置为 /app/data，因此在 /app/data 挂载卷即可持久化所有数据。

如何让另一台机器上的工具指向远程 9router 服务器？

在客户端机器上运行 npx 9router connect http://server-host:20128。该命令不会启动本地服务器。它会使用仪表盘密码登录，复用或创建一个名为 cli- 加主机名的 API 密钥，并写入每个所选工具的配置。它会以 .bak-9router 后缀对每个原始配置备份一次。使用 --tools claude,codex 可预先选择工具，使用 --reset 可撤销更改。

9router 能否为同一提供商使用多个账户？

可以。9router 支持为每个提供商配置多个账户，并通过轮询（round-robin）或基于优先级的路由将请求分摊到各账户。当某个账户达到配额上限时，路由器会切换到下一个账户。这与组合是两回事：账户轮换保持同一模型不变，只更换其背后的凭据；而组合则会切换到另一个模型。