9Router 快速入门：5 分钟连接 Claude Code、Codex、Cursor 到 40+ AI 提供方并实现智能路由

本篇技术指南以 9Router 官方日语版快速入门文档（gitbook/content/ja/getting-started/quick-start.md）为骨架，完整讲解从全局安装、启动本地路由服务，到接入 OAuth 订阅型 / API Key 低价型 / 免费型三类 Provider、配置主流编码工具、创建多级自动回退 Combo 与成本优化策略的完整流程。读完本文，你将能够在本地一键拉起 9Router 网关（默认 http://localhost:20128），并让 Claude Code、Codex、Cursor、Cline 等任意兼容 OpenAI 协议的客户端共享一套"订阅 → 低价 → 免费"的自动降级链路。

---

1. 环境要求与安装

1.1 前置条件

根据官方安装文档（gitbook/content/ja/getting-started/installation.md），运行 9Router 需要满足：

• Node.js：20.0.0 及以上版本（官方快速入门文档同样标注 Node.js 20+）
• npm：10.0.0 及以上（随 Node.js 一同安装）
• 操作系统：macOS、Linux、Windows（官方推荐 WSL）
• 磁盘空间：安装约需 200MB

先用以下命令确认环境版本：

node --version
# 应显示 v20.x.x 或更高

npm --version
# 应显示 10.x.x 或更高

注：仓库内 CLI 包的 cli/package.json 中 engines.node 声明为 >=18.0.0，即 CLI 启动器在 Node 18 即可运行；但官方文档要求 Node 20+，以文档要求为准可避免兼容性问题。

1.2 全局安装（推荐）

npm install -g 9router

全局安装的优势：

• 可在任意目录直接执行 9router 命令；
• 通过 npm update -g 9router 即可完成升级；
• 安装时 postinstall 钩子（cli/hooks/postinstall.js）会在用户数据目录中按需安装 SQLite 运行时（sql.js / better-sqlite3）与系统托盘运行时，避免 Windows 全局更新时的文件占用（EBUSY）问题。

如果只想在单个项目内使用，可执行 npm install 9router 后通过 npx 9router 启动；需要参与源码开发时，则克隆仓库后在 app 目录执行 npm install && npm run build && npm start。

---

2. 启动与首次登录

2.1 启动服务

9router

启动后的预期行为（与 cli/cli.js 实现一致）：

1. 服务监听 http://localhost:20128，控制台（Dashboard）自动在浏览器打开；
2. 在用户主目录创建数据目录 ~/.9router（Windows 为 %APPDATA%\9router，该路径逻辑见 src/lib/dataDir.js，并可用环境变量 DATA_DIR 覆盖）；
3. API Key 自动生成，可直接在 Dashboard → Settings → API Keys 中复制，格式形如 9r_1234567890abcdef1234567890abcdef；
4. 默认端口为 20128，默认绑定 0.0.0.0。

首次登录凭据：

• 默认密码：123456

⚠️ 安全提醒： 首次登录后请立即在 Dashboard → Settings → Change Password 中修改默认密码；生产环境务必通过环境变量 JWT_SECRET 与 INITIAL_PASSWORD 覆盖默认值。

2.2 常用启动参数

从 cli/cli.js 的帮助输出可以看到，9router 命令支持以下参数：

9router [options]

  -p, --port <port>   指定服务端口（默认 20128）
  -H, --host <host>   指定绑定地址（默认 0.0.0.0）
  -n, --no-browser    启动时不自动打开浏览器
  -l, --log           显示服务日志（默认隐藏）
  -t, --tray          以系统托盘模式后台运行
  --skip-update       跳过启动时的版本检查
  -h, --help          显示帮助
  -v, --version       显示版本号

例如改用 3000 端口并仅本机访问：

9router --port 3000 --host 127.0.0.1

CLI 启动器内部会通过 TCP 轮询等待服务就绪（而非盲目等待固定时长），并在服务异常退出后自动重启（最多 2 次，超过后自动禁用 MITM 再拉起），同时支持 Web UI / 终端 UI / 托盘三种交互界面切换。

---

3. 验证服务是否可用

安装文档提供了三个可复现的验证手段，对应的路由实现均可在仓库中找到。

3.1 检查健康状态

curl http://localhost:20128/health

返回 {"ok": true}，实现见 src/app/api/health/route.js。

3.2 列出可用模型（OpenAI 兼容）

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer your-api-key"

返回 OpenAI 风格的模型列表，形如：

{
  "object": "list",
  "data": [
    {
      "id": "cc/claude-opus-4-5-20251101",
      "object": "model",
      "owned_by": "claude-code"
    }
  ]
}

该接口实现在 src/app/api/v1/models/route.js，会聚合已连接 Provider 的模型、自定义模型、别名与 Combo，并针对 Kiro、GitHub Copilot、Cursor 等 Provider 动态拉取实时模型目录；模型 ID 统一采用 别名/模型名 的命名空间格式。

