9router Documentation

Unlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40+ providers.

24,839 stars JavaScript JavaScript 1 file · ~25,472 tokens #ai-agents#ai-gateway#anthropic#chatgpt#claude#claude-code#cline#codex
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy 9router on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name 9router -p 20128:20128 --restart always decolua/9router:latest
Configured Services & Ports
⚙️ 9router
image: decolua/9router:latest
🔌 Ports: 20128:20128
⚙️ headroom
image: ghcr.io/chopratejas/headroom:latest
🔌 Ports: 8787:8787
docker-compose.yml
yaml (docker-compose.yml) 
services:
  9router:
    image: decolua/9router:latest
    container_name: 9router
    restart: always
    ports:
      - "20128:20128"
    volumes:
      - 9router-data:/app/data
    env_file:
      - .env
    environment:
      DATA_DIR: /app/data
      PORT: "20128"
      HOSTNAME: "0.0.0.0"
      NODE_ENV: production
      HEADROOM_URL: http://headroom:8787
    depends_on:
      - headroom

  headroom:
    image: ghcr.io/chopratejas/headroom:latest
    container_name: headroom
    restart: always
    ports:
      - "8787:8787"

volumes:
  9router-data:
    name: 9router-data

File: README.md

🤔 Why 9Router?

Stop wasting money, tokens and hitting limits:

  • ❌ Subscription quota expires unused every month
  • ❌ Rate limits stop you mid-coding
  • ❌ Tool outputs (git diff, grep, ls...) burn tokens fast
  • ❌ Expensive APIs ($20-50/month per provider)
  • ❌ Manual switching between providers

9Router solves this:

  • ✅ RTK Token Saver - Auto-compress tool_result content, save 20-40% tokens per request
  • ✅ Maximize subscriptions - Track quota, use every bit before reset
  • ✅ Auto fallback - Subscription → Cheap → Free, zero downtime
  • ✅ Multi-account - Round-robin between accounts per provider
  • ✅ Universal - Works with Claude Code, Codex, Cursor, Cline, any CLI tool

🔄 How It Works

text
┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────────┐
│           9Router (Smart Router)            │
│  • RTK Token Saver (cut tool_result tokens) │
│  • Format translation (OpenAI ↔ Claude)     │
│  • Quota tracking                           │
│  • Auto token refresh                       │
└──────┬──────────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot
       │   ↓ quota exhausted
       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits)

Result: Never stop coding, minimal cost + 20-40% token savings via RTK

⚡ Quick Start

1. Install globally:

bash
npm install 9router
9router

🎉 Dashboard opens at http://localhost:20128

2. Connect a FREE provider (no signup needed):

Dashboard → Providers → Connect Kiro AI (~50 credits/month free: Claude 4.5 + GLM-5 + MiniMax) or OpenCode Free (no auth) → Done!

3. Use in your CLI tool:

text
Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key: [copy from dashboard]
  Model: kr/claude-sonnet-4.5

That's it! Start coding with FREE AI models.

Alternative: run from source (this repository):

This repository package is private (9router-app), so source/Docker execution is the expected local development path.

bash
cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Production mode:

bash
npm run build
PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start

Default URLs:

  • Dashboard: http://localhost:20128/dashboard
  • OpenAI-compatible API: http://localhost:20128/v1

Video Guides

🎬 Made a video about 9Router? Submit a Pull Request adding your video to this section — we'll merge it!

🛠️ Supported CLI Tools

9Router works seamlessly with all major AI coding tools:

🌐 Supported Providers

🔐 OAuth Providers

🆓 Free Providers

Note: iFlow, Qwen Code and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead.

Kiro AI moved to a paid model in Sep 2025 — the free tier is now capped at 50 credits/month (plus 500 trial credits for new accounts in the first 30 days). Paid tiers: Pro $20/mo (1,000 credits), Pro+ $40/mo (2,000), Pro Max $100/mo (5,000), Power $200/mo (10,000).
OpenCode Free model list fluctuates over time (some models free only for limited promos) — subject to change without notice.
Vertex AI: the $300 free credit for new GCP accounts is still valid, but since Mar 2026 the Gemini API endpoint no longer consumes these credits — call the Vertex AI Studio endpoint instead.

🔑 API Key Providers (40+)

🏠 Self-hosted Providers

For speech and embeddings served from your own machine — whisper.cpp,
faster-whisper, Speaches, Kokoro-FastAPI, openedai-speech, llama.cpp/llama-server,
vLLM, Infinity, text-embeddings-inference, or anything else that speaks the OpenAI
shape.

Provider Endpoint used Typical server
Self-hosted STT /v1/audio/transcriptions whisper.cpp, faster-whisper
Self-hosted TTS /v1/audio/speech Kokoro-FastAPI, openedai-speech
Self-hosted Embedding /v1/embeddings llama-server, vLLM, Infinity

Every other speech provider is a named cloud service with a fixed endpoint. These
three read their address from each connection, so one provider can front
several machines and load-balance across them like any other.

Set it on the connection as providerSpecificData.baseUrl:

Provider Give it Result
Self-hosted STT the full URL — http://host:8080/v1/audio/transcriptions used as-is
Self-hosted TTS the server root — http://host:8880 + /v1/audio/speech
Self-hosted Embedding the OpenAI base, /v1 included — http://host:8080/v1 + /embeddings

Mind the /v1 on embeddings. The adapter appends /embeddings, so
http://host:8080 resolves to http://host:8080/embeddings and misses the
OpenAI route — llama-server answers 501. Give it the same base URL an OpenAI
client would use. A full .../v1/embeddings is also accepted, so a value pasted
from a curl example works too.

The API key is not checked by most local servers, but the field must be non-empty:
it is what gives the connection a credentials record, and baseUrl lives there.
Any placeholder works.

Self-hosted Embedding has no cloud fallback by design — a connection saved
without a baseUrl is reported as a configuration error rather than quietly
falling back to api.openai.com, which would send your input text and API key to
a third party under a provider named "Self-hosted".

💡 Key Features

Feature What It Does Why It Matters
🚀 RTK Token Saver (RTK ⭐40K) Compress tool outputs (git diff, grep, ls, tree...) before sending to LLM Save 20-40% input tokens per request
🧠 Headroom Token Saver (Headroom) Optional external /v1/compress proxy before provider routing Save more context tokens without changing clients
🪨 Caveman Mode (Caveman ⭐52K) Inject caveman-speak prompt → LLM replies terse, technical substance preserved Save up to 65% output tokens
🐴 Ponytail (Ponytail) Inject "lazy senior dev" prompt → LLM writes minimal, YAGNI-first code (Lite/Full/Ultra) Fewer output tokens, less refactoring
🎯 Smart 3-Tier Fallback Auto-route: Subscription → Cheap → Free Never stop coding, zero downtime
📊 Real-Time Quota Tracking Live token count + reset countdown Maximize subscription value
🔄 Format Translation OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex Works with any CLI tool
👥 Multi-Account Support Multiple accounts per provider Load balancing + redundancy
🔄 Auto Token Refresh OAuth tokens refresh automatically No manual re-login needed
🎨 Custom Combos Create unlimited model combinations Tailor fallback to your needs
📝 Request Logging Debug mode with full request/response logs Troubleshoot issues easily
💾 Cloud Sync Sync config across devices Same setup everywhere
📊 Usage Analytics Track tokens, cost, trends over time Optimize spending
🌐 Deploy Anywhere Localhost, VPS, Docker, Cloudflare Workers Flexible deployment options

Set X-9Router-Token-Saver: off to bypass all token savers for one chat request.

📖 Feature Details

🚀 RTK Token Saver

Tool outputs (git diff, grep, find, ls, tree, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression before the request hits the LLM:

  • Filters: git-diff, git-status, grep, find, ls, tree, dedup-log, smart-truncate, read-numbered, search-list
  • Auto-detect: No config needed — RTK peeks the first 1KB of each tool_result and picks the right filter.
  • Safe by design: If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request.
  • Universal: Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs before any format translation.
  • Default ON: Toggle anytime in Dashboard → Endpoint settings.
text
Without RTK: 47K tokens sent to LLM
With RTK:    28K tokens sent to LLM   (40% saved · same context · same answer)

🧠 Headroom Token Saver

Headroom is optional and runs separately. 9Router calls Headroom's local /v1/compress endpoint, then keeps normal routing, fallback, auth, and usage tracking:

text
Client → 9Router → Headroom /v1/compress → 9Router → provider

Local setup:

bash
pip install "headroom-ai[proxy]"
headroom proxy --port 8787

Enable in Dashboard → Endpoint → Token Saver → Headroom. Default URL: http://localhost:8787.

Docker examples:

bash
# Headroom service in same Docker network
http://headroom:8787

# Headroom running on host machine
http://host.docker.internal:8787

If Headroom is down or returns an error, 9Router fails open and sends the original request.

🐴 Ponytail (Lazy Senior Dev)

Ponytail injects a "lazy senior dev" system prompt into every request, biasing the LLM toward minimal, YAGNI-first code — deletion over addition, stdlib over new deps, one-liners over abstractions. Adapted from DietrichGebert/ponytail.

  • Lite — Build what's asked, name the lazier alternative.
  • Full — YAGNI ladder enforced: stdlib → native → existing deps → one-liner → minimal code.
  • Ultra — YAGNI extremist: deletion first, ship the one-liner, challenge the rest of the requirement in the same response.
text
Without Ponytail: verbose code, extra abstractions, "just in case" scaffolding
With Ponytail:    shortest working diff, no unrequested abstractions, fewer tokens

Never trades away: input validation, error handling that prevents data loss, security, accessibility, or anything explicitly requested. Enable in Dashboard → Endpoint → Ponytail. Stacks with Caveman (output terseness) and RTK (input compression).

🎯 Smart 3-Tier Fallback

Create combos with automatic fallback:

text
Combo: "my-coding-stack"
  1. cc/claude-opus-4-6        (your subscription)
  2. glm/glm-4.7               (cheap backup, $0.6/1M)
  3. if/kimi-k2-thinking       (free fallback)

→ Auto switches when quota runs out or errors occur

📊 Real-Time Quota Tracking

  • Token consumption per provider
  • Reset countdown (5-hour, daily, weekly)
  • Cost estimation for paid tiers
  • Monthly spending reports

🔄 Format Translation

Seamless translation between formats:

  • OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex ↔ Antigravity ↔ Ollama ↔ OpenAI Responses
  • Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format
  • Works with any tool that supports custom OpenAI endpoints

👥 Multi-Account Support

  • Add multiple accounts per provider
  • Auto round-robin or priority-based routing
  • Fallback to next account when one hits quota

🔄 Auto Token Refresh

  • OAuth tokens automatically refresh before expiration
  • No manual re-authentication needed
  • Seamless experience across all providers

🎨 Custom Combos

  • Create unlimited model combinations
  • Mix subscription, cheap, and free tiers
  • Name your combos for easy access
  • Share combos across devices with Cloud Sync

📝 Request Logging

  • Enable debug mode for full request/response logs
  • Track API calls, headers, and payloads
  • Troubleshoot integration issues
  • Export logs for analysis

💾 Cloud Sync

  • Sync providers, combos, and settings across devices
  • Automatic background sync
  • Secure encrypted storage
  • Access your setup from anywhere

Cloud Runtime Notes

  • Prefer server-side cloud variables in production:
    • BASE_URL (internal callback URL used by sync scheduler)
    • CLOUD_URL (cloud sync endpoint base)
  • NEXT_PUBLIC_BASE_URL and NEXT_PUBLIC_CLOUD_URL are still supported for compatibility/UI, but server runtime now prioritizes BASE_URL/CLOUD_URL.
  • Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable.

📊 Usage Analytics

  • Track token usage per provider and model
  • Cost estimation and spending trends
  • Monthly reports and insights
  • Optimize your AI spending

💡 IMPORTANT - Understanding Dashboard Costs:

The "cost" displayed in Usage Analytics is for tracking and comparison purposes only.
9Router itself never charges you anything. You only pay providers directly (if using paid services).

Example: If your dashboard shows "$290 total cost" while using Kiro free models, this represents
what you would have paid using paid APIs directly. Your actual cost = $0 (Kiro free tier: ~50 credits/mo).

Think of it as a "savings tracker" showing how much you're saving by using free models or
routing through 9Router!

🌐 Deploy Anywhere

  • 💻 Localhost - Default, works offline
  • ☁️ VPS/Cloud - Share across devices
  • 🐳 Docker - One-command deployment
  • 🚀 Cloudflare Workers - Global edge network

💰 Pricing at a Glance

Tier Provider Cost Quota Reset Best For
🚀 TOKEN SAVER RTK (built-in) FREE Always on Save 20-40% tokens on EVERY request
💳 SUBSCRIPTION Claude Code (Pro/Max) $20-200/mo 5h + weekly Already subscribed
Codex (Plus/Pro) $20-200/mo 5h + weekly OpenAI users
GitHub Copilot $10-19/mo Monthly GitHub users
Cursor IDE $20/mo Monthly Cursor users
💰 CHEAP GLM-5.1 / GLM-4.7 $0.6/1M Daily 10AM Budget backup
MiniMax M2.7 $0.2/1M 5-hour rolling Cheapest option
Kimi K2.5 $9/mo flat 10M tokens/mo Predictable cost
🆓 FREE Kiro AI $0 50 credits/mo Claude 4.5 + GLM-5 + MiniMax free (paid tiers above)
OpenCode Free $0 Varies* No auth, auto-fetch models (list changes over time)
Vertex AI $300 credits New GCP accounts Gemini 3 Pro + DeepSeek + GLM-5 (use Vertex AI Studio endpoint for free credits)

💡 Pro Tip: RTK + Kiro AI + OpenCode Free combo = $0 cost + 20-40% token savings!

📊 Understanding 9Router Costs & Billing

9Router Billing Reality:

✅ 9Router software = FREE forever (open source, never charges)
✅ Dashboard "costs" = Display/tracking only (not actual bills)
✅ You pay providers directly (subscriptions or API fees)
✅ FREE providers stay FREE (Kiro ~50 credits/mo, OpenCode Free, Vertex $300 credits = $0 within free-tier limits) — note iFlow/Qwen/Gemini CLI free tiers were discontinued in 2026
❌ 9Router never sends invoices or charges your card

How Cost Display Works:

The dashboard shows estimated costs as if you were using paid APIs directly. This is not billing - it's a comparison tool to show your savings.

Example Scenario:

text
Dashboard Display:
• Total Requests: 1,662
• Total Tokens: 47M
• Display Cost: $290

Reality Check:
• Provider: Kiro (free tier: ~50 credits/mo)
• Actual Payment: $0.00
• What $290 Means: Amount you SAVED by using free models!

Payment Rules:

  • Subscription providers (Claude Code, Codex): Pay them directly via their websites
  • Cheap providers (GLM, MiniMax): Pay them directly, 9Router just routes
  • FREE providers (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges
  • 9Router: Never charges anything, ever

🎯 Use Cases

Case 1: "I have Claude Pro subscription"

Problem: Quota expires unused, rate limits during heavy coding

Solution:

text
Combo: "maximize-claude"
  1. cc/claude-opus-4-7        (use subscription fully)
  2. glm/glm-5.1               (cheap backup when quota out)
  3. kr/claude-sonnet-4.5      (free emergency fallback)

Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration

Case 2: "I want zero cost"

Problem: Can't afford subscriptions, need reliable AI coding

Solution:

text
Combo: "free-forever"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free via Kiro, ~50 credits/mo)
  2. kr/glm-5                  (GLM-5 free via Kiro)
  3. oc/<auto>                 (OpenCode Free, no auth)

Monthly cost: $0
Quality: Production-ready models + RTK saves 20-40% tokens

Case 3: "I need 24/7 coding, no interruptions"

Problem: Deadlines, can't afford downtime

Solution:

text
Combo: "always-on"
  1. cc/claude-opus-4-7        (best quality)
  2. cx/gpt-5.5                (second subscription)
  3. glm/glm-5.1               (cheap, resets daily)
  4. minimax/MiniMax-M2.7      (cheapest, 5h reset)
  5. kr/claude-sonnet-4.5      (free via Kiro, ~50 credits/mo)

Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)

