9Router là gì? Phân tích repo decolua/9router và hướng dẫn sử dụng

9Router là gì? Phân tích repo decolua/9router và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ GitHub Open Graph preview của repo decolua/9router. Ảnh không phải SVG.¹

Tóm tắt nhanh

9Router là một AI router/proxy mã nguồn mở dành cho các công cụ AI coding như Claude Code, Codex, Cursor, Cline, OpenCode, OpenClaw, GitHub Copilot, Antigravity và nhiều CLI/IDE khác. Repo chính thức mô tả 9Router là “FREE AI Router & Token Saver”, giúp kết nối các AI code tools tới hơn 40 provider và hơn 100 model, đồng thời có cơ chế fallback tự động và tiết kiệm token bằng RTK.²

Nói dễ hiểu: thay vì mỗi công cụ AI coding phải cấu hình riêng một API key hoặc một provider, bạn chạy 9Router ở máy local hoặc server, rồi trỏ các tool về một endpoint chung:

http://localhost:20128/v1

Sau đó 9Router quyết định request nên đi tới provider/model nào: subscription, provider giá rẻ hoặc provider miễn phí, tùy combo bạn cấu hình.

9Router giải quyết vấn đề gì?

Khi dùng AI coding agent, bạn thường gặp các vấn đề như quota, rate limit, nhiều API key, nhiều subscription và tool output quá dài. Tool output từ git diff, grep, find, ls, tree hoặc log có thể chiếm rất nhiều prompt tokens. 9Router đứng giữa tool và provider để xử lý routing, fallback, format translation và token saving.

Claude Code / Codex / Cursor / Cline / OpenCode
        ↓
OpenAI-compatible endpoint: http://localhost:20128/v1
        ↓
9Router
        ↓
Claude Code subscription / Codex / Copilot / GLM / MiniMax / Kimi / Kiro / OpenCode Free / Vertex / custom provider

README mô tả mô hình hoạt động theo 3 tier: subscription → cheap → free; khi quota hoặc provider lỗi, router tự chuyển sang tầng tiếp theo.³

9Router không phải là gì?

Điểm quan trọng: 9Router là lớp routing. Nó không làm model thông minh hơn. Nó giúp bạn dùng nhiều nguồn model linh hoạt hơn, theo dõi quota tốt hơn và giảm token bị lãng phí.

Repo decolua/9router có gì đáng chú ý?

Trang GitHub của repo cho thấy decolua/9router là public repo, license MIT, có khoảng 16k sao tại thời điểm tham khảo. README ghi mục tiêu chính là “Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.”⁴

Repo có các phần chính:

README ghi tech stack gồm Node.js 20+, Next.js 16, React 19, Tailwind CSS 4, SQLite, Server-Sent Events, OAuth 2.0 PKCE, JWT và API keys.⁵

Cài đặt nhanh

Cài global bằng npm:

npm install -g 9router
9router

Sau khi chạy, dashboard mở ở:

http://localhost:20128

Endpoint API mặc định:

http://localhost:20128/v1

README hướng dẫn quick start gồm ba bước: cài global, connect provider trong dashboard, rồi trỏ CLI tool tới endpoint http://localhost:20128/v1 kèm API key lấy từ dashboard.⁶

Chạy từ source

Nếu muốn chạy repo local:

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

cp .env.example .env
npm install

PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Chạy production mode:

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

README lưu ý package trong repo là private 9router-app, nên với source/Docker thì chạy local development hoặc production từ source là hướng phù hợp.⁷

Cấu hình các tool AI coding

Claude Code

Sửa file:

~/.claude/config.json

Ví dụ:

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

Codex CLI

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

codex "your prompt"

Cursor IDE

Trong Cursor:

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

Cline / Continue / RooCode

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

OpenClaw

README ghi OpenClaw chỉ hoạt động với local 9Router và khuyến nghị dùng 127.0.0.1 thay vì localhost để tránh vấn đề IPv6 resolution.⁸

{
  "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)"
          }
        ]
      }
    }
  }
}

Provider và model trong 9Router

README chia provider thành ba nhóm lớn.⁹

1. Subscription providers

Dùng khi bạn đã có gói trả phí/subscription:

• Claude Code Pro/Max
• Codex Plus/Pro
• GitHub Copilot
• Cursor IDE

Mục tiêu: tận dụng quota subscription, theo dõi reset và fallback khi quota hết.

2. Cheap providers

