9Router 快速上手指南：5 分钟搭建可自动回退的免费 AI 路由网关-育师

9Router 快速上手指南：5 分钟搭建可自动回退的免费 AI 路由网关

【免费下载链接】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

导读

本文是 9Router 的完整快速入门指南，覆盖从全局安装、Dashboard 初始化到连接 Claude Code、Codex、Cursor、Cline 等编码工具的完整链路。你将学会通过 OAuth、API Key 与免费渠道三类方式接入 40+ 提供商，并利用 Combos（自动回退链）实现"订阅 → 便宜 → 免费"三层路由，在配额耗尽时零停机切换，同时掌握每月 $10-20 量级的成本优化策略。

1. 快速了解 9Router

9Router 是一个运行在本地的 AI 请求路由网关：你的编码工具（Claude Code、Codex、Cursor、Cline、Copilot 等）只需把请求指向http://localhost:20128/v1，9Router 就会完成格式翻译（OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 等）、配额跟踪、OAuth 令牌自动刷新，并按你配置的优先级把请求转发到订阅渠道、便宜 API 或免费渠道。

从仓库源码可以看到完整的实现支撑：CLI 启动器位于 cli/cli.js，npm 包9router的 bin 入口定义在 cli/package.json；各提供商接入注册表位于 open-sse/providers/registry（如claude.js、codex.js、github.js、cursor.js、gemini.js等）；OpenAI 兼容的/chat/completions等 API 路由位于 src/app/api。

2. 安装与启动

2.1 安装

全局安装 9Router：

npm install -g 9router

环境要求：Node.js 20.0.0 或更高版本（npm 10+ 随 Node.js 一起安装），支持 macOS、Linux、Windows（推荐 WSL），安装占用约 200MB。检查版本：

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

若使用仓库源码本地开发，可参考 README.md 中的方式：cp .env.example .env && npm install后运行npm run dev（开发模式）或npm run build && npm run start（生产模式）。仓库根package.json中定义了这些脚本。完整安装细节（本地安装、源码安装、卸载、权限修复等）见安装指南。

2.2 启动

9router

启动后：

🎉Dashboard 自动打开：http://localhost:20128
默认密码：123456（请登录后在 Dashboard 的 Settings → Change Password 中立即修改）
API Key 自动生成：可在 Dashboard → Settings → API Keys 中复制，格式形如9r_1234567890abcdef1234567890abcdef
数据目录默认创建于~/.9router（包含db.json数据库、api-keys.json、logs/日志目录）

从源码看，CLI 启动器 cli/cli.js 会轮询等待服务器在指定端口就绪（默认 15 秒超时），并在启动前通过 cli/hooks/sqliteRuntime.js 保证 SQLite 运行时可用。

常用环境变量（完整清单见 .env.example）：

# 安全（生产环境必填） export JWT_SECRET="your-secure-secret-change-this" export INITIAL_PASSWORD="your-password" # 存储与服务器 export DATA_DIR="~/.9router" export PORT="20128" export NODE_ENV="production"

2.3 验证安装

服务启动后可用 curl 验证：

# 健康检查 curl http://localhost:20128/health # 列出可用模型 curl http://localhost:20128/v1/models \ -H "Authorization: Bearer your-api-key" # 测试一次聊天补全 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!"} ] }'

3. 连接提供商：三种方式

Dashboard → Providers 页面提供了三类接入方式，分别适用于不同渠道。

3.1 Option A：OAuth（订阅型提供商）

适用场景：Claude Code、Codex、Gemini CLI、GitHub Copilot 这类以订阅额度计费的渠道。

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

示例：Claude Code

点击 "Connect Claude Code"
使用你的 Claude 账号登录
授权 9Router
✅ 完成！使用模型：cc/claude-opus-4-5-20251101

OAuth 接入后令牌会自动刷新，无需反复手动重新登录，这一能力对应仓库中的令牌刷新服务（open-sse/services/tokenRefresh.js）与 OAuth 凭据管理（open-sse/services/oauthCredentialManager.js）。

3.2 Option B：API Key（便宜型提供商）

适用场景：GLM、MiniMax、Kimi、OpenRouter 等按量计费的低价 API。

Dashboard → Providers → Add API Key → 选择提供商 → 粘贴 API Key → 保存

示例：GLM-4.7

在智谱 AI 平台注册并获取 API Key（Coding Plan）
Dashboard → Add API Key → Provider:glm→ 粘贴 Key
✅ 完成！使用模型：glm/glm-4.7

3.3 Option C：免费提供商（零成本）

适用场景：iFlow、Qwen、Kiro 等免费渠道。

Dashboard → Providers → Connect [Free Provider] → Device code 或 OAuth → 无限制使用

示例：iFlow

点击 "Connect iFlow"
使用 iFlow 账号登录并授权
✅ 完成！使用 8 个模型：if/kimi-k2-thinking、if/qwen3-coder-plus等

⚠️ 上游免费政策会随时间变化：README 中已注明 iFlow、Qwen Code、Gemini CLI 的免费档位在 2026 年陆续被调整或停用，建议以 README.md 中的最新说明与官方公告为准，必要时切换到 Kiro / OpenCode Free / Vertex 等当前推荐渠道。

4. 在 CLI 工具中使用

所有支持自定义 OpenAI 兼容端点的工具，都可以把端点指向 9Router。下面覆盖四种典型配置。

4.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

4.2 Claude Desktop

编辑~/.claude/config.json：

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

4.3 Cline / Continue / RooCode

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

4.4 Codex CLI

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

实现原理：9Router 在请求转发前完成跨格式翻译——客户端发来的 OpenAI 格式请求会被转换为目标提供商的本地格式。这一转换管线位于 open-sse/translator（请求/响应/格式/关注点转换器），并通过 src/proxy.js 挂载到服务路由。也就是说，无论你的工具用哪种协议，9Router 都能把它"翻译"给任意提供商。