3.3 测试一次对话

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cc/claude-opus-4-5-20251101",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

/v1/chat/completions 的实现位于 src/app/api/v1/chat/completions/route.js，请求会进入 handleChat 处理器，由 open-sse 层的格式翻译器在 OpenAI / Claude / Gemini 等协议之间自动转换后转发给真实 Provider。

---

4. 连接 Provider：三种方式

9Router 支持三种 Provider 接入方式，按"优先级从高到低"合理搭配，即可构建完整的自动降级链路。

4.1 选项 A：OAuth 登录（订阅型 Provider）

适用场景：Claude Code、Codex、Gemini CLI、GitHub Copilot 等已订阅的服务。

Dashboard → Providers → Connect [Provider]
→ OAuth 登录 → 令牌自动刷新
→ 配额跟踪启用

示例：连接 Claude Code

1. 点击「Connect Claude Code」；
2. 使用 Claude 账号登录；
3. 授权 9Router 访问；
4. ✅ 完成！即可使用模型 cc/claude-opus-4-5-20251101。

OAuth 接入后，9Router 会跟踪 5 小时滚动与周配额，并在令牌过期前自动刷新，无需手动重新登录（相关实现可参考 open-sse/services/tokenRefresh.js 与 src/app/api/oauth/[provider]/[action]/route.js）。

4.2 选项 B：API Key（低价 Provider）

适用场景：GLM、MiniMax、Kimi、OpenRouter 等按量计费或低价服务。

Dashboard → Providers → Add API Key
→ 选择 Provider
→ 粘贴 API Key
→ 保存

示例：接入 GLM-4.7

1. 在智谱 AI 开放平台注册并开通 Coding Plan 获取 API Key；
2. Dashboard → Add API Key → Provider 选择 glm → 粘贴密钥；
3. ✅ 完成！即可使用模型 glm/glm-4.7。

4.3 选项 C：免费 Provider（零成本）

适用场景：iFlow、Qwen、Kiro 等免费档位。

Dashboard → Providers → Connect [Free Provider]
→ 设备码或 OAuth 登录
→ 免费使用

示例：连接 iFlow

1. 点击「Connect iFlow」；
2. 使用 iFlow 账号登录并授权；
3. ✅ 完成！可用 8 个模型，如 if/kimi-k2-thinking、if/qwen3-coder-plus 等。

注意（以仓库 README 的最新提示为准）： 免费档位政策会随时间调整。README（README.md）指出 iFlow、Qwen Code 与 Gemini CLI 的免费档已于 2026 年陆续停止，当前推荐的免费通道为 Kiro AI（新账号约 50 积分/月，另赠 500 试用积分）与 OpenCode Free（无需登录，模型自动拉取）。接入前请以 Dashboard 中实际展示的 Provider 列表为准。

---

5. 将编码工具指向 9Router

9Router 提供 OpenAI 兼容网关，任何支持自定义 Base URL 的工具都能接入。统一要点：

• Base URL：http://localhost:20128/v1
• API Key：从 Dashboard → Settings → API Keys 复制
• Model：按需选择 cc/、glm/、if/ 等命名空间下的模型

5.1 Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key:     [从 9Router Dashboard 获取]
  Model:              cc/claude-opus-4-5-20251101

5.2 Claude Desktop

编辑 ~/.claude/config.json：

{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-9router-api-key"
}

5.3 Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key:  [从 Dashboard 获取]
Model:    cc/claude-opus-4-5-20251101

5.4 Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-9router-api-key"

codex "your prompt"

仓库在 src/app/api/cli-tools/ 下还提供了 Claude Code、Codex、Cline、Copilot、OpenClaw 等十余种工具的配置生成接口（如 claude-settings、codex-settings、cline-settings 等），可在 Dashboard 的 CLI Tools 页面按需生成对应工具的配置内容。

---

6. 创建智能 Combo：多级自动回退

Combo（组合）是 9Router 的核心能力：把多个模型按优先级编排成一个"路由链"，配额耗尽或出错时自动切换到下一层，实现零停机。

6.1 创建示例

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-5-20251101  (订阅优先)
  2. glm/glm-4.7                  (低价备份，$0.6/百万 token)
  3. if/kimi-k2-thinking          (免费回退)

CLI 中使用: premium-coding

6.2 运行机制

1. 首选尝试 Claude Opus（消耗订阅配额）；
2. 配额耗尽 → 自动切到 GLM-4.7（超低单价）；
3. 触发预算上限 → 自动切到 iFlow（免费）；
4. 全程自动切换，零停机。

6.3 命名与校验

Combo 名称将作为模型 ID 在客户端使用（如 premium-coding），因此有严格校验。从 src/app/api/combos/route.js 的源码可见：名称只能包含字母、数字、-、_、.（正则 ^[a-zA-Z0-9_.\-]+$），且不允许重复；创建时还可指定 kind 字段以声明组合用途（默认 LLM）。创建成功后，/v1/models 会把该 Combo 作为一个模型条目暴露给客户端，客户端直接以 Combo 名称作为 model 参数请求即可。

---

7. 可用模型速查

以下模型清单来自官方快速入门文档，按成本层级划分。前缀即 Provider 命名空间，客户端在 Model 字段直接使用完整 ID。

7.1 订阅型模型（优先用满）

Claude Code（cc/）— Pro/Max 订阅

模型 ID	说明
cc/claude-opus-4-5-20251101	Claude 4.5 Opus
cc/claude-sonnet-4-5-20250929	Claude 4.5 Sonnet
cc/claude-haiku-4-5-20251001	Claude 4.5 Haiku

Codex（cx/）— Plus/Pro 订阅

模型 ID	说明
cx/gpt-5.2-codex	GPT 5.2 Codex
cx/gpt-5.1-codex-max	GPT 5.1 Codex Max

Gemini CLI（gc/）— 每月 18 万免费额度

模型 ID	说明
gc/gemini-3-flash-preview	Gemini 3 Flash Preview
gc/gemini-2.5-pro	Gemini 2.5 Pro

GitHub Copilot（gh/）— 订阅

模型 ID	说明
gh/gpt-5	GPT-5
gh/claude-4.5-sonnet	Claude 4.5 Sonnet

7.2 低价模型（备份层）

GLM（glm/）— 约 $0.6 / $2.2 每百万 token

模型 ID	说明
glm/glm-4.7	GLM 4.7（每日上午 10 点重置）

MiniMax（minimax/）— 约 $0.20 / $1.00 每百万 token

模型 ID	说明
minimax/MiniMax-M2.1	MiniMax M2.1（5 小时滚动重置）

Kimi（kimi/）— 每月 $9（1000 万 token）

模型 ID	说明
kimi/kimi-latest	Kimi Latest

7.3 免费模型（应急层）

iFlow（if/）— 8 个模型免费

模型 ID	说明
if/kimi-k2-thinking	Kimi K2 Thinking
if/qwen3-coder-plus	Qwen3 Coder Plus
if/glm-4.7	GLM 4.7
if/deepseek-r1	DeepSeek R1

Qwen（qw/）— 3 个模型免费

模型 ID	说明
qw/qwen3-coder-plus	Qwen3 Coder Plus
qw/qwen3-coder-flash	Qwen3 Coder Flash

Kiro（kr/）— 2 个模型免费

模型 ID	说明
kr/claude-sonnet-4.5	Claude Sonnet 4.5
kr/claude-haiku-4.5	Claude Haiku 4.5

各 Provider 的模型注册表集中在 open-sse/providers/registry/ 目录，接入某个 Provider 后可随时通过 /v1/models 查看当前实际可用的完整模型列表（部分 Provider 还支持实时拉取最新目录）。

---

8. 成本优化策略

8.1 月预算 $10～20 的编排

1. 快速任务使用 Gemini CLI 免费档（每月 18 万额度）
2. 用满 Claude Code 订阅配额（已付费，不用白不用）
3. 配额耗尽 → 回退到 GLM（约 $0.6/百万 token）
4. 紧急兜底 → MiniMax M2.1（约 $0.20/百万 token）或 iFlow（免费）

示例（月消耗 1 亿 token 的账单结构）：

通道	消耗量	成本
Gemini CLI	6000 万	$0（免费档）
Claude Code	3000 万	$0（已有订阅）
GLM	800 万	$4.80
MiniMax	200 万	$0.40
合计	1 亿	约 $5.20 + 既有订阅

8.2 配额重置节奏（24 小时不间断编码）

不同 Provider 的配额重置窗口不同，掌握节奏即可全天候覆盖：

1. 早晨：用 Claude Code 新配额（5 小时滚动重置）
2. 下午：切换到 Gemini CLI（每日 1K 额度）
3. 傍晚：用 GLM 日配额（次日早 10 点重置）
4. 深夜：MiniMax（5 小时滚动）或 iFlow（免费）

搭配 Combo 后，以上切换全部自动完成，以最小追加成本实现全天候编码。

说明：Dashboard 中展示的"费用"是用于对比与追踪的估算值，并非实际账单——9Router 本身是开源免费软件，不向你收取任何费用；你只需按用量直接向所使用 Provider 付费（免费档则为零成本）。

---

9. 下一步

继续深入学习可参考仓库内的官方文档：

• 安装详解与常见问题排查：系统要求、环境变量（JWT_SECRET、INITIAL_PASSWORD、DATA_DIR、PORT）、Docker 与 Nginx 反代部署、卸载方式；
• 功能说明：配额跟踪、Combo、部署等进阶能力；
• FAQ：常见问题与解答；
• 故障排查：端口占用（EADDRINUSE）、权限错误（EACCES）、Node 版本过旧等问题的修复方法。

仓库内还提供了完整的单元测试与基线校验（见 tests/），涉及格式翻译、Combo 路由、OAuth 刷新、配额跟踪等核心链路，可作为理解 9Router 内部行为的补充参考。