Dùng làm backup giá rẻ, ví dụ GLM, MiniMax, Kimi, OpenRouter, DeepSeek, Groq, xAI, Mistral, Perplexity, Together AI, Fireworks, Cerebras, Cohere, NVIDIA, SiliconFlow và custom OpenAI/Anthropic-compatible endpoints.

3. Free providers

README hiện khuyến nghị Kiro AI, OpenCode Free và Vertex AI credit, đồng thời lưu ý iFlow, Qwen và Gemini CLI free tier đã thay đổi/ngừng khuyến nghị trong năm 2026.¹⁰

Lưu ý: mọi tuyên bố “free/unlimited” phụ thuộc chính sách provider bên thứ ba. Vì vậy, khi viết bài hoặc triển khai, nên ghi đây là trạng thái theo tài liệu 9Router tại thời điểm tham khảo và có thể thay đổi.

Combo là gì?

Combo là một model ảo gồm nhiều model thật xếp theo thứ tự ưu tiên. Khi model đầu tiên lỗi/hết quota, 9Router chuyển sang model tiếp theo.

Ví dụ:

Combo: premium-coding
1. cc/claude-opus-4-7      # subscription chính
2. glm/glm-5.1             # backup giá rẻ
3. minimax/MiniMax-M2.7    # fallback rẻ hơn
4. kr/claude-sonnet-4.5    # fallback miễn phí

Dùng trong CLI như một model:

premium-coding

README đưa ví dụ combo để maximize subscription hoặc tạo free-only combo.¹¹

Smart 3-Tier Fallback

3-tier fallback là ý tưởng cốt lõi của 9Router:

Tier 1: Subscription
  ↓ hết quota / lỗi
Tier 2: Cheap
  ↓ vượt budget / lỗi
Tier 3: Free

Lợi ích:

• không phải đổi config thủ công;
• giảm downtime khi provider lỗi;
• tận dụng subscription trước khi reset;
• dùng cheap provider làm backup;
• giữ free provider cho emergency/fallback hoặc workload không quan trọng.

RTK Token Saver

9Router tích hợp RTK token saver để nén tool_result trước khi gửi tới LLM. README nói tool outputs như git diff, grep, find, ls, tree, log dumps thường ăn 30–50% prompt budget; RTK auto-detect nội dung và áp filter phù hợp.¹²

Các filter được README nêu:

git-diff
git-status
grep
find
ls
tree
dedup-log
smart-truncate
read-numbered
search-list

Đặc điểm:

• Auto-detect bằng 1KB đầu của tool_result.
• Nếu filter lỗi hoặc output lớn hơn, giữ nguyên text gốc.
• Chạy trước format translation nên dùng được với OpenAI, Claude, Gemini, Cursor, Kiro và OpenAI Responses.
• Bật mặc định, có thể tắt trong dashboard.

Caveman Mode

9Router cũng có Caveman Mode, lấy cảm hứng từ dự án Caveman. README mô tả tính năng này inject prompt để model trả lời ngắn, kỹ thuật hơn, nhằm giảm output tokens, có thể tiết kiệm tới 65% output tokens theo mô tả dự án.¹³

Dùng khi bạn muốn câu trả lời ngắn và tiết kiệm output tokens. Không nên dùng khi cần tài liệu dài, nội dung blog hoặc hướng dẫn cho người mới.

Dashboard chi phí: cần hiểu đúng

README nhấn mạnh 9Router không thu tiền người dùng. “Cost” trong dashboard là ước tính dùng để so sánh/track usage, không phải hóa đơn thật từ 9Router.¹⁴

Quy tắc:

• 9Router software là miễn phí/mã nguồn mở.
• Bạn trả tiền trực tiếp cho provider nếu dùng provider trả phí.
• Free provider vẫn phụ thuộc chính sách free tier của provider đó.
• Dashboard cost là số liệu ước tính để xem usage và “savings”.
• 9Router không có billing system, không giữ thẻ, không gửi invoice.

API Reference cơ bản

9Router expose API OpenAI-compatible.

Chat completions

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cc/claude-opus-4-6",
    "messages": [
      {"role": "user", "content": "Write a function to parse CSV"}
    ],
    "stream": true
  }'

List models

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

README nói endpoint models trả về toàn bộ models và combos ở format OpenAI.¹⁵

Triển khai bằng Docker

Chạy image Docker Hub:

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

Mở:

http://localhost:20128

Dữ liệu SQLite được persist ở:

$HOME/.9router/db/data.sqlite