Case 4: "I want FREE AI in OpenClaw"

Problem: Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free

Solution:

text
Combo: "openclaw-free"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free)
  2. kr/glm-5                  (GLM-5 free)
  3. kr/MiniMax-M2.5           (MiniMax free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

❓ Frequently Asked Questions

📊 Why does my dashboard show high costs?

The dashboard tracks your token usage and displays estimated costs as if you were using paid APIs directly. This is not actual billing - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router.

Example:

  • Dashboard shows: "$290 total cost"
  • Reality: You're using Kiro free models (~50 credits/mo)
  • Your actual cost: $0.00
  • What $290 means: Amount you saved by using free models instead of paid APIs!

The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.

💳 Will I be charged by 9Router?

No. 9Router is free, open-source software that runs on your own computer. It never charges you anything.

You only pay:

  • ✅ Subscription providers (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
  • ✅ Cheap providers (GLM, MiniMax) → Pay them directly, 9Router just routes your requests
  • ❌ 9Router itself → Never charges anything, ever

9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.

🆓 Are FREE providers really unlimited?

Mostly! The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free, but free tiers have limits:

These are free services offered by those respective companies:

  • Kiro AI: ~50 credits/month free (plus 500 trial credits for new accounts in the first 30 days) via AWS Builder ID / Google / GitHub OAuth. Paid tiers available above that.
  • OpenCode Free: No-auth passthrough proxy, models auto-fetched from opencode.ai/zen/v1/models. The free model list fluctuates over time (some models free only for limited promos) — subject to change without notice.
  • Vertex AI: $300 free credits for new Google Cloud accounts (90 days). Since Mar 2026 the Gemini API endpoint no longer consumes these credits — use the Vertex AI Studio endpoint instead.

9Router just routes your requests to them - there's no "catch" or future billing from 9Router itself. They're truly free services, and 9Router makes them easy to use with fallback support.

Discontinued free tiers (no longer recommended):

  • ❌ iFlow: Was free unlimited, now changed to paid (2026)
  • ❌ Qwen Code: Free OAuth tier fully discontinued by Alibaba on 2026-04-15
  • ❌ Gemini CLI: Service fully shut down by Google on 2026-06-18 (replaced by the closed-source Antigravity CLI). Discontinued — do not use.

💰 How do I minimize my actual AI costs?

Free-First Strategy:

  1. Start with 100% free combo:

    text
    1. kr/glm-5 (GLM-5 free via Kiro, ~50 credits/mo)
2. OpenCode Free models (no auth, auto-fetched)
3. Vertex AI Gemini 3 Pro (using the Vertex AI Studio endpoint with $300 credits)

    Cost: $0/month (within Kiro's free credit cap; OpenCode/Vertex subject to their free-tier limits)

  2. Add cheap backup only if you need it:

    text
    4. glm/glm-4.7 ($0.6/1M tokens)

    Additional cost: Only pay for what you actually use

  3. Use subscription providers last:

    • Only if you already have them
    • 9Router helps maximize their value through quota tracking

Result: Most users can operate at $0/month using only free tiers!

📈 What if my usage suddenly spikes?

9Router's smart fallback prevents surprise charges:

Scenario: You're on a coding sprint and blow through your quotas

Without 9Router:

  • ❌ Hit rate limit → Work stops → Frustration
  • ❌ Or: Accidentally rack up huge API bills

With 9Router:

  • ✅ Subscription hits limit → Auto-fallback to cheap tier
  • ✅ Cheap tier gets expensive → Auto-fallback to free tier
  • ✅ Never stop coding → Predictable costs

You're in control: Set spending limits per provider in dashboard, and 9Router respects them.

📖 Setup Guide

🔐 Subscription Providers (Maximize Value)

Claude Code (Pro/Max)

bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-7
  cc/claude-opus-4-6
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Pro Tip: Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!

OpenAI Codex (Plus/Pro)

bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.2-codex

GitHub Copilot

bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5.4
  gh/claude-opus-4.7
  gh/claude-sonnet-4.6
  gh/gemini-3.1-pro-preview
  gh/grok-code-fast-1

Cursor IDE

bash
Dashboard → Providers → Connect Cursor
→ OAuth login
→ Monthly subscription

Models:
  cu/claude-4.6-opus-max
  cu/claude-4.5-sonnet-thinking
  cu/gpt-5.3-codex

💰 Cheap Providers (Backup)

GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M)

  1. Sign up: Zhipu AI
  2. Get API key from Coding Plan
  3. Dashboard → Add API Key:
    • Provider: glm
    • API Key: your-key

Use: glm/glm-5.1, glm/glm-5, glm/glm-4.7

Pro Tip: Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.

MiniMax M2.7 (5h reset, $0.20/1M)

  1. Sign up: MiniMax
  2. Get API key
  3. Dashboard → Add API Key

Use: minimax/MiniMax-M2.7, minimax/MiniMax-M2.5

Pro Tip: Cheapest option for long context (1M tokens)!

Kimi K2.5 ($9/month flat)

  1. Subscribe: Moonshot AI
  2. Get API key
  3. Dashboard → Add API Key

Use: kimi/kimi-k2.5, kimi/kimi-k2.5-thinking

Pro Tip: Fixed $9/month for 10M tokens = $0.90/1M effective cost!

🆓 FREE Providers (Recommended)

Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE)

bash
Dashboard → Connect Kiro
→ AWS Builder ID, AWS IAM Identity Center, Google, or GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
  kr/glm-5
  kr/MiniMax-M2.5
  kr/qwen3-coder-next
  kr/deepseek-3.2

Pro Tip: Best free option for Claude. No API key, no payment, fully unlimited.

OpenCode Free (No auth, auto-fetch models)

bash
Dashboard → Connect OpenCode Free
→ No login required (passthrough proxy)
→ Models auto-fetched from opencode.ai/zen/v1/models

Pro Tip: Fastest setup. Just connect and start coding.

Vertex AI ($300 free credits for new GCP accounts)

bash
Dashboard → Connect Vertex AI
→ Upload Google Cloud Service Account JSON
→ Enable Vertex AI API in your GCP project

Models:
  vertex/gemini-3.1-pro-preview
  vertex/gemini-3-flash-preview
  vertex/gemini-2.5-flash

Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex):
  vertex-partner/glm-5-maas
  vertex-partner/deepseek-v3.2-maas
  vertex-partner/qwen3-next-80b-a3b-thinking-maas

Pro Tip: New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding.

🎨 Create Combos

Example 1: Maximize Subscription → Cheap Backup

text
Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-5.1 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding

Monthly cost example (100M tokens):
  80M via Claude (subscription): $0 extra
  15M via GLM: $9
  5M via MiniMax: $1
  Total: $10 + your subscription

Example 2: Free-Only (Zero Cost)

text
Name: free-combo
Models:
  1. kr/claude-sonnet-4.5 (Claude 4.5 free via Kiro, ~50 credits/mo)
  2. kr/glm-5 (GLM-5 free via Kiro)
  3. vertex/gemini-3.1-pro-preview ($300 free credits)

Cost: $0 forever (+ 20-40% token savings via RTK)!

🔧 CLI Integration

Cursor IDE

text
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from 9router dashboard]
  Model: cc/claude-opus-4-7

Or use combo: premium-coding

Claude Code

Edit ~/.claude/config.json:

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

Codex CLI

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

codex "your prompt"

OpenClaw

Option 1 — Dashboard (recommended):

text
Dashboard → CLI Tools → OpenClaw → Select Model → Apply

Option 2 — Manual: Edit ~/.openclaw/openclaw.json:

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "9router/kr/claude-sonnet-4.5"
      }
    }
  },
  "models": {
    "providers": {
      "9router": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_9router",
        "api": "openai-completions",
        "models": [
          {
            "id": "kr/claude-sonnet-4.5",
            "name": "Claude Sonnet 4.5 (Kiro Free)"
          }
        ]
      }
    }
  }
}

Note: OpenClaw only works with local 9Router. Use 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.

Cline / Continue / RooCode

text
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-7

🚀 Deployment

VPS Deployment

bash
# Clone and install
git clone https://github.com/decolua/9router.git
cd 9router
npm install
npm run build

# Configure
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/9router"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
export MACHINE_ID_SALT="endpoint-proxy-salt"

# Start
npm run start

# Or use PM2
npm install pm2
pm2 start npm --name 9router -- start
pm2 save
pm2 startup

Docker

Published images (multi-platform linux/amd64 + linux/arm64):

Quick start (use published image):

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

→ Open http://localhost:20128

Build from source (dev):

bash
git clone https://github.com/decolua/9router.git
cd 9router/app
docker build -t 9router .
docker run -d --name 9router -p 20128:20128 \
  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router

Container defaults:

  • PORT=20128
  • HOSTNAME=0.0.0.0

Useful commands:

bash
docker logs -f 9router
docker restart 9router
docker stop 9router && docker rm 9router
docker pull decolua/9router:latest   # update to latest

Data persistence: $HOME/.9router/db/data.sqlite on host ↔ /app/data/db/data.sqlite in container.

Environment Variables