5. 创建智能 Combos（自动回退）

Combos 是 9Router 的核心功能：把多个模型按优先级组成一条回退链，前一个模型配额耗尽或出错时自动切换到下一个，实现零停机。

5.1 创建步骤

Dashboard → Combos → Create New Name: premium-coding Models: 1. cc/claude-opus-4-5-20251101 (订阅主用) 2. glm/glm-4.7 (便宜备用, $0.6/1M) 3. if/kimi-k2-thinking (免费兜底) 在 CLI 中直接使用模型名: premium-coding

工作方式：

优先尝试 Claude Opus（使用你的订阅额度）
订阅配额耗尽 → 自动切到 GLM-4.7（超低价）
预算用尽 → 自动切到 iFlow（免费）
全程自动切换，零停机！

5.2 在工具中使用 Combo

# Cursor / Cline：模型名填 premium-coding # Codex CLI： export OPENAI_BASE_URL="http://localhost:20128" codex --model quality-first "your prompt" # 直接调用 API： curl http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "premium-coding", "messages": [{"role": "user", "content": "Write a function to..."}], "stream": true }'

5.3 Combos 进阶配置

预算限制：Dashboard → Combos → Edit → Budget 可设置每日/每月上限，达到上限后 9Router 会跳过付费模型、只走免费层；
临时启停模型：可暂时禁用 Combo 中某个昂贵模型而无需删除整个组合；
克隆组合：Clone 现有 Combo 生成-copy变体，便于按场景微调；
多账号轮询：同一提供商可配置多个账号，自动轮询或按优先级路由（见 README.md 中 Multi-Account Support 说明）。

Combos 的自动回退机制在仓库中由路由与自动切换逻辑实现，相关测试见 tests/unit/combo-autoswitch.test.js、tests/unit/combo-routing.test.js 与 tests/unit/combo-fusion.test.js。更详细的 Combos 设计（预算限制、最佳实践、故障排查）可阅读 Combos 文档。

6. 可用模型清单

9Router 通过provider前缀/模型名的格式引用模型，同一前缀下可接入多个模型。

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

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

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 订阅：

cx/gpt-5.2-codex— GPT 5.2 Codex
cx/gpt-5.1-codex-max— GPT 5.1 Codex Max

Gemini CLI（gc/）— 免费 180K/月：

gc/gemini-3-flash-preview— Gemini 3 Flash Preview
gc/gemini-2.5-pro— Gemini 2.5 Pro

GitHub Copilot（gh/）— 订阅：

gh/gpt-5— GPT-5
gh/claude-4.5-sonnet— Claude 4.5 Sonnet

6.2 便宜型模型（备用）

GLM（glm/）— $0.6/$2.2 每 1M tokens：

glm/glm-4.7— GLM 4.7（每日 10AM 重置）

MiniMax（minimax/）— $0.20/$1.00 每 1M tokens：

minimax/MiniMax-M2.1— MiniMax M2.1（5 小时滚动重置）

Kimi（kimi/）— $9/月（1000 万 tokens）：

kimi/kimi-latest— Kimi Latest

6.3 免费模型（兜底）

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

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 个免费模型：

qw/qwen3-coder-plus— Qwen3 Coder Plus
qw/qwen3-coder-flash— Qwen3 Coder Flash

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

kr/claude-sonnet-4.5— Claude Sonnet 4.5
kr/claude-haiku-4.5— Claude Haiku 4.5

各前缀对应的提供商接入实现可在 open-sse/providers/registry 中按文件名对应查阅（如claude.js、codex.js、github.js、gemini.js、glm-cn.js、minimax.js、kimi-coding.js、kiro.js等）。免费渠道的具体额度以上游平台政策为准。

7. 成本优化策略

7.1 每月预算 $10-20 的参考方案

1. 简单任务用 Gemini CLI 免费档（180K/月） 2. 用满 Claude Code 订阅额度（反正已经付费） 3. 配额耗尽回退 GLM（$0.6/1M） 4. 紧急情况用 MiniMax M2.1（$0.20/1M）或 iFlow（免费） 实例测算（每月 1 亿 tokens）： 6000 万 via Gemini CLI：$0（免费档） 3000 万 via Claude Code：$0（已有订阅） 800 万 via GLM：$4.80 200 万 via MiniMax：$0.40 合计：$5.20/月 + 已有订阅费用

7.2 配额重置节奏策略

不同提供商的配额重置时间不同，按一天内的时段合理调度可以最大化免费额度：

每日例行安排： 1. 上午：Claude Code 配额刚刷新（5 小时重置） 2. 下午：切换到 Gemini CLI（每日 1K） 3. 傍晚：GLM 每日配额（次日 10AM 重置） 4. 深夜：MiniMax（5 小时滚动）或 iFlow（免费） → 以极低额外成本实现 24/7 编码！

7.3 关于成本显示的说明

Dashboard 中显示的成本是估算与对比参考值，并非 9Router 向你收费。9Router 本身完全免费开源，你只需直接向所使用的付费提供商付款（如果有）。例如使用 Kiro 免费模型时，即使 Dashboard 显示 "$290 总成本"，那代表的只是"如果直接调用付费 API 需要花的钱"，即你的节省金额。详见 README.md 中 "Understanding 9Router Costs & Billing" 一节。

8. 下一步

安装细节 — 环境要求、故障排查、部署方式
功能文档 — 配额跟踪、Combos、部署等深入内容
常见问题 — 高频问题解答
故障排查 — 常见问题修复
项目说明 — 架构概览、全部特性与账单说明

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

9Router 快速上手指南：5 分钟搭建可自动回退的免费 AI 路由网关