README ghi images được publish multi-platform linux/amd64 và linux/arm64, có Docker Hub decolua/9router và GHCR ghcr.io/decolua/9router.¹⁶

Triển khai VPS/production

Ví dụ biến môi trường quan trọng:

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 BASE_URL="https://your-9router.example.com"
export CLOUD_URL="https://9router.com"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
export MACHINE_ID_SALT="endpoint-proxy-salt"
export AUTH_COOKIE_SECURE="true"
export REQUIRE_API_KEY="true"

Build và chạy:

npm install
npm run build
npm run start

Nếu expose ra internet, nên đặt sau reverse proxy HTTPS như Nginx/Caddy/Traefik và bật AUTH_COOKIE_SECURE=true cùng REQUIRE_API_KEY=true.¹⁷

Biến môi trường quan trọng

README và .env.example nêu các biến runtime chính:¹⁷¹⁸

Lưu ý bảo mật

9Router xử lý API keys, OAuth tokens, request/response và có thể lưu usage logs. Vì vậy cần cấu hình cẩn thận.

Checklist:

• Đổi INITIAL_PASSWORD ngay khi deploy.
• Đặt JWT_SECRET dài và random.
• Đặt API_KEY_SECRET riêng, không dùng default.
• Đặt MACHINE_ID_SALT riêng.
• Không expose dashboard public nếu chưa có HTTPS/auth.
• Nếu expose API /v1/*, bật REQUIRE_API_KEY=true.
• Đặt AUTH_COOKIE_SECURE=true khi chạy sau HTTPS reverse proxy.
• Không bật ENABLE_REQUEST_LOGS=true nếu request chứa code/secret/dữ liệu khách hàng, trừ khi cần debug.
• Backup ${DATA_DIR}/db/data.sqlite.
• Không commit .env.
• Không chia sẻ SQLite database vì có thể chứa provider config, tokens, keys hoặc usage history.
• Đọc kỹ điều khoản của từng provider, đặc biệt khi dùng OAuth/subscription/IDE traffic.
• Với MITM bridge/intercept, chỉ dùng trong phạm vi chính sách cho phép.

Website 9Router cũng nhắc MITM Bridge dùng để intercept traffic Antigravity/Copilot/Kiro IDE và ghi rõ cần chú ý policy của từng tool.¹⁹

Khi nào nên dùng 9Router?

Nên dùng nếu:

• bạn dùng nhiều AI coding tools;
• bạn có nhiều provider/API key/subscription;
• bạn hay bị rate limit;
• bạn muốn fallback tự động;
• bạn muốn track quota và usage;
• bạn muốn tiết kiệm token tool output;
• bạn muốn endpoint OpenAI-compatible chung cho team;
• bạn muốn self-host router trên VPS/Docker.

Không nên dùng hoặc cần cân nhắc nếu:

• chỉ dùng một provider đơn giản và không bị quota;
• không muốn lưu tokens/keys trong router local;
• môi trường doanh nghiệp cấm proxy tự quản;
• provider policy không cho routing/intercept ngoài client chính thức;
• chưa có HTTPS/auth nhưng định expose ra internet;
• request chứa dữ liệu nhạy cảm và bạn bật full request logs.

Hướng dẫn triển khai cho cá nhân

Bước khuyến nghị:

npm install -g 9router
9router

Sau đó:

1. Mở dashboard ở http://localhost:20128.
2. Đổi password nếu được yêu cầu.
3. Add provider hoặc connect OAuth.
4. Tạo API key cho endpoint.
5. Tạo combo, ví dụ free-combo hoặc premium-coding.
6. Cấu hình Claude Code/Codex/Cursor trỏ về http://localhost:20128/v1.
7. Chạy một request test.
8. Kiểm tra Usage Analytics và quota.

Hướng dẫn triển khai cho team

Giai đoạn 1: thử local

• Mỗi developer chạy 9Router local.
• Tạo combo cá nhân.
• Test với Claude Code/Codex/Cursor.
• Theo dõi token savings và fallback.

Giai đoạn 2: chuẩn hóa combo

Team có thể tạo combo mẫu:

team-premium
1. subscription model chính
2. cheap backup
3. free fallback

team-review
1. model rẻ, context dài
2. free fallback

team-experiment
1. free provider
2. cheap backup nếu cần

Giai đoạn 3: self-host nội bộ

• Deploy trên VPS/private network.
• Bật HTTPS.
• Bật REQUIRE_API_KEY=true.
• Chỉ mở dashboard cho VPN hoặc allowlist IP.
• Backup SQLite.
• Không bật request logs mặc định.
• Ghi tài liệu setup cho từng tool.

Giai đoạn 4: governance

• Quy định provider nào được dùng cho code nội bộ.
• Quy định model nào được dùng cho dữ liệu khách hàng.
• Theo dõi cost ước tính và actual provider billing.
• Review logs nếu bật debug.
• Review cloud sync policy.
• Xóa/revoke tokens khi nhân sự rời team.

So sánh 9Router với các repo trước

9Router nằm ở tầng provider routing. Nó không thay thế Claude Tap/Headroom/RTK, nhưng có thể bổ sung: Claude Tap để debug routing, RTK để tiết kiệm token, 9Router để fallback provider.

FAQ

9Router là gì?

9Router là AI router/proxy mã nguồn mở, cung cấp endpoint OpenAI-compatible để các AI coding tools kết nối tới nhiều provider/model, có fallback tự động, quota tracking, token saver và dashboard local.²

9Router có miễn phí không?

9Router software là miễn phí và mã nguồn mở theo MIT license; README nói 9Router không thu tiền người dùng. Tuy nhiên, bạn vẫn trả tiền trực tiếp cho provider nếu dùng subscription hoặc API trả phí.¹⁴²⁰

9Router hỗ trợ công cụ nào?

README và website nêu hỗ trợ Claude Code, Codex, OpenClaw, OpenCode, Cursor, Antigravity, Cline, Continue, Roo, Copilot, Kilo Code và các tool hỗ trợ endpoint OpenAI-compatible.²¹²²

RTK Token Saver trong 9Router làm gì?

Nó nén tool result như git diff, grep, find, ls, tree, log dumps trước khi gửi tới LLM, nhằm giảm input tokens. README ghi mức tiết kiệm 20–40% per request theo mô tả của dự án.¹²

Có nên expose 9Router ra internet không?

Chỉ nên expose khi có HTTPS, password mạnh, API key enforcement, reverse proxy bảo mật và không bật request logging nhạy cảm. Với cá nhân, chạy localhost là an toàn hơn.

9Router dùng database gì?

README ghi 9Router dùng SQLite; dữ liệu chính nằm ở ${DATA_DIR}/db/data.sqlite, gồm providers, combos, aliases, keys, settings và usage history.²³

Kết luận

decolua/9router là repo rất đáng chú ý nếu bạn dùng AI coding agent hằng ngày. Nó giải quyết vấn đề thực tế: quota, rate limit, nhiều provider, nhiều API key và token tool output quá dài. Điểm mạnh của 9Router là một endpoint chung, dashboard rõ ràng, combo fallback, RTK token saver, format translation và khả năng chạy local/Docker/VPS.

Cách bắt đầu đơn giản nhất là npm install -g 9router, chạy 9router, connect một provider trong dashboard, rồi trỏ Claude Code/Codex/Cursor/Cline về http://localhost:20128/v1. Khi triển khai cho team hoặc internet, cần xem 9Router như một service chứa secret: bật API key, HTTPS, password mạnh, backup SQLite, hạn chế request logs và kiểm tra chính sách từng provider.

Nguồn tham khảo

Footnotes

1. GitHub Open Graph preview image for decolua/9router. https://opengraph.githubassets.com/9router-guide/decolua/9router ↩

2. 9Router README. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

3. 9Router README, “How It Works.” https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

4. GitHub. decolua/9router. https://github.com/decolua/9router ↩

5. 9Router README, Tech Stack. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

6. 9Router README, Quick Start. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

7. 9Router README, run from source and production mode. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

8. 9Router README, CLI Integration. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

9. 9Router README, Supported Providers. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

10. 9Router README, Free Providers and discontinued free tiers note. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

11. 9Router README, Create Combos. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

12. 9Router README, RTK Token Saver. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

13. 9Router README, Key Features. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

14. 9Router README, Understanding 9Router Costs & Billing. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

15. 9Router README, API Reference. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

16. 9Router README, Docker deployment. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

17. 9Router README, Environment Variables. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

18. 9Router .env.example. https://raw.githubusercontent.com/decolua/9router/master/.env.example ↩

19. 9Router website, Advanced Features and MITM Bridge note. https://9router.com ↩

20. 9Router MIT license. https://raw.githubusercontent.com/decolua/9router/master/LICENSE ↩

21. 9Router README, Supported CLI Tools. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

22. 9Router website, CLI/IDE integrations. https://9router.com ↩

23. 9Router README, Runtime Files and Storage. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