Variable Default Description
JWT_SECRET Auto-generated (~/.9router/jwt-secret) JWT signing secret for dashboard auth cookie (override to share across instances)
INITIAL_PASSWORD 123456 First login password when no saved hash exists
DATA_DIR ~/.9router Main app data location (SQLite at $DATA_DIR/db/data.sqlite)
PORT framework default Service port (20128 in examples)
HOSTNAME framework default Bind host (Docker defaults to 0.0.0.0)
NODE_ENV runtime default Set production for deploy
BASE_URL http://localhost:20128 Server-side internal base URL used by cloud sync jobs
CLOUD_URL https://9router.com Server-side cloud sync endpoint base URL
NEXT_PUBLIC_BASE_URL http://localhost:3000 Backward-compatible/public base URL (prefer BASE_URL for server runtime)
NEXT_PUBLIC_CLOUD_URL https://9router.com Backward-compatible/public cloud URL (prefer CLOUD_URL for server runtime)
API_KEY_SECRET endpoint-proxy-api-key-secret HMAC secret for generated API keys
MACHINE_ID_SALT endpoint-proxy-salt Salt for stable machine ID hashing
ENABLE_REQUEST_LOGS false Enables request/response logs under logs/
AUTH_COOKIE_SECURE false Force Secure auth cookie (set true behind HTTPS reverse proxy)
REQUIRE_API_KEY false Enforce Bearer API key on /v1/* routes (recommended for internet-exposed deploys)
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY empty Optional outbound proxy for upstream provider calls
SEARXNG_URL http://localhost:8888/search Endpoint for the built-in unauthenticated SearXNG web-search provider

Notes:

  • Lowercase proxy variables are also supported: http_proxy, https_proxy, all_proxy, no_proxy.
  • .env is not baked into Docker image (.dockerignore); inject runtime config with --env-file or -e.
  • On Windows, APPDATA can be used for local storage path resolution.
  • INSTANCE_NAME appears in older docs/env templates, but is currently not used at runtime.

Runtime Files and Storage

  • Main app state: ${DATA_DIR}/db/data.sqlite (SQLite — providers, combos, aliases, keys, settings, usage history)
  • Auto backups: ${DATA_DIR}/db/backups/
  • Optional request/translator logs: <repo>/logs/... when ENABLE_REQUEST_LOGS=true
  • Both ${DATA_DIR} and ~/.9router resolve to the same location in a Docker container — the symlink /root/.9router -> /app/data is created at build time.

📊 Available Models

View all available models

Claude Code (cc/) - Pro/Max:

  • cc/claude-opus-4-7
  • cc/claude-opus-4-6
  • cc/claude-sonnet-4-6
  • cc/claude-sonnet-4-5-20250929
  • cc/claude-haiku-4-5-20251001

Codex (cx/) - Plus/Pro:

  • cx/gpt-5.5
  • cx/gpt-5.4
  • cx/gpt-5.3-codex
  • cx/gpt-5.2-codex
  • cx/gpt-5.1-codex-max

GitHub Copilot (gh/):

  • gh/gpt-5.4
  • gh/claude-opus-4.7
  • gh/claude-sonnet-4.6
  • gh/gemini-3.1-pro-preview
  • gh/grok-code-fast-1

Cursor (cu/) - Subscription:

  • cu/claude-4.6-opus-max
  • cu/claude-4.5-sonnet-thinking
  • cu/gpt-5.3-codex
  • cu/kimi-k2.5

GLM (glm/) - $0.6/1M:

  • glm/glm-5.1
  • glm/glm-5
  • glm/glm-4.7

MiniMax (minimax/) - $0.2/1M:

  • minimax/MiniMax-M2.7
  • minimax/MiniMax-M2.5

Kimi (kimi/) - $9/mo flat:

  • kimi/kimi-k2.5
  • kimi/kimi-k2.5-thinking

Kiro (kr/) - Free (~50 credits/month, paid tiers above):

  • kr/claude-sonnet-4.5
  • kr/claude-haiku-4.5
  • kr/glm-5
  • kr/MiniMax-M2.5
  • kr/qwen3-coder-next
  • kr/deepseek-3.2

OpenCode Free (oc/) - FREE no-auth:

  • Auto-fetched from opencode.ai/zen/v1/models

Vertex AI (vertex/) - $300 free credits:

  • vertex/gemini-3.1-pro-preview
  • vertex/gemini-3-flash-preview
  • vertex/gemini-2.5-flash
  • vertex-partner/glm-5-maas
  • vertex-partner/deepseek-v3.2-maas

🐛 Troubleshooting

"Language model did not provide messages"

  • Provider quota exhausted → Check dashboard quota tracker
  • Solution: Use combo fallback or switch to cheaper tier

Rate limiting

  • Subscription quota out → Fallback to GLM/MiniMax
  • Add combo: cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5

OAuth token expired

  • Auto-refreshed by 9Router
  • If issues persist: Dashboard → Provider → Reconnect

High costs

  • Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens)
  • Check usage stats in Dashboard
  • Switch primary model to GLM/MiniMax
  • Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks

Dashboard opens on wrong port

  • Set PORT=20128 and NEXT_PUBLIC_BASE_URL=http://localhost:20128

First login not working

  • Check INITIAL_PASSWORD in .env
  • If unset, fallback password is 123456

No request logs under logs/

  • Set ENABLE_REQUEST_LOGS=true

🛠️ Tech Stack

  • Runtime: Node.js 20+
  • Framework: Next.js 16
  • UI: React 19 + Tailwind CSS 4
  • Database: SQLite (better-sqlite3 / node:sqlite / sql.js fallback)
  • Streaming: Server-Sent Events (SSE)
  • Auth: OAuth 2.0 (PKCE) + JWT + API Keys

📝 API Reference

Chat Completions

bash
POST http://localhost:20128/v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

List Models

bash
GET http://localhost:20128/v1/models
Authorization: Bearer your-api-key

→ Returns all models + combos in OpenAI format

📧 Support

👥 Contributors

Thanks to all contributors who helped make 9Router better!

📊 Star Chart

🔀 Forks

OmniRoute — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker.

🙏 Acknowledgments

Built on the shoulders of giants:

  • CLIProxyAPI — original Go implementation that inspired this JavaScript port.
  • RTK — Rust token-saver. 9Router ports its compression pipeline to JS → −20-40% input tokens on every request.
  • Caveman by @JuliusBrussee — viral "why use many token when few token do trick". 9Router adapts its prompt → −65% output tokens.
  • Ponytail by @DietrichGebert — "lazy senior dev" skill. 9Router injects its YAGNI-first ladder → fewer tokens, less code, shorter diffs.

Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub!

📄 License

MIT License - see LICENSE for details.

File: cli/README.md

9Router - FREE AI Router & Token Saver

Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.

Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.





🌐 Website • 📖 Full Docs

🤔 Why 9Router?

Stop wasting money, tokens and hitting limits:

  • ❌ Subscription quota expires unused every month
  • ❌ Rate limits stop you mid-coding
  • ❌ Tool outputs (git diff, grep, ls...) burn tokens fast
  • ❌ Expensive APIs ($20-50/month per provider)

9Router solves this:

  • ✅ RTK Token Saver - Auto-compress tool_result, save 20-40% tokens
  • ✅ Maximize subscriptions - Track quota, use every bit before reset
  • ✅ Auto fallback - Subscription → Cheap → Free, zero downtime
  • ✅ Multi-account - Round-robin between accounts per provider
  • ✅ Universal - Works with any OpenAI/Claude-compatible CLI

⚡ Quick Start

Option 1 — npm (recommended for desktop):

bash
npm install 9router
9router

# Or run directly with npx
npx 9router

Option 2 — Docker (server/VPS):

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

Published images: Docker Hub • GHCR (multi-platform amd64/arm64).

🎉 Dashboard opens at http://localhost:20128

2. Connect a FREE provider (no signup needed):

Dashboard → Providers → Connect Kiro AI (free Claude unlimited) or OpenCode Free (no auth) → Done!

3. Use in your CLI tool:

text
Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key:  [copy from dashboard]
  Model:    kr/claude-sonnet-4.5

That's it! Start coding with FREE AI models.

🚀 CLI Options

bash
9router                    # Start with default settings
9router --port 8080        # Custom port
9router --no-browser       # Don't open browser
9router --skip-update      # Skip auto-update check
9router --help             # Show all options

Dashboard: http://localhost:20128/dashboard

🛠️ Supported CLI Tools

Claude-Code • OpenClaw • Codex • OpenCode • Cursor • Antigravity • Cline • Continue • Droid • Roo • Copilot • Kilo Code • Gemini CLI • Qwen Code • iFlow • Crush • Crusher • Aider

Any tool supporting OpenAI/Claude-compatible API works.

💾 Data Location

  • macOS/Linux: ~/.9router/db/data.sqlite
  • Windows: %APPDATA%/9router/db/data.sqlite
  • Docker: /app/data/db/data.sqlite (mount $HOME/.9router to persist)

📚 Documentation

Full docs, advanced setup, video tutorials & development guide:

🙏 Acknowledgments

📄 License

MIT License - see LICENSE for details.

File: docs/ARCHITECTURE.md

9Router Architecture

Last updated: 2026-02-06

Executive Summary

9Router is a local AI routing gateway and dashboard built on Next.js.
It provides a single OpenAI-compatible endpoint (/v1/*) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.

Core capabilities:

  • OpenAI-compatible API surface for CLI/tools
  • Request/response translation across provider formats
  • Model combo fallback (multi-model sequence)
  • Account-level fallback (multi-account per provider)
  • OAuth + API-key provider connection management
  • Local persistence for providers, keys, aliases, combos, settings, pricing
  • Usage/cost tracking and request logging
  • Optional cloud sync for multi-device/state sync

Primary runtime model:

  • Next.js app routes under src/app/api/* implement both dashboard APIs and compatibility APIs
  • A shared SSE/routing core in src/sse/* + open-sse/* handles provider execution, translation, streaming, fallback, and usage

Scope and Boundaries

In Scope

  • Local gateway runtime
  • Dashboard management APIs
  • Provider authentication and token refresh
  • Request translation and SSE streaming
  • Local state + usage persistence
  • Optional cloud sync orchestration

Out of Scope

  • Cloud service implementation behind NEXT_PUBLIC_CLOUD_URL
  • Provider SLA/control plane outside local process
  • External CLI binaries themselves (Claude CLI, Codex CLI, etc.)

High-Level System Context

mermaid
flowchart LR
    subgraph Clients[Developer Clients]
        C1[Claude Code]
        C2[Codex CLI]
        C3[OpenClaw / Droid / Cline / Continue / Roo]
        C4[Custom OpenAI-compatible clients]
        BROWSER[Browser Dashboard]
    end

    subgraph Router[9Router Local Process]
        API[V1 Compatibility API\n/v1/*]
        DASH[Dashboard + Management API\n/api/*]
        CORE[SSE + Translation Core\nopen-sse + src/sse]
        DB[(db.json)]
        UDB[(usage.json + log.txt)]
    end

    subgraph Upstreams[Upstream Providers]
        P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax]
        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
    end

    subgraph Cloud[Optional Cloud Sync]
        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
    end

    C1 --> API
    C2 --> API
    C3 --> API
    C4 --> API
    BROWSER --> DASH

    API --> CORE
    DASH --> DB
    CORE --> DB
    CORE --> UDB

    CORE --> P1
    CORE --> P2
    CORE --> P3

    DASH --> CLOUD

Core Runtime Components

1) API and Routing Layer (Next.js App Routes)

Main directories:

  • src/app/api/v1/* and src/app/api/v1beta/* for compatibility APIs
  • src/app/api/* for management/configuration APIs
  • Next rewrites in next.config.mjs map /v1/* to /api/v1/*

Important compatibility routes:

  • src/app/api/v1/chat/completions/route.js
  • src/app/api/v1/messages/route.js
  • src/app/api/v1/responses/route.js
  • src/app/api/v1/models/route.js
  • src/app/api/v1/messages/count_tokens/route.js
  • src/app/api/v1beta/models/route.js
  • src/app/api/v1beta/models/[...path]/route.js

Management domains:

  • Auth/settings: src/app/api/auth/*, src/app/api/settings/*
  • Providers/connections: src/app/api/providers*
  • Provider nodes: src/app/api/provider-nodes*
  • OAuth: src/app/api/oauth/*
  • Keys/aliases/combos/pricing: src/app/api/keys*, src/app/api/models/alias, src/app/api/combos*, src/app/api/pricing
  • Usage: src/app/api/usage/*
  • Sync/cloud: src/app/api/sync/*, src/app/api/cloud/*
  • CLI tooling helpers: src/app/api/cli-tools/*

2) SSE + Translation Core

Main flow modules:

  • Entry: src/sse/handlers/chat.js
  • Core orchestration: open-sse/handlers/chatCore.js
  • Provider execution adapters: open-sse/executors/*
  • Format detection/provider config: open-sse/services/provider.js
  • Model parse/resolve: src/sse/services/model.js, open-sse/services/model.js
  • Account fallback logic: open-sse/services/accountFallback.js
  • Translation registry: open-sse/translator/index.js
  • Stream transformations: open-sse/utils/stream.js, open-sse/utils/streamHandler.js
  • Usage extraction/normalization: open-sse/utils/usageTracking.js

3) Persistence Layer

Primary state DB:

  • src/lib/localDb.js
  • file: ${DATA_DIR}/db.json (or ~/.9router/db.json when DATA_DIR is unset)
  • entities: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing

Usage DB:

  • src/lib/usageDb.js
  • files: ~/.9router/usage.json, ~/.9router/log.txt
  • note: currently independent from DATA_DIR

4) Auth + Security Surfaces

  • Dashboard cookie auth: src/proxy.js, src/app/api/auth/login/route.js
  • API key generation/verification: src/shared/utils/apiKey.js
  • Provider secrets persisted in providerConnections entries
  • Optional proxy support for upstream calls via env proxy variables (open-sse/utils/proxyFetch.js)

5) Cloud Sync

  • Scheduler init: src/lib/initCloudSync.js, src/shared/services/initializeCloudSync.js
  • Periodic task: src/shared/services/cloudSyncScheduler.js
  • Control route: src/app/api/sync/cloud/route.js

Request Lifecycle (`/v1/chat/completions`)

mermaid
sequenceDiagram
    autonumber
    participant Client as CLI/SDK Client
    participant Route as /api/v1/chat/completions
    participant Chat as src/sse/handlers/chat
    participant Core as open-sse/handlers/chatCore
    participant Model as Model Resolver
    participant Auth as Credential Selector
    participant Exec as Provider Executor
    participant Prov as Upstream Provider
    participant Stream as Stream Translator
    participant Usage as usageDb

    Client->>Route: POST /v1/chat/completions
    Route->>Chat: handleChat(request)
    Chat->>Model: parse/resolve model or combo

    alt Combo model
        Chat->>Chat: iterate combo models (handleComboChat)
    end

    Chat->>Auth: getProviderCredentials(provider)
    Auth-->>Chat: active account + tokens/api key

    Chat->>Core: handleChatCore(body, modelInfo, credentials)
    Core->>Core: detect source format
    Core->>Core: translate request to target format
    Core->>Exec: execute(provider, transformedBody)
    Exec->>Prov: upstream API call
    Prov-->>Exec: SSE/JSON response
    Exec-->>Core: response + metadata

    alt 401/403
        Core->>Exec: refreshCredentials()
        Exec-->>Core: updated tokens
        Core->>Exec: retry request
    end

    Core->>Stream: translate/normalize stream to client format
    Stream-->>Client: SSE chunks / JSON response

    Stream->>Usage: extract usage + persist history/log

Combo + Account Fallback Flow

mermaid
flowchart TD
    A[Incoming model string] --> B{Is combo name?}
    B -- Yes --> C[Load combo models sequence]
    B -- No --> D[Single model path]

    C --> E[Try model N]
    E --> F[Resolve provider/model]
    D --> F

    F --> G[Select account credentials]
    G --> H{Credentials available?}
    H -- No --> I[Return provider unavailable]
    H -- Yes --> J[Execute request]

    J --> K{Success?}
    K -- Yes --> L[Return response]
    K -- No --> M{Fallback-eligible error?}

    M -- No --> N[Return error]
    M -- Yes --> O[Mark account unavailable cooldown]
    O --> P{Another account for provider?}
    P -- Yes --> G
    P -- No --> Q{In combo with next model?}
    Q -- Yes --> E
    Q -- No --> R[Return all unavailable]

Fallback decisions are driven by open-sse/services/accountFallback.js using status codes and error-message heuristics.

OAuth Onboarding and Token Refresh Lifecycle

mermaid
sequenceDiagram
    autonumber
    participant UI as Dashboard UI
    participant OAuth as /api/oauth/[provider]/[action]
    participant ProvAuth as Provider Auth Server
    participant DB as localDb
    participant Test as /api/providers/[id]/test
    participant Exec as Provider Executor

    UI->>OAuth: GET authorize or device-code
    OAuth->>ProvAuth: create auth/device flow
    ProvAuth-->>OAuth: auth URL or device code payload
    OAuth-->>UI: flow data

    UI->>OAuth: POST exchange or poll
    OAuth->>ProvAuth: token exchange/poll
    ProvAuth-->>OAuth: access/refresh tokens
    OAuth->>DB: createProviderConnection(oauth data)
    OAuth-->>UI: success + connection id

    UI->>Test: POST /api/providers/[id]/test
    Test->>Exec: validate credentials / optional refresh
    Exec-->>Test: valid or refreshed token info
    Test->>DB: update status/tokens/errors
    Test-->>UI: validation result

Refresh during live traffic is executed inside open-sse/handlers/chatCore.js via executor refreshCredentials().

Cloud Sync Lifecycle (Enable / Sync / Disable)

mermaid
sequenceDiagram
    autonumber
    participant UI as Endpoint Page UI
    participant Sync as /api/sync/cloud
    participant DB as localDb
    participant Cloud as External Cloud Sync
    participant Claude as ~/.claude/settings.json

    UI->>Sync: POST action=enable
    Sync->>DB: set cloudEnabled=true
    Sync->>DB: ensure API key exists
    Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
    Cloud-->>Sync: sync result
    Sync->>Cloud: GET /{machineId}/v1/verify
    Sync-->>UI: enabled + verification status

    UI->>Sync: POST action=sync
    Sync->>Cloud: POST /sync/{machineId}
    Cloud-->>Sync: remote data
    Sync->>DB: update newer local tokens/status
    Sync-->>UI: synced

    UI->>Sync: POST action=disable
    Sync->>DB: set cloudEnabled=false
    Sync->>Cloud: DELETE /sync/{machineId}
    Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
    Sync-->>UI: disabled

Periodic sync is triggered by CloudSyncScheduler when cloud is enabled.

Data Model and Storage Map

mermaid
erDiagram
    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage

    SETTINGS {
      boolean cloudEnabled
      number stickyRoundRobinLimit
      boolean requireLogin
      string password_hash
    }

    PROVIDER_CONNECTION {
      string id
      string provider
      string authType
      string name
      number priority
      boolean isActive
      string apiKey
      string accessToken
      string refreshToken
      string expiresAt
      string testStatus
      string lastError
      string rateLimitedUntil
      json providerSpecificData
    }

    PROVIDER_NODE {
      string id
      string type
      string name
      string prefix
      string apiType
      string baseUrl
    }

    MODEL_ALIAS {
      string alias
      string targetModel
    }

    COMBO {
      string id
      string name
      string[] models
    }

    API_KEY {
      string id
      string name
      string key
      string machineId
      boolean isActive
    }

    USAGE_ENTRY {
      string provider
      string model
      number prompt_tokens
      number completion_tokens
      string connectionId
      string timestamp
    }

Physical storage files:

  • main state: ${DATA_DIR}/db.json (or ~/.9router/db.json)
  • usage stats: ~/.9router/usage.json
  • request log lines: ~/.9router/log.txt
  • optional translator/request debug sessions: <repo>/logs/...

Deployment Topology

mermaid
flowchart LR
    subgraph LocalHost[Developer Host]
        CLI[CLI Tools]
        Browser[Dashboard Browser]
    end

    subgraph ContainerOrProcess[9Router Runtime]
        Next[Next.js Server\nPORT=20128]
        Core[SSE Core + Executors]
        MainDB[(db.json)]
        UsageDB[(usage.json/log.txt)]
    end

    subgraph External[External Services]
        Providers[AI Providers]
        SyncCloud[Cloud Sync Service]
    end

    CLI --> Next
    Browser --> Next
    Next --> Core
    Next --> MainDB
    Core --> MainDB
    Core --> UsageDB
    Core --> Providers
    Next --> SyncCloud

Module Mapping (Decision-Critical)

Route and API Modules

  • src/app/api/v1/*, src/app/api/v1beta/*: compatibility APIs
  • src/app/api/providers*: provider CRUD, validation, testing
  • src/app/api/provider-nodes*: custom compatible node management
  • src/app/api/oauth/*: OAuth/device-code flows
  • src/app/api/keys*: local API key lifecycle
  • src/app/api/models/alias: alias management
  • src/app/api/combos*: fallback combo management
  • src/app/api/pricing: pricing overrides for cost calculation
  • src/app/api/usage/*: usage and logs APIs
  • src/app/api/sync/* + src/app/api/cloud/*: cloud sync and cloud-facing helpers
  • src/app/api/cli-tools/*: local CLI config writers/checkers

Routing and Execution Core

  • src/sse/handlers/chat.js: request parse, combo handling, account selection loop
  • open-sse/handlers/chatCore.js: translation, executor dispatch, retry/refresh handling, stream setup
  • open-sse/executors/*: provider-specific network and format behavior

Translation Registry and Format Converters

  • open-sse/translator/index.js: translator registry and orchestration
  • Request translators: open-sse/translator/request/*
  • Response translators: open-sse/translator/response/*
  • Format constants: open-sse/translator/formats.js

Persistence

  • src/lib/localDb.js: persistent config/state
  • src/lib/usageDb.js: usage history and rolling request logs

Provider Executor Coverage

Specialized executors:

  • antigravity
  • gemini-cli
  • github
  • kiro
  • codex
  • cursor

Default executor path:

  • all other providers (including compatible node providers) use open-sse/executors/default.js

Format Translation Coverage

Detected source formats include:

  • openai
  • openai-responses
  • claude
  • gemini

Target formats include:

  • OpenAI chat/Responses
  • Claude
  • Gemini/Gemini-CLI/Antigravity envelope
  • Kiro
  • Cursor

Translations are selected dynamically based on source payload shape and provider target format.

Failure Modes and Resilience

1) Account/Provider Availability

  • provider account cooldown on transient/rate/auth errors
  • account fallback before failing request
  • combo model fallback when current model/provider path is exhausted

2) Token Expiry

  • pre-check and refresh with retry for refreshable providers
  • 401/403 retry after refresh attempt in core path

3) Stream Safety

  • disconnect-aware stream controller
  • translation stream with end-of-stream flush and [DONE] handling
  • usage estimation fallback when provider usage metadata is missing

4) Cloud Sync Degradation

  • sync errors are surfaced but local runtime continues
  • scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default

5) Data Integrity

  • DB shape migration/repair for missing keys
  • corrupt JSON reset safeguards for localDb and usageDb

Observability and Operational Signals

Runtime visibility sources:

  • console logs from src/sse/utils/logger.js
  • per-request usage aggregates in usage.json
  • textual request status log in log.txt
  • optional deep request/translation logs under logs/ when ENABLE_REQUEST_LOGS=true
  • dashboard usage endpoints (/api/usage/*) for UI consumption

Security-Sensitive Boundaries

  • JWT secret (JWT_SECRET) secures dashboard session cookie verification/signing
  • Initial password fallback (INITIAL_PASSWORD, default 123456) must be overridden in real deployments
  • API key HMAC secret (API_KEY_SECRET) secures generated local API key format
  • Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
  • Cloud sync endpoints rely on API key auth + machine id semantics

Environment and Runtime Matrix

Environment variables actively used by code:

  • App/auth: JWT_SECRET, INITIAL_PASSWORD
  • Storage: DATA_DIR
  • Security hashing: API_KEY_SECRET, MACHINE_ID_SALT
  • Logging: ENABLE_REQUEST_LOGS
  • Sync/cloud URLing: NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_CLOUD_URL
  • Outbound proxy: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY and lowercase variants
  • Platform/runtime helpers (not app-specific config): APPDATA, NODE_ENV, PORT, HOSTNAME

Known Architectural Notes

  1. usageDb currently stores under ~/.9router and does not follow DATA_DIR.
  2. /api/v1/route.js returns a static model list and is not the main models source used by /v1/models.
  3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
  4. Cloud behavior depends on correct NEXT_PUBLIC_BASE_URL and cloud endpoint reachability.

Operational Verification Checklist

  • Build from source: cd /root/dev/9router && npm run build
  • Build Docker image: cd /root/dev/9router && docker build -t 9router .
  • Start service and verify:
  • GET /api/settings
  • GET /api/v1/models
  • CLI target base URL should be http://<host>:20128/v1 when PORT=20128

File: gitbook/content/zh-CN/deployment/cloud.md

☁️ 云端部署

将 9Router 部署到 VPS 或 Docker,实现远程访问和生产使用。

🖥️ VPS 部署

前置要求

  • Ubuntu 20.04+ 或类似 Linux 发行版
  • Node.js 20+
  • Git
  • root 或 sudo 权限

步骤 1:克隆仓库

bash
git clone https://github.com/decolua/9router.git
cd 9router/app

步骤 2:安装依赖

bash
npm install

步骤 3:构建应用

bash
npm run build

步骤 4:配置环境变量

创建 .env 文件或导出变量:

bash
export JWT_SECRET="your-secure-secret-change-this-to-random-string"
export INITIAL_PASSWORD="your-secure-password"
export DATA_DIR="/var/lib/9router"
export NODE_ENV="production"

环境变量:

变量 默认值 说明
JWT_SECRET 自动生成 生产环境必须修改! 用于 JWT token 签名
INITIAL_PASSWORD 123456 仪表盘登录密码
DATA_DIR ~/.9router 数据库与数据存储路径
NODE_ENV development 部署时设为 production
ENABLE_REQUEST_LOGS false 启用 debug 请求/响应日志

步骤 5:创建数据目录

bash
sudo mkdir -p /var/lib/9router
sudo chown $USER:$USER /var/lib/9router

步骤 6:启动应用

bash
npm run start

步骤 7:用 PM2 部署到生产环境

PM2 让应用持续运行,崩溃时自动重启:

bash
# 全局安装 PM2
npm install pm2

# 用 PM2 启动 9Router
pm2 start npm --name 9router -- start

# 保存 PM2 配置
pm2 save

# 设置开机自启
pm2 startup
# 按上一条命令打印的提示执行

PM2 管理命令:

bash
# 查看日志
pm2 logs 9router

# 重启应用
pm2 restart 9router

# 停止应用
pm2 stop 9router

# 查看状态
pm2 status

# 监控资源
pm2 monit

🐳 Docker 部署

方式 1:使用 Dockerfile

在 app 目录中创建 Dockerfile:

dockerfile
FROM node:20-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application files
COPY . .

# Build application
RUN npm run build

# Expose ports
EXPOSE 3000 20128

# Set environment variables
ENV NODE_ENV=production
ENV DATA_DIR=/app/data

# Create data directory
RUN mkdir -p /app/data

# Start application
CMD ["npm", "run", "start"]

构建并运行:

bash
# 构建镜像
docker build -t 9router .

# 运行容器
docker run -d \
  --name 9router \
  -p 3000:3000 \
  -p 20128:20128 \
  -e JWT_SECRET="your-secure-secret-change-this" \
  -e INITIAL_PASSWORD="your-secure-password" \
  -v 9router-data:/app/data \
  9router

方式 2:Docker Compose

创建 docker-compose.yml:

yaml
version: '3.8'

services:
  9router:
    build: .
    container_name: 9router
    ports:
      - "3000:3000"
      - "20128:20128"
    environment:
      - NODE_ENV=production
      - JWT_SECRET=your-secure-secret-change-this
      - INITIAL_PASSWORD=your-secure-password
      - DATA_DIR=/app/data
    volumes:
      - 9router-data:/app/data
    restart: unless-stopped

volumes:
  9router-data:

使用 Docker Compose 运行:

bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重新构建并重启
docker-compose up -d --build

🌐 Nginx 反向代理

为什么使用 Nginx?

  • SSL/TLS 终止
  • 域名映射
  • 负载均衡
  • 更好的安全性

步骤 1:安装 Nginx

bash
sudo apt update
sudo apt install nginx

步骤 2:配置 Nginx

创建 /etc/nginx/sites-available/9router:

nginx
server {
    listen 80;
    server_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL certificates (use certbot to generate)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Proxy to 9Router
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # SSE support - CRITICAL for streaming
        proxy_buffering off;
        proxy_read_timeout 86400;
    }

    # API endpoint
    location /v1 {
        proxy_pass http://localhost:20128;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE support - CRITICAL for streaming
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

步骤 3:启用站点

bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重新加载 Nginx
sudo systemctl reload nginx

步骤 4:使用 Let's Encrypt 配置 SSL

bash
# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com

# 自动续期已自动配置
# 测试续期
sudo certbot renew --dry-run

🔒 安全注意事项

1. 修改默认凭据

关键: 部署前修改 JWT_SECRET 和 INITIAL_PASSWORD:

bash
# 生成安全的 JWT secret
openssl rand -base64 32

# 将该值用于 JWT_SECRET
export JWT_SECRET="generated-secret-here"

2. 防火墙配置

bash
# 允许 SSH
sudo ufw allow 22/tcp

# 允许 HTTP/HTTPS(若使用 Nginx)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 若不使用反向代理,放开 9Router 端口
sudo ufw allow 3000/tcp
sudo ufw allow 20128/tcp

# 启用防火墙
sudo ufw enable

3. 限制仪表盘访问

如果只需要 API 访问,可限制仪表盘端口:

bash
# 仅允许 localhost 访问仪表盘
sudo ufw deny 3000/tcp

通过 SSH 隧道访问仪表盘:

bash
ssh -L 3000:localhost:3000 [email protected]
# 然后在浏览器打开 http://localhost:3000

4. 定期更新

bash
# 更新系统包
sudo apt update && sudo apt upgrade -y

# 更新 9Router
cd /path/to/9router/app
git pull
npm install
npm run build
pm2 restart 9router

5. 备份策略

bash
# 备份数据目录
tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router

# 每日自动备份(加入 crontab)
0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router

📊 监控

检查应用状态

bash
# PM2 状态
pm2 status

# 查看日志
pm2 logs 9router --lines 100

# 监控资源
pm2 monit

Nginx 日志

bash
# 访问日志
sudo tail -f /var/log/nginx/access.log

# 错误日志
sudo tail -f /var/log/nginx/error.log

系统资源

bash
# CPU 和内存使用
htop

# 磁盘使用
df -h

# 网络连接
netstat -tulpn | grep -E '3000|20128'

🚨 故障排除

应用无法启动

bash
# 查看日志
pm2 logs 9router

# 检查端口是否被占用
sudo lsof -i :3000
sudo lsof -i :20128

# 检查环境变量
pm2 env 9router

Nginx 502 Bad Gateway

bash
# 检查 9Router 是否运行
pm2 status

# 查看 Nginx 错误日志
sudo tail -f /var/log/nginx/error.log

# 测试 Nginx 配置
sudo nginx -t

SSE 流式输出无法工作

确保 Nginx 配置中已设置 proxy_buffering off 以支持 SSE。

权限被拒绝错误

bash
# 修复数据目录权限
sudo chown -R $USER:$USER /var/lib/9router
chmod 755 /var/lib/9router

🔗 下一步

File: gitbook/content/zh-CN/deployment/localhost.md

🏠 本地部署

在本机运行 9Router,用于开发和个人使用。

📦 安装

通过 npm 全局安装 9Router:

bash
npm install 9router

要求:

  • Node.js 20 或更高
  • npm 9 或更高

🚀 启动服务器

一条命令启动 9Router:

bash
9router

仪表盘会自动在浏览器中打开,地址为 http://localhost:3000

默认配置:

  • 仪表盘: http://localhost:3000
  • API Endpoint: http://localhost:20128/v1
  • 数据目录: ~/.9router

🔧 配置

自定义数据目录

通过环境变量设置自定义数据目录:

bash
DATA_DIR=/path/to/data 9router

自定义端口

API 端口(20128)和仪表盘端口(3000)在应用中配置。如需修改,你需要改源码或使用支持的环境变量(如果有)。

🛑 停止服务器

在运行 9Router 的终端中按 Ctrl+C。

bash
# 在运行 9router 的终端中
^C  # 按 Ctrl+C

服务器会优雅关闭并保存所有数据。

🔄 重启服务器

再次运行启动命令即可:

bash
9router

所有配置、API keys 和组合都保存在数据目录中。

📊 更新 9Router

更新到最新版本:

bash
npm update -g 9router

查看当前版本:

bash
npm list -g 9router

🔍 故障排除

端口已被占用

如果端口 20128 或 3000 已被占用:

bash
# 找到使用该端口的进程(macOS/Linux)
lsof -i :20128
lsof -i :3000

# 杀掉进程
kill -9

权限错误

安装过程中遇到权限错误:

bash
# 使用 sudo(不推荐)
sudo npm install 9router

# 或修复 npm 权限(推荐)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

数据目录问题

数据目录无法访问:

bash
# 检查权限
ls -la ~/.9router

# 修复权限
chmod 755 ~/.9router

📁 数据目录结构

text
~/.9router/
├── db.json           # 主数据库(提供商、组合、设置)
├── logs/             # 应用日志
└── cache/            # 临时缓存文件

备份数据:

bash
# 备份
cp -r ~/.9router ~/.9router.backup

# 恢复
cp -r ~/.9router.backup ~/.9router

🔗 下一步

File: gitbook/content/zh-CN/features/combos.md

组合(Combos)- 自定义回退链

创建自定义的模型组合并自动回退。组合让你根据成本、质量和可用性定义自己的路由策略。

什么是组合?

组合是你在仪表盘中创建的 自定义回退链。它不是单一模型,而是定义一组顺序模型,由 9Router 依次尝试。

示例:

text
组合名: premium-coding
模型:
  1. cc/claude-opus-4-5-20251101 (首选)
  2. glm/glm-4.7 (#1 配额耗尽时)
  3. minimax/MiniMax-M2.1 (#2 配额耗尽时)

CLI 中使用:

text
Model: premium-coding

9Router 会按顺序自动尝试每个模型,直到成功为止。

为什么使用组合?

1. 最大化订阅价值

text
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking

→ 先用订阅,低价备用,免费应急
→ 充分利用你已付费的订阅

2. 最小化成本

text
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking

→ 从最便宜的付费选项开始(每 1M $0.60)
→ 回退到更便宜的(每 1M $0.20)
→ 应急免费层
→ 总成本: 约 $5-10/月,而 ChatGPT API 需要 $2000

3. 保障 24/7 可用

text
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking

→ 末尾总是放免费层
→ 永不耗尽配额
→ 随时随地编码

4. 质量优化

text
cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro

→ 优先最好的模型
→ 回退到其他高端模型
→ 整个回退链保持高质量

如何创建组合

步骤 1:打开仪表盘

text
http://localhost:20128
→ 用密码登录

步骤 2:进入组合页面

text
仪表盘 → 组合 → 新建组合

步骤 3:配置组合

组合名:

text
premium-coding

描述(可选):

text
订阅优先,低价备用,免费应急

选择模型:

text
1. cc/claude-opus-4-5-20251101
2. glm/glm-4.7
3. minimax/MiniMax-M2.1

拖动排序 - 自上而下表示优先级。

步骤 4:保存

text
点击 "Save Combo"
→ 组合出现在模型列表中

步骤 5:在 CLI 中使用

text
Cursor/Cline/任意工具:
  Model: premium-coding

示例组合

示例 1:Premium Coding(订阅 → 低价 → 免费)

目标:最大化订阅价值,最小化额外成本。

text
仪表盘 → 组合 → 新建

名称: premium-coding
模型:
  1. cc/claude-opus-4-5-20251101
  2. glm/glm-4.7
  3. minimax/MiniMax-M2.1

用法:

text
Cursor IDE:
  Model: premium-coding

行为:

text
早上(全新配额):
  请求 → cc/claude-opus-4-5 ✅

下午(Claude 配额用完):
  请求 → glm/glm-4.7 ✅ (自动切换)

晚上(GLM 配额用完):
  请求 → minimax/MiniMax-M2.1 ✅ (自动切换)

月成本(100M tokens):

text
80M 通过 Claude Code: $0(订阅)
15M 通过 GLM: $9
5M 通过 MiniMax: $1
合计: $10 + 你的订阅

节省:相比 ChatGPT API($2000)约 99%。

示例 2:Budget Combo(低价 → 免费)

目标:最小化成本,免费层作为备用。

text
仪表盘 → 组合 → 新建

名称: budget-combo
模型:
  1. glm/glm-4.7
  2. minimax/MiniMax-M2.1
  3. if/kimi-k2-thinking

用法:

text
Cline:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  Model: budget-combo

行为:

text
请求 → glm/glm-4.7
  ✅ 每日配额可用 → 使用 GLM(每 1M $0.60)
  ❌ 配额耗尽 → 尝试 MiniMax(每 1M $0.20)
  ❌ MiniMax 配额用完 → 使用 iFlow(免费)

月成本(100M tokens):

text
70M 通过 GLM: $42
20M 通过 MiniMax: $4
10M 通过 iFlow: $0
合计: $46,而 ChatGPT API 需 $2000

节省:97%。

示例 3:Free Combo(零成本)

目标:100% 免费,永不付费。

text
仪表盘 → 组合 → 新建

名称: free-combo
模型:
  1. if/kimi-k2-thinking
  2. qw/qwen3-coder-plus
  3. kr/claude-sonnet-4.5

用法:

text
Claude Desktop:
  Model: free-combo

行为:

text
请求 → if/kimi-k2-thinking
  ✅ 可用 → 使用 iFlow
  ❌ 错误 → 尝试 Qwen
  ❌ 错误 → 尝试 Kiro

月成本:

text
100M tokens 通过免费提供商: $0
合计: 永远 $0

适用场景:个人项目、学习、试验。

示例 4:Quality First(仅高端模型)

目标:最高质量,无低价回退。

text
仪表盘 → 组合 → 新建

名称: quality-first
模型:
  1. cc/claude-opus-4-5-20251101
  2. cx/gpt-5.2-codex
  3. gc/gemini-3-pro-preview

用法:

text
Codex CLI:
  export OPENAI_BASE_URL="http://localhost:20128"
  Model: quality-first

行为:

text
请求 → cc/claude-opus-4-5
  ❌ 配额用完 → cx/gpt-5.2-codex
  ❌ 配额用完 → gc/gemini-3-pro-preview
  ❌ 全部用完 → 返回错误(无低价回退)

适用场景:关键生产代码、复杂重构。

示例 5:Multi-Subscription(用足所有订阅)

目标:在产生额外费用前用足所有订阅。

text
仪表盘 → 组合 → 新建

名称: multi-sub
模型:
  1. gc/gemini-3-flash-preview (每月免费 180K)
  2. cc/claude-opus-4-5-20251101 (Pro 订阅)
  3. cx/gpt-5.2-codex (Plus 订阅)
  4. gh/gpt-5 (Copilot 订阅)
  5. glm/glm-4.7 (低价备用)
  6. if/kimi-k2-thinking (免费应急)

月成本(200M tokens):

text
50M 通过 Gemini CLI: $0(免费层)
80M 通过 Claude Code: $0(订阅)
40M 通过 Codex: $0(订阅)
20M 通过 Copilot: $0(订阅)
8M 通过 GLM: $4.80
2M 通过 iFlow: $0
合计: $4.80 + 你已有的订阅

结果:190M tokens 来自订阅,只有 $4.80 额外费用。

示例 6:配额重置优化

目标:根据重置时间分配使用。

text
仪表盘 → 组合 → 新建

名称: reset-optimized
模型:
  1. cc/claude-opus-4-5 (5h 重置, 早上用)
  2. gc/gemini-3-flash (每日 1K, 下午用)
  3. glm/glm-4.7 (每日 10AM 重置, 晚上用)
  4. minimax/MiniMax-M2.1 (5h 滚动, 夜里用)
  5. if/kimi-k2-thinking (无限, 应急)

日常安排:

text
08:00 - 13:00: Claude Code(全新 5h 配额)
13:00 - 18:00: Gemini CLI(每日 1K 配额)
18:00 - 22:00: GLM(次日 10AM 重置)
22:00 - 08:00: MiniMax(5h 滚动)或 iFlow

结果:24/7 编码,成本极低。

在 CLI 工具中使用组合

Cursor IDE

text
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [从仪表盘获取]
  Model: premium-coding

Claude Desktop

编辑 ~/.claude/config.json:

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

Codex CLI

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

codex --model quality-first "your prompt"

Cline / Continue / RooCode

text
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [从仪表盘获取]
Model: free-combo

API 请求

bash
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
  }'

最佳实践

1. 总是包含免费层

text
✅ 好:
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking

❌ 不好:
cc/claude-opus → glm/glm-4.7
(无免费回退,可能耗尽配额)

原因:确保 24/7 可用,绝不会被配额卡住。

2. 按成本排序(便宜 → 贵)

text
✅ 好:
glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus

❌ 不好:
cc/claude-opus → glm/glm-4.7
(在简单任务上浪费订阅配额)

例外:如果想充分利用订阅价值,把订阅放在最前面。

3. 匹配质量要求

text
生产代码:
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7

简单任务:
glm/glm-4.7 → if/kimi-k2-thinking

试验:
if/kimi-k2-thinking → qw/qwen3-coder-plus

4. 考虑配额重置时间

text
早上组合(配额刚刷新):
cc/claude-opus → cx/gpt-5.2-codex

晚上组合(配额大概率耗尽):
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking

5. 为不同场景创建多个组合

text
premium-coding: 复杂任务
budget-combo: 简单任务
free-combo: 试验
quality-first: 生产代码

根据任务需求切换组合。

6. 监控组合性能

text
仪表盘 → 分析 → 组合使用:
  premium-coding:
    80% 通过 cc/claude-opus(良好,使用订阅)
    15% 通过 glm/glm-4.7(可接受备用)
    5% 通过 minimax(罕见回退)

优化:回退使用过多时,提高主配额或重新排序模型。

高级配置

为组合设置预算上限

text
仪表盘 → 组合 → 编辑 → 预算:
  每日上限: $5
  每月上限: $50

达到上限时,9Router 跳过付费模型,仅使用免费层。

启用/禁用组合中的模型

text
仪表盘 → 组合 → 编辑 → 模型:
  ✅ cc/claude-opus-4-5(启用)
  ❌ glm/glm-4.7(暂时禁用)
  ✅ if/kimi-k2-thinking(启用)

用途:暂时禁用昂贵模型而不删除组合。

克隆已有组合

text
仪表盘 → 组合 → 克隆 "premium-coding"
→ 生成带 "-copy" 后缀的副本
→ 修改后另存为新组合

用途:为不同场景创建变体。

故障排除

问题:组合未出现在模型列表中

方案:

  1. 刷新仪表盘
  2. 检查组合已保存(绿色对勾)
  3. 重启 CLI 工具以刷新模型列表

问题:组合总是用最后一个模型(免费层)

方案:

  1. 检查主模型的配额(仪表盘 → 配额)
  2. 确认 API keys 有效(仪表盘 → 提供商)
  3. 检查是否超出预算上限

问题:组合成本超出预期

方案:

  1. 仪表盘 → 分析 → 查看组合使用情况
  2. 检查主模型是否配额耗尽
  3. 重新排序模型(更便宜的放前面)
  4. 设置预算上限

相关

File: gitbook/content/zh-CN/features/quota-tracking.md

配额跟踪 & 使用监控

实时跟踪 token 消耗、监控配额上限、估算成本,并在配额用尽前获得提醒。绝不浪费订阅配额,也不超出预算上限。

概览

9Router 为所有提供商提供完善的配额跟踪:

  • 实时 token 消耗 - 查看每次请求使用的 tokens
  • 配额上限与剩余 - 跟踪使用 vs 上限
  • 重置倒计时 - 了解配额何时刷新
  • 成本估算 - 计算付费层支出
  • 月度报告 - 分析使用模式
  • 告警与通知 - 接近上限时收到警告

仪表盘总览

配额摘要

text
仪表盘 → 主页 → 配额概览

┌─────────────────────────────────────────────┐
│ Claude Code (cc/)                           │
│ ████████████░░░░░░░░ 2.5h / 5h (50%)       │
│ 重置剩余: 2h 30m                            │
│ 成本: $0(订阅)                             │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Gemini CLI (gc/)                            │
│ ████████░░░░░░░░░░░░ 450 / 1000 (45%)      │
│ 每日重置剩余: 18h 30m                       │
│ 本月: 45K / 180K (25%)                      │
│ 成本: $0(免费层)                           │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ GLM-4.7 (glm/)                              │
│ ██████████████░░░░░░ 7M / 10M tokens (70%)  │
│ 重置: 每日 10:00 AM(5h 35m 后)            │
│ 今日成本: $4.20                             │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ MiniMax M2.1 (minimax/)                     │
│ ████████████████░░░░ 4M / 5M tokens (80%)   │
│ 5h 滚动窗口                                  │
│ 成本(5h): $0.80                            │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ iFlow (if/)                                 │
│ ████████████████████ 无限                   │
│ 成本: $0(永久免费)                        │
└─────────────────────────────────────────────┘

实时 Token 消耗

按请求跟踪

每次请求都会显示详细的 token 使用情况:

text
仪表盘 → 活动 → 最近请求

请求 #1234
模型: cc/claude-opus-4-5-20251101
时间戳: 2026-02-04 04:15:32

Tokens:
  输入: 1,250 tokens
  输出: 850 tokens
  合计: 2,100 tokens

成本: $0(订阅配额)
耗时: 3.2s
状态: ✅ 成功

实时使用监控

text
仪表盘 → 实时监控

当前请求:
  模型: glm/glm-4.7
  已流式输出 tokens: 450 / 预计 ~800
  当前成本: $0.0009
  耗时: 1.8s

按模型分解 Token

text
仪表盘 → 分析 → Token 使用

今日(2026-02-04):
  cc/claude-opus-4-5: 15M tokens($0,订阅)
  glm/glm-4.7: 8M tokens($4.80)
  if/kimi-k2-thinking: 3M tokens($0,免费)
  
合计: 26M tokens
成本: $4.80

配额上限与重置时间

订阅型提供商

Claude Code (Pro/Max)

text
配额类型: 基于时间(5 小时滚动)
上限: 5 小时使用时长
重置: 5 小时滚动窗口 + 每周刷新
跟踪: 每个模型的使用时间

仪表盘显示:
  Opus: 已用 2.5h / 5h
  Sonnet: 已用 1.2h / 5h
  Haiku: 已用 0.8h / 5h
  
每周重置: 每周一 00:00 UTC

OpenAI Codex (Plus/Pro)

text
配额类型: 基于时间(5 小时滚动)
上限: 5 小时(Plus)/ 10 小时(Pro)
重置: 5 小时滚动窗口 + 每周刷新

仪表盘显示:
  GPT-5.2 Codex: 已用 3.5h / 5h
  重置剩余: 1h 30m

Gemini CLI(免费)

text
配额类型: 请求次数 + 月度 tokens
每日上限: 1,000 次请求
月度上限: 180,000 次补全
重置: 每日 00:00 UTC + 每月 1 日

仪表盘显示:
  今日: 450 / 1,000 次请求 (45%)
  本月: 45K / 180K 次补全 (25%)
  每日重置剩余: 18h 30m
  月度重置剩余: 26 天

GitHub Copilot

text
配额类型: 月度使用量
上限: 因套餐而异
重置: 每月 1 日

仪表盘显示:
  使用: 月度配额 60%
  重置: 2026 年 3 月 1 日(25 天后)

低价提供商

GLM-4.7

text
配额类型: 每日 token 上限
上限: 10M tokens/天(Coding Plan)
重置: 每日 10:00 AM 北京时间(UTC+8)

仪表盘显示:
  已用: 7M / 10M tokens (70%)
  剩余: 3M tokens
  重置剩余: 5h 35m
  今日成本: $4.20

MiniMax M2.1

text
配额类型: 5 小时滚动窗口
上限: 每 5 小时 5M tokens
重置: 连续滚动窗口

仪表盘显示:
  已用(5h): 4M / 5M tokens (80%)
  最早一次使用过期: 45m
  成本(5h): $0.80

Kimi K2

text
配额类型: 月度订阅
上限: 10M tokens/月($9 固定)
重置: 订阅日每月一次

仪表盘显示:
  已用: 6M / 10M tokens (60%)
  重置: 2026 年 2 月 15 日(11 天后)
  成本: $9/月(预付)

免费提供商

iFlow / Qwen / Kiro

text
配额类型: 无限(限速)
上限: 无硬上限
重置: 不适用

仪表盘显示:
  今日已用: 5M tokens
  成本: $0(永久免费)
  状态: ✅ 可用

成本估算

实时成本跟踪

text
仪表盘 → 成本 → 今日

订阅型提供商: $0
  Claude Code: 15M tokens($0,包含)
  Gemini CLI: 3M tokens($0,免费层)

付费提供商: $4.80
  GLM-4.7: 8M tokens($4.80)
    输入: 6M × $0.60/1M = $3.60
    输出: 2M × $2.20/1M = $4.40
    合计: $4.80

免费提供商: $0
  iFlow: 3M tokens($0)

今日合计: $4.80

月度支出报告

text
仪表盘 → 成本 → 本月(2026 年 2 月)

第 1 周(2 月 1-7 日):
  订阅: $0(80M tokens)
  付费: $15.20(25M tokens)
  免费: $0(10M tokens)
  合计: $15.20

第 2 周(2 月 8-14 日):
  订阅: $0(75M tokens)
  付费: $12.80(20M tokens)
  免费: $0(8M tokens)
  合计: $12.80

本月至今: $28.00
预计(30 天): ~$120

按提供商分解:
  GLM-4.7: $22.00 (78%)
  MiniMax M2.1: $6.00 (22%)
  
每 1M tokens 平均成本: $0.62
相比 ChatGPT API 节省: 97%($4,000 → $120)

成本预测

text
仪表盘 → 成本 → 预测

基于近 7 天使用:
  日均: 50M tokens
  日成本: $4.50

月度预测:
  Tokens: 1,500M (1.5B)
  成本: $135
  
分解:
  订阅: 900M tokens($0)
  GLM-4.7: 450M tokens($90)
  MiniMax: 120M tokens($24)
  免费: 30M tokens($0)

预算状态:
  每日上限: $5 → 今日已用 90%
  每月上限: $150 → 预计 90%
  ⚠️ 警告: 可能超出每月预算

使用仪表盘

总览统计

text
仪表盘 → 分析 → 总览

今日(2026-02-04):
  请求: 1,234
  Tokens: 26M
  成本: $4.80
  平均响应时间: 2.1s

本周:
  请求: 8,456
  Tokens: 180M
  成本: $28.00
  成功率: 99.2%

本月:
  请求: 15,234
  Tokens: 320M
  成本: $52.00
  Top 模型: cc/claude-opus-4-5 (45%)

按模型使用

text
仪表盘 → 分析 → 模型

Top 模型(本月):
1. cc/claude-opus-4-5: 145M tokens (45%)
2. glm/glm-4.7: 95M tokens (30%)
3. if/kimi-k2-thinking: 50M tokens (16%)
4. minimax/MiniMax-M2.1: 20M tokens (6%)
5. gc/gemini-3-flash: 10M tokens (3%)

成本分解:
  cc/claude-opus: $0(订阅)
  glm/glm-4.7: $45.00
  if/kimi-k2-thinking: $0(免费)
  minimax/MiniMax-M2.1: $7.00
  gc/gemini-3-flash: $0(免费)

按时间使用

text
仪表盘 → 分析 → 时间线

按小时使用(今日):
00:00 - 01:00: 0.5M tokens
01:00 - 02:00: 0.2M tokens
...
08:00 - 09:00: 3.2M tokens(峰值)
09:00 - 10:00: 2.8M tokens
...
23:00 - 00:00: 0.8M tokens

峰值时段: 08:00 - 12:00(早上编码)
低谷时段: 00:00 - 06:00(夜间)

按组合使用

text
仪表盘 → 分析 → 组合

premium-coding:
  请求: 456
  Tokens: 12M
  成本: $2.40
  
  分解:
    cc/claude-opus: 8M tokens (67%, $0)
    glm/glm-4.7: 3M tokens (25%, $1.80)
    minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)

budget-combo:
  请求: 234
  Tokens: 6M
  成本: $1.20
  
  分解:
    glm/glm-4.7: 4M tokens (67%, $2.40)
    if/kimi-k2-thinking: 2M tokens (33%, $0)

告警与通知

配额告警

text
仪表盘 → 设置 → 告警

配额预警:
  ✅ 配额使用 80% 时告警
  ✅ 配额使用 90% 时告警
  ✅ 配额耗尽时告警
  ✅ 配额重置时通知

发送方式:
  ✅ 仪表盘通知
  ✅ 邮件(可选)
  ✅ Webhook(可选)

通知示例:

text
⚠️ Claude Code 配额已用 80%
   剩余 2.5h(1h 30m 后重置)
   
⚠️ GLM-4.7 配额已用 90%
   剩余 1M tokens(5h 后重置)
   
✅ Gemini CLI 配额已重置
   1,000 次请求可用(每日上限)

预算告警

text
仪表盘 → 设置 → 预算告警

每日预算: $5
  ✅ 80%($4)告警
  ✅ 100%($5)告警
  ✅ 超额时自动切换到免费层

每月预算: $150
  ✅ 50%($75)告警
  ✅ 80%($120)告警
  ✅ 100%($150)告警

通知示例:

text
⚠️ 每日预算已用 80%
   今日花费 $4.00 / $5.00
   
⚠️ 每月预算达到 50%
   本月花费 $75 / $150
   预计: $135(预算内)
   
🚨 每日预算超额
   今日花费 $5.20 / $5.00
   已自动切换到免费层

成本异常检测

text
仪表盘 → 设置 → 异常检测

✅ 检测异常支出模式
✅ 成本峰值告警(>2× 日均)
✅ 配额耗尽模式警告

告警示例:
⚠️ 检测到成本峰值
   今日: $12.50(2.5× 日均)
   原因: GLM-4.7 高用量(20M tokens)
   建议: 检查主模型是否配额耗尽

最佳实践

1. 每日监控配额

text
日常:
1. 查看仪表盘配额概览(30 秒)
2. 检查重置时间
3. 根据配额可用性规划使用

示例:

text
早晨检查:
  ✅ Claude Code: 5h 可用(刚重置)
  ✅ Gemini CLI: 1K 请求可用
  ⚠️ GLM-4.7: 剩 2M tokens(10AM 重置)
  
行动: 早上工作用 Claude Code

2. 设置预算上限

text
仪表盘 → 设置 → 预算:
  每日: $5(防止超支)
  每月: $150(与预算对齐)

结果:达到上限时自动切换到免费层。

3. 优化组合使用

text
仪表盘 → 分析 → 组合:
  查看哪些模型用得最多
  调整组合顺序以最小化成本

示例:

text
当前: cc/claude-opus → glm/glm-4.7
  80% 通过 Claude(好)
  20% 通过 GLM($12/月)

优化后: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
  50% 通过 Gemini(免费)
  40% 通过 Claude(订阅)
  10% 通过 GLM($6/月)
  
节省: $6/月

4. 跟踪重置时间

text
仪表盘 → 配额 → 重置日程:
  Claude Code: 5h 滚动 + 每周一
  Gemini CLI: 每日 00:00 UTC + 每月 1 日
  GLM-4.7: 每日 10:00 AM 北京时间
  MiniMax: 5h 滚动窗口

策略:配额刚刷新时使用对应提供商。

5. 查看月度报告

text
仪表盘 → 分析 → 月度报告:
  总 tokens: 1.5B
  总成本: $120
  节省: 相比 ChatGPT API 节省 97%
  
洞察:
  - 60% 用量来自订阅($0)
  - 30% 通过 GLM($90)
  - 10% 通过免费层($0)
  
优化:
  - 增加 Gemini CLI 用量(免费)
  - 减少 GLM 用量(更贵)

API 访问

获取配额状态

bash
GET http://localhost:20128/api/quota
Authorization: Bearer your-api-key

Response:
{
  "providers": [
    {
      "id": "cc",
      "name": "Claude Code",
      "quota": {
        "used": 2.5,
        "limit": 5,
        "unit": "hours",
        "percentage": 50
      },
      "reset": {
        "type": "rolling",
        "window": "5h",
        "nextReset": "2026-02-04T06:45:00Z"
      },
      "cost": {
        "today": 0,
        "month": 0,
        "currency": "USD"
      }
    },
    {
      "id": "glm",
      "name": "GLM-4.7",
      "quota": {
        "used": 7000000,
        "limit": 10000000,
        "unit": "tokens",
        "percentage": 70
      },
      "reset": {
        "type": "daily",
        "time": "10:00 AM UTC+8",
        "nextReset": "2026-02-04T10:00:00+08:00"
      },
      "cost": {
        "today": 4.20,
        "month": 52.00,
        "currency": "USD"
      }
    }
  ]
}

获取使用统计

bash
GET http://localhost:20128/api/usage?period=today
Authorization: Bearer your-api-key

Response:
{
  "period": "today",
  "date": "2026-02-04",
  "summary": {
    "requests": 1234,
    "tokens": 26000000,
    "cost": 4.80
  },
  "byModel": [
    {
      "model": "cc/claude-opus-4-5",
      "requests": 456,
      "tokens": 15000000,
      "cost": 0
    },
    {
      "model": "glm/glm-4.7",
      "requests": 234,
      "tokens": 8000000,
      "cost": 4.80
    }
  ]
}

故障排除

问题:配额显示 0% 但请求失败

方案:

  1. 检查提供商连接(仪表盘 → 提供商)
  2. 确认 API keys 有效
  3. 检查提供商是否宕机(状态页)
  4. 尝试重新连接 OAuth 提供商

问题:成本估算不正确

方案:

  1. 仪表盘 → 设置 → 定价
  2. 确认每个提供商的定价与当前一致
  3. 若提供商调整费率,更新定价
  4. 若差异持续,联系支持

问题:重置时间没有更新

方案:

  1. 刷新仪表盘(F5)
  2. 检查系统时间是否正确
  3. 确认时区设置
  4. 若问题持续,重启 9Router

问题:未收到告警

方案:

  1. 仪表盘 → 设置 → 告警
  2. 确认邮箱地址正确
  3. 检查垃圾邮件夹
  4. 测试通知(Send Test 按钮)

相关

File: gitbook/content/zh-CN/features/smart-routing.md

智能路由 & 自动回退

9Router 通过 3 层回退系统,自动将你的请求路由到最佳可用提供商。绝不再因配额限制或速率限制而中断编码。

工作原理

9Router 使用智能路由,最大化已有订阅价值、最小化成本,并保障 24/7 可用:

text
请求 → 9Router → 检查第 1 层 (订阅)
                     ↓ 配额耗尽
                     检查第 2 层 (低价)
                     ↓ 预算上限
                     检查第 3 层 (免费)
                     ↓
                     响应

3 层回退系统

第 1 层:订阅(主力)

  • Claude Code(Pro/Max)
  • OpenAI Codex(Plus/Pro)
  • Gemini CLI(每月免费 180K)
  • GitHub Copilot
  • Antigravity(Google)

目标:充分挖掘你已付费订阅的价值。

第 2 层:低价(备用)

  • GLM-4.7(输入每 1M $0.60)
  • MiniMax M2.1(输入每 1M $0.20)
  • Kimi K2($9/月固定)

目标:订阅配额用完后的超低价备用(比 ChatGPT API 便宜 ~90%)。

第 3 层:免费(应急)

  • iFlow(8 个模型)
  • Qwen(3 个模型)
  • Kiro(Claude 免费)

目标:零成本回退,实现无限编码。

自动切换

9Router 实时监控配额,自动切换提供商:

场景 1:订阅配额耗尽

text
用户请求 → cc/claude-opus-4-5
           ↓ 配额耗尽(达到 5 小时限制)
           自动切换 → glm/glm-4.7
           ↓ 每日配额耗尽
           自动切换 → minimax/MiniMax-M2.1
           ↓ 5 小时配额耗尽
           自动切换 → if/kimi-k2-thinking (免费)
           ↓
           响应已送达 ✅

结果:零停机,无缝体验。

场景 2:速率限制

text
用户请求 → cx/gpt-5.2-codex
           ↓ 速率受限(请求过多)
           自动切换 → glm/glm-4.7
           ↓
           响应已送达 ✅

场景 3:提供商不可用

text
用户请求 → cc/claude-opus-4-5
           ↓ 提供商错误(503)
           自动切换 → 下一个可用模型
           ↓
           响应已送达 ✅

模型选择逻辑

9Router 基于以下因素选择最佳模型:

  1. 配额可用性 - 检查提供商是否仍有剩余配额
  2. 成本层级 - 优先订阅 → 低价 → 免费
  3. 重置时间 - 考虑配额何时重置
  4. 提供商健康度 - 跳过有错误的提供商

优先级示例

对 cc/claude-opus-4-5 的请求:

text
1. 检查 Claude Code 配额
   ✅ 可用 → 使用 cc/claude-opus-4-5
   ❌ 耗尽 → 继续步骤 2

2. 检查回退层(若已配置)
   ✅ GLM 配额可用 → 使用 glm/glm-4.7
   ❌ 耗尽 → 继续步骤 3

3. 检查免费层
   ✅ iFlow 可用 → 使用 if/kimi-k2-thinking
   ❌ 全部耗尽 → 返回配额错误

配置选项

仪表盘设置

1. 启用/禁用自动回退

text
仪表盘 → 设置 → 智能路由
→ 切换 "Auto Fallback" ON/OFF
  • ON(默认):自动层级切换
  • OFF:严格模式,主模型不可用时返回错误

2. 设置预算上限

text
仪表盘 → 设置 → 预算控制
→ 每日上限: $5
→ 每月上限: $50

预算耗尽时,9Router 自动切换到免费层。

3. 配置回退顺序

text
仪表盘 → 设置 → 回退优先级
→ 拖动以重新排序每层内的提供商

自定义顺序示例:

text
第 1 层: Gemini CLI → Claude Code → Codex
第 2 层: MiniMax → GLM → Kimi
第 3 层: iFlow → Kiro → Qwen

4. 配额重置通知

text
仪表盘 → 设置 → 通知
→ 配额重置时邮件提醒
→ 配额使用 80% 时告警

示例

示例 1:基础自动回退

设置:

text
Model: cc/claude-opus-4-5-20251101
Fallback: 自动(默认 3 层)

行为:

text
早上(全新配额):
  请求 → cc/claude-opus-4-5 ✅

下午(配额耗尽):
  请求 → glm/glm-4.7 ✅ (自动切换)

晚上(GLM 配额用完):
  请求 → minimax/MiniMax-M2.1 ✅ (自动切换)

深夜(付费配额全部耗尽):
  请求 → if/kimi-k2-thinking ✅ (免费层)

成本:额外约 $5-10/月(大部分由订阅覆盖)。

示例 2:预算优先路由

设置:

text
仪表盘 → 设置:
  每日预算: $2
  每月预算: $20
  Fallback: 启用

行为:

text
1-15 日(预算内):
  请求 → glm/glm-4.7 (低价层)
  成本: $1.50/天

第 16 日(达到预算):
  请求 → if/kimi-k2-thinking (免费层)
  成本: $0

下月(预算重置):
  请求 → 重新使用 glm/glm-4.7

结果:绝不超过 $20/月,始终可用。

示例 3:仅订阅模式

设置:

text
仪表盘 → 设置:
  Auto Fallback: OFF
  Strict mode: ON

行为:

text
请求 → cc/claude-opus-4-5
  ✅ 配额可用 → 成功
  ❌ 配额耗尽 → 返回错误(无回退)

适用场景:只想用付费订阅,绝不产生额外成本。

示例 4:仅免费模式

设置:

text
Model: if/kimi-k2-thinking
Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5

行为:

text
所有请求 → 仅免费层
成本: 永远 $0

适用场景:个人项目、学习、试验。

最佳实践

1. 最大化订阅价值

text
策略:
- 将订阅模型设为第 1 层
- 在仪表盘监控配额使用
- 仅在订阅耗尽时使用低价层

示例组合:

text
cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking

2. 成本优化

text
策略:
- 先用 Gemini CLI 免费层(每月 180K)
- 回退到 GLM/MiniMax(超低价)
- 应急: iFlow(免费)

示例组合:

text
gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking

3. 质量优先

text
策略:
- 使用最佳模型(Claude Opus、GPT-5.2)
- 回退到优秀的低价模型(GLM-4.7)
- 最后手段: 免费层

示例组合:

text
cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7

4. 24/7 可用性

text
策略:
- 回退链中总是包含免费层
- 监控配额重置时间
- 在多个提供商间分散使用

示例组合:

text
cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking

结果:永不耗尽配额,随时编码。

配额重置策略

围绕配额重置时间规划使用:

提供商 配额重置 策略
Claude Code 5 小时 + 每周 早上使用,配额最新鲜
Codex 5 小时 + 每周 Claude 配额用完后使用
Gemini CLI 每日(1K)+ 每月(180K) 全天均匀使用
GLM-4.7 每日 10:00 AM 晚上使用,次日上午重置
MiniMax M2.1 5 小时滚动 任意时间用,跟踪滚动窗口
iFlow/Qwen/Kiro 无限制 应急备用

日常安排示例:

text
08:00 - 13:00: Claude Code(全新 5h 配额)
13:00 - 18:00: Gemini CLI(每日 1K 配额)
18:00 - 22:00: GLM-4.7(便宜,10AM 重置)
22:00 - 08:00: MiniMax 或 iFlow(5h 滚动 或 免费)

监控与告警

仪表盘配额跟踪

text
仪表盘 → 配额概览:
  Claude Code: 剩余 2.5h / 5h (50%)
  Gemini CLI: 今日 450 / 1000 次请求
  GLM-4.7: 5M / 10M tokens (8h 后重置)
  MiniMax: 3M / 5M tokens (5h 滚动)

实时通知

text
仪表盘 → 通知:
  ⚠️ Claude Code 配额使用 80%(剩 1h)
  ✅ GLM-4.7 配额已重置(10M tokens 可用)
  💰 每日预算使用 50%($2.50 / $5)

使用分析

text
仪表盘 → 分析:
  今日: 50M tokens
    - 30M 通过 Claude Code(订阅)
    - 15M 通过 GLM-4.7($9)
    - 5M 通过 iFlow(免费)
  
  成本: $9(对比 ChatGPT API $1000)
  节省: 99%

故障排除

问题:"All providers quota exhausted"

方案:

  1. 查看仪表盘配额跟踪
  2. 等待配额重置(查看倒计时)
  3. 在回退链中加入免费层
  4. 或提高预算上限

问题:"Too many fallback switches"

方案:

  1. 检查主提供商是否宕机
  2. 提高配额上限(升级订阅)
  3. 使用更便宜的主模型(用 GLM 代替 Claude)

问题:"Unexpected costs"

方案:

  1. 仪表盘 → 分析 → 查看使用情况
  2. 设置每日/每月预算上限
  3. 非关键任务切换到免费层
  4. 使用带免费回退的组合

相关

File: gitbook/content/zh-CN/getting-started/installation.md

安装

9Router 的详细安装指南,附故障排除技巧。

要求

系统要求

  • Node.js:版本 20.0.0 或更高
  • npm:版本 10.0.0 或更高(随 Node.js 安装)
  • OS:macOS、Linux、Windows(推荐 WSL)
  • 磁盘空间:安装约需 200MB

查看版本

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

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

没有 Node.js? 从 nodejs.org 安装

安装方式

方式 1:全局安装(推荐)

全局安装,任何位置都能使用:

bash
npm install 9router

启动 9Router:

bash
9router

优势:

  • ✅ 任意目录均可运行
  • ✅ 命令简单:9router
  • ✅ 通过 npm update -g 9router 自动更新

方式 2:本地安装

在特定项目中安装:

bash
mkdir my-9router
cd my-9router
npm install 9router

启动 9Router:

bash
npx 9router

优势:

  • ✅ 项目隔离
  • ✅ 项目级版本控制
  • ✅ 不污染全局命名空间

方式 3:源码安装(开发用)

从 GitHub 克隆并构建:

bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install
npm run build
npm start

优势:

  • ✅ 最新开发特性
  • ✅ 可参与开发
  • ✅ 可自定义修改

首次运行

启动服务器

bash
9router

发生了什么:

  1. 服务器启动在 http://localhost:20128
  2. 仪表盘在浏览器中自动打开
  3. 数据目录创建在 ~/.9router
  4. API key 自动生成

仪表盘登录

默认凭据:

  • 密码:123456

⚠️ 立即修改密码:

  1. 登录仪表盘
  2. 设置 → 修改密码
  3. 使用强密码

获取 API Key

text
仪表盘 → 设置 → API Keys
→ 复制你的 API key
→ 在 CLI 工具中使用

API key 格式示例:

text
9r_1234567890abcdef1234567890abcdef

验证安装

检查服务器状态

bash
curl http://localhost:20128/health

预期响应:

json
{
  "status": "ok",
  "version": "1.0.0"
}

列出可用模型

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

预期响应:

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

测试 Chat Completion

bash
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!"}
    ]
  }'

配置

环境变量

创建 .env 文件或设置环境变量:

bash
# Security (REQUIRED in production)
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"

# Storage
export DATA_DIR="~/.9router"

# Server
export PORT="20128"
export NODE_ENV="production"

# Logging
export ENABLE_REQUEST_LOGS="false"

数据目录

默认位置: ~/.9router

内容:

text
~/.9router/
  ├── db.json           # 数据库(提供商、组合、使用)
  ├── api-keys.json     # API keys
  └── logs/             # 请求日志(若启用)

修改位置:

bash
export DATA_DIR="/custom/path"
9router

端口配置

默认端口: 20128

修改端口:

bash
export PORT="3000"
9router

或用命令行:

bash
9router --port 3000

故障排除

端口已被占用

错误:

text
Error: listen EADDRINUSE: address already in use :::20128

方案 1:杀掉占用进程

bash
# 找到使用 20128 端口的进程
lsof -i :20128

# 杀掉进程
kill -9

方案 2:使用其他端口

bash
9router --port 3000

权限被拒绝

错误:

text
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'

方案:使用 sudo(不推荐)或修复 npm 权限

bash
# 修复 npm 权限(推荐)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install 9router

Node.js 版本过低

错误:

text
Error: The engine "node" is incompatible with this module

方案:更新 Node.js

bash
# 使用 nvm(推荐)
nvm install 20
nvm use 20

# 或从 nodejs.org 下载

仪表盘无法打开

问题: 仪表盘没有自动打开

方案 1:手动打开

text
http://localhost:20128

方案 2:检查防火墙

bash
# macOS: 在 System Preferences → Security 中允许 Node.js
# Linux: 检查 iptables
# Windows: 检查 Windows Firewall

无法连接提供商

问题: OAuth 登录失败或 API key 无效

方案 1:检查网络连接

bash
ping google.com

方案 2:检查提供商状态

方案 3:重新生成 API key

text
仪表盘 → 提供商 → 断开 → 重新连接

内存占用过高

问题: 9Router 占用过多 RAM

方案:重启服务器

bash
# 停止
pkill -f 9router

# 启动
9router

或用 PM2 自动重启:

bash
npm install pm2
pm2 start 9router --name 9router
pm2 save

部署选项

本地开发

bash
npm install 9router
9router

适用场景: 个人编码、测试

VPS/云服务器

bash
# 安装
npm install 9router

# 配置
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"

# 用 PM2 启动
npm install pm2
pm2 start 9router --name 9router
pm2 save
pm2 startup

适用场景: 团队访问、远程编码

Docker

bash
docker pull 9router/9router:latest

docker run -d \
  -p 20128:20128 \
  -e JWT_SECRET="your-secure-secret" \
  -e INITIAL_PASSWORD="your-password" \
  -v 9router-data:/root/.9router \
  --name 9router \
  9router/9router:latest

适用场景: 容器化部署、Kubernetes

反向代理(Nginx)

nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:20128;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        
        # SSE support for streaming
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

适用场景: HTTPS、自定义域名、负载均衡

卸载

移除全局安装

bash
npm uninstall -g 9router

移除数据目录

bash
rm -rf ~/.9router

移除配置

bash
# 从 shell 配置中移除环境变量
nano ~/.bashrc  # 或 ~/.zshrc
# 删除 9router 相关的 export

下一步

需要帮助?

File: gitbook/content/zh-CN/getting-started/quick-start.md

入门指南

5 分钟启动 9Router,开始智能路由 AI 请求。

快速开始

1. 安装

bash
npm install 9router

要求: Node.js 20+(安装详情)

2. 启动

bash
9router

🎉 仪表盘自动打开 地址为 http://localhost:20128

  • 默认密码:123456(在仪表盘中修改)
  • API key 自动生成
  • 可立即连接提供商

3. 连接提供商

有 3 种方式连接提供商:

方式 A:OAuth(订阅型提供商)

适用于: Claude Code、Codex、Gemini CLI、GitHub Copilot

text
仪表盘 → 提供商 → 连接 [提供商]
→ OAuth 登录 → 自动刷新 token
→ 启用配额跟踪

示例:Claude Code

  1. 点击 "Connect Claude Code"
  2. 用你的 Claude 账户登录
  3. 授权 9Router
  4. ✅ 完成!使用模型:cc/claude-opus-4-5-20251101

方式 B:API Key(低价提供商)

适用于: GLM、MiniMax、Kimi、OpenRouter

text
仪表盘 → 提供商 → 添加 API Key
→ 选择提供商
→ 粘贴 API key
→ 保存

示例:GLM-4.7

  1. 在 Zhipu AI 注册
  2. 从 Coding Plan 获取 API key
  3. 仪表盘 → 添加 API Key → 提供商:glm → 粘贴 key
  4. ✅ 完成!使用模型:glm/glm-4.7

方式 C:免费提供商(零成本)

适用于: iFlow、Qwen、Kiro

text
仪表盘 → 提供商 → 连接 [免费提供商]
→ 设备码或 OAuth
→ 无限使用

示例:iFlow

  1. 点击 "Connect iFlow"
  2. 用 iFlow 账户登录
  3. 授权
  4. ✅ 完成!使用 8 个模型:if/kimi-k2-thinking、if/qwen3-coder-plus 等

4. 在 CLI 工具中使用

将你的编码工具指向 9Router:

Cursor IDE

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

Claude Desktop

编辑 ~/.claude/config.json:

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

Cline / Continue / RooCode

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

Codex CLI

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

codex "your prompt"

5. 创建智能组合(可选)

组合(Combos)可在多个模型之间实现自动回退:

text
仪表盘 → 组合 → 新建

名称: premium-coding
模型:
  1. cc/claude-opus-4-5-20251101 (订阅主力)
  2. glm/glm-4.7 (低价备用, $0.6/1M)
  3. if/kimi-k2-thinking (免费回退)

CLI 中使用: premium-coding

工作原理:

  1. 先尝试 Claude Opus(你的订阅)
  2. 配额耗尽 → GLM-4.7(超低价)
  3. 预算上限 → iFlow(免费)
  4. 零停机,自动切换!

可用模型

订阅型模型(优先使用)

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

低价模型(备用)

GLM (glm/) - 每 1M $0.6/$2.2:

  • glm/glm-4.7 - GLM 4.7(每日 10AM 重置)

MiniMax (minimax/) - 每 1M $0.20/$1.00:

  • minimax/MiniMax-M2.1 - MiniMax M2.1(5h 重置)

Kimi (kimi/) - $9/月(10M tokens):

  • kimi/kimi-latest - Kimi Latest

免费模型(应急)

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

成本优化策略

月度预算:$10-20/月

text
1. 用 Gemini CLI 免费层(每月 180K)处理快速任务
2. 用足 Claude Code 订阅配额(你已经付费了)
3. 配额用完后回退到 GLM(每 1M $0.6)
4. 应急: MiniMax M2.1(每 1M $0.20)或 iFlow(免费)

真实案例(每月 100M tokens):
  60M 通过 Gemini CLI: $0(免费层)
  30M 通过 Claude Code: $0(你已有的订阅)
  8M 通过 GLM: $4.80
  2M 通过 MiniMax: $0.40
  合计: $5.20/月 + 已有订阅

配额重置策略

text
日常安排:
1. 早上: 全新的 Claude Code 配额(5h 重置)
2. 下午: 切换到 Gemini CLI(每日 1K)
3. 晚上: GLM 每日配额(次日 10AM 重置)
4. 深夜: MiniMax(5h 滚动)或 iFlow(免费)

→ 24/7 编码,几乎零额外成本!

下一步

需要帮助?

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai-agents Browse ai-agents catalog → #ai-gateway Browse ai-gateway catalog → #anthropic Browse anthropic catalog → #chatgpt Browse chatgpt catalog → #claude Browse claude catalog → #claude-code Browse claude-code catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →