MythEclipse/9router
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feat : Gitbook

Browse Source
This commit is contained in:
decolua
2026-05-11 11:50:24 +07:00
parent 7ad538bcf2
commit fd92af77a0
124 changed files with 34154 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitbook/.gitignore
+44
View File
@@ -0,0 +1,44 @@
# Dependencies
node_modules/
.pnp
.pnp.js
# Testing
coverage/
# Next.js
.next/
out/
build/
dist/
# Production
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Environment
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Misc
*.tsbuildinfo
# Wrangler
.wrangler/
.dev.vars
gitbook/app/[lang]/[...slug]/page.js
+36
View File
@@ -0,0 +1,36 @@
import DocsLayout from "@/components/DocsLayout";
import DocsContent from "@/components/DocsContent";
import { extractHeadings } from "@/utils/markdown";
import { loadContent, getAllSlugs } from "@/lib/content";
import { LANG_CODES, isValidLang, DEFAULT_LANG } from "@/constants/languages";
import { notFound } from "next/navigation";
export const dynamicParams = false;
export async function generateStaticParams() {
// Build params for every (lang × slug) combination based on default language slugs.
const slugs = getAllSlugs(DEFAULT_LANG);
const params = [];
for (const lang of LANG_CODES) {
for (const slug of slugs) {
params.push({ lang, slug });
}
}
return params;
}
export default async function DocPage({ params }) {
const { lang, slug } = await params;
if (!isValidLang(lang)) notFound();
const content = loadContent(lang, slug);
if (!content) notFound();
const headings = extractHeadings(content);
return (
<DocsLayout headings={headings} lang={lang}>
<DocsContent content={content} />
</DocsLayout>
);
}
gitbook/app/[lang]/page.js
+26
View File
@@ -0,0 +1,26 @@
import DocsLayout from "@/components/DocsLayout";
import DocsContent from "@/components/DocsContent";
import { extractHeadings } from "@/utils/markdown";
import { loadContent } from "@/lib/content";
import { LANG_CODES, isValidLang } from "@/constants/languages";
import { notFound } from "next/navigation";
export const dynamicParams = false;
export async function generateStaticParams() {
return LANG_CODES.map(lang => ({ lang }));
}
export default async function LangHomePage({ params }) {
const { lang } = await params;
if (!isValidLang(lang)) notFound();
const content = loadContent(lang, "index") || "# 9Router Documentation\n\nContent coming soon...";
const headings = extractHeadings(content);
return (
<DocsLayout headings={headings} lang={lang}>
<DocsContent content={content} />
</DocsLayout>
);
}
gitbook/app/globals.css
+190
View File
@@ -0,0 +1,190 @@
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap');
@import "tailwindcss";
/* Base styles */
* {
box-sizing: border-box;
}
body {
font-family: 'Inter', system-ui, -apple-system, sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
margin: 0;
padding: 0;
}
/* Scrollbar */
::-webkit-scrollbar {
width: 8px;
height: 8px;
}
::-webkit-scrollbar-track {
background: transparent;
}
::-webkit-scrollbar-thumb {
background: #CBD5E1;
border-radius: 4px;
}
::-webkit-scrollbar-thumb:hover {
background: #E68A6E;
}
/* Code highlighting */
pre {
background: #F1F5F9 !important;
border-radius: 8px;
padding: 1rem;
overflow-x: auto;
}
code {
font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
font-size: 0.875rem;
line-height: 1.5;
}
/* Inline code */
:not(pre) > code {
background: #F1F5F9;
color: #E68A6E;
padding: 0.125rem 0.375rem;
border-radius: 4px;
font-size: 0.875em;
}
/* Markdown content styles */
.markdown-content h1 {
font-size: 2.5rem;
font-weight: 800;
color: #E68A6E;
/* margin-top: 2rem; */
margin-bottom: 1rem;
line-height: 1.2;
display: flex;
align-items: center;
}
.markdown-content h1 svg {
width: 2.5rem;
height: 2.5rem;
flex-shrink: 0;
}
.markdown-content h2 {
font-size: 2rem;
font-weight: 700;
color: #000000;
margin-top: 2rem;
margin-bottom: 1rem;
line-height: 1.3;
border-bottom: 1px solid #E5E7EB;
padding-bottom: 0.5rem;
}
.markdown-content h3 {
font-size: 1.5rem;
font-weight: 600;
color: #000000;
margin-top: 1.5rem;
margin-bottom: 0.75rem;
line-height: 1.4;
}
.markdown-content p {
font-size: 1.125rem;
line-height: 1.75;
margin-bottom: 1rem;
color: #6B7280;
}
.markdown-content ul,
.markdown-content ol {
margin-left: 1.5rem;
margin-bottom: 1rem;
}
.markdown-content li {
font-size: 1.125rem;
line-height: 1.75;
margin-bottom: 0.5rem;
color: #6B7280;
}
.markdown-content a {
color: #E68A6E;
text-decoration: underline;
transition: opacity 0.2s;
}
.markdown-content a:hover {
opacity: 0.8;
}
.markdown-content blockquote {
border-left: 4px solid #E68A6E;
padding-left: 1rem;
margin: 1rem 0;
font-style: italic;
color: #6B7280;
}
.markdown-content strong {
font-weight: 600;
color: #000000;
}
/* Smooth scroll */
html {
scroll-behavior: smooth;
scroll-padding-top: 5rem; /* Offset for sticky header (64px + padding) */
}
/* Heading anchor offset for sticky header */
.markdown-content h1,
.markdown-content h2,
.markdown-content h3 {
scroll-margin-top: 5rem;
}
/* Mobile menu overlay */
.mobile-menu-overlay {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.5);
z-index: 40;
animation: fadeIn 0.2s ease-out;
}
@keyframes fadeIn {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
.mobile-menu-drawer {
position: fixed;
top: 0;
left: 0;
bottom: 0;
width: 280px;
background: white;
z-index: 50;
animation: slideInLeft 0.3s ease-out;
overflow-y: auto;
}
@keyframes slideInLeft {
from {
transform: translateX(-100%);
}
to {
transform: translateX(0);
}
}
gitbook/app/layout.js
+21
View File
@@ -0,0 +1,21 @@
import { DOCS_CONFIG } from "@/constants/docsConfig";
import "./globals.css";
export const metadata = {
title: DOCS_CONFIG.title,
description: DOCS_CONFIG.description,
};
export default function RootLayout({ children }) {
return (
<html lang="en">
<head>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
</head>
<body className="bg-[#FCFBF9] text-[#6B7280]">
{children}
</body>
</html>
);
}
gitbook/app/page.js
+26
View File
@@ -0,0 +1,26 @@
import { DEFAULT_LANG } from "@/constants/languages";
// Static-friendly redirect to default language (meta refresh + client script)
export const metadata = {
title: "Redirecting...",
other: {
"http-equiv:refresh": `0; url=/${DEFAULT_LANG}/`
}
};
export default function HomePage() {
const target = `/${DEFAULT_LANG}/`;
return (
<>
<script
dangerouslySetInnerHTML={{
__html: `window.location.replace("${target}");`
}}
/>
<meta httpEquiv="refresh" content={`0; url=${target}`} />
<p style={{ padding: "2rem", textAlign: "center" }}>
Redirecting to <a href={target}>{target}</a>...
</p>
</>
);
}
gitbook/components/DocsContent.js
+13
View File
@@ -0,0 +1,13 @@
"use client";
import { MarkdownRenderer } from "@/utils/markdown";
export default function DocsContent({ content }) {
return (
<main className="flex-1 overflow-y-auto">
<article className="max-w-4xl mx-auto px-6 py-8">
<MarkdownRenderer content={content} />
</article>
</main>
);
}
gitbook/components/DocsHeader.js
+78
View File
@@ -0,0 +1,78 @@
"use client";
import { useState } from "react";
import Link from "next/link";
import { DOCS_CONFIG } from "@/constants/docsConfig";
import { DEFAULT_LANG } from "@/constants/languages";
import { ExternalLink, Menu, X } from "lucide-react";
import DocsSidebar from "./DocsSidebar";
import LanguageSwitcher from "./LanguageSwitcher";
export default function DocsHeader({ lang = DEFAULT_LANG }) {
const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
return (
<>
<header className="sticky top-0 z-50 w-full border-b bg-white/80 backdrop-blur-sm border-gray-200">
<div className=" mx-auto px-4 h-16 flex items-center justify-between">
{/* Mobile menu button */}
<button
onClick={() => setMobileMenuOpen(true)}
className="lg:hidden p-2 rounded-lg hover:bg-gray-100 transition-colors"
aria-label="Open menu"
>
<Menu className="w-6 h-6 text-gray-600" />
</button>
{/* Logo */}
<Link href={`/${lang}`} className="flex items-center gap-2 font-bold text-2xl text-black hover:opacity-80 transition-opacity">
<span>9</span>
<span className="text-[#E68A6E]">{DOCS_CONFIG.logo} Docs</span>
</Link>
{/* Right side */}
<div className="flex items-center gap-2 sm:gap-3">
<LanguageSwitcher currentLang={lang} />
{/* Go to App */}
<Link
href={DOCS_CONFIG.appUrl}
target="_blank"
rel="noopener noreferrer"
className="flex items-center gap-2 px-3 sm:px-4 py-2 bg-[#E68A6E] text-white rounded-lg font-medium hover:bg-[#d67a5e] transition-colors text-sm"
>
<span className="hidden sm:inline">Go to App</span>
<ExternalLink className="w-4 h-4" />
</Link>
</div>
</div>
</header>
{/* Mobile menu */}
{mobileMenuOpen && (
<>
<div
className="mobile-menu-overlay lg:hidden"
onClick={() => setMobileMenuOpen(false)}
/>
<div className="mobile-menu-drawer lg:hidden">
<div className="flex items-center justify-between p-4 border-b border-gray-200">
<span className="font-bold text-lg text-black">
<span className="text-[#E68A6E]">9</span>{DOCS_CONFIG.logo} Docs
</span>
<button
onClick={() => setMobileMenuOpen(false)}
className="p-2 rounded-lg hover:bg-gray-100 transition-colors"
aria-label="Close menu"
>
<X className="w-5 h-5 text-gray-600" />
</button>
</div>
<DocsSidebar isMobile onClose={() => setMobileMenuOpen(false)} lang={lang} />
</div>
</>
)}
</>
);
}
gitbook/components/DocsLayout.js
+25
View File
@@ -0,0 +1,25 @@
"use client";
import DocsHeader from "./DocsHeader";
import DocsSidebar from "./DocsSidebar";
import DocsToc from "./DocsToc";
import { DEFAULT_LANG } from "@/constants/languages";
export default function DocsLayout({ children, headings = [], lang = DEFAULT_LANG }) {
return (
<div className="min-h-screen flex flex-col bg-[#FCFBF9]">
<DocsHeader lang={lang} />
<div className="flex-1 flex">
{/* Desktop sidebar */}
<div className="hidden lg:block">
<DocsSidebar lang={lang} />
</div>
<div className="flex-1 flex">
{children}
<DocsToc headings={headings} />
</div>
</div>
</div>
);
}
gitbook/components/DocsSidebar.js
+122
View File
@@ -0,0 +1,122 @@
"use client";
import { useState } from "react";
import Link from "next/link";
import { usePathname } from "next/navigation";
import { DOCS_CONFIG } from "@/constants/docsConfig";
import { DEFAULT_LANG } from "@/constants/languages";
import { ChevronDown, ChevronRight, BookOpen, Rocket, Terminal, Monitor, FolderOpen, HelpCircle, MessageCircle, Layers, Plug, Cloud, Zap, Wallet, Gift, GitBranch, BarChart3, Code2, Sparkles, Server, Globe } from "lucide-react";
const SECTION_ICONS = {
"Getting Started": Rocket,
"Providers": Layers,
"Features": Zap,
"Integration": Plug,
"Deployment": Cloud,
"Help": HelpCircle
};
const ITEM_ICONS = {
"Introduction": BookOpen,
"Quick Start": Rocket,
"Installation": Terminal,
"Subscription (Maximize)": Sparkles,
"Cheap (Backup)": Wallet,
"Free (Fallback)": Gift,
"Smart Routing": GitBranch,
"Combos & Fallback": Layers,
"Quota Tracking": BarChart3,
"Claude Code": Code2,
"OpenAI Codex": Code2,
"Cursor": Code2,
"Cline": Code2,
"Roo": Code2,
"Continue": Code2,
"Other Tools": Plug,
"Localhost": Monitor,
"Cloud (VPS/Docker)": Server,
"Troubleshooting": HelpCircle,
"FAQ": MessageCircle
};
export default function DocsSidebar({ isMobile = false, onClose, lang = DEFAULT_LANG }) {
const pathname = usePathname();
const [openSections, setOpenSections] = useState(
DOCS_CONFIG.navigation.map((_, i) => i)
);
const toggleSection = (index) => {
setOpenSections(prev =>
prev.includes(index)
? prev.filter(i => i !== index)
: [...prev, index]
);
};
// Build URL for a navigation slug under current language
const buildHref = (slug) => (slug ? `/${lang}/${slug}` : `/${lang}`);
const isActive = (slug) => pathname === buildHref(slug);
const handleLinkClick = () => {
if (isMobile && onClose) {
onClose();
}
};
return (
<aside className={`${isMobile ? 'w-full' : 'w-64'} border-r bg-white border-gray-200 ${isMobile ? 'h-full' : 'h-[calc(100vh-4rem)] sticky top-16'} overflow-y-auto`}>
<nav className="p-4 space-y-6">
{DOCS_CONFIG.navigation.map((section, sectionIndex) => {
const SectionIcon = SECTION_ICONS[section.title] || BookOpen;
return (
<div key={sectionIndex}>
{/* Section title */}
<button
onClick={() => toggleSection(sectionIndex)}
className="flex items-center justify-between w-full text-sm font-semibold text-gray-900 mb-2 hover:text-[#E68A6E] transition-colors"
>
<span className="flex items-center gap-2">
<SectionIcon className="w-4 h-4" />
{section.title}
</span>
{openSections.includes(sectionIndex) ? (
<ChevronDown className="w-4 h-4" />
) : (
<ChevronRight className="w-4 h-4" />
)}
</button>
{/* Section items */}
{openSections.includes(sectionIndex) && (
<ul className="space-y-1">
{section.items.map((item, itemIndex) => {
const ItemIcon = ITEM_ICONS[item.title] || BookOpen;
return (
<li key={itemIndex}>
<Link
href={buildHref(item.slug)}
onClick={handleLinkClick}
className={`flex items-center gap-2 px-3 py-2 text-sm rounded-lg transition-colors ${
isActive(item.slug)
? "bg-[#E68A6E]/10 text-[#E68A6E] font-medium"
: "text-gray-600 hover:bg-gray-100 hover:text-gray-900"
}`}
>
<ItemIcon className="w-4 h-4" />
{item.title}
</Link>
</li>
);
})}
</ul>
)}
</div>
);
})}
</nav>
</aside>
);
}
gitbook/components/DocsToc.js
+59
View File
@@ -0,0 +1,59 @@
"use client";
import { useEffect, useState } from "react";
import { List } from "lucide-react";
export default function DocsToc({ headings }) {
const [activeId, setActiveId] = useState("");
useEffect(() => {
const observer = new IntersectionObserver(
(entries) => {
entries.forEach((entry) => {
if (entry.isIntersecting) {
setActiveId(entry.target.id);
}
});
},
{ rootMargin: "-80px 0px -80% 0px" }
);
headings.forEach(({ id }) => {
const element = document.getElementById(id);
if (element) observer.observe(element);
});
return () => observer.disconnect();
}, [headings]);
if (!headings || headings.length === 0) return null;
return (
<aside className="hidden xl:block w-64 border-l bg-white border-gray-200 h-[calc(100vh-4rem)] sticky top-16 overflow-y-auto">
<nav className="p-4">
<h3 className="flex items-center gap-2 text-sm font-semibold text-gray-900 mb-3">
<List className="w-4 h-4" />
On this page
</h3>
<ul className="space-y-2">
{headings.map((heading, idx) => (
<li key={`${heading.id}-${idx}`}>
<a
href={`#${heading.id}`}
className={`block text-sm transition-colors ${
heading.level === 3 ? "pl-4" : ""
} ${
activeId === heading.id
? "text-[#E68A6E] font-medium"
: "text-gray-600 hover:text-gray-900"
}`}
>
{heading.text}
</a>
</li>
))}
</ul>
</nav>
</aside>
);
}
gitbook/components/LanguageSwitcher.js
+96
View File
@@ -0,0 +1,96 @@
"use client";
import { useState, useEffect } from "react";
import { createPortal } from "react-dom";
import { useRouter, usePathname } from "next/navigation";
import { Globe, X } from "lucide-react";
import { LANGUAGES, getLanguage, DEFAULT_LANG } from "@/constants/languages";
function extractLangFromPath(pathname) {
const match = pathname.match(/^\/([^/]+)(?:\/(.*))?$/);
if (!match) return { lang: DEFAULT_LANG, rest: "" };
return { lang: match[1], rest: match[2] || "" };
}
export default function LanguageSwitcher({ currentLang }) {
const [open, setOpen] = useState(false);
const [mounted, setMounted] = useState(false);
const router = useRouter();
const pathname = usePathname();
const current = getLanguage(currentLang);
useEffect(() => {
setMounted(true);
}, []);
// Lock body scroll when modal is open
useEffect(() => {
if (open) {
document.body.style.overflow = "hidden";
return () => { document.body.style.overflow = ""; };
}
}, [open]);
const switchTo = (code) => {
const { rest } = extractLangFromPath(pathname);
const target = rest ? `/${code}/${rest}` : `/${code}`;
setOpen(false);
router.push(target);
};
const modal = open && (
<div className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/50 p-4" onClick={() => setOpen(false)}>
<div
className="bg-white rounded-xl shadow-2xl max-w-md w-full max-h-[80vh] overflow-hidden"
onClick={(e) => e.stopPropagation()}
>
<div className="flex items-center justify-between p-4 border-b border-gray-200">
<h2 className="font-bold text-lg text-gray-900">Select Language</h2>
<button
onClick={() => setOpen(false)}
className="p-1.5 rounded-lg hover:bg-gray-100 transition-colors"
aria-label="Close"
>
<X className="w-5 h-5 text-gray-600" />
</button>
</div>
<div className="p-2 overflow-y-auto max-h-[60vh]">
{LANGUAGES.map((lang) => (
<button
key={lang.code}
onClick={() => switchTo(lang.code)}
className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-lg text-left transition-colors ${
lang.code === currentLang
? "bg-[#E68A6E]/10 text-[#E68A6E] font-medium"
: "text-gray-700 hover:bg-gray-100"
}`}
>
<span className="text-2xl">{lang.flag}</span>
<div className="flex-1">
<div className="font-medium">{lang.native}</div>
<div className="text-xs text-gray-500">{lang.name}</div>
</div>
{lang.code === currentLang && <span className="text-xs">✓</span>}
</button>
))}
</div>
</div>
</div>
);
return (
<>
<button
onClick={() => setOpen(true)}
className="flex items-center gap-1.5 px-2.5 py-1.5 text-sm text-gray-700 bg-gray-100 rounded-lg hover:bg-gray-200 transition-colors"
aria-label="Switch language"
>
<Globe className="w-4 h-4" />
<span className="hidden sm:inline">{current.flag} {current.native}</span>
<span className="sm:hidden">{current.flag}</span>
</button>
{mounted && open && createPortal(modal, document.body)}
</>
);
}
gitbook/constants/docsConfig.js
+60
View File
@@ -0,0 +1,60 @@
export const DOCS_CONFIG = {
title: "9Router Documentation",
description: "Smart AI model router - Maximize subscriptions, minimize costs",
logo: "9Router",
appUrl: "https://9router.com",
githubUrl: "https://github.com/decolua/9router",
navigation: [
{
title: "Getting Started",
items: [
{ title: "Introduction", slug: "" },
{ title: "Quick Start", slug: "getting-started/quick-start" },
{ title: "Installation", slug: "getting-started/installation" }
]
},
{
title: "Providers",
items: [
{ title: "Subscription (Maximize)", slug: "providers/subscription" },
{ title: "Cheap (Backup)", slug: "providers/cheap" },
{ title: "Free (Fallback)", slug: "providers/free" }
]
},
{
title: "Features",
items: [
{ title: "Smart Routing", slug: "features/smart-routing" },
{ title: "Combos & Fallback", slug: "features/combos" },
{ title: "Quota Tracking", slug: "features/quota-tracking" }
]
},
{
title: "Integration",
items: [
{ title: "Claude Code", slug: "integration/claude-code" },
{ title: "OpenAI Codex", slug: "integration/codex" },
{ title: "Cursor", slug: "integration/cursor" },
{ title: "Cline", slug: "integration/cline" },
{ title: "Roo", slug: "integration/roo" },
{ title: "Continue", slug: "integration/continue" },
{ title: "Other Tools", slug: "integration/other-tools" }
]
},
{
title: "Deployment",
items: [
{ title: "Localhost", slug: "deployment/localhost" },
{ title: "Cloud (VPS/Docker)", slug: "deployment/cloud" }
]
},
{
title: "Help",
items: [
{ title: "Troubleshooting", slug: "troubleshooting" },
{ title: "FAQ", slug: "faq" }
]
}
]
};
gitbook/constants/languages.js
+19
View File
@@ -0,0 +1,19 @@
export const DEFAULT_LANG = "en";
export const LANGUAGES = [
{ code: "en", name: "English", native: "English", flag: "🇺🇸" },
{ code: "vi", name: "Vietnamese", native: "Tiếng Việt", flag: "🇻🇳" },
{ code: "zh-CN", name: "Chinese (Simplified)", native: "简体中文", flag: "🇨🇳" },
{ code: "es", name: "Spanish", native: "Español", flag: "🇪🇸" },
{ code: "ja", name: "Japanese", native: "日本語", flag: "🇯🇵" }
];
export const LANG_CODES = LANGUAGES.map(l => l.code);
export function isValidLang(code) {
return LANG_CODES.includes(code);
}
export function getLanguage(code) {
return LANGUAGES.find(l => l.code === code) || LANGUAGES[0];
}
gitbook/content/en/deployment/cloud.md
+473
View File
@@ -0,0 +1,473 @@
# ☁️ Cloud Deployment
Deploy 9Router on VPS or Docker for remote access and production use.
---
## 🖥️ VPS Deployment
### Prerequisites
- Ubuntu 20.04+ or similar Linux distribution
- Node.js 20+
- Git
- Root or sudo access
### Step 1: Clone Repository
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
```
### Step 2: Install Dependencies
```bash
npm install
```
### Step 3: Build Application
```bash
npm run build
```
### Step 4: Configure Environment Variables
Create a `.env` file or export variables:
```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"
```
**Environment Variables:**
| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | Auto-generated | **MUST change in production!** Used for JWT token signing |
| `INITIAL_PASSWORD` | `123456` | Dashboard login password |
| `DATA_DIR` | `~/.9router` | Database and data storage path |
| `NODE_ENV` | `development` | Set to `production` for deployment |
| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request/response logs |
### Step 5: Create Data Directory
```bash
sudo mkdir -p /var/lib/9router
sudo chown $USER:$USER /var/lib/9router
```
### Step 6: Start Application
```bash
npm run start
```
### Step 7: Setup PM2 for Production
PM2 keeps your application running and restarts it on crashes:
```bash
# Install PM2 globally
npm install -g pm2
# Start 9Router with PM2
pm2 start npm --name 9router -- start
# Save PM2 configuration
pm2 save
# Setup PM2 to start on system boot
pm2 startup
# Follow the instructions printed by the command above
```
**PM2 Management Commands:**
```bash
# View logs
pm2 logs 9router
# Restart application
pm2 restart 9router
# Stop application
pm2 stop 9router
# View status
pm2 status
# Monitor resources
pm2 monit
```
---
## 🐳 Docker Deployment
### Option 1: Using Dockerfile
Create a `Dockerfile` in the `app` directory:
```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"]
```
**Build and Run:**
```bash
# Build image
docker build -t 9router .
# Run container
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
```
### Option 2: Docker Compose
Create `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:
```
**Run with Docker Compose:**
```bash
# Start services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
# Rebuild and restart
docker-compose up -d --build
```
---
## 🌐 Reverse Proxy with Nginx
### Why Use Nginx?
- SSL/TLS termination
- Domain name mapping
- Load balancing
- Better security
### Step 1: Install Nginx
```bash
sudo apt update
sudo apt install nginx
```
### Step 2: Configure Nginx
Create `/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;
}
}
```
### Step 3: Enable Site
```bash
# Create symbolic link
sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
# Test configuration
sudo nginx -t
# Reload Nginx
sudo systemctl reload nginx
```
### Step 4: Setup SSL with Let's Encrypt
```bash
# Install certbot
sudo apt install certbot python3-certbot-nginx
# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com
# Auto-renewal is configured automatically
# Test renewal
sudo certbot renew --dry-run
```
---
## 🔒 Security Considerations
### 1. Change Default Credentials
**CRITICAL:** Change `JWT_SECRET` and `INITIAL_PASSWORD` before deployment:
```bash
# Generate secure JWT secret
openssl rand -base64 32
# Use this value for JWT_SECRET
export JWT_SECRET="generated-secret-here"
```
### 2. Firewall Configuration
```bash
# Allow SSH
sudo ufw allow 22/tcp
# Allow HTTP/HTTPS (if using Nginx)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# If NOT using reverse proxy, allow 9Router ports
sudo ufw allow 3000/tcp
sudo ufw allow 20128/tcp
# Enable firewall
sudo ufw enable
```
### 3. Restrict Dashboard Access
If you only need API access, restrict dashboard port:
```bash
# Only allow localhost access to dashboard
sudo ufw deny 3000/tcp
```
Access dashboard via SSH tunnel:
```bash
ssh -L 3000:localhost:3000 user@your-server.com
# Then open http://localhost:3000 in your browser
```
### 4. Regular Updates
```bash
# Update system packages
sudo apt update && sudo apt upgrade -y
# Update 9Router
cd /path/to/9router/app
git pull
npm install
npm run build
pm2 restart 9router
```
### 5. Backup Strategy
```bash
# Backup data directory
tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
# Automated daily backup (add to crontab)
0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
```
---
## 📊 Monitoring
### Check Application Status
```bash
# PM2 status
pm2 status
# View logs
pm2 logs 9router --lines 100
# Monitor resources
pm2 monit
```
### Nginx Logs
```bash
# Access logs
sudo tail -f /var/log/nginx/access.log
# Error logs
sudo tail -f /var/log/nginx/error.log
```
### System Resources
```bash
# CPU and memory usage
htop
# Disk usage
df -h
# Network connections
netstat -tulpn | grep -E '3000|20128'
```
---
## 🚨 Troubleshooting
### Application Won't Start
```bash
# Check logs
pm2 logs 9router
# Check if ports are in use
sudo lsof -i :3000
sudo lsof -i :20128
# Check environment variables
pm2 env 9router
```
### Nginx 502 Bad Gateway
```bash
# Check if 9Router is running
pm2 status
# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log
# Test Nginx configuration
sudo nginx -t
```
### SSE Streaming Not Working
Ensure `proxy_buffering off` is set in Nginx configuration for SSE support.
### Permission Denied Errors
```bash
# Fix data directory permissions
sudo chown -R $USER:$USER /var/lib/9router
chmod 755 /var/lib/9router
```
---
## 🔗 Next Steps
- [Connect Providers](/providers/subscription.md)
- [Setup Combos](/features/combos.md)
- [Integrate with Tools](/integration/cursor.md)
gitbook/content/en/deployment/localhost.md
+164
View File
@@ -0,0 +1,164 @@
# 🏠 Localhost Deployment
Run 9Router on your local machine for development and personal use.
---
## 📦 Installation
Install 9Router globally via npm:
```bash
npm install -g 9router
```
**Requirements:**
- Node.js 20 or higher
- npm 9 or higher
---
## 🚀 Starting the Server
Start 9Router with a single command:
```bash
9router
```
The dashboard will automatically open in your browser at `http://localhost:3000`
**Default Configuration:**
- **Dashboard**: `http://localhost:3000`
- **API Endpoint**: `http://localhost:20128/v1`
- **Data Directory**: `~/.9router`
---
## 🔧 Configuration
### Custom Data Directory
Set a custom data directory using environment variable:
```bash
DATA_DIR=/path/to/data 9router
```
### Custom Port
The API port (20128) and dashboard port (3000) are configured in the application. To change them, you'll need to modify the source code or use environment variables if supported.
---
## 🛑 Stopping the Server
Press `Ctrl+C` in the terminal where 9Router is running.
```bash
# In the terminal running 9router
^C # Press Ctrl+C
```
The server will gracefully shut down and save all data.
---
## 🔄 Restarting the Server
Simply run the start command again:
```bash
9router
```
All your configurations, API keys, and combos are preserved in the data directory.
---
## 📊 Updating 9Router
Update to the latest version:
```bash
npm update -g 9router
```
Check your current version:
```bash
npm list -g 9router
```
---
## 🔍 Troubleshooting
### Port Already in Use
If port 20128 or 3000 is already in use:
```bash
# Find process using the port (macOS/Linux)
lsof -i :20128
lsof -i :3000
# Kill the process
kill -9 <PID>
```
### Permission Errors
If you encounter permission errors during installation:
```bash
# Use sudo (not recommended)
sudo npm install -g 9router
# Or fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
### Data Directory Issues
If the data directory is not accessible:
```bash
# Check permissions
ls -la ~/.9router
# Fix permissions
chmod 755 ~/.9router
```
---
## 📁 Data Directory Structure
```
~/.9router/
├── db.json # Main database (providers, combos, settings)
├── logs/ # Application logs
└── cache/ # Temporary cache files
```
**Backup Your Data:**
```bash
# Backup
cp -r ~/.9router ~/.9router.backup
# Restore
cp -r ~/.9router.backup ~/.9router
```
---
## 🔗 Next Steps
- [Connect Providers](/providers/subscription.md)
- [Create Combos](/features/combos.md)
- [Integrate with CLI Tools](/integration/cursor.md)
gitbook/content/en/faq.md
+387
View File
@@ -0,0 +1,387 @@
# Frequently Asked Questions
Common questions about 9Router.
---
## What is 9Router?
**9Router is an AI model router that maximizes your subscription value and minimizes costs.**
It intelligently routes requests across multiple AI providers using a 3-tier fallback system:
1. **Subscription tier** - Maximize Claude Code, Codex, Gemini quotas you already pay for
2. **Cheap tier** - Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
3. **Free tier** - Emergency backup with unlimited free models
**Key benefits:**
- Never waste subscription quota
- Automatic fallback when quota exhausted
- Real-time quota tracking
- 90% cost savings vs direct API usage
---
## How does pricing work?
**9Router uses a 3-tier pricing strategy:**
### Tier 1: Subscription (Maximize First)
- **Claude Code** (Pro/Max): $20-100/month - 5-hour + weekly quota
- **OpenAI Codex** (Plus/Pro): $20-200/month - 5-hour + weekly quota
- **Gemini CLI**: FREE - 180K completions/month + 1K/day
- **GitHub Copilot**: $10-19/month - Monthly reset
- **Antigravity**: FREE - Similar to Gemini
**Goal:** Use every bit of quota before it resets!
### Tier 2: Cheap (Backup)
- **GLM-4.7**: $0.60/$2.20 per 1M tokens - Daily reset 10AM
- **MiniMax M2.1**: $0.20/$1.00 per 1M tokens - 5-hour rolling
- **Kimi K2**: $9/month flat (10M tokens)
**Goal:** 90% cheaper than ChatGPT API ($20/1M)!
### Tier 3: Free (Emergency)
- **iFlow**: 8 models FREE (Kimi K2, Qwen3, GLM, MiniMax...)
- **Qwen**: 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
- **Kiro**: 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
**Goal:** Zero cost fallback when everything else is quota-limited!
---
## Is 9Router free?
**Yes, 9Router itself is 100% free and open source.**
**Free tier providers available:**
- **Gemini CLI** - 180K completions/month (FREE Google account)
- **iFlow** - 8 models unlimited (FREE OAuth)
- **Qwen** - 3 models unlimited (FREE OAuth)
- **Kiro** - Claude Sonnet/Haiku (FREE AWS Builder ID)
**You can code for FREE forever using only free tier providers!**
**Optional paid providers:**
- Subscription services you may already have (Claude Code, Codex, Copilot)
- Ultra-cheap alternatives ($0.20-$0.60 per 1M tokens)
---
## Which providers are supported?
### Subscription Providers
- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
- **Gemini CLI** (FREE) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
### Cheap Providers
- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
- **MiniMax** - MiniMax M2.1
- **Kimi** (Moonshot AI) - Kimi Latest
- **OpenRouter** - Passthrough to any OpenRouter model
### Free Providers
- **iFlow** - 8 models (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
- **Qwen** - 3 models (Qwen3 Coder Plus/Flash, Vision)
- **Kiro** - 2 models (Claude Sonnet 4.5, Haiku 4.5)
**Total: 15+ providers, 50+ models**
See [providers documentation](providers/subscription.md) for details.
---
## Can I use multiple providers?
**Yes! This is 9Router's core feature.**
**Combos allow you to chain multiple providers with automatic fallback:**
```
Example combo: "premium-coding"
1. cc/claude-opus-4-5 (Subscription primary)
2. glm/glm-4.7 (Cheap backup)
3. if/kimi-k2 (Free emergency)
→ Auto-switches when quota exhausted
→ Never stops coding
→ Minimal extra cost
```
**How to create combos:**
```
Dashboard → Combos → Create New
→ Add models in priority order
→ Use combo name in CLI: "premium-coding"
```
**Benefits:**
- Zero downtime when quota runs out
- Automatic cost optimization
- Single model name for all tools
See [combos documentation](features/combos.md) for examples.
---
## How does quota tracking work?
**9Router tracks quota in real-time for all providers:**
**Features:**
- **Token consumption** - Input/output tokens per request
- **Reset countdown** - Time until quota refreshes
- **Usage stats** - Daily/weekly/monthly reports
- **Cost estimation** - Projected spending (paid tiers)
- **Quota alerts** - Notifications when quota low
**Quota types:**
- **5-hour rolling** - Claude Code, Codex, MiniMax
- **Daily reset** - Gemini CLI (1K/day), GLM (10AM)
- **Weekly reset** - Claude Code, Codex (additional quota)
- **Monthly reset** - Gemini CLI (180K), GitHub Copilot (1st)
**View quota:**
```
Dashboard → Providers → Quota Tracking
→ Real-time usage + reset countdown
```
See [quota tracking documentation](features/quota-tracking.md) for details.
---
## Does 9Router work with Cursor?
**Yes, but Cursor requires a cloud endpoint.**
**Problem:** Cursor IDE doesn't support localhost endpoints.
**Solution:** Use 9Router cloud deployment:
```
Cursor Settings → Models → Advanced:
OpenAI API Base URL: https://9router.com/v1
OpenAI API Key: [from dashboard]
Model: cc/claude-opus-4-5-20251101
```
**Alternative:** Self-host on VPS with public domain:
```bash
# Deploy to VPS
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install && npm run build
npm start
# Configure Nginx reverse proxy
# Point Cursor to: https://your-domain.com/v1
```
**Other CLI tools work with localhost:**
- Cline ✅
- Claude Desktop ✅
- Codex CLI ✅
- Continue ✅
- RooCode ✅
See [Cursor integration guide](integration/cursor.md) for details.
---
## Can I self-host 9Router?
**Yes! 9Router supports multiple deployment options:**
### Localhost (Default)
```bash
npm install -g 9router
9router
→ Dashboard: http://localhost:3000
→ API: http://localhost:20128/v1
```
### VPS/Cloud
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install && npm run build
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"
npm start
```
### Docker
```bash
docker build -t 9router .
docker run -d \
-p 3000:3000 \
-e JWT_SECRET="your-secret" \
-v 9router-data:/app/data \
9router
```
### Cloudflare Workers
```bash
cd 9router/app
npm run deploy:cloudflare
```
**Environment variables:**
- `JWT_SECRET` - **MUST change in production!**
- `DATA_DIR` - Database storage path (default: `~/.9router`)
- `INITIAL_PASSWORD` - Dashboard login (default: `123456`)
- `NODE_ENV` - Set to `production` for deploy
See [deployment guide](getting-started/installation.md#deployment) for details.
---
## Is my data secure?
**Yes, 9Router prioritizes security and privacy:**
**Local storage:**
- All data stored locally in `~/.9router` (or custom `DATA_DIR`)
- No data sent to 9Router servers
- OAuth tokens encrypted with JWT
**No telemetry:**
- No usage tracking
- No analytics
- No phone-home
**Open source:**
- Full source code available on GitHub
- Audit security yourself
- Community-reviewed
**Best practices:**
- Change `JWT_SECRET` in production
- Use strong `INITIAL_PASSWORD`
- Enable HTTPS for cloud deployments
- Rotate API keys regularly
**What 9Router stores:**
- Provider OAuth tokens (encrypted)
- API keys (encrypted)
- Usage statistics (local only)
- Combo configurations
**What 9Router does NOT store:**
- Your prompts or responses
- Code you generate
- Personal information
---
## How do I update 9Router?
**Update methods depend on installation type:**
### Global NPM Install
```bash
npm update -g 9router
```
### Local Install
```bash
cd 9router/app
git pull origin main
npm install
npm run build
npm start
```
### Docker
```bash
docker pull 9router:latest
docker stop 9router
docker rm 9router
docker run -d \
-p 3000:3000 \
-v 9router-data:/app/data \
9router:latest
```
**Check version:**
```bash
9router --version
```
**Breaking changes:**
- Check [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
- Backup `~/.9router` before major updates
- Review migration guides for major versions
---
## How can I contribute?
**We welcome contributions!**
### Ways to contribute:
1. **Report bugs:**
- [GitHub Issues](https://github.com/decolua/9router/issues)
- Include error logs, steps to reproduce
2. **Request features:**
- [GitHub Discussions](https://github.com/decolua/9router/discussions)
- Describe use case and benefits
3. **Submit code:**
```bash
# Fork repo
git clone https://github.com/YOUR_USERNAME/9router.git
cd 9router
# Create branch
git checkout -b feature/your-feature
# Make changes
npm install
npm run dev
# Test
npm test
# Commit and push
git add .
git commit -m "Add your feature"
git push origin feature/your-feature
# Create Pull Request on GitHub
```
4. **Improve docs:**
- Fix typos, add examples
- Translate to other languages
- Write tutorials
5. **Add providers:**
- Implement new provider adapters
- See `app/lib/providers/` for examples
**Contribution guidelines:**
- Follow existing code style
- Add tests for new features
- Update documentation
- Keep commits atomic and descriptive
See [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) for details.
---
## Need More Help?
- **Documentation:** [9router.com/docs](https://9router.com/docs)
- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
gitbook/content/en/features/combos.md
+537
View File
@@ -0,0 +1,537 @@
# Combos - Custom Fallback Chains
Create custom model combinations with automatic fallback. Combos let you define your own routing strategy based on cost, quality, and availability.
---
## What Are Combos?
Combos are **custom fallback chains** that you create in the dashboard. Instead of using a single model, you define a sequence of models that 9Router tries in order.
**Example:**
```
Combo name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101 (try first)
2. glm/glm-4.7 (if #1 quota exhausted)
3. minimax/MiniMax-M2.1 (if #2 quota exhausted)
```
**Usage in CLI:**
```
Model: premium-coding
```
9Router automatically tries each model in sequence until one succeeds.
---
## Why Use Combos?
### 1. Maximize Subscription Value
```
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
→ Use subscription first, cheap backup, free emergency
→ Get full value from subscriptions you already pay for
```
### 2. Minimize Costs
```
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
→ Start with cheapest paid option ($0.60/1M)
→ Fallback to even cheaper ($0.20/1M)
→ Emergency free tier
→ Total cost: ~$5-10/month vs $2000 on ChatGPT API
```
### 3. Ensure 24/7 Availability
```
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
→ Always include free tier at the end
→ Never run out of quota
→ Code anytime, anywhere
```
### 4. Optimize for Quality
```
cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
→ Best models first
→ Fallback to other premium models
→ Maintain high quality across fallback chain
```
---
## How to Create Combos
### Step 1: Open Dashboard
```
http://localhost:20128
→ Login with your password
```
### Step 2: Navigate to Combos
```
Dashboard → Combos → Create New Combo
```
### Step 3: Configure Combo
**Combo Name:**
```
premium-coding
```
**Description (optional):**
```
Subscription first, cheap backup, free emergency
```
**Select Models:**
```
1. cc/claude-opus-4-5-20251101
2. glm/glm-4.7
3. minimax/MiniMax-M2.1
```
**Drag to reorder** - Priority from top to bottom.
### Step 4: Save
```
Click "Save Combo"
→ Combo appears in model list
```
### Step 5: Use in CLI
```
Cursor/Cline/Any tool:
Model: premium-coding
```
---
## Example Combos
### Example 1: Premium Coding (Subscription → Cheap → Free)
**Goal**: Maximize subscription value, minimize extra costs.
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101
2. glm/glm-4.7
3. minimax/MiniMax-M2.1
```
**Usage:**
```
Cursor IDE:
Model: premium-coding
```
**Behavior:**
```
Morning (fresh quota):
Request → cc/claude-opus-4-5 ✅
Afternoon (Claude quota out):
Request → glm/glm-4.7 ✅ (auto switched)
Evening (GLM quota out):
Request → minimax/MiniMax-M2.1 ✅ (auto switched)
```
**Monthly cost (100M tokens):**
```
80M via Claude Code: $0 (subscription)
15M via GLM: $9
5M via MiniMax: $1
Total: $10 + your subscription
```
**Savings**: ~99% vs ChatGPT API ($2000).
---
### Example 2: Budget Combo (Cheap → Free)
**Goal**: Minimize costs, use free tier as backup.
```
Dashboard → Combos → Create New
Name: budget-combo
Models:
1. glm/glm-4.7
2. minimax/MiniMax-M2.1
3. if/kimi-k2-thinking
```
**Usage:**
```
Cline:
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
Model: budget-combo
```
**Behavior:**
```
Request → glm/glm-4.7
✅ Daily quota available → Use GLM ($0.60/1M)
❌ Quota exhausted → Try MiniMax ($0.20/1M)
❌ MiniMax quota out → Use iFlow (FREE)
```
**Monthly cost (100M tokens):**
```
70M via GLM: $42
20M via MiniMax: $4
10M via iFlow: $0
Total: $46 vs $2000 on ChatGPT API
```
**Savings**: 97%.
---
### Example 3: Free Combo (Zero Cost)
**Goal**: 100% free, no costs ever.
```
Dashboard → Combos → Create New
Name: free-combo
Models:
1. if/kimi-k2-thinking
2. qw/qwen3-coder-plus
3. kr/claude-sonnet-4.5
```
**Usage:**
```
Claude Desktop:
Model: free-combo
```
**Behavior:**
```
Request → if/kimi-k2-thinking
✅ Available → Use iFlow
❌ Error → Try Qwen
❌ Error → Try Kiro
```
**Monthly cost:**
```
100M tokens via free providers: $0
Total: $0 forever
```
**Use case**: Personal projects, learning, experimentation.
---
### Example 4: Quality First (Premium Models Only)
**Goal**: Best quality, no cheap fallback.
```
Dashboard → Combos → Create New
Name: quality-first
Models:
1. cc/claude-opus-4-5-20251101
2. cx/gpt-5.2-codex
3. gc/gemini-3-pro-preview
```
**Usage:**
```
Codex CLI:
export OPENAI_BASE_URL="http://localhost:20128"
Model: quality-first
```
**Behavior:**
```
Request → cc/claude-opus-4-5
❌ Quota out → cx/gpt-5.2-codex
❌ Quota out → gc/gemini-3-pro-preview
❌ All out → Return error (no cheap fallback)
```
**Use case**: Critical production code, complex refactoring.
---
### Example 5: Multi-Subscription (Maximize All)
**Goal**: Use all subscriptions before paying extra.
```
Dashboard → Combos → Create New
Name: multi-sub
Models:
1. gc/gemini-3-flash-preview (FREE 180K/month)
2. cc/claude-opus-4-5-20251101 (Pro subscription)
3. cx/gpt-5.2-codex (Plus subscription)
4. gh/gpt-5 (Copilot subscription)
5. glm/glm-4.7 (Cheap backup)
6. if/kimi-k2-thinking (Free emergency)
```
**Monthly cost (200M tokens):**
```
50M via Gemini CLI: $0 (free tier)
80M via Claude Code: $0 (subscription)
40M via Codex: $0 (subscription)
20M via Copilot: $0 (subscription)
8M via GLM: $4.80
2M via iFlow: $0
Total: $4.80 + existing subscriptions
```
**Result**: Use 190M tokens from subscriptions, only $4.80 extra.
---
### Example 6: Quota Reset Optimization
**Goal**: Distribute usage based on reset times.
```
Dashboard → Combos → Create New
Name: reset-optimized
Models:
1. cc/claude-opus-4-5 (5h reset, use morning)
2. gc/gemini-3-flash (1K/day, use afternoon)
3. glm/glm-4.7 (daily 10AM reset, use evening)
4. minimax/MiniMax-M2.1 (5h rolling, use night)
5. if/kimi-k2-thinking (unlimited, emergency)
```
**Daily routine:**
```
08:00 - 13:00: Claude Code (fresh 5h quota)
13:00 - 18:00: Gemini CLI (1K/day quota)
18:00 - 22:00: GLM (resets 10AM next day)
22:00 - 08:00: MiniMax (5h rolling) or iFlow
```
**Result**: Code 24/7 with minimal costs.
---
## Use Combos in CLI Tools
### Cursor IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from dashboard]
Model: premium-coding
```
### Claude Desktop
Edit `~/.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
```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: free-combo
```
### API Request
```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
}'
```
---
## Best Practices
### 1. Always Include Free Tier
```
✅ Good:
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
❌ Bad:
cc/claude-opus → glm/glm-4.7
(no free fallback, can run out of quota)
```
**Why**: Ensures 24/7 availability, never blocked by quota.
### 2. Order by Cost (Cheap to Expensive)
```
✅ Good:
glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
❌ Bad:
cc/claude-opus → glm/glm-4.7
(wastes subscription quota on simple tasks)
```
**Exception**: If you want to maximize subscription value, put subscription first.
### 3. Match Quality Requirements
```
For production code:
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
For quick tasks:
glm/glm-4.7 → if/kimi-k2-thinking
For experimentation:
if/kimi-k2-thinking → qw/qwen3-coder-plus
```
### 4. Consider Quota Reset Times
```
Morning combo (fresh quotas):
cc/claude-opus → cx/gpt-5.2-codex
Evening combo (quotas likely exhausted):
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
```
### 5. Create Multiple Combos for Different Use Cases
```
premium-coding: For complex tasks
budget-combo: For simple tasks
free-combo: For experimentation
quality-first: For production code
```
**Switch between combos** based on task requirements.
### 6. Monitor Combo Performance
```
Dashboard → Analytics → Combo Usage:
premium-coding:
80% via cc/claude-opus (good, using subscription)
15% via glm/glm-4.7 (acceptable backup)
5% via minimax (rare fallback)
```
**Optimize**: If too much fallback usage, increase primary quota or reorder models.
---
## Advanced Configuration
### Set Budget Limits per Combo
```
Dashboard → Combos → Edit → Budget:
Daily limit: $5
Monthly limit: $50
```
When limit reached, 9Router skips paid models and uses free tier only.
### Enable/Disable Models in Combo
```
Dashboard → Combos → Edit → Models:
✅ cc/claude-opus-4-5 (enabled)
❌ glm/glm-4.7 (temporarily disabled)
✅ if/kimi-k2-thinking (enabled)
```
**Use case**: Temporarily disable expensive models without deleting combo.
### Clone Existing Combo
```
Dashboard → Combos → Clone "premium-coding"
→ Creates copy with "-copy" suffix
→ Modify and save as new combo
```
**Use case**: Create variations for different scenarios.
---
## Troubleshooting
**Issue: Combo not appearing in model list**
**Solution:**
1. Refresh dashboard
2. Check combo is saved (green checkmark)
3. Restart CLI tool to refresh model list
**Issue: Combo always uses last model (free tier)**
**Solution:**
1. Check quota for primary models (Dashboard → Quota)
2. Verify API keys are valid (Dashboard → Providers)
3. Check budget limits not exceeded
**Issue: Combo costs more than expected**
**Solution:**
1. Dashboard → Analytics → Review combo usage
2. Check if primary models are quota-exhausted
3. Reorder models (put cheaper first)
4. Set budget limits
---
## Related
- [Smart Routing](./smart-routing.md) - How auto fallback works
- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
gitbook/content/en/features/quota-tracking.md
+687
View File
@@ -0,0 +1,687 @@
# Quota Tracking & Usage Monitoring
Track real-time token consumption, monitor quota limits, estimate costs, and get alerts before running out. Never waste subscription quota or exceed budget limits.
---
## Overview
9Router provides comprehensive quota tracking for all providers:
- **Real-time token consumption** - See tokens used per request
- **Quota limits & remaining** - Track usage vs limits
- **Reset countdown** - Know when quota refreshes
- **Cost estimation** - Calculate spending for paid tiers
- **Monthly reports** - Analyze usage patterns
- **Alerts & notifications** - Get warned before limits
---
## Dashboard Overview
### Quota Summary
```
Dashboard → Home → Quota Overview
┌─────────────────────────────────────────────┐
│ Claude Code (cc/) │
│ ████████████░░░░░░░░ 2.5h / 5h (50%) │
│ Resets in: 2h 30m │
│ Cost: $0 (subscription) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Gemini CLI (gc/) │
│ ████████░░░░░░░░░░░░ 450 / 1000 (45%) │
│ Daily reset in: 18h 30m │
│ Monthly: 45K / 180K (25%) │
│ Cost: $0 (free tier) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ GLM-4.7 (glm/) │
│ ██████████████░░░░░░ 7M / 10M tokens (70%) │
│ Resets: Daily 10:00 AM (in 5h 35m) │
│ Cost today: $4.20 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ MiniMax M2.1 (minimax/) │
│ ████████████████░░░░ 4M / 5M tokens (80%) │
│ Rolling 5h window │
│ Cost (5h): $0.80 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ iFlow (if/) │
│ ████████████████████ Unlimited │
│ Cost: $0 (free forever) │
└─────────────────────────────────────────────┘
```
---
## Real-Time Token Consumption
### Per-Request Tracking
Every request shows detailed token usage:
```
Dashboard → Activity → Recent Requests
Request #1234
Model: cc/claude-opus-4-5-20251101
Timestamp: 2026-02-04 04:15:32
Tokens:
Input: 1,250 tokens
Output: 850 tokens
Total: 2,100 tokens
Cost: $0 (subscription quota)
Duration: 3.2s
Status: ✅ Success
```
### Live Usage Monitor
```
Dashboard → Live Monitor
Current request:
Model: glm/glm-4.7
Tokens streamed: 450 / ~800 estimated
Cost so far: $0.0009
Duration: 1.8s
```
### Token Breakdown by Model
```
Dashboard → Analytics → Token Usage
Today (Feb 4, 2026):
cc/claude-opus-4-5: 15M tokens ($0, subscription)
glm/glm-4.7: 8M tokens ($4.80)
if/kimi-k2-thinking: 3M tokens ($0, free)
Total: 26M tokens
Cost: $4.80
```
---
## Quota Limits & Reset Times
### Subscription Providers
**Claude Code (Pro/Max)**
```
Quota type: Time-based (5-hour rolling)
Limit: 5 hours of usage
Reset: Rolling 5-hour window + Weekly refresh
Tracking: Usage time per model
Dashboard shows:
Opus: 2.5h / 5h used
Sonnet: 1.2h / 5h used
Haiku: 0.8h / 5h used
Weekly reset: Every Monday 00:00 UTC
```
**OpenAI Codex (Plus/Pro)**
```
Quota type: Time-based (5-hour rolling)
Limit: 5 hours (Plus) / 10 hours (Pro)
Reset: Rolling 5-hour window + Weekly refresh
Dashboard shows:
GPT-5.2 Codex: 3.5h / 5h used
Resets in: 1h 30m
```
**Gemini CLI (FREE)**
```
Quota type: Request count + Monthly tokens
Daily limit: 1,000 requests
Monthly limit: 180,000 completions
Reset: Daily 00:00 UTC + Monthly 1st
Dashboard shows:
Today: 450 / 1,000 requests (45%)
This month: 45K / 180K completions (25%)
Daily reset in: 18h 30m
Monthly reset in: 26 days
```
**GitHub Copilot**
```
Quota type: Monthly usage
Limit: Varies by plan
Reset: 1st of each month
Dashboard shows:
Usage: 60% of monthly quota
Resets: March 1, 2026 (in 25 days)
```
### Cheap Providers
**GLM-4.7**
```
Quota type: Daily token limit
Limit: 10M tokens/day (Coding Plan)
Reset: Daily 10:00 AM Beijing Time (UTC+8)
Dashboard shows:
Used: 7M / 10M tokens (70%)
Remaining: 3M tokens
Resets in: 5h 35m
Cost today: $4.20
```
**MiniMax M2.1**
```
Quota type: Rolling 5-hour window
Limit: 5M tokens per 5 hours
Reset: Continuous rolling window
Dashboard shows:
Used (5h): 4M / 5M tokens (80%)
Oldest usage expires in: 45m
Cost (5h): $0.80
```
**Kimi K2**
```
Quota type: Monthly subscription
Limit: 10M tokens/month ($9 flat)
Reset: Monthly on subscription date
Dashboard shows:
Used: 6M / 10M tokens (60%)
Resets: Feb 15, 2026 (in 11 days)
Cost: $9/month (prepaid)
```
### Free Providers
**iFlow / Qwen / Kiro**
```
Quota type: Unlimited (rate-limited)
Limit: No hard limit
Reset: N/A
Dashboard shows:
Used today: 5M tokens
Cost: $0 (free forever)
Status: ✅ Available
```
---
## Cost Estimation
### Real-Time Cost Tracking
```
Dashboard → Costs → Today
Subscription providers: $0
Claude Code: 15M tokens ($0, included)
Gemini CLI: 3M tokens ($0, free tier)
Paid providers: $4.80
GLM-4.7: 8M tokens ($4.80)
Input: 6M × $0.60/1M = $3.60
Output: 2M × $2.20/1M = $4.40
Total: $4.80
Free providers: $0
iFlow: 3M tokens ($0)
Total today: $4.80
```
### Monthly Spending Report
```
Dashboard → Costs → This Month (February 2026)
Week 1 (Feb 1-7):
Subscription: $0 (80M tokens)
Paid: $15.20 (25M tokens)
Free: $0 (10M tokens)
Total: $15.20
Week 2 (Feb 8-14):
Subscription: $0 (75M tokens)
Paid: $12.80 (20M tokens)
Free: $0 (8M tokens)
Total: $12.80
Month to date: $28.00
Projected (30 days): ~$120
Breakdown by provider:
GLM-4.7: $22.00 (78%)
MiniMax M2.1: $6.00 (22%)
Average cost per 1M tokens: $0.62
Savings vs ChatGPT API: 97% ($4,000 → $120)
```
### Cost Projection
```
Dashboard → Costs → Projections
Based on last 7 days usage:
Daily average: 50M tokens
Daily cost: $4.50
Monthly projection:
Tokens: 1,500M (1.5B)
Cost: $135
Breakdown:
Subscription: 900M tokens ($0)
GLM-4.7: 450M tokens ($90)
MiniMax: 120M tokens ($24)
Free: 30M tokens ($0)
Budget status:
Daily limit: $5 → 90% used today
Monthly limit: $150 → 90% projected
⚠️ Warning: May exceed monthly budget
```
---
## Usage Dashboard
### Overview Stats
```
Dashboard → Analytics → Overview
Today (Feb 4, 2026):
Requests: 1,234
Tokens: 26M
Cost: $4.80
Avg response time: 2.1s
This week:
Requests: 8,456
Tokens: 180M
Cost: $28.00
Success rate: 99.2%
This month:
Requests: 15,234
Tokens: 320M
Cost: $52.00
Top model: cc/claude-opus-4-5 (45%)
```
### Usage by Model
```
Dashboard → Analytics → Models
Top models (this month):
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%)
Cost breakdown:
cc/claude-opus: $0 (subscription)
glm/glm-4.7: $45.00
if/kimi-k2-thinking: $0 (free)
minimax/MiniMax-M2.1: $7.00
gc/gemini-3-flash: $0 (free)
```
### Usage by Time
```
Dashboard → Analytics → Timeline
Hourly usage (today):
00:00 - 01:00: 0.5M tokens
01:00 - 02:00: 0.2M tokens
...
08:00 - 09:00: 3.2M tokens (peak)
09:00 - 10:00: 2.8M tokens
...
23:00 - 00:00: 0.8M tokens
Peak hours: 08:00 - 12:00 (morning coding)
Low hours: 00:00 - 06:00 (night)
```
### Usage by Combo
```
Dashboard → Analytics → Combos
premium-coding:
Requests: 456
Tokens: 12M
Cost: $2.40
Breakdown:
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:
Requests: 234
Tokens: 6M
Cost: $1.20
Breakdown:
glm/glm-4.7: 4M tokens (67%, $2.40)
if/kimi-k2-thinking: 2M tokens (33%, $0)
```
---
## Alerts & Notifications
### Quota Alerts
```
Dashboard → Settings → Alerts
Quota warnings:
✅ Alert at 80% quota used
✅ Alert at 90% quota used
✅ Alert when quota exhausted
✅ Notify when quota resets
Delivery:
✅ Dashboard notification
✅ Email (optional)
✅ Webhook (optional)
```
**Example notifications:**
```
⚠️ Claude Code quota 80% used
2.5h remaining (resets in 1h 30m)
⚠️ GLM-4.7 quota 90% used
1M tokens remaining (resets in 5h)
✅ Gemini CLI quota reset
1,000 requests available (daily limit)
```
### Budget Alerts
```
Dashboard → Settings → Budget Alerts
Daily budget: $5
✅ Alert at 80% ($4)
✅ Alert at 100% ($5)
✅ Auto-switch to free tier when exceeded
Monthly budget: $150
✅ Alert at 50% ($75)
✅ Alert at 80% ($120)
✅ Alert at 100% ($150)
```
**Example notifications:**
```
⚠️ Daily budget 80% used
$4.00 / $5.00 spent today
⚠️ Monthly budget 50% reached
$75 / $150 spent this month
Projected: $135 (within budget)
🚨 Daily budget exceeded
$5.20 / $5.00 spent today
Auto-switched to free tier
```
### Cost Anomaly Detection
```
Dashboard → Settings → Anomaly Detection
✅ Detect unusual spending patterns
✅ Alert on cost spikes (>2× daily average)
✅ Warn on quota exhaustion patterns
Example alert:
⚠️ Cost spike detected
Today: $12.50 (2.5× daily average)
Reason: High GLM-4.7 usage (20M tokens)
Suggestion: Check if primary models quota-exhausted
```
---
## Best Practices
### 1. Monitor Quota Daily
```
Daily routine:
1. Check dashboard quota overview (30 seconds)
2. Review reset times
3. Plan usage around quota availability
```
**Example:**
```
Morning check:
✅ Claude Code: 5h available (fresh reset)
✅ Gemini CLI: 1K requests available
⚠️ GLM-4.7: 2M tokens left (resets 10AM)
Action: Use Claude Code for morning work
```
### 2. Set Budget Limits
```
Dashboard → Settings → Budget:
Daily: $5 (prevents overspending)
Monthly: $150 (aligns with budget)
```
**Result**: Auto-switch to free tier when limit reached.
### 3. Optimize Combo Usage
```
Dashboard → Analytics → Combos:
Review which models are used most
Adjust combo order to minimize costs
```
**Example:**
```
Current: cc/claude-opus → glm/glm-4.7
80% via Claude (good)
20% via GLM ($12/month)
Optimized: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
50% via Gemini (free)
40% via Claude (subscription)
10% via GLM ($6/month)
Savings: $6/month
```
### 4. Track Reset Times
```
Dashboard → Quota → Reset Schedule:
Claude Code: 5h rolling + Weekly Monday
Gemini CLI: Daily 00:00 UTC + Monthly 1st
GLM-4.7: Daily 10:00 AM Beijing Time
MiniMax: Rolling 5h window
```
**Strategy**: Use providers when quota is fresh.
### 5. Review Monthly Reports
```
Dashboard → Analytics → Monthly Report:
Total tokens: 1.5B
Total cost: $120
Savings: 97% vs ChatGPT API
Insights:
- 60% usage via subscriptions ($0)
- 30% via GLM ($90)
- 10% via free tier ($0)
Optimization:
- Increase Gemini CLI usage (free)
- Reduce GLM usage (expensive)
```
---
## API Access
### Get Quota Status
```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"
}
}
]
}
```
### Get Usage Stats
```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
}
]
}
```
---
## Troubleshooting
**Issue: Quota shows 0% but requests failing**
**Solution:**
1. Check provider connection (Dashboard → Providers)
2. Verify API keys are valid
3. Check if provider is down (status page)
4. Try reconnecting OAuth providers
**Issue: Cost estimation incorrect**
**Solution:**
1. Dashboard → Settings → Pricing
2. Verify pricing per provider matches current rates
3. Update pricing if provider changed rates
4. Contact support if discrepancy persists
**Issue: Reset time not updating**
**Solution:**
1. Refresh dashboard (F5)
2. Check system time is correct
3. Verify timezone settings
4. Restart 9Router if issue persists
**Issue: Alerts not received**
**Solution:**
1. Dashboard → Settings → Alerts
2. Verify email address is correct
3. Check spam folder
4. Test notification (Send Test button)
---
## Related
- [Smart Routing](./smart-routing.md) - Auto fallback based on quota
- [Combos](./combos.md) - Create custom fallback chains
gitbook/content/en/features/smart-routing.md
+407
View File
@@ -0,0 +1,407 @@
# Smart Routing & Auto Fallback
9Router automatically routes your requests through the best available provider using a 3-tier fallback system. Never stop coding due to quota limits or rate limiting.
---
## How It Works
9Router uses intelligent routing to maximize your existing subscriptions, minimize costs, and ensure 24/7 availability:
```
Request → 9Router → Check Tier 1 (Subscription)
↓ quota exhausted
Check Tier 2 (Cheap)
↓ budget limit
Check Tier 3 (Free)
↓
Response
```
### 3-Tier Fallback System
**Tier 1: SUBSCRIPTION (Primary)**
- Claude Code (Pro/Max)
- OpenAI Codex (Plus/Pro)
- Gemini CLI (FREE 180K/month)
- GitHub Copilot
- Antigravity (Google)
**Goal**: Maximize value from subscriptions you already pay for.
**Tier 2: CHEAP (Backup)**
- GLM-4.7 ($0.60/1M input)
- MiniMax M2.1 ($0.20/1M input)
- Kimi K2 ($9/month flat)
**Goal**: Ultra-cheap backup when subscription quota runs out (~90% cheaper than ChatGPT API).
**Tier 3: FREE (Emergency)**
- iFlow (8 models)
- Qwen (3 models)
- Kiro (Claude FREE)
**Goal**: Zero-cost fallback for unlimited coding.
---
## Automatic Switching
9Router monitors quota in real-time and switches providers automatically:
### Scenario 1: Subscription Quota Exhausted
```
User request → cc/claude-opus-4-5
↓ quota exhausted (5-hour limit reached)
Auto switch → glm/glm-4.7
↓ daily quota exhausted
Auto switch → minimax/MiniMax-M2.1
↓ 5-hour quota exhausted
Auto switch → if/kimi-k2-thinking (FREE)
↓
Response delivered ✅
```
**Result**: Zero downtime, seamless experience.
### Scenario 2: Rate Limiting
```
User request → cx/gpt-5.2-codex
↓ rate limited (too many requests)
Auto switch → glm/glm-4.7
↓
Response delivered ✅
```
### Scenario 3: Provider Unavailable
```
User request → cc/claude-opus-4-5
↓ provider error (503)
Auto switch → next available model
↓
Response delivered ✅
```
---
## Model Selection Logic
9Router selects the best model based on:
1. **Quota availability** - Check if provider has remaining quota
2. **Cost tier** - Prefer subscription → cheap → free
3. **Reset timing** - Consider when quota resets
4. **Provider health** - Skip providers with errors
### Priority Order Example
For a request to `cc/claude-opus-4-5`:
```
1. Check Claude Code quota
✅ Available → Use cc/claude-opus-4-5
❌ Exhausted → Continue to step 2
2. Check fallback tier (if configured)
✅ GLM quota available → Use glm/glm-4.7
❌ Exhausted → Continue to step 3
3. Check free tier
✅ iFlow available → Use if/kimi-k2-thinking
❌ All exhausted → Return quota error
```
---
## Configuration Options
### Dashboard Settings
**1. Enable/Disable Auto Fallback**
```
Dashboard → Settings → Smart Routing
→ Toggle "Auto Fallback" ON/OFF
```
- **ON** (default): Automatic tier switching
- **OFF**: Strict mode, return error if primary model unavailable
**2. Set Budget Limits**
```
Dashboard → Settings → Budget Control
→ Daily limit: $5
→ Monthly limit: $50
```
When budget reached, 9Router automatically switches to free tier.
**3. Configure Fallback Order**
```
Dashboard → Settings → Fallback Priority
→ Drag to reorder providers within each tier
```
Example custom order:
```
Tier 1: Gemini CLI → Claude Code → Codex
Tier 2: MiniMax → GLM → Kimi
Tier 3: iFlow → Kiro → Qwen
```
**4. Quota Reset Notifications**
```
Dashboard → Settings → Notifications
→ Email when quota resets
→ Alert when 80% quota used
```
---
## Examples
### Example 1: Basic Auto Fallback
**Setup:**
```
Model: cc/claude-opus-4-5-20251101
Fallback: Auto (default 3-tier)
```
**Behavior:**
```
Morning (fresh quota):
Request → cc/claude-opus-4-5 ✅
Afternoon (quota exhausted):
Request → glm/glm-4.7 ✅ (auto switched)
Evening (GLM quota out):
Request → minimax/MiniMax-M2.1 ✅ (auto switched)
Late night (all paid quota out):
Request → if/kimi-k2-thinking ✅ (free tier)
```
**Cost**: ~$5-10/month extra (mostly covered by subscription).
### Example 2: Budget-Conscious Routing
**Setup:**
```
Dashboard → Settings:
Daily budget: $2
Monthly budget: $20
Fallback: Enabled
```
**Behavior:**
```
Day 1-15 (within budget):
Requests → glm/glm-4.7 (cheap tier)
Cost: $1.50/day
Day 16 (budget reached):
Requests → if/kimi-k2-thinking (free tier)
Cost: $0
Next month (budget resets):
Requests → glm/glm-4.7 again
```
**Result**: Never exceed $20/month, always available.
### Example 3: Subscription-Only Mode
**Setup:**
```
Dashboard → Settings:
Auto Fallback: OFF
Strict mode: ON
```
**Behavior:**
```
Request → cc/claude-opus-4-5
✅ Quota available → Success
❌ Quota exhausted → Return error (no fallback)
```
**Use case**: When you only want to use paid subscriptions, no extra costs.
### Example 4: Free-Only Mode
**Setup:**
```
Model: if/kimi-k2-thinking
Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
```
**Behavior:**
```
All requests → Free tier only
Cost: $0 forever
```
**Use case**: Personal projects, learning, experimentation.
---
## Best Practices
### 1. Maximize Subscription Value
```
Strategy:
- Set subscription models as Tier 1
- Monitor quota usage in dashboard
- Use cheap tier only when subscription exhausted
```
**Example combo:**
```
cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
```
### 2. Optimize for Cost
```
Strategy:
- Use Gemini CLI free tier first (180K/month)
- Fallback to GLM/MiniMax (ultra-cheap)
- Emergency: iFlow (free)
```
**Example combo:**
```
gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
```
### 3. Optimize for Quality
```
Strategy:
- Use best models (Claude Opus, GPT-5.2)
- Fallback to good cheap models (GLM-4.7)
- Last resort: Free tier
```
**Example combo:**
```
cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
```
### 4. 24/7 Availability
```
Strategy:
- Always include free tier in fallback
- Monitor quota reset times
- Distribute usage across providers
```
**Example combo:**
```
cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
```
**Result**: Never run out of quota, code anytime.
---
## Quota Reset Strategy
Plan your usage around quota reset times:
| Provider | Quota Reset | Strategy |
|----------|-------------|----------|
| **Claude Code** | 5-hour + weekly | Use in morning, fresh quota |
| **Codex** | 5-hour + weekly | Use after Claude quota out |
| **Gemini CLI** | Daily (1K) + Monthly (180K) | Use throughout day |
| **GLM-4.7** | Daily 10:00 AM | Use evening, resets next morning |
| **MiniMax M2.1** | 5-hour rolling | Use anytime, tracks rolling window |
| **iFlow/Qwen/Kiro** | No limit | Emergency backup |
**Daily routine example:**
```
08:00 - 13:00: Claude Code (fresh 5h quota)
13:00 - 18:00: Gemini CLI (1K/day quota)
18:00 - 22:00: GLM-4.7 (cheap, resets 10AM)
22:00 - 08:00: MiniMax or iFlow (5h rolling or free)
```
---
## Monitoring & Alerts
### Dashboard Quota Tracker
```
Dashboard → Quota Overview:
Claude Code: 2.5h / 5h remaining (50%)
Gemini CLI: 450 / 1000 requests today
GLM-4.7: 5M / 10M tokens (resets in 8h)
MiniMax: 3M / 5M tokens (rolling 5h)
```
### Real-Time Notifications
```
Dashboard → Notifications:
⚠️ Claude Code quota 80% used (1h remaining)
✅ GLM-4.7 quota reset (10M tokens available)
💰 Daily budget 50% used ($2.50 / $5)
```
### Usage Analytics
```
Dashboard → Analytics:
Today: 50M tokens
- 30M via Claude Code (subscription)
- 15M via GLM-4.7 ($9)
- 5M via iFlow (free)
Cost: $9 (vs $1000 on ChatGPT API)
Savings: 99%
```
---
## Troubleshooting
**Issue: "All providers quota exhausted"**
**Solution:**
1. Check dashboard quota tracker
2. Wait for quota reset (see countdown)
3. Add free tier to fallback chain
4. Or increase budget limit
**Issue: "Too many fallback switches"**
**Solution:**
1. Check if primary provider is down
2. Increase quota limits (upgrade subscription)
3. Use cheaper primary model (GLM instead of Claude)
**Issue: "Unexpected costs"**
**Solution:**
1. Dashboard → Analytics → Review usage
2. Set daily/monthly budget limits
3. Switch to free tier for non-critical tasks
4. Use combos with free fallback
---
## Related
- [Combos](./combos.md) - Create custom fallback chains
- [Quota Tracking](./quota-tracking.md) - Monitor usage and costs
gitbook/content/en/getting-started/installation.md
+478
View File
@@ -0,0 +1,478 @@
# Installation
Detailed installation guide for 9Router with troubleshooting tips.
---
## Requirements
### System Requirements
- **Node.js**: Version 20.0.0 or higher
- **npm**: Version 10.0.0 or higher (comes with Node.js)
- **OS**: macOS, Linux, Windows (WSL recommended)
- **Disk Space**: ~200MB for installation
### Check Your Version
```bash
node --version
# Should show v20.x.x or higher
npm --version
# Should show 10.x.x or higher
```
**Don't have Node.js?** Install from [nodejs.org](https://nodejs.org/)
---
## Installation Methods
### Method 1: Global Installation (Recommended)
Install 9Router globally to use from anywhere:
```bash
npm install -g 9router
```
**Start 9Router:**
```bash
9router
```
**Benefits:**
- ✅ Run from any directory
- ✅ Simple command: `9router`
- ✅ Auto-updates with `npm update -g 9router`
### Method 2: Local Installation
Install in a specific project:
```bash
mkdir my-9router
cd my-9router
npm install 9router
```
**Start 9Router:**
```bash
npx 9router
```
**Benefits:**
- ✅ Isolated per project
- ✅ Version control per project
- ✅ No global namespace pollution
### Method 3: From Source (Development)
Clone and build from GitHub:
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install
npm run build
npm start
```
**Benefits:**
- ✅ Latest development features
- ✅ Contribute to development
- ✅ Custom modifications
---
## First Run
### Start the Server
```bash
9router
```
**What happens:**
1. Server starts on `http://localhost:20128`
2. Dashboard opens automatically in browser
3. Data directory created at `~/.9router`
4. API key generated automatically
### Dashboard Login
**Default credentials:**
- Password: `123456`
**⚠️ Change password immediately:**
1. Login to dashboard
2. Settings → Change Password
3. Use strong password
### Get Your API Key
```
Dashboard → Settings → API Keys
→ Copy your API key
→ Use in CLI tools
```
**Example API key format:**
```
9r_1234567890abcdef1234567890abcdef
```
---
## Verify Installation
### Check Server Status
```bash
curl http://localhost:20128/health
```
**Expected response:**
```json
{
"status": "ok",
"version": "1.0.0"
}
```
### List Available Models
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer your-api-key"
```
**Expected response:**
```json
{
"object": "list",
"data": [
{
"id": "cc/claude-opus-4-5-20251101",
"object": "model",
"created": 1234567890,
"owned_by": "claude-code"
}
]
}
```
### Test 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!"}
]
}'
```
---
## Configuration
### Environment Variables
Create `.env` file or set environment variables:
```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"
```
### Data Directory
**Default location:** `~/.9router`
**Contents:**
```
~/.9router/
├── db.json # Database (providers, combos, usage)
├── api-keys.json # API keys
└── logs/ # Request logs (if enabled)
```
**Change location:**
```bash
export DATA_DIR="/custom/path"
9router
```
### Port Configuration
**Default port:** `20128`
**Change port:**
```bash
export PORT="3000"
9router
```
**Or use command line:**
```bash
9router --port 3000
```
---
## Troubleshooting
### Port Already in Use
**Error:**
```
Error: listen EADDRINUSE: address already in use :::20128
```
**Solution 1: Kill existing process**
```bash
# Find process using port 20128
lsof -i :20128
# Kill process
kill -9 <PID>
```
**Solution 2: Use different port**
```bash
9router --port 3000
```
### Permission Denied
**Error:**
```
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
```
**Solution: Use sudo (not recommended) or fix npm permissions**
```bash
# Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Then install again
npm install -g 9router
```
### Node.js Version Too Old
**Error:**
```
Error: The engine "node" is incompatible with this module
```
**Solution: Update Node.js**
```bash
# Using nvm (recommended)
nvm install 20
nvm use 20
# Or download from nodejs.org
```
### Dashboard Not Opening
**Issue:** Dashboard doesn't open automatically
**Solution 1: Open manually**
```
http://localhost:20128
```
**Solution 2: Check firewall**
```bash
# macOS: Allow Node.js in System Preferences → Security
# Linux: Check iptables
# Windows: Check Windows Firewall
```
### Cannot Connect to Providers
**Issue:** OAuth login fails or API key invalid
**Solution 1: Check internet connection**
```bash
ping google.com
```
**Solution 2: Check provider status**
- Claude Code: [status.anthropic.com](https://status.anthropic.com)
- OpenAI: [status.openai.com](https://status.openai.com)
- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
**Solution 3: Regenerate API key**
```
Dashboard → Provider → Disconnect → Reconnect
```
### High Memory Usage
**Issue:** 9Router using too much RAM
**Solution: Restart server**
```bash
# Stop
pkill -f 9router
# Start
9router
```
**Or use PM2 for auto-restart:**
```bash
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
```
---
## Deployment Options
### Local Development
```bash
npm install -g 9router
9router
```
**Use case:** Personal coding, testing
### VPS/Cloud Server
```bash
# Install
npm install -g 9router
# Configure
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"
# Start with PM2
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
pm2 startup
```
**Use case:** Team access, remote coding
### 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
```
**Use case:** Containerized deployment, Kubernetes
### Reverse Proxy (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;
}
}
```
**Use case:** HTTPS, custom domain, load balancing
---
## Uninstallation
### Remove Global Installation
```bash
npm uninstall -g 9router
```
### Remove Data Directory
```bash
rm -rf ~/.9router
```
### Remove Configuration
```bash
# Remove environment variables from shell config
nano ~/.bashrc # or ~/.zshrc
# Delete 9router-related exports
```
---
## Next Steps
- [Getting Started Guide](../getting-started.md) - Connect providers and start coding
- [Features](../features/) - Explore quota tracking, combos, deployment
- [Troubleshooting](../troubleshooting.md) - Fix common issues
---
## Need Help?
- **Website**: [9router.com](https://9router.com)
- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
gitbook/content/en/getting-started/quick-start.md
+247
View File
@@ -0,0 +1,247 @@
# Getting Started
Get 9Router running in 5 minutes and start routing AI requests intelligently.
---
## Quick Start
### 1. Install
```bash
npm install -g 9router
```
**Requirements:** Node.js 20+ ([Installation details](getting-started/installation.md))
### 2. Start
```bash
9router
```
🎉 **Dashboard opens automatically** at `http://localhost:20128`
- Default password: `123456` (change in dashboard)
- API key generated automatically
- Ready to connect providers
### 3. Connect Providers
You have 3 ways to connect providers:
#### Option A: OAuth (Subscription Providers)
**Best for:** Claude Code, Codex, Gemini CLI, GitHub Copilot
```
Dashboard → Providers → Connect [Provider]
→ OAuth login → Auto token refresh
→ Quota tracking enabled
```
**Example: Claude Code**
1. Click "Connect Claude Code"
2. Login with your Claude account
3. Authorize 9Router
4. ✅ Done! Use model: `cc/claude-opus-4-5-20251101`
#### Option B: API Key (Cheap Providers)
**Best for:** GLM, MiniMax, Kimi, OpenRouter
```
Dashboard → Providers → Add API Key
→ Select provider
→ Paste API key
→ Save
```
**Example: GLM-4.7**
1. Sign up at [Zhipu AI](https://open.bigmodel.cn/)
2. Get API key from Coding Plan
3. Dashboard → Add API Key → Provider: `glm` → Paste key
4. ✅ Done! Use model: `glm/glm-4.7`
#### Option C: Free Providers (No Cost)
**Best for:** iFlow, Qwen, Kiro
```
Dashboard → Providers → Connect [Free Provider]
→ Device code or OAuth
→ Unlimited usage
```
**Example: iFlow**
1. Click "Connect iFlow"
2. Login with iFlow account
3. Authorize
4. ✅ Done! Use 8 models: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
---
## 4. Use in CLI Tools
Point your coding tool to 9Router:
### Cursor IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from 9router dashboard]
Model: cc/claude-opus-4-5-20251101
```
### Claude Desktop
Edit `~/.claude/config.json`:
```json
{
"anthropic_api_base": "http://localhost:20128/v1",
"anthropic_api_key": "your-9router-api-key"
}
```
### Cline / Continue / RooCode
```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
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. Create Smart Combos (Optional)
Combos enable automatic fallback between models:
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101 (Subscription primary)
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
3. if/kimi-k2-thinking (Free fallback)
Use in CLI: premium-coding
```
**How it works:**
1. Tries Claude Opus first (your subscription)
2. If quota exhausted → GLM-4.7 (ultra-cheap)
3. If budget limit → iFlow (free)
4. Zero downtime, automatic switching!
---
## Available Models
### Subscription Models (Maximize First)
**Claude Code (`cc/`)** - Pro/Max subscription:
- `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 subscription:
- `cx/gpt-5.2-codex` - GPT 5.2 Codex
- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
**Gemini CLI (`gc/`)** - FREE 180K/month:
- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
**GitHub Copilot (`gh/`)** - Subscription:
- `gh/gpt-5` - GPT-5
- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
### Cheap Models (Backup)
**GLM (`glm/`)** - $0.6/$2.2 per 1M:
- `glm/glm-4.7` - GLM 4.7 (daily reset 10AM)
**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
- `minimax/MiniMax-M2.1` - MiniMax M2.1 (5h reset)
**Kimi (`kimi/`)** - $9/month (10M tokens):
- `kimi/kimi-latest` - Kimi Latest
### FREE Models (Emergency)
**iFlow (`if/`)** - 8 models FREE:
- `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 models FREE:
- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
**Kiro (`kr/`)** - 2 models FREE:
- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
- `kr/claude-haiku-4.5` - Claude Haiku 4.5
---
## Cost Optimization Strategy
### Monthly Budget: $10-20/month
```
1. Use Gemini CLI free tier (180K/month) for quick tasks
2. Use Claude Code subscription quota fully (you already pay)
3. Fallback to GLM ($0.6/1M) when quota out
4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
Real example (100M tokens/month):
60M via Gemini CLI: $0 (free tier)
30M via Claude Code: $0 (subscription you already have)
8M via GLM: $4.80
2M via MiniMax: $0.40
Total: $5.20/month + existing subscriptions
```
### Quota Reset Strategy
```
Daily routine:
1. Morning: Fresh Claude Code quota (5h reset)
2. Afternoon: Switch to Gemini CLI (1K/day)
3. Evening: GLM daily quota (reset 10AM next day)
4. Late night: MiniMax (5h rolling) or iFlow (free)
→ Code 24/7 with minimal extra cost!
```
---
## Next Steps
- [Installation Details](getting-started/installation.md) - Requirements, troubleshooting
- [Features](features/) - Explore quota tracking, combos, deployment
- [FAQ](faq.md) - Common questions and answers
- [Troubleshooting](troubleshooting.md) - Fix common issues
---
## Need Help?
- **Website**: [9router.com](https://9router.com)
- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
gitbook/content/en/index.md
+164
View File
@@ -0,0 +1,164 @@
# Welcome to 9Router
**Use Claude, Codex, Gemini for FREE • Ultra-cheap alternatives from $0.20/1M tokens**
9Router is an AI model router that maximizes your subscription value and minimizes costs through intelligent routing and automatic fallback.
---
## What is 9Router?
9Router is a smart proxy that sits between your coding tools (Cursor, Cline, Claude Desktop) and AI providers. It automatically routes requests to the best available model based on quota, cost, and availability.
**Stop wasting money:**
- ❌ Subscription quota expires unused every month
- ❌ Rate limits stop you mid-coding
- ❌ Expensive APIs ($20-50/month per provider)
- ❌ Manual switching between providers
**Start maximizing value:**
- ✅ **Maximize Subscriptions** - Track and use every bit of Claude Code, Codex, Gemini quota
- ✅ **FREE Available** - Access iFlow, Qwen, Kiro models via CLI
- ✅ **Ultra-Cheap Backup** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
- ✅ **Smart Fallback** - Subscription → Cheap → Free, automatic switching
---
## Key Features
### 🔄 Smart 3-Tier Fallback
```
Setup once, never stop coding:
Tier 1 (SUBSCRIPTION): Claude Code → Codex → Gemini
↓ quota exhausted
Tier 2 (CHEAP): GLM-4.7 → MiniMax M2.1 → Kimi
↓ budget limit
Tier 3 (FREE): iFlow → Qwen → Kiro
→ Automatic switching, zero downtime!
```
### 📊 Quota Tracking
- Real-time token consumption per provider
- Reset countdown (5-hour, daily, weekly, monthly)
- Cost estimation for paid tiers
- Monthly spending reports
### 🎯 Universal CLI Support
Works with any tool that supports custom OpenAI endpoints:
✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Any OpenAI-compatible tool**
### 💰 Cost Optimization
**Real example (100M tokens/month):**
```
60M via Gemini CLI: $0 (free tier)
30M via Claude Code: $0 (subscription you already have)
8M via GLM: $4.80
2M via MiniMax: $0.40
Total: $5.20/month vs $2000 on ChatGPT API!
```
---
## Why Choose 9Router?
### Maximize Subscriptions
Already paying for Claude Code ($20-100/month) or Codex ($20-200/month)? Get full value:
- Track quota usage in real-time
- Auto-switch when quota resets (5-hour, weekly)
- Use every token before it expires
- Gemini CLI: 180K completions/month **FREE**
### Ultra-Cheap Backup
When subscription quota runs out, pay pennies:
| Provider | Cost per 1M tokens | Reset |
|----------|-------------------|-------|
| **GLM-4.7** | $0.60 input / $2.20 output | Daily 10:00 AM |
| **MiniMax M2.1** | $0.20 input / $1.00 output | 5-hour rolling |
| **Kimi K2** | $9/month (10M tokens) | Monthly |
**~90% cheaper than ChatGPT API ($20/1M)!**
### Free Forever Fallback
Emergency backup when everything else is quota-limited:
- **iFlow**: 8 models (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
- **Qwen**: 3 models (Qwen3 Coder Plus/Flash, Vision)
- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
---
## Quick Start
Get started in 2 minutes:
```bash
# Install globally
npm install -g 9router
# Start (dashboard opens automatically)
9router
```
🎉 **Dashboard opens** → Connect providers → Start coding!
**Use in your CLI tool:**
```
Endpoint: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-5-20251101
```
[→ Full Getting Started Guide](getting-started.md)
---
## Use Cases
### For Individual Developers
- Maximize your Claude Code/Codex subscription
- Use Gemini CLI free tier (180K/month)
- Fallback to ultra-cheap models ($0.20/1M)
- Code 24/7 without rate limits
### For Teams
- Deploy on VPS/Cloud for shared access
- Track team spending in real-time
- Set budget limits per tier
- Centralized provider management
### For Mobile/Remote Coding
- Use cloud deployment (https://9router.com)
- Access from iPad, phone, anywhere
- No localhost limitations
- Cloudflare edge network (300+ locations)
---
## What's Next?
- [Getting Started](getting-started.md) - Install and configure in 5 minutes
- [Installation Guide](getting-started/installation.md) - Detailed setup instructions
- [Features](features/) - Explore all capabilities
- [FAQ](faq.md) - Common questions
---
<div align="center">
<sub>Built with ❤️ for developers maximizing AI value</sub>
</div>
gitbook/content/en/integration/claude-code.md
+109
View File
@@ -0,0 +1,109 @@
# Claude Code Integration
Integrate 9Router with Claude Code CLI to route your Anthropic API requests through 9Router's intelligent routing system.
## Prerequisites
- Claude Code CLI installed
- 9Router running locally or cloud endpoint configured
- API key from 9Router dashboard
## Setup
### 1. Configure Environment Variables
Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
```bash
# Base URL for 9Router
export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
# Optional: Set default models for aliases
export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
```
### 2. Reload Shell Configuration
```bash
source ~/.zshrc # or ~/.bashrc
```
### 3. Verify Configuration
Check that the environment variables are set correctly:
```bash
echo $ANTHROPIC_BASE_URL
```
## Model Aliases
Claude Code supports the following model aliases that map to 9Router models:
| Alias | Model | Environment Variable |
|-------|-------|---------------------|
| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
## Usage Examples
### Using Model Aliases
```bash
# Use Opus model
claude --model opus "Explain quantum computing"
# Use Sonnet model
claude --model sonnet "Write a Python function"
# Use Haiku model
claude --model haiku "Quick code review"
```
### Using Full Model Names
```bash
claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
```
## Settings File
Claude Code stores its configuration in `~/.claude/settings.json`. You can manually edit this file if needed:
```json
{
"baseUrl": "http://localhost:20128/v1",
"defaultModel": "sonnet"
}
```
## Troubleshooting
### Connection Issues
If you encounter connection errors:
1. Verify 9Router is running: `curl http://localhost:20128/health`
2. Check environment variables are set correctly
3. Ensure no firewall is blocking port 20128
### Model Not Found
If you get "model not found" errors:
1. Verify the model name matches your 9Router configuration
2. Check that the provider connection is active in 9Router dashboard
3. Ensure the model is available in your connected providers
## Cloud Endpoint
To use 9Router cloud endpoint instead of localhost:
```bash
export ANTHROPIC_BASE_URL="https://9router.com"
```
Make sure you have configured your API key in the 9Router cloud dashboard.
gitbook/content/en/integration/cline.md
+201
View File
@@ -0,0 +1,201 @@
# Cline Integration
Integrate 9Router with Cline VSCode extension to route your AI requests through 9Router's intelligent routing system.
## Prerequisites
- Visual Studio Code installed
- Cline extension installed from VSCode marketplace
- 9Router running locally or cloud endpoint configured
- API key from 9Router dashboard
## Setup
### 1. Open Cline Settings
1. Open Visual Studio Code
2. Open the Cline extension panel (click the Cline icon in the sidebar)
3. Click the **Settings** icon (gear icon) in the Cline panel
### 2. Select API Provider
1. In the Cline settings, find **API Provider** dropdown
2. Select **Ollama** from the list
- Note: We use Ollama provider type because it's compatible with OpenAI-style APIs
### 3. Configure Base URL
Set the base URL to your 9Router endpoint:
**For Local 9Router:**
```
http://localhost:20128/v1
```
**For Cloud 9Router:**
```
https://9router.com
```
**Steps:**
1. In the **Base URL** field, enter your 9Router endpoint
2. Make sure to include `/v1` at the end
### 4. Add API Key
1. In the **API Key** field, enter your 9Router API key
2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
3. The key should start with `sk-9router-`
### 5. Select Model
1. In the **Model** dropdown, you can either:
- Select from available models (if Cline auto-detects them)
- Manually enter the model name from your 9Router configuration
2. Common model names:
- `gpt-4`
- `gpt-4o`
- `claude-opus-4-5`
- `claude-sonnet-4-5`
- `gemini-2.0-flash`
### 6. Save Configuration
Click **Save** or close the settings panel. Cline will automatically save your configuration.
## Configuration Example
Your Cline settings should look like this:
```
API Provider: Ollama
Base URL: http://localhost:20128/v1
API Key: sk-9router-xxxxxxxxxxxxx
Model: gpt-4
```
## Available Models
You can use any model configured in your 9Router dashboard. Common examples:
| Model Name | Provider | Description |
|------------|----------|-------------|
| `gpt-4` | OpenAI | GPT-4 Turbo |
| `gpt-4o` | OpenAI | GPT-4 Optimized |
| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
## Usage
### Chat with AI
1. Open the Cline panel in VSCode
2. Type your message in the chat input
3. Press Enter to send
4. Cline will use 9Router to process your request
### Code Generation
1. Ask Cline to generate code: "Create a React component for a login form"
2. Cline will generate code using 9Router
3. Review and accept the generated code
### Code Explanation
1. Select code in your editor
2. Ask Cline: "Explain this code"
3. Get AI-powered explanations through 9Router
### File Operations
1. Ask Cline to create, modify, or delete files
2. Cline will use 9Router to understand context and make changes
3. Review changes before accepting
## Troubleshooting
### "Connection Failed" Error
1. Verify 9Router is running: `curl http://localhost:20128/health`
2. Check that the base URL is correct and includes `/v1`
3. Ensure no firewall is blocking port 20128
4. Try restarting VSCode
### "Invalid API Key" Error
1. Verify your API key in 9Router dashboard
2. Make sure you copied the entire key including the `sk-9router-` prefix
3. Check that the API key has not expired
4. Try regenerating a new API key
### "Model Not Found" Error
1. Verify the model name matches exactly with your 9Router configuration
2. Check that the provider connection is active in 9Router dashboard
3. Ensure the model is available in your connected providers
4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
### Cline Not Responding
1. Check the Cline output panel for error messages
2. Verify your 9Router instance is running and healthy
3. Try reloading VSCode window (Cmd/Ctrl + Shift + P → "Reload Window")
4. Check 9Router logs for any errors
## Advanced Configuration
### Using Cloud Endpoint
To use 9Router cloud endpoint instead of localhost:
1. In Cline settings, set Base URL to: `https://9router.com`
2. Make sure you have configured your API key in the 9Router cloud dashboard
3. Ensure your cloud endpoint is active and accessible
### Multiple Models
You can quickly switch between models:
1. Open Cline settings
2. Change the **Model** field to a different model
3. Save and continue chatting with the new model
### Custom Timeout
If you experience timeout issues with large requests:
1. Open VSCode settings (Cmd/Ctrl + ,)
2. Search for "Cline timeout"
3. Increase the timeout value (default is usually 30 seconds)
## Best Practices
1. **Use Appropriate Models**: Choose faster models (like Haiku or Flash) for simple tasks, and more powerful models (like Opus or GPT-4) for complex tasks
2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
3. **Context Management**: Keep your conversations focused to reduce token usage
4. **Model Switching**: Switch models based on task complexity to optimize cost and performance
5. **API Key Security**: Never commit your API key to version control
## Integration with 9Router Features
### Model Routing
9Router automatically routes your requests to the best available provider based on:
- Model availability
- Provider health status
- Cost optimization
- Load balancing
### Fallback Support
If a provider fails, 9Router automatically falls back to alternative providers configured in your dashboard.
### Usage Tracking
Monitor your Cline usage through 9Router dashboard:
- Total requests
- Token usage
- Cost per model
- Provider distribution
gitbook/content/en/integration/codex.md
+136
View File
@@ -0,0 +1,136 @@
# OpenAI Codex CLI Integration
Integrate 9Router with OpenAI Codex CLI to route your OpenAI API requests through 9Router's intelligent routing system.
## Prerequisites
- OpenAI Codex CLI installed
- 9Router running locally or cloud endpoint configured
- API key from 9Router dashboard
## Setup
### 1. Configure Environment Variables
Set the following environment variables in your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`):
```bash
# Base URL for 9Router
export OPENAI_BASE_URL="http://localhost:20128/v1"
# API Key from 9Router dashboard
export OPENAI_API_KEY="your-9router-api-key"
```
### 2. Reload Shell Configuration
```bash
source ~/.zshrc # or ~/.bashrc
```
### 3. Verify Configuration
Check that the environment variables are set correctly:
```bash
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY
```
## Available Models
9Router provides the following Codex models:
| Model ID | Description |
|----------|-------------|
| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Latest version |
| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Extended context |
## Usage Examples
### Basic Usage
```bash
# Use GPT-5.2 Codex
codex --model cx/gpt-5.2-codex "Write a function to sort an array"
# Use GPT-5.1 Codex Max
codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
```
### Code Generation
```bash
codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
```
### Code Explanation
```bash
codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
```
## Configuration File
You can also configure Codex CLI using a configuration file. Create or edit `~/.codex/config.json`:
```json
{
"baseUrl": "http://localhost:20128/v1",
"apiKey": "your-9router-api-key",
"defaultModel": "cx/gpt-5.2-codex"
}
```
## Troubleshooting
### Authentication Errors
If you encounter authentication errors:
1. Verify your API key is correct in 9Router dashboard
2. Check that `OPENAI_API_KEY` environment variable is set
3. Ensure the API key has not expired
### Connection Issues
If you encounter connection errors:
1. Verify 9Router is running: `curl http://localhost:20128/health`
2. Check environment variables are set correctly
3. Ensure no firewall is blocking port 20128
### Model Not Available
If you get "model not available" errors:
1. Verify the model name matches your 9Router configuration
2. Check that the OpenAI provider connection is active in 9Router dashboard
3. Ensure the model is available in your connected providers
## Cloud Endpoint
To use 9Router cloud endpoint instead of localhost:
```bash
export OPENAI_BASE_URL="https://9router.com"
```
Make sure you have configured your API key in the 9Router cloud dashboard.
## Advanced Configuration
### Custom Timeout
```bash
export OPENAI_TIMEOUT=60 # seconds
```
### Debug Mode
Enable debug mode to see detailed request/response logs:
```bash
export CODEX_DEBUG=true
codex --model cx/gpt-5.2-codex "Your prompt"
```
gitbook/content/en/integration/continue.md
+249
View File
@@ -0,0 +1,249 @@
# Continue VSCode Extension Integration
Integrate 9Router with Continue extension to bring AI assistance directly into Visual Studio Code.
## Prerequisites
- Visual Studio Code installed
- Continue extension installed from VSCode marketplace
- 9Router API key from [dashboard](https://9router.com/dashboard)
- 9Router running (local or cloud)
## Configuration Steps
### 1. Open Continue Configuration
1. Open VSCode
2. Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
3. Type "Continue: Open Config" and select it
4. This opens `~/.continue/config.json`
### 2. Add 9Router Model Configuration
Add the following configuration to your `config.json`:
**Single Model Setup:**
```json
{
"models": [
{
"title": "9Router - Claude Opus",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
}
]
}
```
**Multiple Models Setup:**
```json
{
"models": [
{
"title": "9Router - Claude Opus (Best)",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - Claude Sonnet (Balanced)",
"provider": "openai",
"model": "cc/claude-sonnet-4-20250514",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - DeepSeek Chat (Code)",
"provider": "openai",
"model": "cx/deepseek-chat",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - Claude Haiku (Fast)",
"provider": "openai",
"model": "cc/claude-haiku-4-20250514",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
}
]
}
```
**For Cloud 9Router:**
Replace `apiBase` with:
```json
"apiBase": "https://9router.com/v1"
```
### 3. Save and Reload
1. Save the configuration file
2. Reload VSCode window: `Cmd+Shift+P` → "Developer: Reload Window"
3. Continue extension will load the new configuration
### 4. Select Model
1. Open Continue sidebar (click Continue icon in left panel)
2. Click model selector dropdown at the top
3. Choose your preferred 9Router model
## Available Models
### Claude Models (Anthropic)
- `cc/claude-opus-4-5-20251101` - Most capable, best for complex tasks
- `cc/claude-sonnet-4-20250514` - Balanced performance and speed
- `cc/claude-haiku-4-20250514` - Fastest, good for simple tasks
### DeepSeek Models
- `cx/deepseek-chat` - Excellent for code generation
- `cx/deepseek-reasoner` - Best for complex problem solving
### GLM Models (Zhipu AI)
- `glm/glm-4-plus` - Advanced Chinese and English
- `glm/glm-4-flash` - Fast responses
## Usage Examples
### Code Explanation
1. Select code in editor
2. Open Continue sidebar
3. Type: "Explain this code"
4. Model: `cc/claude-sonnet-4-20250514`
### Code Generation
1. Open Continue sidebar
2. Type: "Create a React component for user profile card"
3. Model: `cx/deepseek-chat`
### Refactoring
1. Select code to refactor
2. Type: "Refactor this to use async/await"
3. Model: `cc/claude-sonnet-4-20250514`
### Bug Fixing
1. Select problematic code
2. Type: "Find and fix the bug in this code"
3. Model: `cx/deepseek-reasoner`
## Advanced Configuration
### Custom System Prompts
Add custom system prompts for specific behaviors:
```json
{
"models": [
{
"title": "9Router - Code Expert",
"provider": "openai",
"model": "cx/deepseek-chat",
"apiKey": "your-api-key",
"apiBase": "http://localhost:20128/v1",
"systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
}
]
}
```
### Temperature and Parameters
Adjust model behavior with parameters:
```json
{
"models": [
{
"title": "9Router - Creative Writer",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key",
"apiBase": "http://localhost:20128/v1",
"temperature": 0.9,
"topP": 0.95
}
]
}
```
### Context Providers
Configure what context Continue sends to the model:
```json
{
"contextProviders": [
{
"name": "code",
"params": {
"maxLines": 100
}
},
{
"name": "diff",
"params": {}
},
{
"name": "terminal",
"params": {}
}
]
}
```
## Keyboard Shortcuts
- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Open Continue chat
- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Inline edit
- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Regenerate response
## Troubleshooting
### Model Not Responding
- Check 9Router is running: `curl http://localhost:20128/health`
- Verify API key in config.json
- Check VSCode Developer Console for errors: `Help` → `Toggle Developer Tools`
### Wrong Model Selected
- Click model dropdown in Continue sidebar
- Select correct 9Router model
- Model name must match exactly (case-sensitive)
### Configuration Not Loading
- Verify JSON syntax is valid (use JSON validator)
- Check file location: `~/.continue/config.json`
- Reload VSCode window after changes
### Slow Performance
- Switch to faster models (haiku, flash)
- Reduce context size in contextProviders
- Check network latency to 9Router
## Best Practices
### Model Selection Strategy
- **Quick edits**: Use `cc/claude-haiku-4-20250514`
- **Code generation**: Use `cx/deepseek-chat`
- **Complex refactoring**: Use `cc/claude-opus-4-5-20251101`
- **Problem solving**: Use `cx/deepseek-reasoner`
### Context Management
- Select only relevant code before asking
- Use specific, clear prompts
- Break complex tasks into smaller steps
### Cost Optimization
- Use faster/cheaper models for simple tasks
- Limit context size when possible
- Cache frequently used responses
## Next Steps
- [Configure Cursor](cursor.md) for enhanced IDE integration
- [Set up Roo](roo.md) for AI assistant
- [Explore CLI usage](../cli/basic-usage.md)
- [Learn about model selection](../models/overview.md)
gitbook/content/en/integration/cursor.md
+149
View File
@@ -0,0 +1,149 @@
# Cursor Integration
Integrate 9Router with Cursor IDE to route your AI requests through 9Router's intelligent routing system.
## Prerequisites
- Cursor IDE installed
- Cursor Pro account (required for custom API endpoints)
- 9Router cloud endpoint configured
- API key from 9Router dashboard
## ⚠️ Important Notes
> **Cloud Endpoint Required**: Cursor routes requests through its own server and does not support localhost endpoints. You must use the 9Router cloud endpoint: `https://9router.com`
> **Cursor Pro Required**: This feature requires a Cursor Pro account to use custom API endpoints.
## Setup
### 1. Open Cursor Settings
1. Open Cursor IDE
2. Go to **Settings** (Cmd/Ctrl + ,)
3. Navigate to **Models** section
### 2. Enable OpenAI API
1. Find the **OpenAI API key** option
2. Enable the toggle to activate custom API configuration
### 3. Configure Base URL
Set the base URL to 9Router cloud endpoint:
```
https://9router.com
```
**Steps:**
1. In the Models settings, locate the **Base URL** field
2. Enter: `https://9router.com`
3. Click **Save**
### 4. Add API Key
1. In the **API Key** field, enter your 9Router API key
2. You can find your API key in the 9Router dashboard under **Settings → API Keys**
3. Click **Save**
### 5. Add Custom Model
1. Click **View All Models** button
2. Click **Add Custom Model**
3. Enter the model name from your 9Router configuration (e.g., `gpt-4`, `claude-opus-4-5`, etc.)
4. Click **Add**
### 6. Select Model
1. In the Cursor chat interface, click the model selector dropdown
2. Choose your custom model from the list
3. Start using 9Router with Cursor!
## Configuration Example
Your Cursor settings should look like this:
```
OpenAI API: ✓ Enabled
Base URL: https://9router.com
API Key: sk-9router-xxxxxxxxxxxxx
Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
```
## Available Models
You can use any model configured in your 9Router dashboard. Common examples:
| Model Name | Provider | Description |
|------------|----------|-------------|
| `gpt-4` | OpenAI | GPT-4 Turbo |
| `gpt-4o` | OpenAI | GPT-4 Optimized |
| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
## Usage
### Chat Interface
1. Open Cursor chat (Cmd/Ctrl + L)
2. Select your model from the dropdown
3. Start chatting with AI through 9Router
### Inline Code Generation
1. Select code in your editor
2. Press Cmd/Ctrl + K
3. Enter your prompt
4. Cursor will use 9Router to generate code
### Code Explanation
1. Select code in your editor
2. Press Cmd/Ctrl + L
3. Ask "Explain this code"
4. Get AI-powered explanations through 9Router
## Troubleshooting
### "Invalid API Key" Error
1. Verify your API key in 9Router dashboard
2. Make sure you copied the entire key including the `sk-9router-` prefix
3. Check that the API key has not expired
4. Try regenerating a new API key
### "Model Not Found" Error
1. Verify the model name matches exactly with your 9Router configuration
2. Check that the provider connection is active in 9Router dashboard
3. Ensure the model is available in your connected providers
4. Try using the full model name (e.g., `openai/gpt-4` instead of `gpt-4`)
### Connection Issues
1. Verify you are using the cloud endpoint: `https://9router.com`
2. Check your internet connection
3. Ensure 9Router cloud service is operational
4. Try disabling VPN or proxy if enabled
### Localhost Not Working
> **Remember**: Cursor does not support localhost endpoints. You must use the cloud endpoint `https://9router.com`. If you need to use a local 9Router instance, consider using a tunneling service like ngrok to expose your local endpoint.
## Cloud Endpoint Setup
If you're running 9Router locally and want to use it with Cursor:
1. Enable cloud endpoint in 9Router settings
2. Configure your cloud endpoint URL in 9Router dashboard
3. Use the cloud URL in Cursor settings
4. Ensure your local 9Router instance is accessible from the internet
## Best Practices
1. **Use Model Aliases**: Create short aliases for frequently used models in 9Router
2. **Monitor Usage**: Check 9Router dashboard for usage statistics and costs
3. **Rotate API Keys**: Regularly rotate your API keys for security
4. **Test Models**: Try different models to find the best one for your use case
gitbook/content/en/integration/other-tools.md
+416
View File
@@ -0,0 +1,416 @@
# Other Tools Integration
9Router is compatible with any tool that supports the OpenAI API format. This guide covers generic integration patterns for various tools and custom applications.
## Overview
9Router provides an OpenAI-compatible API endpoint that works with:
- Custom scripts and applications
- API clients and testing tools
- CLI tools and utilities
- Third-party integrations
- Development frameworks
## Generic Setup Pattern
Any OpenAI-compatible tool can connect to 9Router using these settings:
**Local 9Router:**
```
Base URL: http://localhost:20128/v1
API Key: your-api-key-from-dashboard
Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
```
**Cloud 9Router:**
```
Base URL: https://9router.com/v1
API Key: your-api-key-from-dashboard
Model: any 9Router model (cc/*, cx/*, glm/*, etc.)
```
## Available Models
### Claude Models (Anthropic)
- `cc/claude-opus-4-5-20251101`
- `cc/claude-sonnet-4-20250514`
- `cc/claude-haiku-4-20250514`
### DeepSeek Models
- `cx/deepseek-chat`
- `cx/deepseek-reasoner`
### GLM Models (Zhipu AI)
- `glm/glm-4-plus`
- `glm/glm-4-flash`
## Integration Examples
### Python with OpenAI SDK
```python
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[
{"role": "user", "content": "Hello, how are you?"}
]
)
print(response.choices[0].message.content)
```
### Node.js with OpenAI SDK
```javascript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
const response = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [
{ role: "user", content: "Hello, how are you?" }
]
});
console.log(response.choices[0].message.content);
```
### cURL Command
```bash
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-from-dashboard" \
-d '{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
]
}'
```
### HTTP Client (Postman, Insomnia)
**Request:**
```
POST http://localhost:20128/v1/chat/completions
```
**Headers:**
```
Content-Type: application/json
Authorization: Bearer your-api-key-from-dashboard
```
**Body:**
```json
{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
],
"temperature": 0.7,
"max_tokens": 1000
}
```
### LangChain Integration
```python
from langchain.chat_models import ChatOpenAI
from langchain.schema import HumanMessage
llm = ChatOpenAI(
model_name="cc/claude-sonnet-4-20250514",
openai_api_key="your-api-key-from-dashboard",
openai_api_base="http://localhost:20128/v1",
temperature=0.7
)
messages = [HumanMessage(content="Explain quantum computing")]
response = llm(messages)
print(response.content)
```
### LlamaIndex Integration
```python
from llama_index.llms import OpenAI
llm = OpenAI(
model="cc/claude-sonnet-4-20250514",
api_key="your-api-key-from-dashboard",
api_base="http://localhost:20128/v1"
)
response = llm.complete("What is machine learning?")
print(response.text)
```
## Custom Script Examples
### Batch Processing Script
```python
import openai
import json
openai.api_key = "your-api-key-from-dashboard"
openai.api_base = "http://localhost:20128/v1"
def process_batch(prompts, model="cx/deepseek-chat"):
results = []
for prompt in prompts:
response = openai.ChatCompletion.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
results.append({
"prompt": prompt,
"response": response.choices[0].message.content
})
return results
prompts = [
"Explain AI in one sentence",
"What is machine learning?",
"Define neural networks"
]
results = process_batch(prompts)
print(json.dumps(results, indent=2))
```
### Streaming Response Handler
```javascript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
async function streamResponse(prompt) {
const stream = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [{ role: "user", content: prompt }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || "";
process.stdout.write(content);
}
}
streamResponse("Write a short story about AI");
```
### Multi-Model Comparison
```python
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
models = [
"cc/claude-sonnet-4-20250514",
"cx/deepseek-chat",
"glm/glm-4-plus"
]
prompt = "Explain quantum computing in simple terms"
for model in models:
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
print(f"\n=== {model} ===")
print(response.choices[0].message.content)
```
## Common Integration Patterns
### Environment Variables
Store credentials securely:
```bash
# .env file
ROUTER_API_KEY=your-api-key-from-dashboard
ROUTER_BASE_URL=http://localhost:20128/v1
ROUTER_MODEL=cc/claude-sonnet-4-20250514
```
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("ROUTER_API_KEY"),
base_url=os.getenv("ROUTER_BASE_URL")
)
```
### Error Handling
```python
from openai import OpenAI, OpenAIError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)
except OpenAIError as e:
print(f"Error: {e}")
```
### Retry Logic
```python
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
def chat_with_retry(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
except RateLimitError:
if attempt < max_retries - 1:
time.sleep(2 ** attempt) # Exponential backoff
else:
raise
```
## Troubleshooting
### Connection Issues
**Problem:** Cannot connect to 9Router
```bash
# Check if 9Router is running
curl http://localhost:20128/health
# Expected response:
{"status": "ok"}
```
**Solution:**
- Verify 9Router is running
- Check port 20128 is not blocked
- Ensure correct base URL (include `/v1`)
### Authentication Errors
**Problem:** 401 Unauthorized
```
Error: Invalid API key
```
**Solution:**
- Verify API key from dashboard
- Check Authorization header format: `Bearer your-api-key`
- Ensure no extra spaces or newlines in API key
### Model Not Found
**Problem:** 404 Model not found
```
Error: Model 'cc/claude-opus' not found
```
**Solution:**
- Use exact model name (case-sensitive)
- Check available models: `curl http://localhost:20128/v1/models`
- Verify model is enabled in your plan
### Timeout Issues
**Problem:** Request timeout
```
Error: Request timed out after 30s
```
**Solution:**
- Increase timeout in client configuration
- Use faster models for time-sensitive tasks
- Check network connection to 9Router
### Rate Limiting
**Problem:** 429 Too Many Requests
```
Error: Rate limit exceeded
```
**Solution:**
- Implement exponential backoff
- Reduce request frequency
- Check rate limits in dashboard
- Consider upgrading plan
## Best Practices
### Security
- Store API keys in environment variables
- Never commit API keys to version control
- Use HTTPS for cloud deployments
- Rotate API keys regularly
### Performance
- Use appropriate models for task complexity
- Implement caching for repeated queries
- Use streaming for long responses
- Batch requests when possible
### Error Handling
- Always implement try-catch blocks
- Add retry logic with exponential backoff
- Log errors for debugging
- Provide fallback mechanisms
### Cost Optimization
- Choose cost-effective models for simple tasks
- Cache responses when appropriate
- Monitor usage in dashboard
- Set request limits in code
## Next Steps
- [Configure Cursor](cursor.md) for IDE integration
- [Set up Continue](continue.md) for VSCode
- [Explore CLI usage](../cli/basic-usage.md)
- [Learn about model selection](../models/overview.md)
- [API Reference](../api/reference.md)
gitbook/content/en/integration/roo.md
+127
View File
@@ -0,0 +1,127 @@
# Roo AI Assistant Integration
Integrate 9Router with Roo AI Assistant to access multiple AI models through a unified interface.
## Prerequisites
- Roo AI Assistant installed
- 9Router API key from [dashboard](https://9router.com/dashboard)
- 9Router running (local or cloud)
## Configuration Steps
### 1. Open Roo Settings
Launch Roo AI Assistant and open the settings panel.
### 2. Configure API Provider
1. Navigate to **API Provider** settings
2. Select **Ollama** as the provider type
3. Configure the following settings:
**For Local 9Router:**
```
Base URL: http://localhost:20128/v1
API Key: your-api-key-from-dashboard
```
**For Cloud 9Router:**
```
Base URL: https://9router.com/v1
API Key: your-api-key-from-dashboard
```
### 3. Select Model
Choose from available 9Router models:
**Claude Models:**
- `cc/claude-opus-4-5-20251101` - Most capable
- `cc/claude-sonnet-4-20250514` - Balanced
- `cc/claude-haiku-4-20250514` - Fast
**DeepSeek Models:**
- `cx/deepseek-chat` - General purpose
- `cx/deepseek-reasoner` - Complex reasoning
**GLM Models:**
- `glm/glm-4-plus` - Advanced
- `glm/glm-4-flash` - Fast responses
### 4. Test Connection
Send a test message to verify the integration:
```
Hello! Can you confirm you're connected through 9Router?
```
## Usage Examples
### Basic Chat
```
Ask Roo: "Explain quantum computing in simple terms"
Model: cc/claude-sonnet-4-20250514
```
### Code Generation
```
Ask Roo: "Write a Python function to calculate Fibonacci numbers"
Model: cx/deepseek-chat
```
### Complex Reasoning
```
Ask Roo: "Analyze the trade-offs between microservices and monolithic architecture"
Model: cx/deepseek-reasoner
```
## Model Selection Tips
- **Quick tasks**: Use `cc/claude-haiku-4-20250514` or `glm/glm-4-flash`
- **Balanced performance**: Use `cc/claude-sonnet-4-20250514` or `cx/deepseek-chat`
- **Complex reasoning**: Use `cc/claude-opus-4-5-20251101` or `cx/deepseek-reasoner`
- **Cost optimization**: Use DeepSeek or GLM models
## Troubleshooting
### Connection Failed
- Verify 9Router is running: `curl http://localhost:20128/health`
- Check API key is correct
- Ensure Base URL includes `/v1` suffix
### Model Not Available
- Check model name matches exactly (case-sensitive)
- Verify model is enabled in your 9Router plan
- Try a different model from the list
### Slow Responses
- Switch to faster models (haiku, flash)
- Check network connection
- Monitor 9Router logs for issues
## Advanced Configuration
### Custom Model Aliases
You can create shortcuts for frequently used models in Roo settings:
```
Alias: "fast" → cc/claude-haiku-4-20250514
Alias: "smart" → cc/claude-opus-4-5-20251101
Alias: "code" → cx/deepseek-chat
```
### Multiple Profiles
Set up different profiles for different use cases:
- **Development**: DeepSeek models for code
- **Writing**: Claude models for content
- **Research**: Reasoner models for analysis
## Next Steps
- [Configure Cursor](cursor.md) for IDE integration
- [Set up Continue](continue.md) for VSCode
- [Explore CLI usage](../cli/basic-usage.md)
gitbook/content/en/providers/cheap.md
+462
View File
@@ -0,0 +1,462 @@
# Cheap Providers - Ultra-Cheap Backup
When subscription quota runs out, pay pennies instead of dollars. ~90% cheaper than ChatGPT API!
---
## Overview
Cheap tier providers are your **backup** when subscription quota exhausted:
- 💰 **GLM-4.7** - $0.6/$2.2 per 1M tokens (daily reset)
- 💰 **MiniMax M2.1** - $0.2/$1.0 per 1M tokens (5h reset)
- 💰 **Kimi K2** - $9/month flat (10M tokens)
**Strategy:** Use after subscription quota out, before free tier. Massive cost savings vs ChatGPT API ($20/1M).
---
## GLM-4.7 (Daily Reset)
### Pricing
| Tier | Input | Output | Reset |
|------|-------|--------|-------|
| Standard | $0.60/1M | $2.20/1M | Daily 10:00 AM |
| Coding Plan | $0.60/1M | $2.20/1M | Daily 10:00 AM (3× quota) |
**Cost Example (10M tokens):**
- Input: 10M × $0.60 = $6
- Output: 10M × $2.20 = $22
- **Total: $6-22** vs $200 on ChatGPT API!
### Setup
**Step 1: Sign Up**
1. Visit [Zhipu AI](https://open.bigmodel.cn/)
2. Create account (phone verification)
3. Choose **Coding Plan** for 3× quota at same price
**Step 2: Get API Key**
```bash
Dashboard → API Keys → Create New
→ Copy API key (starts with "zhipu-")
```
**Step 3: Add to 9Router**
```bash
9router
# Dashboard → Providers → Add API Key
Provider: glm
API Key: zhipu-your-api-key-here
```
**Step 4: Use in CLI**
```
Model: glm/glm-4.7
glm/glm-4.6v (vision)
```
### Available Models
| Model ID | Description | Context | Best For |
|----------|-------------|---------|----------|
| `glm/glm-4.7` | GLM 4.7 | 128K | Coding, general tasks |
| `glm/glm-4.6v` | GLM 4.6V Vision | 128K | Image analysis |
### Pro Tips
- **Coding Plan** - 3× quota at same price ($0.6/$2.2)
- **Daily reset** - Fresh quota at 10:00 AM Beijing time
- **Best for coding** - Optimized for code generation
- **128K context** - Handle large files
### Quota Reset
```
Daily reset: 10:00 AM Beijing Time (UTC+8)
→ 2:00 AM UTC
→ 6:00 PM PST (previous day)
→ 9:00 PM EST (previous day)
Plan your heavy tasks around reset time!
```
---
## MiniMax M2.1 (5-Hour Reset)
### Pricing
| Tier | Input | Output | Reset |
|------|-------|--------|-------|
| Standard | $0.20/1M | $1.00/1M | 5-hour rolling |
**Cost Example (10M tokens):**
- Input: 10M × $0.20 = $2
- Output: 10M × $1.00 = $10
- **Total: $2-10** - Cheapest option!
### Setup
**Step 1: Sign Up**
1. Visit [MiniMax](https://www.minimax.io/)
2. Create account
3. Verify email/phone
**Step 2: Get API Key**
```bash
Dashboard → API Management → Create Key
→ Copy API key
```
**Step 3: Add to 9Router**
```bash
9router
# Dashboard → Providers → Add API Key
Provider: minimax
API Key: your-minimax-api-key
```
**Step 4: Use in CLI**
```
Model: minimax/MiniMax-M2.1
```
### Available Models
| Model ID | Description | Context | Best For |
|----------|-------------|---------|----------|
| `minimax/MiniMax-M2.1` | MiniMax M2.1 | 1M tokens | Long context, coding |
### Pro Tips
- **Cheapest option** - $0.20/1M input (90% cheaper than ChatGPT)
- **5-hour rolling** - Quota resets every 5 hours
- **1M context** - Massive context window
- **Best for long files** - Handle entire codebases
### Quota Reset
```
5-hour rolling window:
→ Use quota → Wait 5 hours → Fresh quota
Example:
10:00 AM - Use 5M tokens
3:00 PM - Fresh quota available
8:00 PM - Fresh quota available
Code 24/7 with minimal cost!
```
---
## Kimi K2 (Flat $9/month)
### Pricing
| Plan | Monthly Cost | Included Tokens | Effective Cost |
|------|--------------|-----------------|----------------|
| Subscription | $9 | 10M tokens | $0.90/1M |
**Cost Example:**
- $9/month flat
- 10M tokens included
- **Effective: $0.90/1M** - Best value for consistent usage!
### Setup
**Step 1: Subscribe**
1. Visit [Moonshot AI](https://platform.moonshot.ai/)
2. Create account
3. Subscribe to $9/month plan
**Step 2: Get API Key**
```bash
Dashboard → API Keys → Create New
→ Copy API key
```
**Step 3: Add to 9Router**
```bash
9router
# Dashboard → Providers → Add API Key
Provider: kimi
API Key: your-kimi-api-key
```
**Step 4: Use in CLI**
```
Model: kimi/kimi-latest
```
### Available Models
| Model ID | Description | Context | Best For |
|----------|-------------|---------|----------|
| `kimi/kimi-latest` | Kimi Latest | 200K | General coding |
### Pro Tips
- **Fixed cost** - $9/month regardless of usage (up to 10M)
- **Best for consistent usage** - If you use 10M/month, only $0.90/1M
- **Monthly reset** - 10M tokens reset monthly
- **Predictable billing** - No surprise costs
### Quota Reset
```
Monthly reset: 1st of each month
→ 10M tokens refresh
Example monthly usage:
Week 1: 3M tokens
Week 2: 2M tokens
Week 3: 3M tokens
Week 4: 2M tokens
Total: 10M tokens = $9 flat
```
---
## Pricing Comparison
| Provider | Input/1M | Output/1M | Reset | 10M Cost | Best For |
|----------|----------|-----------|-------|----------|----------|
| **GLM-4.7** | $0.60 | $2.20 | Daily 10AM | $6-22 | Daily quota users |
| **MiniMax M2.1** | $0.20 | $1.00 | 5-hour | $2-10 | **Cheapest!** |
| **Kimi K2** | $0.90 | $0.90 | Monthly | **$9 flat** | Consistent usage |
| ChatGPT API | $20.00 | $20.00 | None | $200 | ❌ Expensive |
**Savings:** 90-95% cheaper than ChatGPT API!
---
## Usage Example
### Cursor IDE Setup
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from 9router dashboard]
Model: glm/glm-4.7
```
### Create Combo (Recommended)
```
Dashboard → Combos → Create New
Name: cheap-backup
Models:
1. cc/claude-opus-4-5 (Subscription primary)
2. glm/glm-4.7 (Cheap backup, daily reset)
3. minimax/MiniMax-M2.1 (Cheapest fallback)
4. if/kimi-k2-thinking (FREE emergency)
Use in CLI: cheap-backup
```
**Result:** Subscription → Cheap → Cheapest → Free
---
## Cost Optimization
### Strategy 1: Daily Reset Routine
```
Morning (10AM): Fresh GLM quota
→ Use GLM for heavy tasks
→ Save subscription quota
Afternoon: Subscription quota
→ Use Claude/Codex for complex tasks
Evening: MiniMax (5h reset)
→ Cheap fallback for late work
Night: Free tier (iFlow)
→ Zero cost emergency backup
```
### Strategy 2: Budget-First
```
Set monthly budget: $20
Allocation:
- $9 Kimi K2 (10M tokens flat)
- $6 GLM daily quota (10M tokens)
- $5 MiniMax overflow (25M tokens)
Total: 45M tokens for $20
vs 1M tokens for $20 on ChatGPT API!
```
### Strategy 3: Maximize Subscriptions First
```
Priority:
1. Gemini CLI (180K/month FREE)
2. Claude Code (subscription you already pay)
3. GLM-4.7 (cheap backup, $0.6/1M)
4. MiniMax M2.1 (cheapest, $0.2/1M)
5. iFlow (FREE emergency)
Monthly cost example (100M tokens):
- 60M via Gemini CLI: $0 (free)
- 30M via Claude Code: $0 (subscription)
- 8M via GLM: $4.80
- 2M via MiniMax: $0.40
Total: $5.20/month!
```
---
## Real-World Examples
### Example 1: Heavy Coding Month (100M tokens)
```
Breakdown:
- 60M via subscription (Claude/Codex): $0 extra
- 30M via GLM-4.7: $18
- 10M via MiniMax M2.1: $2
Total: $20/month
vs $2000 on ChatGPT API!
Savings: 99% cheaper!
```
### Example 2: Budget Coder ($10/month)
```
Strategy:
- $9 Kimi K2 (10M tokens)
- $1 MiniMax overflow (5M tokens)
Total: 15M tokens for $10
vs 0.5M tokens for $10 on ChatGPT API!
30× more tokens!
```
### Example 3: Freelancer (Variable Usage)
```
Light month (20M tokens):
- 15M via subscription: $0
- 5M via GLM: $3
Total: $3
Heavy month (150M tokens):
- 60M via subscription: $0
- 60M via GLM: $36
- 30M via MiniMax: $6
Total: $42
Average: $22.50/month
vs $3400 on ChatGPT API!
```
---
## Best Practices
### 1. Track Daily Quota
```
Dashboard shows:
- GLM quota: 75% used (reset in 6h)
- MiniMax quota: 50% used (reset in 2h)
- Kimi quota: 8M/10M used (reset in 15 days)
Plan heavy tasks around reset times!
```
### 2. Use Coding Plan (GLM)
```
Standard: 1× quota
Coding Plan: 3× quota (same price!)
→ Always choose Coding Plan
```
### 3. Combine with Free Tier
```
Combo:
1. gc/gemini-3-flash (FREE primary)
2. glm/glm-4.7 (cheap backup)
3. minimax/MiniMax-M2.1 (cheapest)
4. if/kimi-k2-thinking (FREE emergency)
Result: Minimize costs, maximize uptime
```
### 4. Set Budget Alerts
```
Dashboard → Settings → Budget Alerts
Daily: $2 limit
Weekly: $10 limit
Monthly: $30 limit
→ Auto switch to free tier when limit reached
```
---
## Troubleshooting
### "Quota exhausted"
**Solution:**
- GLM: Wait until 10:00 AM Beijing time
- MiniMax: Wait 5 hours from first use
- Kimi: Wait until 1st of next month
- Use combo fallback to free tier
### "API key invalid"
**Solution:**
- Check API key copied correctly
- Verify account has credits
- Regenerate API key if needed
### "High costs"
**Solution:**
- Check usage stats in Dashboard
- Set budget alerts
- Switch to MiniMax ($0.2/1M cheapest)
- Use free tier for non-critical tasks
---
## Next Steps
- **Add free fallback:** [Free Providers](./free.md)
- **Setup subscriptions:** [Subscription Providers](./subscription.md)
- **Create combos:** Dashboard → Combos → Create New
gitbook/content/en/providers/free.md
+442
View File
@@ -0,0 +1,442 @@
# Free Providers - Zero Cost Fallback
Emergency backup when everything else is quota-limited. Code 24/7 with zero cost!
---
## Overview
Free tier providers are your **fallback** when subscription and cheap quota exhausted:
- 🆓 **iFlow** - 8 models FREE (Kimi K2, Qwen3, GLM 4.7, MiniMax M2...)
- 🆓 **Qwen** - 3 models FREE (Qwen3 Coder Plus/Flash, Vision)
- 🆓 **Kiro** - 2 models FREE (Claude Sonnet 4.5, Haiku 4.5)
**Strategy:** Use as emergency backup. Unlimited usage, zero cost forever!
---
## iFlow (8 FREE Models)
### Pricing
| Plan | Monthly Cost | Models | Quota |
|------|--------------|--------|-------|
| FREE | $0 | 8 models | Unlimited |
**Best Value:** Most models in free tier! Kimi K2, Qwen3, GLM, MiniMax, DeepSeek.
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect iFlow
```
**Step 2: iFlow OAuth Login**
- Click "Connect iFlow"
- Browser opens → iFlow login page
- Create account or login
- Grant permissions
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: if/kimi-k2-thinking
if/kimi-k2
if/qwen3-coder-plus
if/glm-4.7
if/minimax-m2
if/deepseek-r1
if/deepseek-v3.2-chat
if/deepseek-v3.2-reasoner
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `if/kimi-k2-thinking` | Kimi K2 Thinking | Complex reasoning |
| `if/kimi-k2` | Kimi K2 | General coding |
| `if/qwen3-coder-plus` | Qwen3 Coder Plus | Code generation |
| `if/glm-4.7` | GLM 4.7 | Chinese + English |
| `if/minimax-m2` | MiniMax M2 | Long context |
| `if/deepseek-r1` | DeepSeek R1 | Reasoning tasks |
| `if/deepseek-v3.2-chat` | DeepSeek V3.2 Chat | Conversational |
| `if/deepseek-v3.2-reasoner` | DeepSeek V3.2 Reasoner | Complex logic |
### Pro Tips
- **8 models FREE** - Most variety in free tier
- **Unlimited usage** - No quota limits
- **Kimi K2 Thinking** - Best for complex reasoning
- **DeepSeek R1** - Strong reasoning capabilities
---
## Qwen (3 FREE Models)
### Pricing
| Plan | Monthly Cost | Models | Quota |
|------|--------------|--------|-------|
| FREE | $0 | 3 models | Unlimited |
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect Qwen
```
**Step 2: Device Code Authorization**
- Click "Connect Qwen"
- Dashboard shows device code
- Visit authorization URL
- Enter device code
- Login to Qwen account
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: qw/qwen3-coder-plus
qw/qwen3-coder-flash
qw/vision-model
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `qw/qwen3-coder-plus` | Qwen3 Coder Plus | Advanced coding |
| `qw/qwen3-coder-flash` | Qwen3 Coder Flash | Fast responses |
| `qw/vision-model` | Qwen3 Vision | Image analysis |
### Pro Tips
- **Qwen3 Coder Plus** - Strong coding capabilities
- **Qwen3 Coder Flash** - Fast for quick tasks
- **Vision model** - FREE image analysis
- **Unlimited usage** - No quota limits
---
## Kiro (Claude FREE)
### Pricing
| Plan | Monthly Cost | Models | Quota |
|------|--------------|--------|-------|
| FREE | $0 | Claude Sonnet 4.5, Haiku 4.5 | Unlimited |
**Best Value:** FREE Claude! Same quality as paid Claude Code.
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect Kiro
```
**Step 2: AWS Builder ID or OAuth**
- Click "Connect Kiro"
- Choose login method:
- AWS Builder ID (recommended)
- Google account
- GitHub account
- Grant permissions
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: kr/claude-sonnet-4.5
kr/claude-haiku-4.5
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `kr/claude-sonnet-4.5` | Claude Sonnet 4.5 | Balanced quality/speed |
| `kr/claude-haiku-4.5` | Claude Haiku 4.5 | Fast responses |
### Pro Tips
- **FREE Claude** - Same quality as paid tier
- **AWS Builder ID** - Easy setup with AWS account
- **Unlimited usage** - No quota limits
- **Best quality** - Claude 4.5 for free!
---
## Feature Comparison
| Provider | Models | Best Model | Setup | Quota |
|----------|--------|------------|-------|-------|
| **iFlow** | 8 | Kimi K2 Thinking | OAuth | Unlimited |
| **Qwen** | 3 | Qwen3 Coder Plus | Device Code | Unlimited |
| **Kiro** | 2 | Claude Sonnet 4.5 | AWS Builder ID | Unlimited |
**Winner:** iFlow for variety, Kiro for quality!
---
## Usage Example
### Cursor IDE Setup
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from 9router dashboard]
Model: if/kimi-k2-thinking
```
### Create Combo (Recommended)
```
Dashboard → Combos → Create New
Name: free-combo
Models:
1. if/kimi-k2-thinking (iFlow primary)
2. qw/qwen3-coder-plus (Qwen backup)
3. kr/claude-sonnet-4.5 (Kiro quality)
Use in CLI: free-combo
```
**Result:** Zero cost, maximum uptime!
---
## Full Fallback Strategy
### Complete 3-Tier Combo
```
Dashboard → Combos → Create New
Name: complete-fallback
Models:
1. gc/gemini-3-flash-preview (FREE subscription)
2. cc/claude-opus-4-5 (Paid subscription)
3. glm/glm-4.7 (Cheap backup, $0.6/1M)
4. minimax/MiniMax-M2.1 (Cheapest, $0.2/1M)
5. if/kimi-k2-thinking (FREE fallback)
6. kr/claude-sonnet-4.5 (FREE quality)
Use in CLI: complete-fallback
```
**Result:**
- Tier 1: FREE subscription (Gemini CLI)
- Tier 2: Paid subscription (Claude Code)
- Tier 3: Cheap backup (GLM, MiniMax)
- Tier 4: FREE fallback (iFlow, Kiro)
**Never stop coding!**
---
## Best Practices
### 1. Use as Emergency Backup
```
Priority:
1. Subscription tier (maximize paid quota)
2. Cheap tier (pennies per 1M tokens)
3. FREE tier (unlimited, zero cost)
Only use free tier when:
- Subscription quota exhausted
- Budget limit reached
- Testing/non-critical tasks
```
### 2. Choose Right Model
```
Complex reasoning: if/kimi-k2-thinking
Fast coding: qw/qwen3-coder-flash
Best quality: kr/claude-sonnet-4.5
Long context: if/minimax-m2
Vision tasks: qw/vision-model
```
### 3. Create Free-Only Combo
```
For zero-cost coding:
Name: zero-cost
Models:
1. kr/claude-sonnet-4.5 (Best quality)
2. if/kimi-k2-thinking (Complex tasks)
3. qw/qwen3-coder-plus (Fast coding)
Cost: $0 forever!
```
### 4. Test Before Production
```
Use free tier to:
- Test prompts
- Prototype features
- Learn new frameworks
- Non-critical tasks
Save paid quota for:
- Production code
- Complex refactoring
- Critical features
```
---
## Real-World Examples
### Example 1: Student/Learner (Zero Budget)
```
Setup:
1. kr/claude-sonnet-4.5 (Best quality)
2. if/kimi-k2-thinking (Complex reasoning)
3. qw/qwen3-coder-plus (Fast coding)
Monthly cost: $0
Usage: Unlimited
Perfect for:
- Learning to code
- Personal projects
- Homework/assignments
```
### Example 2: Freelancer (Budget-Conscious)
```
Setup:
1. gc/gemini-3-flash-preview (FREE 180K/month)
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
3. if/kimi-k2-thinking (FREE fallback)
Monthly cost: $5-10
Usage: 100M+ tokens
Perfect for:
- Client projects (paid tier)
- Testing (free tier)
- Emergency backup
```
### Example 3: Heavy User (Maximize Everything)
```
Setup:
1. gc/gemini-3-flash-preview (FREE 180K/month)
2. cc/claude-opus-4-5 (Subscription $20-100)
3. cx/gpt-5.2-codex (Subscription $20-200)
4. glm/glm-4.7 (Cheap $0.6/1M)
5. minimax/MiniMax-M2.1 (Cheapest $0.2/1M)
6. if/kimi-k2-thinking (FREE unlimited)
7. kr/claude-sonnet-4.5 (FREE quality)
Monthly cost: $40-320 (subscriptions) + $10-20 (cheap tier)
Usage: 500M+ tokens
Perfect for:
- Professional development
- Team projects
- 24/7 coding
```
---
## Cost Comparison
### Scenario: 100M tokens/month
**Option 1: ChatGPT API Only**
```
100M × $20/1M = $2,000/month
```
**Option 2: 9Router Free Tier Only**
```
100M via free tier = $0/month
Savings: $2,000/month (100%)
```
**Option 3: 9Router Complete Strategy**
```
60M via Gemini CLI (FREE): $0
30M via Claude Code (subscription): $0 extra
8M via GLM (cheap): $4.80
2M via iFlow (FREE): $0
Total: $4.80/month + subscriptions you already have
Savings: $1,995/month (99.76%)
```
---
## Troubleshooting
### "OAuth failed"
**Solution:**
- Check internet connection
- Try different browser
- Clear browser cache
- Reconnect in dashboard
### "Model not available"
**Solution:**
- Check provider connected in dashboard
- Verify OAuth token valid
- Reconnect provider if needed
### "Slow responses"
**Solution:**
- Free tier may have lower priority
- Use during off-peak hours
- Switch to different free provider
- Upgrade to cheap tier for speed
---
## Limitations
### Free Tier Considerations
- **Speed** - May be slower than paid tiers
- **Priority** - Lower priority during peak hours
- **Rate limits** - Possible rate limiting (but unlimited quota)
- **Availability** - May have occasional downtime
**Solution:** Use 3-tier fallback strategy for reliability!
---
## Next Steps
- **Setup subscriptions:** [Subscription Providers](./subscription.md)
- **Add cheap backup:** [Cheap Providers](./cheap.md)
- **Create combos:** Dashboard → Combos → Create New
- **Start coding:** Use `complete-fallback` combo for maximum reliability
gitbook/content/en/providers/subscription.md
+404
View File
@@ -0,0 +1,404 @@
# Subscription Providers - Maximize Your Value
Maximize your existing AI subscriptions with smart quota tracking and automatic fallback. Use every bit of your subscription before it resets!
---
## Overview
Subscription tier providers are your **primary** choice - you're already paying for them, so get full value:
- ✅ **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
- ✅ **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
- ✅ **Gemini CLI** (FREE tier!) - 180K completions/month
- ✅ **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
- ✅ **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
**Strategy:** Use these first, track quota in real-time, fallback to cheap/free when exhausted.
---
## Claude Code (Pro/Max)
### Pricing
| Plan | Monthly Cost | Quota Reset | Models |
|------|--------------|-------------|--------|
| Pro | $20 | 5-hour + Weekly | Opus, Sonnet, Haiku |
| Max | $100 | 5-hour + Weekly | Opus, Sonnet, Haiku |
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard opens → Providers → Connect Claude Code
```
**Step 2: OAuth Login**
- Click "Connect Claude Code"
- Browser opens → Login to Claude.ai
- Auto token refresh enabled
- Quota tracking starts
**Step 3: Use in CLI**
```
Model: cc/claude-opus-4-5-20251101
cc/claude-sonnet-4-5-20250929
cc/claude-haiku-4-5-20251001
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `cc/claude-opus-4-5-20251101` | Claude 4.5 Opus | Complex tasks, architecture |
| `cc/claude-sonnet-4-5-20250929` | Claude 4.5 Sonnet | Balanced speed/quality |
| `cc/claude-haiku-4-5-20251001` | Claude 4.5 Haiku | Fast responses |
### Pro Tips
- **Use Opus for complex tasks** - Architecture decisions, refactoring
- **Use Sonnet for speed** - Quick edits, code generation
- **Track quota per model** - Dashboard shows usage per model
- **5-hour reset** - Fresh quota every 5 hours + weekly reset
---
## OpenAI Codex (Plus/Pro)
### Pricing
| Plan | Monthly Cost | Quota Reset | Models |
|------|--------------|-------------|--------|
| Plus | $20 | 5-hour + Weekly | GPT 5.2, GPT 5.1 |
| Pro | $200 | 5-hour + Weekly | GPT 5.2 Codex, GPT 5.1 Max |
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect Codex
```
**Step 2: OAuth Login**
- Click "Connect Codex"
- Browser opens to `http://localhost:1455`
- Login to OpenAI account
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: cx/gpt-5.2-codex
cx/gpt-5.1-codex-max
cx/gpt-5.2
cx/gpt-5.1-codex
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `cx/gpt-5.2-codex` | GPT 5.2 Codex | Latest coding model |
| `cx/gpt-5.1-codex-max` | GPT 5.1 Codex Max | Maximum context |
| `cx/gpt-5.2` | GPT 5.2 | General tasks |
| `cx/gpt-5.1-codex` | GPT 5.1 Codex | Stable coding |
### Pro Tips
- **5-hour rolling quota** - Fresh quota every 5 hours
- **Weekly reset** - Full quota reset weekly
- **Pro tier** - 10× more quota than Plus
---
## Gemini CLI (FREE 180K/month!)
### Pricing
| Plan | Monthly Cost | Quota | Reset |
|------|--------------|-------|-------|
| FREE | $0 | 180K completions/month + 1K/day | Daily + Monthly |
**Best Value:** Huge free tier! Use this before paid tiers.
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect Gemini CLI
```
**Step 2: Google OAuth**
- Click "Connect Gemini CLI"
- Browser opens → Login to Google account
- Grant permissions
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: gc/gemini-3-flash-preview
gc/gemini-3-pro-preview
gc/gemini-2.5-pro
gc/gemini-2.5-flash
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `gc/gemini-3-flash-preview` | Gemini 3 Flash Preview | Fast responses |
| `gc/gemini-3-pro-preview` | Gemini 3 Pro Preview | Complex tasks |
| `gc/gemini-2.5-pro` | Gemini 2.5 Pro | Stable production |
| `gc/gemini-2.5-flash` | Gemini 2.5 Flash | Quick tasks |
### Pro Tips
- **180K completions/month** - Massive free tier
- **1K/day limit** - Daily quota resets at midnight
- **Use first** - Free tier, use before paid subscriptions
- **No credit card** - Completely free with Google account
---
## GitHub Copilot
### Pricing
| Plan | Monthly Cost | Quota Reset | Models |
|------|--------------|-------------|--------|
| Individual | $10 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
| Business | $19 | Monthly (1st) | GPT-5, Claude 4.5, Gemini 3 |
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect GitHub
```
**Step 2: OAuth via GitHub**
- Click "Connect GitHub"
- Browser opens → Login to GitHub
- Authorize GitHub Copilot
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: gh/gpt-5
gh/gpt-5.1-codex-max
gh/claude-4.5-sonnet
gh/gemini-3-pro
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `gh/gpt-5` | GPT-5 | Latest OpenAI model |
| `gh/gpt-5.1-codex-max` | GPT-5.1 Codex Max | Maximum context |
| `gh/claude-4.5-sonnet` | Claude 4.5 Sonnet | Anthropic quality |
| `gh/gemini-3-pro` | Gemini 3 Pro | Google quality |
### Pro Tips
- **Monthly reset** - Full quota reset on 1st of month
- **Multiple models** - Access GPT, Claude, Gemini in one subscription
- **Business tier** - Higher quota for teams
---
## Antigravity (Google Account)
### Pricing
| Plan | Monthly Cost | Quota | Models |
|------|--------------|-------|--------|
| FREE | $0 | Similar to Gemini CLI | Gemini 3 Pro, Claude Sonnet 4.5 |
### Setup
**Step 1: Connect via Dashboard**
```bash
9router
# Dashboard → Providers → Connect Antigravity
```
**Step 2: Google OAuth**
- Click "Connect Antigravity"
- Browser opens → Login to Google account
- Grant permissions
- Auto token refresh enabled
**Step 3: Use in CLI**
```
Model: ag/gemini-3-pro-high
ag/claude-sonnet-4-5
ag/claude-opus-4-5-thinking
```
### Available Models
| Model ID | Description | Best For |
|----------|-------------|----------|
| `ag/gemini-3-pro-high` | Gemini 3 Pro High | High-quality responses |
| `ag/claude-sonnet-4-5` | Claude Sonnet 4.5 | Anthropic quality |
| `ag/claude-opus-4-5-thinking` | Claude Opus 4.5 Thinking | Complex reasoning |
### Pro Tips
- **Free tier** - No cost with Google account
- **Claude access** - Free Claude Sonnet/Opus
- **Quota similar to Gemini CLI** - Daily/monthly limits
---
## Pricing Comparison
| Provider | Monthly Cost | Quota Reset | Value |
|----------|--------------|-------------|-------|
| **Claude Code Pro** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Best quality |
| **Claude Code Max** | $100 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ Highest quota |
| **Codex Plus** | $20 | 5-hour + Weekly | ⭐⭐⭐⭐ Good value |
| **Codex Pro** | $200 | 5-hour + Weekly | ⭐⭐⭐⭐⭐ 10× quota |
| **Gemini CLI** | **$0** | Daily + Monthly | ⭐⭐⭐⭐⭐ FREE 180K/month! |
| **GitHub Copilot** | $10-19 | Monthly (1st) | ⭐⭐⭐⭐ Multi-model |
| **Antigravity** | **$0** | Daily + Monthly | ⭐⭐⭐⭐ FREE Claude! |
---
## Usage Example
### Cursor IDE Setup
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from 9router dashboard]
Model: cc/claude-opus-4-5-20251101
```
### Create Combo (Recommended)
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. gc/gemini-3-flash-preview (FREE, use first)
2. cc/claude-opus-4-5-20251101 (Subscription)
3. cx/gpt-5.2-codex (Subscription backup)
Use in CLI: premium-coding
```
**Result:** Maximize free tier → Use subscription → Auto fallback
---
## Quota Tracking
9Router tracks quota in real-time:
- **Token consumption** - Input/output tokens per request
- **Reset countdown** - Time until next quota reset
- **Usage percentage** - How much quota used
- **Auto fallback** - Switch to next tier when exhausted
**Dashboard view:**
```
Claude Code Pro
├─ Quota: 75% used
├─ Reset: 2h 15m (5-hour)
├─ Weekly reset: 3 days
└─ Fallback: glm/glm-4.7 (cheap tier)
```
---
## Best Practices
### 1. Use Free Tier First
```
Priority:
1. Gemini CLI (180K/month FREE)
2. Antigravity (FREE Claude)
3. Claude Code/Codex (paid subscriptions)
```
### 2. Track Quota Daily
- Check dashboard every morning
- Plan heavy tasks around quota resets
- Use cheap/free tier for non-critical tasks
### 3. Create Smart Combos
```
Example combo:
1. gc/gemini-3-flash-preview (FREE primary)
2. cc/claude-opus-4-5 (Complex tasks)
3. glm/glm-4.7 (Cheap backup)
4. if/kimi-k2-thinking (FREE fallback)
```
### 4. Optimize by Time
```
Morning: Fresh 5-hour quota (Claude/Codex)
Afternoon: Gemini CLI (1K/day)
Evening: Subscription quota
Night: Cheap/free tier
```
---
## Troubleshooting
### "Quota exhausted"
**Solution:**
- Check dashboard quota tracker
- Wait for reset (5-hour or daily)
- Use combo fallback to cheap/free tier
### "OAuth token expired"
**Solution:**
- Auto-refreshed by 9Router
- If issues: Dashboard → Provider → Reconnect
### "Rate limiting"
**Solution:**
- Subscription quota out
- Add fallback: `cc/claude-opus → glm/glm-4.7`
- Use free tier: `if/kimi-k2-thinking`
---
## Next Steps
- **Setup cheap backup:** [Cheap Providers](./cheap.md)
- **Add free fallback:** [Free Providers](./free.md)
- **Create combos:** Dashboard → Combos → Create New
gitbook/content/en/troubleshooting.md
+351
View File
@@ -0,0 +1,351 @@
# Troubleshooting
Common issues and solutions when using 9Router.
---
## "Language model did not provide messages"
**Problem:** Request fails with empty response or error message.
**Causes:**
- Provider quota exhausted
- API key invalid or expired
- Model not available
**Solutions:**
1. **Check quota status:**
```
Dashboard → Providers → View quota tracker
```
If quota is exhausted, wait for reset or switch provider.
2. **Use combo fallback:**
```
Dashboard → Combos → Create fallback chain
Example: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
```
3. **Verify provider connection:**
```
Dashboard → Providers → Reconnect if needed
```
---
## Rate Limiting
**Problem:** "Rate limit exceeded" or "Too many requests" errors.
**Causes:**
- Subscription quota depleted (5-hour/daily/weekly limits)
- API rate limits hit
- Too many concurrent requests
**Solutions:**
1. **Check reset time:**
```
Dashboard → Quota Tracking → View reset countdown
```
2. **Switch to cheap tier:**
```
Use: glm/glm-4.7 ($0.6/1M tokens)
minimax/MiniMax-M2.1 ($0.20/1M tokens)
```
3. **Add fallback combo:**
```
Dashboard → Combos → Add backup models
Primary: cc/claude-opus (subscription)
Backup: glm/glm-4.7 (cheap)
Emergency: if/kimi-k2 (free)
```
---
## OAuth Token Expired
**Problem:** "Unauthorized" or "Token expired" errors.
**Causes:**
- OAuth token expired (auto-refresh failed)
- Provider session invalidated
- Network issues during refresh
**Solutions:**
1. **Auto-refresh (default):**
9Router automatically refreshes tokens. Wait 30 seconds and retry.
2. **Manual reconnect:**
```
Dashboard → Providers → [Provider Name] → Reconnect
→ Complete OAuth flow again
```
3. **Check provider status:**
Verify provider service is online (Claude Code, Codex, etc.)
---
## High Costs
**Problem:** Unexpected high usage or costs.
**Causes:**
- Using expensive models unnecessarily
- No fallback to cheaper tiers
- Large context windows
**Solutions:**
1. **Check usage stats:**
```
Dashboard → Usage Stats → View token consumption
→ Identify high-cost models
```
2. **Switch to cheaper models:**
```
Replace: cc/claude-opus ($20-100/month subscription)
With: glm/glm-4.7 ($0.6/1M tokens)
minimax/MiniMax-M2.1 ($0.20/1M tokens)
```
3. **Use free tier:**
```
if/kimi-k2-thinking (FREE)
qw/qwen3-coder-plus (FREE)
kr/claude-sonnet-4.5 (FREE)
gc/gemini-3-flash-preview (FREE 180K/month)
```
4. **Optimize prompts:**
- Reduce context size
- Use streaming for long responses
- Cache common prompts
---
## Connection Refused
**Problem:** "ECONNREFUSED" or "Cannot connect to localhost:20128".
**Causes:**
- 9Router not running
- Port 20128 blocked
- Firewall blocking connection
**Solutions:**
1. **Start 9Router:**
```bash
9router
```
Dashboard should open at http://localhost:3000
2. **Verify port 20128:**
```bash
# Check if port is listening
lsof -i :20128
# Or on Windows
netstat -ano | findstr :20128
```
3. **Check firewall:**
- macOS: System Settings → Network → Firewall
- Windows: Windows Defender Firewall → Allow app
- Linux: `sudo ufw allow 20128`
4. **Use cloud endpoint:**
If localhost doesn't work (e.g., Cursor IDE):
```
Endpoint: https://9router.com/v1
```
---
## Dashboard Not Opening
**Problem:** Dashboard doesn't load at http://localhost:3000.
**Causes:**
- Port 3000 already in use
- 9Router crashed
- Browser cache issues
**Solutions:**
1. **Check if 9Router is running:**
```bash
# Check process
ps aux | grep 9router
# Check port 3000
lsof -i :3000
```
2. **Kill conflicting process:**
```bash
# macOS/Linux
lsof -ti:3000 | xargs kill -9
# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
```
3. **Restart 9Router:**
```bash
# Stop
pkill -f 9router
# Start
9router
```
4. **Clear browser cache:**
- Chrome: Ctrl+Shift+Delete → Clear cache
- Try incognito mode
5. **Check firewall settings:**
Ensure port 3000 is not blocked.
---
## Model Not Found
**Problem:** "Model not found" or "Invalid model" errors.
**Causes:**
- Provider not connected
- Model ID typo
- Provider inactive
**Solutions:**
1. **Verify provider connection:**
```
Dashboard → Providers → Check status (green = active)
```
2. **Check model ID format:**
```
Correct: cc/claude-opus-4-5-20251101
Wrong: claude-opus-4-5-20251101
Format: [provider-prefix]/[model-name]
```
3. **List available models:**
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer your-api-key"
```
4. **Reconnect provider:**
```
Dashboard → Providers → [Provider] → Reconnect
```
---
## Slow Response
**Problem:** Requests take too long or timeout.
**Causes:**
- Provider latency
- Network issues
- Large context/response
- Provider rate limiting
**Solutions:**
1. **Check provider status:**
```
Dashboard → Providers → View latency stats
```
2. **Switch to faster model:**
```
Fast: cc/claude-haiku-4-5 (Haiku is faster than Opus)
gc/gemini-3-flash-preview
qw/qwen3-coder-flash
```
3. **Use streaming:**
```json
{
"model": "cc/claude-opus-4-5",
"messages": [...],
"stream": true
}
```
4. **Check network:**
```bash
# Test latency
ping api.anthropic.com
ping api.openai.com
```
5. **Reduce context size:**
- Trim message history
- Use smaller prompts
- Enable context pruning in CLI tool
---
## API Key Invalid
**Problem:** "Invalid API key" or "Authentication failed" errors.
**Causes:**
- Wrong API key copied
- API key expired
- API key not generated
**Solutions:**
1. **Regenerate API key:**
```
Dashboard → Settings → API Keys → Generate New Key
→ Copy and use new key
```
2. **Verify key format:**
```
Correct: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
Wrong: Missing 9r_ prefix
```
3. **Check key in CLI config:**
```bash
# Cursor
Settings → Models → OpenAI API Key
# Cline
Settings → API Key
# Environment variable
export OPENAI_API_KEY="9r_your_key"
```
4. **Test API key:**
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer 9r_your_key"
```
---
## Need More Help?
- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
- **Documentation:** [9router.com/docs](https://9router.com/docs)
- **FAQ:** [faq.md](faq.md)
gitbook/content/es/deployment/cloud.md
+473
View File
@@ -0,0 +1,473 @@
# ☁️ Despliegue en la nube
Despliega 9Router en VPS o Docker para acceso remoto y uso en producción.
---
## 🖥️ Despliegue en VPS
### Requisitos previos
- Ubuntu 20.04+ o distribución Linux similar
- Node.js 20+
- Git
- Acceso root o sudo
### Paso 1: Clonar el repositorio
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
```
### Paso 2: Instalar dependencias
```bash
npm install
```
### Paso 3: Compilar la aplicación
```bash
npm run build
```
### Paso 4: Configurar variables de entorno
Crea un archivo `.env` o exporta variables:
```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"
```
**Variables de entorno:**
| Variable | Por defecto | Descripción |
|----------|---------|-------------|
| `JWT_SECRET` | Auto-generado | **¡DEBE cambiarse en producción!** Usado para firmar tokens JWT |
| `INITIAL_PASSWORD` | `123456` | Contraseña de login del dashboard |
| `DATA_DIR` | `~/.9router` | Ruta de almacenamiento de la base de datos |
| `NODE_ENV` | `development` | Establece a `production` para despliegue |
| `ENABLE_REQUEST_LOGS` | `false` | Habilita logs de debug de request/response |
### Paso 5: Crear el directorio de datos
```bash
sudo mkdir -p /var/lib/9router
sudo chown $USER:$USER /var/lib/9router
```
### Paso 6: Iniciar la aplicación
```bash
npm run start
```
### Paso 7: Configurar PM2 para producción
PM2 mantiene tu aplicación corriendo y la reinicia en caso de crash:
```bash
# Instalar PM2 globalmente
npm install -g pm2
# Iniciar 9Router con PM2
pm2 start npm --name 9router -- start
# Guardar la configuración de PM2
pm2 save
# Configurar PM2 para iniciar al arrancar el sistema
pm2 startup
# Sigue las instrucciones impresas por el comando anterior
```
**Comandos de gestión de PM2:**
```bash
# Ver logs
pm2 logs 9router
# Reiniciar aplicación
pm2 restart 9router
# Detener aplicación
pm2 stop 9router
# Ver estado
pm2 status
# Monitorear recursos
pm2 monit
```
---
## 🐳 Despliegue con Docker
### Opción 1: Usando Dockerfile
Crea un `Dockerfile` en el directorio `app`:
```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"]
```
**Build y Run:**
```bash
# Construir imagen
docker build -t 9router .
# Ejecutar contenedor
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
```
### Opción 2: Docker Compose
Crea `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:
```
**Ejecutar con Docker Compose:**
```bash
# Iniciar servicios
docker-compose up -d
# Ver logs
docker-compose logs -f
# Detener servicios
docker-compose down
# Reconstruir y reiniciar
docker-compose up -d --build
```
---
## 🌐 Proxy reverso con Nginx
### ¿Por qué usar Nginx?
- Terminación SSL/TLS
- Mapeo de nombre de dominio
- Balanceo de carga
- Mejor seguridad
### Paso 1: Instalar Nginx
```bash
sudo apt update
sudo apt install nginx
```
### Paso 2: Configurar Nginx
Crea `/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;
}
}
```
### Paso 3: Habilitar el sitio
```bash
# Crear enlace simbólico
sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
# Probar configuración
sudo nginx -t
# Recargar Nginx
sudo systemctl reload nginx
```
### Paso 4: Configurar SSL con Let's Encrypt
```bash
# Instalar certbot
sudo apt install certbot python3-certbot-nginx
# Obtener certificado SSL
sudo certbot --nginx -d your-domain.com
# La auto-renovación se configura automáticamente
# Probar renovación
sudo certbot renew --dry-run
```
---
## 🔒 Consideraciones de seguridad
### 1. Cambiar credenciales por defecto
**CRÍTICO:** Cambia `JWT_SECRET` y `INITIAL_PASSWORD` antes del despliegue:
```bash
# Generar JWT secret seguro
openssl rand -base64 32
# Usa este valor para JWT_SECRET
export JWT_SECRET="generated-secret-here"
```
### 2. Configuración del firewall
```bash
# Permitir SSH
sudo ufw allow 22/tcp
# Permitir HTTP/HTTPS (si usas Nginx)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Si NO usas proxy reverso, permite los puertos de 9Router
sudo ufw allow 3000/tcp
sudo ufw allow 20128/tcp
# Habilitar firewall
sudo ufw enable
```
### 3. Restringir el acceso al dashboard
Si solo necesitas acceso por API, restringe el puerto del dashboard:
```bash
# Solo permitir acceso localhost al dashboard
sudo ufw deny 3000/tcp
```
Accede al dashboard vía túnel SSH:
```bash
ssh -L 3000:localhost:3000 user@your-server.com
# Luego abre http://localhost:3000 en tu navegador
```
### 4. Actualizaciones regulares
```bash
# Actualizar paquetes del sistema
sudo apt update && sudo apt upgrade -y
# Actualizar 9Router
cd /path/to/9router/app
git pull
npm install
npm run build
pm2 restart 9router
```
### 5. Estrategia de respaldo
```bash
# Respaldar el directorio de datos
tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
# Respaldo automatizado diario (agregar a crontab)
0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
```
---
## 📊 Monitoreo
### Verificar el estado de la aplicación
```bash
# Estado PM2
pm2 status
# Ver logs
pm2 logs 9router --lines 100
# Monitorear recursos
pm2 monit
```
### Logs de Nginx
```bash
# Logs de acceso
sudo tail -f /var/log/nginx/access.log
# Logs de error
sudo tail -f /var/log/nginx/error.log
```
### Recursos del sistema
```bash
# Uso de CPU y memoria
htop
# Uso de disco
df -h
# Conexiones de red
netstat -tulpn | grep -E '3000|20128'
```
---
## 🚨 Solución de problemas
### La aplicación no inicia
```bash
# Verificar logs
pm2 logs 9router
# Verificar si los puertos están en uso
sudo lsof -i :3000
sudo lsof -i :20128
# Verificar variables de entorno
pm2 env 9router
```
### Nginx 502 Bad Gateway
```bash
# Verificar si 9Router está corriendo
pm2 status
# Verificar logs de error de Nginx
sudo tail -f /var/log/nginx/error.log
# Probar configuración de Nginx
sudo nginx -t
```
### El streaming SSE no funciona
Asegúrate de que `proxy_buffering off` esté configurado en Nginx para soporte SSE.
### Errores de permiso denegado
```bash
# Corregir permisos del directorio de datos
sudo chown -R $USER:$USER /var/lib/9router
chmod 755 /var/lib/9router
```
---
## 🔗 Próximos pasos
- [Conectar proveedores](/providers/subscription.md)
- [Configurar combos](/features/combos.md)
- [Integrar con herramientas](/integration/cursor.md)
gitbook/content/es/deployment/localhost.md
+164
View File
@@ -0,0 +1,164 @@
# 🏠 Despliegue en localhost
Ejecuta 9Router en tu máquina local para desarrollo y uso personal.
---
## 📦 Instalación
Instala 9Router globalmente vía npm:
```bash
npm install -g 9router
```
**Requisitos:**
- Node.js 20 o superior
- npm 9 o superior
---
## 🚀 Iniciar el servidor
Inicia 9Router con un solo comando:
```bash
9router
```
El dashboard se abrirá automáticamente en tu navegador en `http://localhost:3000`
**Configuración por defecto:**
- **Dashboard**: `http://localhost:3000`
- **API Endpoint**: `http://localhost:20128/v1`
- **Directorio de datos**: `~/.9router`
---
## 🔧 Configuración
### Directorio de datos personalizado
Establece un directorio de datos personalizado usando una variable de entorno:
```bash
DATA_DIR=/path/to/data 9router
```
### Puerto personalizado
El puerto de API (20128) y el puerto del dashboard (3000) están configurados en la aplicación. Para cambiarlos, necesitarás modificar el código fuente o usar variables de entorno si se soportan.
---
## 🛑 Detener el servidor
Presiona `Ctrl+C` en la terminal donde 9Router se está ejecutando.
```bash
# En la terminal ejecutando 9router
^C # Presiona Ctrl+C
```
El servidor se apagará correctamente y guardará todos los datos.
---
## 🔄 Reiniciar el servidor
Simplemente ejecuta el comando de inicio nuevamente:
```bash
9router
```
Todas tus configuraciones, API keys y combos se preservan en el directorio de datos.
---
## 📊 Actualizar 9Router
Actualiza a la última versión:
```bash
npm update -g 9router
```
Verifica tu versión actual:
```bash
npm list -g 9router
```
---
## 🔍 Solución de problemas
### Puerto ya en uso
Si el puerto 20128 o 3000 ya está en uso:
```bash
# Encontrar proceso usando el puerto (macOS/Linux)
lsof -i :20128
lsof -i :3000
# Matar el proceso
kill -9 <PID>
```
### Errores de permisos
Si encuentras errores de permisos durante la instalación:
```bash
# Usar sudo (no recomendado)
sudo npm install -g 9router
# O corregir los permisos de npm (recomendado)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
### Problemas con el directorio de datos
Si el directorio de datos no es accesible:
```bash
# Verificar permisos
ls -la ~/.9router
# Corregir permisos
chmod 755 ~/.9router
```
---
## 📁 Estructura del directorio de datos
```
~/.9router/
├── db.json # Main database (providers, combos, settings)
├── logs/ # Application logs
└── cache/ # Temporary cache files
```
**Respaldar tus datos:**
```bash
# Respaldo
cp -r ~/.9router ~/.9router.backup
# Restaurar
cp -r ~/.9router.backup ~/.9router
```
---
## 🔗 Próximos pasos
- [Conectar proveedores](/providers/subscription.md)
- [Crear combos](/features/combos.md)
- [Integrar con herramientas CLI](/integration/cursor.md)
gitbook/content/es/faq.md
+387
View File
@@ -0,0 +1,387 @@
# Preguntas frecuentes
Preguntas comunes sobre 9Router.
---
## ¿Qué es 9Router?
**9Router es un router de modelos de IA que maximiza el valor de tu suscripción y minimiza los costos.**
Enruta inteligentemente las solicitudes a través de múltiples proveedores de IA usando un sistema de fallback de 3 niveles:
1. **Nivel de suscripción** - Maximiza las cuotas de Claude Code, Codex, Gemini que ya pagas
2. **Nivel barato** - Alternativas ultra-baratas ($0.20-$0.60 por 1M tokens)
3. **Nivel gratis** - Respaldo de emergencia con modelos gratis ilimitados
**Beneficios clave:**
- Nunca desperdicies la cuota de suscripción
- Fallback automático cuando se agota la cuota
- Seguimiento de cuota en tiempo real
- 90% de ahorro en costos vs uso directo de API
---
## ¿Cómo funciona el precio?
**9Router usa una estrategia de precios de 3 niveles:**
### Nivel 1: Suscripción (Maximiza primero)
- **Claude Code** (Pro/Max): $20-100/mes - Cuota de 5 horas + semanal
- **OpenAI Codex** (Plus/Pro): $20-200/mes - Cuota de 5 horas + semanal
- **Gemini CLI**: GRATIS - 180K completados/mes + 1K/día
- **GitHub Copilot**: $10-19/mes - Reinicio mensual
- **Antigravity**: GRATIS - Similar a Gemini
**Objetivo:** ¡Usa cada bit de cuota antes de que se reinicie!
### Nivel 2: Barato (Respaldo)
- **GLM-4.7**: $0.60/$2.20 por 1M tokens - Reinicio diario 10AM
- **MiniMax M2.1**: $0.20/$1.00 por 1M tokens - 5 horas rolling
- **Kimi K2**: $9/mes plano (10M tokens)
**Objetivo:** ¡90% más barato que ChatGPT API ($20/1M)!
### Nivel 3: Gratis (Emergencia)
- **iFlow**: 8 modelos GRATIS (Kimi K2, Qwen3, GLM, MiniMax...)
- **Qwen**: 3 modelos GRATIS (Qwen3 Coder Plus/Flash, Vision)
- **Kiro**: 2 modelos GRATIS (Claude Sonnet 4.5, Haiku 4.5)
**Objetivo:** ¡Fallback de cero costo cuando todo lo demás está limitado por cuota!
---
## ¿9Router es gratis?
**Sí, 9Router en sí es 100% gratis y open source.**
**Proveedores de nivel gratis disponibles:**
- **Gemini CLI** - 180K completados/mes (cuenta Google GRATIS)
- **iFlow** - 8 modelos ilimitados (OAuth GRATIS)
- **Qwen** - 3 modelos ilimitados (OAuth GRATIS)
- **Kiro** - Claude Sonnet/Haiku (AWS Builder ID GRATIS)
**¡Puedes codificar GRATIS para siempre usando solo proveedores de nivel gratis!**
**Proveedores de pago opcionales:**
- Servicios de suscripción que ya puedes tener (Claude Code, Codex, Copilot)
- Alternativas ultra-baratas ($0.20-$0.60 por 1M tokens)
---
## ¿Qué proveedores son compatibles?
### Proveedores de suscripción
- **Claude Code** (Pro/Max) - Claude 4.5 Opus/Sonnet/Haiku
- **OpenAI Codex** (Plus/Pro) - GPT 5.2 Codex, GPT 5.1 Codex Max
- **Gemini CLI** (GRATIS) - Gemini 3 Flash/Pro, 2.5 Pro/Flash
- **GitHub Copilot** - GPT-5, Claude 4.5, Gemini 3
- **Antigravity** (Google) - Gemini 3 Pro, Claude Sonnet 4.5
### Proveedores baratos
- **GLM** (Zhipu AI) - GLM 4.7, GLM 4.6V Vision
- **MiniMax** - MiniMax M2.1
- **Kimi** (Moonshot AI) - Kimi Latest
- **OpenRouter** - Passthrough a cualquier modelo de OpenRouter
### Proveedores gratis
- **iFlow** - 8 modelos (Kimi K2, Qwen3, GLM, MiniMax, DeepSeek...)
- **Qwen** - 3 modelos (Qwen3 Coder Plus/Flash, Vision)
- **Kiro** - 2 modelos (Claude Sonnet 4.5, Haiku 4.5)
**Total: 15+ proveedores, 50+ modelos**
Consulta la [documentación de proveedores](providers/subscription.md) para más detalles.
---
## ¿Puedo usar múltiples proveedores?
**¡Sí! Esta es la característica principal de 9Router.**
**Los combos te permiten encadenar múltiples proveedores con fallback automático:**
```
Ejemplo de combo: "premium-coding"
1. cc/claude-opus-4-5 (Suscripción principal)
2. glm/glm-4.7 (Respaldo barato)
3. if/kimi-k2 (Emergencia gratis)
→ Cambio automático cuando se agota la cuota
→ Nunca para de codificar
→ Costo extra mínimo
```
**Cómo crear combos:**
```
Dashboard → Combos → Create New
→ Agrega modelos en orden de prioridad
→ Usa el nombre del combo en CLI: "premium-coding"
```
**Beneficios:**
- Cero tiempo de inactividad cuando se agota la cuota
- Optimización automática de costos
- Un solo nombre de modelo para todas las herramientas
Consulta la [documentación de combos](features/combos.md) para ejemplos.
---
## ¿Cómo funciona el seguimiento de cuota?
**9Router rastrea la cuota en tiempo real para todos los proveedores:**
**Características:**
- **Consumo de tokens** - Tokens de entrada/salida por solicitud
- **Cuenta regresiva de reinicio** - Tiempo hasta que se refresca la cuota
- **Estadísticas de uso** - Reportes diarios/semanales/mensuales
- **Estimación de costos** - Gasto proyectado (niveles de pago)
- **Alertas de cuota** - Notificaciones cuando la cuota es baja
**Tipos de cuota:**
- **5 horas rolling** - Claude Code, Codex, MiniMax
- **Reinicio diario** - Gemini CLI (1K/día), GLM (10AM)
- **Reinicio semanal** - Claude Code, Codex (cuota adicional)
- **Reinicio mensual** - Gemini CLI (180K), GitHub Copilot (día 1)
**Ver cuota:**
```
Dashboard → Providers → Quota Tracking
→ Uso en tiempo real + cuenta regresiva de reinicio
```
Consulta la [documentación de seguimiento de cuota](features/quota-tracking.md) para detalles.
---
## ¿9Router funciona con Cursor?
**Sí, pero Cursor requiere un endpoint en la nube.**
**Problema:** Cursor IDE no soporta endpoints en localhost.
**Solución:** Usa el despliegue en la nube de 9Router:
```
Cursor Settings → Models → Advanced:
OpenAI API Base URL: https://9router.com/v1
OpenAI API Key: [desde el dashboard]
Model: cc/claude-opus-4-5-20251101
```
**Alternativa:** Auto-hospéda en VPS con dominio público:
```bash
# Despliega en VPS
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install && npm run build
npm start
# Configura proxy reverso Nginx
# Apunta Cursor a: https://your-domain.com/v1
```
**Otras herramientas CLI funcionan con localhost:**
- Cline ✅
- Claude Desktop ✅
- Codex CLI ✅
- Continue ✅
- RooCode ✅
Consulta la [guía de integración de Cursor](integration/cursor.md) para detalles.
---
## ¿Puedo auto-hospedar 9Router?
**¡Sí! 9Router soporta múltiples opciones de despliegue:**
### Localhost (Por defecto)
```bash
npm install -g 9router
9router
→ Dashboard: http://localhost:3000
→ API: http://localhost:20128/v1
```
### VPS/Cloud
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install && npm run build
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"
npm start
```
### Docker
```bash
docker build -t 9router .
docker run -d \
-p 3000:3000 \
-e JWT_SECRET="your-secret" \
-v 9router-data:/app/data \
9router
```
### Cloudflare Workers
```bash
cd 9router/app
npm run deploy:cloudflare
```
**Variables de entorno:**
- `JWT_SECRET` - **¡DEBE cambiarse en producción!**
- `DATA_DIR` - Ruta de almacenamiento de la base de datos (por defecto: `~/.9router`)
- `INITIAL_PASSWORD` - Login del dashboard (por defecto: `123456`)
- `NODE_ENV` - Establece en `production` para desplegar
Consulta la [guía de despliegue](getting-started/installation.md#deployment) para detalles.
---
## ¿Mis datos están seguros?
**Sí, 9Router prioriza la seguridad y privacidad:**
**Almacenamiento local:**
- Todos los datos se almacenan localmente en `~/.9router` (o `DATA_DIR` personalizado)
- No se envían datos a los servidores de 9Router
- Tokens OAuth cifrados con JWT
**Sin telemetría:**
- Sin seguimiento de uso
- Sin analítica
- Sin phone-home
**Open source:**
- Código fuente completo disponible en GitHub
- Audita la seguridad tú mismo
- Revisado por la comunidad
**Mejores prácticas:**
- Cambia `JWT_SECRET` en producción
- Usa un `INITIAL_PASSWORD` fuerte
- Habilita HTTPS para despliegues en la nube
- Rota las API keys regularmente
**Lo que 9Router almacena:**
- Tokens OAuth de proveedores (cifrados)
- API keys (cifradas)
- Estadísticas de uso (solo locales)
- Configuraciones de combos
**Lo que 9Router NO almacena:**
- Tus prompts o respuestas
- El código que generas
- Información personal
---
## ¿Cómo actualizo 9Router?
**Los métodos de actualización dependen del tipo de instalación:**
### Instalación global NPM
```bash
npm update -g 9router
```
### Instalación local
```bash
cd 9router/app
git pull origin main
npm install
npm run build
npm start
```
### Docker
```bash
docker pull 9router:latest
docker stop 9router
docker rm 9router
docker run -d \
-p 3000:3000 \
-v 9router-data:/app/data \
9router:latest
```
**Verificar versión:**
```bash
9router --version
```
**Cambios disruptivos:**
- Revisa [CHANGELOG.md](https://github.com/decolua/9router/blob/main/CHANGELOG.md)
- Respalda `~/.9router` antes de actualizaciones mayores
- Revisa las guías de migración para versiones mayores
---
## ¿Cómo puedo contribuir?
**¡Damos la bienvenida a las contribuciones!**
### Formas de contribuir:
1. **Reportar bugs:**
- [GitHub Issues](https://github.com/decolua/9router/issues)
- Incluye logs de error, pasos para reproducir
2. **Solicitar características:**
- [GitHub Discussions](https://github.com/decolua/9router/discussions)
- Describe el caso de uso y los beneficios
3. **Enviar código:**
```bash
# Fork del repo
git clone https://github.com/YOUR_USERNAME/9router.git
cd 9router
# Crea una rama
git checkout -b feature/your-feature
# Haz cambios
npm install
npm run dev
# Prueba
npm test
# Commit y push
git add .
git commit -m "Add your feature"
git push origin feature/your-feature
# Crea un Pull Request en GitHub
```
4. **Mejorar docs:**
- Corrige errores tipográficos, agrega ejemplos
- Traduce a otros idiomas
- Escribe tutoriales
5. **Agregar proveedores:**
- Implementa nuevos adaptadores de proveedores
- Consulta `app/lib/providers/` para ejemplos
**Directrices de contribución:**
- Sigue el estilo de código existente
- Agrega tests para nuevas características
- Actualiza la documentación
- Mantén los commits atómicos y descriptivos
Consulta [CONTRIBUTING.md](https://github.com/decolua/9router/blob/main/CONTRIBUTING.md) para detalles.
---
## ¿Necesitas más ayuda?
- **Documentación:** [9router.com/docs](https://9router.com/docs)
- **GitHub:** [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
gitbook/content/es/features/combos.md
+537
View File
@@ -0,0 +1,537 @@
# Combos - Cadenas de fallback personalizadas
Crea combinaciones de modelos personalizadas con fallback automático. Los combos te permiten definir tu propia estrategia de enrutamiento basada en costo, calidad y disponibilidad.
---
## ¿Qué son los combos?
Los combos son **cadenas de fallback personalizadas** que creas en el dashboard. En lugar de usar un solo modelo, defines una secuencia de modelos que 9Router intenta en orden.
**Ejemplo:**
```
Nombre del combo: premium-coding
Modelos:
1. cc/claude-opus-4-5-20251101 (intentar primero)
2. glm/glm-4.7 (si #1 tiene cuota agotada)
3. minimax/MiniMax-M2.1 (si #2 tiene cuota agotada)
```
**Uso en CLI:**
```
Model: premium-coding
```
9Router intenta automáticamente cada modelo en secuencia hasta que uno tenga éxito.
---
## ¿Por qué usar combos?
### 1. Maximiza el valor de la suscripción
```
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
→ Usa la suscripción primero, respaldo barato, emergencia gratis
→ Obtén el valor completo de las suscripciones que ya pagas
```
### 2. Minimiza costos
```
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
→ Comienza con la opción de pago más barata ($0.60/1M)
→ Fallback a una aún más barata ($0.20/1M)
→ Nivel de emergencia gratis
→ Costo total: ~$5-10/mes vs $2000 en ChatGPT API
```
### 3. Garantiza disponibilidad 24/7
```
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7 → if/kimi-k2-thinking
→ Siempre incluye el nivel gratis al final
→ Nunca te quedes sin cuota
→ Codifica en cualquier momento, en cualquier lugar
```
### 4. Optimiza por calidad
```
cc/claude-opus-4-5 → cx/gpt-5.2-codex → gc/gemini-3-pro
→ Mejores modelos primero
→ Fallback a otros modelos premium
→ Mantén alta calidad en toda la cadena de fallback
```
---
## Cómo crear combos
### Paso 1: Abrir el dashboard
```
http://localhost:20128
→ Inicia sesión con tu contraseña
```
### Paso 2: Navegar a Combos
```
Dashboard → Combos → Create New Combo
```
### Paso 3: Configurar el combo
**Nombre del combo:**
```
premium-coding
```
**Descripción (opcional):**
```
Suscripción primero, respaldo barato, emergencia gratis
```
**Seleccionar modelos:**
```
1. cc/claude-opus-4-5-20251101
2. glm/glm-4.7
3. minimax/MiniMax-M2.1
```
**Arrastra para reordenar** - Prioridad de arriba a abajo.
### Paso 4: Guardar
```
Clic en "Save Combo"
→ El combo aparece en la lista de modelos
```
### Paso 5: Usar en CLI
```
Cursor/Cline/Cualquier herramienta:
Model: premium-coding
```
---
## Combos de ejemplo
### Ejemplo 1: Premium Coding (Suscripción → Barato → Gratis)
**Objetivo**: Maximizar el valor de la suscripción, minimizar costos extras.
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101
2. glm/glm-4.7
3. minimax/MiniMax-M2.1
```
**Uso:**
```
Cursor IDE:
Model: premium-coding
```
**Comportamiento:**
```
Mañana (cuota fresca):
Solicitud → cc/claude-opus-4-5 ✅
Tarde (cuota de Claude agotada):
Solicitud → glm/glm-4.7 ✅ (cambio automático)
Noche (cuota de GLM agotada):
Solicitud → minimax/MiniMax-M2.1 ✅ (cambio automático)
```
**Costo mensual (100M tokens):**
```
80M vía Claude Code: $0 (suscripción)
15M vía GLM: $9
5M vía MiniMax: $1
Total: $10 + tu suscripción
```
**Ahorros**: ~99% vs ChatGPT API ($2000).
---
### Ejemplo 2: Combo de presupuesto (Barato → Gratis)
**Objetivo**: Minimizar costos, usar el nivel gratis como respaldo.
```
Dashboard → Combos → Create New
Name: budget-combo
Models:
1. glm/glm-4.7
2. minimax/MiniMax-M2.1
3. if/kimi-k2-thinking
```
**Uso:**
```
Cline:
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
Model: budget-combo
```
**Comportamiento:**
```
Solicitud → glm/glm-4.7
✅ Cuota diaria disponible → Usa GLM ($0.60/1M)
❌ Cuota agotada → Intenta MiniMax ($0.20/1M)
❌ Cuota de MiniMax agotada → Usa iFlow (GRATIS)
```
**Costo mensual (100M tokens):**
```
70M vía GLM: $42
20M vía MiniMax: $4
10M vía iFlow: $0
Total: $46 vs $2000 en ChatGPT API
```
**Ahorros**: 97%.
---
### Ejemplo 3: Combo gratis (Cero costo)
**Objetivo**: 100% gratis, sin costos nunca.
```
Dashboard → Combos → Create New
Name: free-combo
Models:
1. if/kimi-k2-thinking
2. qw/qwen3-coder-plus
3. kr/claude-sonnet-4.5
```
**Uso:**
```
Claude Desktop:
Model: free-combo
```
**Comportamiento:**
```
Solicitud → if/kimi-k2-thinking
✅ Disponible → Usa iFlow
❌ Error → Intenta Qwen
❌ Error → Intenta Kiro
```
**Costo mensual:**
```
100M tokens vía proveedores gratis: $0
Total: $0 para siempre
```
**Caso de uso**: Proyectos personales, aprendizaje, experimentación.
---
### Ejemplo 4: Calidad primero (Solo modelos premium)
**Objetivo**: Mejor calidad, sin fallback barato.
```
Dashboard → Combos → Create New
Name: quality-first
Models:
1. cc/claude-opus-4-5-20251101
2. cx/gpt-5.2-codex
3. gc/gemini-3-pro-preview
```
**Uso:**
```
Codex CLI:
export OPENAI_BASE_URL="http://localhost:20128"
Model: quality-first
```
**Comportamiento:**
```
Solicitud → cc/claude-opus-4-5
❌ Cuota agotada → cx/gpt-5.2-codex
❌ Cuota agotada → gc/gemini-3-pro-preview
❌ Todo agotado → Devuelve error (sin fallback barato)
```
**Caso de uso**: Código crítico de producción, refactoring complejo.
---
### Ejemplo 5: Multi-suscripción (Maximiza todo)
**Objetivo**: Usa todas las suscripciones antes de pagar extra.
```
Dashboard → Combos → Create New
Name: multi-sub
Models:
1. gc/gemini-3-flash-preview (GRATIS 180K/mes)
2. cc/claude-opus-4-5-20251101 (suscripción Pro)
3. cx/gpt-5.2-codex (suscripción Plus)
4. gh/gpt-5 (suscripción Copilot)
5. glm/glm-4.7 (respaldo barato)
6. if/kimi-k2-thinking (emergencia gratis)
```
**Costo mensual (200M tokens):**
```
50M vía Gemini CLI: $0 (nivel gratis)
80M vía Claude Code: $0 (suscripción)
40M vía Codex: $0 (suscripción)
20M vía Copilot: $0 (suscripción)
8M vía GLM: $4.80
2M vía iFlow: $0
Total: $4.80 + suscripciones existentes
```
**Resultado**: Usa 190M tokens de suscripciones, solo $4.80 extra.
---
### Ejemplo 6: Optimización de reinicio de cuota
**Objetivo**: Distribuir el uso según los tiempos de reinicio.
```
Dashboard → Combos → Create New
Name: reset-optimized
Models:
1. cc/claude-opus-4-5 (reinicio 5h, usar mañana)
2. gc/gemini-3-flash (1K/día, usar tarde)
3. glm/glm-4.7 (reinicio diario 10AM, usar noche)
4. minimax/MiniMax-M2.1 (rolling 5h, usar madrugada)
5. if/kimi-k2-thinking (ilimitado, emergencia)
```
**Rutina diaria:**
```
08:00 - 13:00: Claude Code (cuota fresca de 5h)
13:00 - 18:00: Gemini CLI (cuota 1K/día)
18:00 - 22:00: GLM (se reinicia 10AM del día siguiente)
22:00 - 08:00: MiniMax (rolling 5h) o iFlow
```
**Resultado**: Codifica 24/7 con costos mínimos.
---
## Usar combos en herramientas CLI
### Cursor IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [desde el dashboard]
Model: premium-coding
```
### Claude Desktop
Edita `~/.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
```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [desde el dashboard]
Model: free-combo
```
### Solicitud por 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
}'
```
---
## Mejores prácticas
### 1. Siempre incluye el nivel gratis
```
✅ Bueno:
cc/claude-opus → glm/glm-4.7 → if/kimi-k2-thinking
❌ Malo:
cc/claude-opus → glm/glm-4.7
(sin fallback gratis, puede quedarse sin cuota)
```
**Por qué**: Garantiza disponibilidad 24/7, nunca bloqueado por cuota.
### 2. Ordena por costo (Barato a costoso)
```
✅ Bueno:
glm/glm-4.7 → minimax/MiniMax-M2.1 → cc/claude-opus
❌ Malo:
cc/claude-opus → glm/glm-4.7
(desperdicia cuota de suscripción en tareas simples)
```
**Excepción**: Si quieres maximizar el valor de la suscripción, pon la suscripción primero.
### 3. Coincide con los requisitos de calidad
```
Para código de producción:
cc/claude-opus → cx/gpt-5.2-codex → glm/glm-4.7
Para tareas rápidas:
glm/glm-4.7 → if/kimi-k2-thinking
Para experimentación:
if/kimi-k2-thinking → qw/qwen3-coder-plus
```
### 4. Considera los tiempos de reinicio de cuota
```
Combo matutino (cuotas frescas):
cc/claude-opus → cx/gpt-5.2-codex
Combo nocturno (cuotas probablemente agotadas):
glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
```
### 5. Crea múltiples combos para diferentes casos de uso
```
premium-coding: Para tareas complejas
budget-combo: Para tareas simples
free-combo: Para experimentación
quality-first: Para código de producción
```
**Cambia entre combos** según los requisitos de la tarea.
### 6. Monitorea el desempeño del combo
```
Dashboard → Analytics → Combo Usage:
premium-coding:
80% vía cc/claude-opus (bueno, usando suscripción)
15% vía glm/glm-4.7 (respaldo aceptable)
5% vía minimax (fallback raro)
```
**Optimiza**: Si hay demasiado uso de fallback, aumenta la cuota principal o reordena modelos.
---
## Configuración avanzada
### Establecer límites de presupuesto por combo
```
Dashboard → Combos → Edit → Budget:
Daily limit: $5
Monthly limit: $50
```
Cuando se alcanza el límite, 9Router omite los modelos de pago y usa solo el nivel gratis.
### Habilitar/Deshabilitar modelos en un combo
```
Dashboard → Combos → Edit → Models:
✅ cc/claude-opus-4-5 (habilitado)
❌ glm/glm-4.7 (deshabilitado temporalmente)
✅ if/kimi-k2-thinking (habilitado)
```
**Caso de uso**: Deshabilitar temporalmente modelos costosos sin eliminar el combo.
### Clonar un combo existente
```
Dashboard → Combos → Clone "premium-coding"
→ Crea una copia con sufijo "-copy"
→ Modifica y guarda como nuevo combo
```
**Caso de uso**: Crear variaciones para diferentes escenarios.
---
## Solución de problemas
**Problema: El combo no aparece en la lista de modelos**
**Solución:**
1. Refresca el dashboard
2. Verifica que el combo esté guardado (marca verde)
3. Reinicia la herramienta CLI para refrescar la lista de modelos
**Problema: El combo siempre usa el último modelo (nivel gratis)**
**Solución:**
1. Verifica la cuota de los modelos principales (Dashboard → Quota)
2. Verifica que las API keys sean válidas (Dashboard → Providers)
3. Verifica que no se hayan excedido los límites de presupuesto
**Problema: El combo cuesta más de lo esperado**
**Solución:**
1. Dashboard → Analytics → Revisa el uso del combo
2. Verifica si los modelos principales tienen cuota agotada
3. Reordena los modelos (pon los más baratos primero)
4. Establece límites de presupuesto
---
## Relacionado
- [Enrutamiento inteligente](./smart-routing.md) - Cómo funciona el fallback automático
- [Seguimiento de cuota](./quota-tracking.md) - Monitorea uso y costos
gitbook/content/es/features/quota-tracking.md
+687
View File
@@ -0,0 +1,687 @@
# Seguimiento de cuota y monitoreo de uso
Rastrea el consumo de tokens en tiempo real, monitorea los límites de cuota, estima costos y recibe alertas antes de quedarte sin recursos. Nunca desperdicies cuota de suscripción ni excedas los límites de presupuesto.
---
## Resumen
9Router proporciona un seguimiento de cuota integral para todos los proveedores:
- **Consumo de tokens en tiempo real** - Mira los tokens usados por solicitud
- **Límites de cuota y restantes** - Rastrea el uso vs límites
- **Cuenta regresiva de reinicio** - Sabe cuándo se refresca la cuota
- **Estimación de costos** - Calcula el gasto para niveles de pago
- **Reportes mensuales** - Analiza patrones de uso
- **Alertas y notificaciones** - Recibe advertencias antes de los límites
---
## Resumen del dashboard
### Resumen de cuota
```
Dashboard → Home → Quota Overview
┌─────────────────────────────────────────────┐
│ Claude Code (cc/) │
│ ████████████░░░░░░░░ 2.5h / 5h (50%) │
│ Se reinicia en: 2h 30m │
│ Costo: $0 (suscripción) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Gemini CLI (gc/) │
│ ████████░░░░░░░░░░░░ 450 / 1000 (45%) │
│ Reinicio diario en: 18h 30m │
│ Mensual: 45K / 180K (25%) │
│ Costo: $0 (nivel gratis) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ GLM-4.7 (glm/) │
│ ██████████████░░░░░░ 7M / 10M tokens (70%) │
│ Se reinicia: Diario 10:00 AM (en 5h 35m) │
│ Costo hoy: $4.20 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ MiniMax M2.1 (minimax/) │
│ ████████████████░░░░ 4M / 5M tokens (80%) │
│ Ventana rolling 5h │
│ Costo (5h): $0.80 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ iFlow (if/) │
│ ████████████████████ Ilimitado │
│ Costo: $0 (gratis para siempre) │
└─────────────────────────────────────────────┘
```
---
## Consumo de tokens en tiempo real
### Seguimiento por solicitud
Cada solicitud muestra el uso detallado de tokens:
```
Dashboard → Activity → Recent Requests
Request #1234
Model: cc/claude-opus-4-5-20251101
Timestamp: 2026-02-04 04:15:32
Tokens:
Input: 1,250 tokens
Output: 850 tokens
Total: 2,100 tokens
Cost: $0 (cuota de suscripción)
Duration: 3.2s
Status: ✅ Success
```
### Monitor de uso en vivo
```
Dashboard → Live Monitor
Solicitud actual:
Model: glm/glm-4.7
Tokens transmitidos: 450 / ~800 estimados
Costo hasta ahora: $0.0009
Duración: 1.8s
```
### Desglose de tokens por modelo
```
Dashboard → Analytics → Token Usage
Hoy (4 feb 2026):
cc/claude-opus-4-5: 15M tokens ($0, suscripción)
glm/glm-4.7: 8M tokens ($4.80)
if/kimi-k2-thinking: 3M tokens ($0, gratis)
Total: 26M tokens
Costo: $4.80
```
---
## Límites de cuota y tiempos de reinicio
### Proveedores de suscripción
**Claude Code (Pro/Max)**
```
Tipo de cuota: Basado en tiempo (rolling 5 horas)
Límite: 5 horas de uso
Reinicio: Ventana rolling 5 horas + refresh semanal
Seguimiento: Tiempo de uso por modelo
El dashboard muestra:
Opus: 2.5h / 5h usados
Sonnet: 1.2h / 5h usados
Haiku: 0.8h / 5h usados
Reinicio semanal: Todos los lunes 00:00 UTC
```
**OpenAI Codex (Plus/Pro)**
```
Tipo de cuota: Basado en tiempo (rolling 5 horas)
Límite: 5 horas (Plus) / 10 horas (Pro)
Reinicio: Ventana rolling 5 horas + refresh semanal
El dashboard muestra:
GPT-5.2 Codex: 3.5h / 5h usados
Se reinicia en: 1h 30m
```
**Gemini CLI (GRATIS)**
```
Tipo de cuota: Conteo de solicitudes + tokens mensuales
Límite diario: 1,000 solicitudes
Límite mensual: 180,000 completados
Reinicio: Diario 00:00 UTC + Mensual día 1
El dashboard muestra:
Hoy: 450 / 1,000 solicitudes (45%)
Este mes: 45K / 180K completados (25%)
Reinicio diario en: 18h 30m
Reinicio mensual en: 26 días
```
**GitHub Copilot**
```
Tipo de cuota: Uso mensual
Límite: Varía según el plan
Reinicio: 1ro de cada mes
El dashboard muestra:
Uso: 60% de la cuota mensual
Se reinicia: 1 mar 2026 (en 25 días)
```
### Proveedores baratos
**GLM-4.7**
```
Tipo de cuota: Límite diario de tokens
Límite: 10M tokens/día (Coding Plan)
Reinicio: Diario 10:00 AM hora de Beijing (UTC+8)
El dashboard muestra:
Usados: 7M / 10M tokens (70%)
Restantes: 3M tokens
Se reinicia en: 5h 35m
Costo hoy: $4.20
```
**MiniMax M2.1**
```
Tipo de cuota: Ventana rolling 5 horas
Límite: 5M tokens por 5 horas
Reinicio: Ventana rolling continua
El dashboard muestra:
Usados (5h): 4M / 5M tokens (80%)
El uso más antiguo expira en: 45m
Costo (5h): $0.80
```
**Kimi K2**
```
Tipo de cuota: Suscripción mensual
Límite: 10M tokens/mes ($9 plano)
Reinicio: Mensual en la fecha de suscripción
El dashboard muestra:
Usados: 6M / 10M tokens (60%)
Se reinicia: 15 feb 2026 (en 11 días)
Costo: $9/mes (pagado por adelantado)
```
### Proveedores gratis
**iFlow / Qwen / Kiro**
```
Tipo de cuota: Ilimitado (con rate-limit)
Límite: Sin límite duro
Reinicio: N/A
El dashboard muestra:
Usados hoy: 5M tokens
Costo: $0 (gratis para siempre)
Estado: ✅ Disponible
```
---
## Estimación de costos
### Seguimiento de costos en tiempo real
```
Dashboard → Costs → Today
Proveedores de suscripción: $0
Claude Code: 15M tokens ($0, incluido)
Gemini CLI: 3M tokens ($0, nivel gratis)
Proveedores de pago: $4.80
GLM-4.7: 8M tokens ($4.80)
Input: 6M × $0.60/1M = $3.60
Output: 2M × $2.20/1M = $4.40
Total: $4.80
Proveedores gratis: $0
iFlow: 3M tokens ($0)
Total hoy: $4.80
```
### Reporte de gasto mensual
```
Dashboard → Costs → This Month (Febrero 2026)
Semana 1 (1-7 feb):
Suscripción: $0 (80M tokens)
Pago: $15.20 (25M tokens)
Gratis: $0 (10M tokens)
Total: $15.20
Semana 2 (8-14 feb):
Suscripción: $0 (75M tokens)
Pago: $12.80 (20M tokens)
Gratis: $0 (8M tokens)
Total: $12.80
Mes hasta la fecha: $28.00
Proyectado (30 días): ~$120
Desglose por proveedor:
GLM-4.7: $22.00 (78%)
MiniMax M2.1: $6.00 (22%)
Costo promedio por 1M tokens: $0.62
Ahorros vs ChatGPT API: 97% ($4,000 → $120)
```
### Proyección de costos
```
Dashboard → Costs → Projections
Basado en uso de los últimos 7 días:
Promedio diario: 50M tokens
Costo diario: $4.50
Proyección mensual:
Tokens: 1,500M (1.5B)
Costo: $135
Desglose:
Suscripción: 900M tokens ($0)
GLM-4.7: 450M tokens ($90)
MiniMax: 120M tokens ($24)
Gratis: 30M tokens ($0)
Estado del presupuesto:
Límite diario: $5 → 90% usado hoy
Límite mensual: $150 → 90% proyectado
⚠️ Advertencia: Puede exceder el presupuesto mensual
```
---
## Dashboard de uso
### Estadísticas generales
```
Dashboard → Analytics → Overview
Hoy (4 feb 2026):
Solicitudes: 1,234
Tokens: 26M
Costo: $4.80
Tiempo promedio de respuesta: 2.1s
Esta semana:
Solicitudes: 8,456
Tokens: 180M
Costo: $28.00
Tasa de éxito: 99.2%
Este mes:
Solicitudes: 15,234
Tokens: 320M
Costo: $52.00
Modelo principal: cc/claude-opus-4-5 (45%)
```
### Uso por modelo
```
Dashboard → Analytics → Models
Modelos principales (este mes):
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%)
Desglose de costos:
cc/claude-opus: $0 (suscripción)
glm/glm-4.7: $45.00
if/kimi-k2-thinking: $0 (gratis)
minimax/MiniMax-M2.1: $7.00
gc/gemini-3-flash: $0 (gratis)
```
### Uso por tiempo
```
Dashboard → Analytics → Timeline
Uso por hora (hoy):
00:00 - 01:00: 0.5M tokens
01:00 - 02:00: 0.2M tokens
...
08:00 - 09:00: 3.2M tokens (pico)
09:00 - 10:00: 2.8M tokens
...
23:00 - 00:00: 0.8M tokens
Horas pico: 08:00 - 12:00 (codificación matutina)
Horas bajas: 00:00 - 06:00 (noche)
```
### Uso por combo
```
Dashboard → Analytics → Combos
premium-coding:
Solicitudes: 456
Tokens: 12M
Costo: $2.40
Desglose:
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:
Solicitudes: 234
Tokens: 6M
Costo: $1.20
Desglose:
glm/glm-4.7: 4M tokens (67%, $2.40)
if/kimi-k2-thinking: 2M tokens (33%, $0)
```
---
## Alertas y notificaciones
### Alertas de cuota
```
Dashboard → Settings → Alerts
Advertencias de cuota:
✅ Alerta al 80% de cuota usada
✅ Alerta al 90% de cuota usada
✅ Alerta cuando la cuota se agota
✅ Notificar cuando la cuota se reinicia
Entrega:
✅ Notificación del dashboard
✅ Email (opcional)
✅ Webhook (opcional)
```
**Ejemplo de notificaciones:**
```
⚠️ Cuota de Claude Code 80% usada
2.5h restantes (se reinicia en 1h 30m)
⚠️ Cuota de GLM-4.7 90% usada
1M tokens restantes (se reinicia en 5h)
✅ Cuota de Gemini CLI reiniciada
1,000 solicitudes disponibles (límite diario)
```
### Alertas de presupuesto
```
Dashboard → Settings → Budget Alerts
Presupuesto diario: $5
✅ Alerta al 80% ($4)
✅ Alerta al 100% ($5)
✅ Cambio automático al nivel gratis cuando se excede
Presupuesto mensual: $150
✅ Alerta al 50% ($75)
✅ Alerta al 80% ($120)
✅ Alerta al 100% ($150)
```
**Ejemplo de notificaciones:**
```
⚠️ Presupuesto diario 80% usado
$4.00 / $5.00 gastados hoy
⚠️ Presupuesto mensual 50% alcanzado
$75 / $150 gastados este mes
Proyectado: $135 (dentro del presupuesto)
🚨 Presupuesto diario excedido
$5.20 / $5.00 gastados hoy
Cambio automático al nivel gratis
```
### Detección de anomalías de costo
```
Dashboard → Settings → Anomaly Detection
✅ Detectar patrones de gasto inusuales
✅ Alerta en picos de costo (>2× promedio diario)
✅ Advertencia en patrones de agotamiento de cuota
Ejemplo de alerta:
⚠️ Pico de costo detectado
Hoy: $12.50 (2.5× promedio diario)
Razón: Alto uso de GLM-4.7 (20M tokens)
Sugerencia: Verifica si los modelos principales tienen cuota agotada
```
---
## Mejores prácticas
### 1. Monitorea la cuota diariamente
```
Rutina diaria:
1. Revisa el resumen de cuota del dashboard (30 segundos)
2. Revisa los tiempos de reinicio
3. Planifica el uso según la disponibilidad de cuota
```
**Ejemplo:**
```
Revisión matutina:
✅ Claude Code: 5h disponibles (reinicio fresco)
✅ Gemini CLI: 1K solicitudes disponibles
⚠️ GLM-4.7: 2M tokens restantes (se reinicia 10AM)
Acción: Usar Claude Code para el trabajo matutino
```
### 2. Establece límites de presupuesto
```
Dashboard → Settings → Budget:
Diario: $5 (previene gastos excesivos)
Mensual: $150 (alinea con el presupuesto)
```
**Resultado**: Cambio automático al nivel gratis cuando se alcanza el límite.
### 3. Optimiza el uso de combos
```
Dashboard → Analytics → Combos:
Revisa qué modelos se usan más
Ajusta el orden del combo para minimizar costos
```
**Ejemplo:**
```
Actual: cc/claude-opus → glm/glm-4.7
80% vía Claude (bueno)
20% vía GLM ($12/mes)
Optimizado: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
50% vía Gemini (gratis)
40% vía Claude (suscripción)
10% vía GLM ($6/mes)
Ahorros: $6/mes
```
### 4. Rastrea los tiempos de reinicio
```
Dashboard → Quota → Reset Schedule:
Claude Code: 5h rolling + Semanal lunes
Gemini CLI: Diario 00:00 UTC + Mensual día 1
GLM-4.7: Diario 10:00 AM hora Beijing
MiniMax: Ventana rolling 5h
```
**Estrategia**: Usa proveedores cuando la cuota esté fresca.
### 5. Revisa los reportes mensuales
```
Dashboard → Analytics → Monthly Report:
Total de tokens: 1.5B
Costo total: $120
Ahorros: 97% vs ChatGPT API
Insights:
- 60% de uso vía suscripciones ($0)
- 30% vía GLM ($90)
- 10% vía nivel gratis ($0)
Optimización:
- Aumentar el uso de Gemini CLI (gratis)
- Reducir el uso de GLM (costoso)
```
---
## Acceso por API
### Obtener estado de cuota
```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"
}
}
]
}
```
### Obtener estadísticas de uso
```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
}
]
}
```
---
## Solución de problemas
**Problema: La cuota muestra 0% pero las solicitudes fallan**
**Solución:**
1. Verifica la conexión del proveedor (Dashboard → Providers)
2. Verifica que las API keys sean válidas
3. Verifica si el proveedor está caído (página de estado)
4. Intenta reconectar los proveedores OAuth
**Problema: Estimación de costos incorrecta**
**Solución:**
1. Dashboard → Settings → Pricing
2. Verifica que el precio por proveedor coincida con las tarifas actuales
3. Actualiza el precio si el proveedor cambió las tarifas
4. Contacta a soporte si la discrepancia persiste
**Problema: El tiempo de reinicio no se actualiza**
**Solución:**
1. Refresca el dashboard (F5)
2. Verifica que la hora del sistema sea correcta
3. Verifica la configuración de zona horaria
4. Reinicia 9Router si el problema persiste
**Problema: No se reciben alertas**
**Solución:**
1. Dashboard → Settings → Alerts
2. Verifica que la dirección de email sea correcta
3. Revisa la carpeta de spam
4. Prueba la notificación (botón Send Test)
---
## Relacionado
- [Enrutamiento inteligente](./smart-routing.md) - Fallback automático según cuota
- [Combos](./combos.md) - Crea cadenas de fallback personalizadas
gitbook/content/es/features/smart-routing.md
+407
View File
@@ -0,0 +1,407 @@
# Enrutamiento inteligente y fallback automático
9Router enruta automáticamente tus solicitudes a través del mejor proveedor disponible usando un sistema de fallback de 3 niveles. Nunca dejes de codificar debido a límites de cuota o rate-limiting.
---
## Cómo funciona
9Router usa enrutamiento inteligente para maximizar tus suscripciones existentes, minimizar costos y garantizar disponibilidad 24/7:
```
Solicitud → 9Router → Verificar Nivel 1 (Suscripción)
↓ cuota agotada
Verificar Nivel 2 (Barato)
↓ límite de presupuesto
Verificar Nivel 3 (Gratis)
↓
Respuesta
```
### Sistema de fallback de 3 niveles
**Nivel 1: SUSCRIPCIÓN (Primario)**
- Claude Code (Pro/Max)
- OpenAI Codex (Plus/Pro)
- Gemini CLI (GRATIS 180K/mes)
- GitHub Copilot
- Antigravity (Google)
**Objetivo**: Maximizar el valor de las suscripciones que ya pagas.
**Nivel 2: BARATO (Respaldo)**
- GLM-4.7 ($0.60/1M entrada)
- MiniMax M2.1 ($0.20/1M entrada)
- Kimi K2 ($9/mes plano)
**Objetivo**: Respaldo ultra-barato cuando se agota la cuota de suscripción (~90% más barato que ChatGPT API).
**Nivel 3: GRATIS (Emergencia)**
- iFlow (8 modelos)
- Qwen (3 modelos)
- Kiro (Claude GRATIS)
**Objetivo**: Fallback de cero costo para codificación ilimitada.
---
## Cambio automático
9Router monitorea la cuota en tiempo real y cambia de proveedor automáticamente:
### Escenario 1: Cuota de suscripción agotada
```
Solicitud del usuario → cc/claude-opus-4-5
↓ cuota agotada (límite de 5 horas alcanzado)
Cambio automático → glm/glm-4.7
↓ cuota diaria agotada
Cambio automático → minimax/MiniMax-M2.1
↓ cuota de 5 horas agotada
Cambio automático → if/kimi-k2-thinking (GRATIS)
↓
Respuesta entregada ✅
```
**Resultado**: Cero tiempo de inactividad, experiencia sin interrupciones.
### Escenario 2: Rate limiting
```
Solicitud del usuario → cx/gpt-5.2-codex
↓ rate limited (demasiadas solicitudes)
Cambio automático → glm/glm-4.7
↓
Respuesta entregada ✅
```
### Escenario 3: Proveedor no disponible
```
Solicitud del usuario → cc/claude-opus-4-5
↓ error del proveedor (503)
Cambio automático → siguiente modelo disponible
↓
Respuesta entregada ✅
```
---
## Lógica de selección de modelo
9Router selecciona el mejor modelo según:
1. **Disponibilidad de cuota** - Verifica si el proveedor tiene cuota restante
2. **Nivel de costo** - Prefiere suscripción → barato → gratis
3. **Tiempo de reinicio** - Considera cuándo se reinicia la cuota
4. **Salud del proveedor** - Omite proveedores con errores
### Ejemplo de orden de prioridad
Para una solicitud a `cc/claude-opus-4-5`:
```
1. Verificar cuota de Claude Code
✅ Disponible → Usa cc/claude-opus-4-5
❌ Agotada → Continúa al paso 2
2. Verificar nivel de fallback (si está configurado)
✅ Cuota de GLM disponible → Usa glm/glm-4.7
❌ Agotada → Continúa al paso 3
3. Verificar nivel gratis
✅ iFlow disponible → Usa if/kimi-k2-thinking
❌ Todo agotado → Devuelve error de cuota
```
---
## Opciones de configuración
### Configuración del dashboard
**1. Habilitar/Deshabilitar fallback automático**
```
Dashboard → Settings → Smart Routing
→ Toggle "Auto Fallback" ON/OFF
```
- **ON** (por defecto): Cambio automático de nivel
- **OFF**: Modo estricto, devuelve error si el modelo principal no está disponible
**2. Establecer límites de presupuesto**
```
Dashboard → Settings → Budget Control
→ Límite diario: $5
→ Límite mensual: $50
```
Cuando se alcanza el presupuesto, 9Router cambia automáticamente al nivel gratis.
**3. Configurar el orden de fallback**
```
Dashboard → Settings → Fallback Priority
→ Arrastra para reordenar proveedores dentro de cada nivel
```
Ejemplo de orden personalizado:
```
Nivel 1: Gemini CLI → Claude Code → Codex
Nivel 2: MiniMax → GLM → Kimi
Nivel 3: iFlow → Kiro → Qwen
```
**4. Notificaciones de reinicio de cuota**
```
Dashboard → Settings → Notifications
→ Email cuando se reinicia la cuota
→ Alerta cuando se usa 80% de cuota
```
---
## Ejemplos
### Ejemplo 1: Fallback automático básico
**Configuración:**
```
Model: cc/claude-opus-4-5-20251101
Fallback: Auto (3 niveles por defecto)
```
**Comportamiento:**
```
Mañana (cuota fresca):
Solicitud → cc/claude-opus-4-5 ✅
Tarde (cuota agotada):
Solicitud → glm/glm-4.7 ✅ (cambio automático)
Noche (cuota de GLM agotada):
Solicitud → minimax/MiniMax-M2.1 ✅ (cambio automático)
Madrugada (toda la cuota de pago agotada):
Solicitud → if/kimi-k2-thinking ✅ (nivel gratis)
```
**Costo**: ~$5-10/mes extra (en su mayoría cubierto por la suscripción).
### Ejemplo 2: Enrutamiento consciente del presupuesto
**Configuración:**
```
Dashboard → Settings:
Presupuesto diario: $2
Presupuesto mensual: $20
Fallback: Habilitado
```
**Comportamiento:**
```
Día 1-15 (dentro del presupuesto):
Solicitudes → glm/glm-4.7 (nivel barato)
Costo: $1.50/día
Día 16 (presupuesto alcanzado):
Solicitudes → if/kimi-k2-thinking (nivel gratis)
Costo: $0
Mes siguiente (presupuesto se reinicia):
Solicitudes → glm/glm-4.7 nuevamente
```
**Resultado**: Nunca excede $20/mes, siempre disponible.
### Ejemplo 3: Modo solo suscripción
**Configuración:**
```
Dashboard → Settings:
Fallback automático: OFF
Modo estricto: ON
```
**Comportamiento:**
```
Solicitud → cc/claude-opus-4-5
✅ Cuota disponible → Éxito
❌ Cuota agotada → Devuelve error (sin fallback)
```
**Caso de uso**: Cuando solo quieres usar suscripciones de pago, sin costos extras.
### Ejemplo 4: Modo solo gratis
**Configuración:**
```
Model: if/kimi-k2-thinking
Fallback: qw/qwen3-coder-plus → kr/claude-sonnet-4.5
```
**Comportamiento:**
```
Todas las solicitudes → Solo nivel gratis
Costo: $0 para siempre
```
**Caso de uso**: Proyectos personales, aprendizaje, experimentación.
---
## Mejores prácticas
### 1. Maximiza el valor de la suscripción
```
Estrategia:
- Establece modelos de suscripción como Nivel 1
- Monitorea el uso de cuota en el dashboard
- Usa el nivel barato solo cuando la suscripción se agote
```
**Ejemplo de combo:**
```
cc/claude-opus-4-5 → glm/glm-4.7 → if/kimi-k2-thinking
```
### 2. Optimiza por costo
```
Estrategia:
- Usa el nivel gratis de Gemini CLI primero (180K/mes)
- Fallback a GLM/MiniMax (ultra-baratos)
- Emergencia: iFlow (gratis)
```
**Ejemplo de combo:**
```
gc/gemini-3-flash-preview → glm/glm-4.7 → if/kimi-k2-thinking
```
### 3. Optimiza por calidad
```
Estrategia:
- Usa los mejores modelos (Claude Opus, GPT-5.2)
- Fallback a modelos baratos buenos (GLM-4.7)
- Último recurso: Nivel gratis
```
**Ejemplo de combo:**
```
cc/claude-opus-4-5 → cx/gpt-5.2-codex → glm/glm-4.7
```
### 4. Disponibilidad 24/7
```
Estrategia:
- Siempre incluye el nivel gratis en el fallback
- Monitorea los tiempos de reinicio de cuota
- Distribuye el uso entre proveedores
```
**Ejemplo de combo:**
```
cc/claude-opus-4-5 → glm/glm-4.7 → minimax/MiniMax-M2.1 → if/kimi-k2-thinking
```
**Resultado**: Nunca te quedas sin cuota, codifica en cualquier momento.
---
## Estrategia de reinicio de cuota
Planifica tu uso según los tiempos de reinicio de cuota:
| Proveedor | Reinicio de cuota | Estrategia |
|----------|-------------|----------|
| **Claude Code** | 5 horas + semanal | Usar en la mañana, cuota fresca |
| **Codex** | 5 horas + semanal | Usar después de cuota de Claude |
| **Gemini CLI** | Diario (1K) + Mensual (180K) | Usar durante el día |
| **GLM-4.7** | Diario 10:00 AM | Usar en la noche, se reinicia al día siguiente |
| **MiniMax M2.1** | Rolling 5 horas | Usar cuando sea, rastrea ventana rolling |
| **iFlow/Qwen/Kiro** | Sin límite | Respaldo de emergencia |
**Ejemplo de rutina diaria:**
```
08:00 - 13:00: Claude Code (cuota fresca 5h)
13:00 - 18:00: Gemini CLI (cuota 1K/día)
18:00 - 22:00: GLM-4.7 (barato, se reinicia 10AM)
22:00 - 08:00: MiniMax o iFlow (rolling 5h o gratis)
```
---
## Monitoreo y alertas
### Rastreador de cuota del dashboard
```
Dashboard → Quota Overview:
Claude Code: 2.5h / 5h restantes (50%)
Gemini CLI: 450 / 1000 solicitudes hoy
GLM-4.7: 5M / 10M tokens (se reinicia en 8h)
MiniMax: 3M / 5M tokens (rolling 5h)
```
### Notificaciones en tiempo real
```
Dashboard → Notifications:
⚠️ Cuota de Claude Code 80% usada (1h restante)
✅ Cuota de GLM-4.7 reiniciada (10M tokens disponibles)
💰 Presupuesto diario 50% usado ($2.50 / $5)
```
### Analítica de uso
```
Dashboard → Analytics:
Hoy: 50M tokens
- 30M vía Claude Code (suscripción)
- 15M vía GLM-4.7 ($9)
- 5M vía iFlow (gratis)
Costo: $9 (vs $1000 en ChatGPT API)
Ahorros: 99%
```
---
## Solución de problemas
**Problema: "All providers quota exhausted"**
**Solución:**
1. Verifica el rastreador de cuota del dashboard
2. Espera el reinicio de cuota (mira la cuenta regresiva)
3. Agrega el nivel gratis a la cadena de fallback
4. O aumenta el límite de presupuesto
**Problema: "Demasiados cambios de fallback"**
**Solución:**
1. Verifica si el proveedor principal está caído
2. Aumenta los límites de cuota (mejora la suscripción)
3. Usa un modelo principal más barato (GLM en lugar de Claude)
**Problema: "Costos inesperados"**
**Solución:**
1. Dashboard → Analytics → Revisa el uso
2. Establece límites de presupuesto diarios/mensuales
3. Cambia al nivel gratis para tareas no críticas
4. Usa combos con fallback gratis
---
## Relacionado
- [Combos](./combos.md) - Crea cadenas de fallback personalizadas
- [Seguimiento de cuota](./quota-tracking.md) - Monitorea uso y costos
gitbook/content/es/getting-started/installation.md
+478
View File
@@ -0,0 +1,478 @@
# Instalación
Guía detallada de instalación de 9Router con consejos de solución de problemas.
---
## Requisitos
### Requisitos del sistema
- **Node.js**: Versión 20.0.0 o superior
- **npm**: Versión 10.0.0 o superior (viene con Node.js)
- **OS**: macOS, Linux, Windows (WSL recomendado)
- **Espacio en disco**: ~200MB para la instalación
### Verifica tu versión
```bash
node --version
# Debería mostrar v20.x.x o superior
npm --version
# Debería mostrar 10.x.x o superior
```
**¿No tienes Node.js?** Instálalo desde [nodejs.org](https://nodejs.org/)
---
## Métodos de instalación
### Método 1: Instalación global (Recomendado)
Instala 9Router globalmente para usar desde cualquier lugar:
```bash
npm install -g 9router
```
**Iniciar 9Router:**
```bash
9router
```
**Beneficios:**
- ✅ Ejecuta desde cualquier directorio
- ✅ Comando simple: `9router`
- ✅ Auto-actualizaciones con `npm update -g 9router`
### Método 2: Instalación local
Instala en un proyecto específico:
```bash
mkdir my-9router
cd my-9router
npm install 9router
```
**Iniciar 9Router:**
```bash
npx 9router
```
**Beneficios:**
- ✅ Aislado por proyecto
- ✅ Control de versiones por proyecto
- ✅ Sin contaminación del namespace global
### Método 3: Desde el código fuente (Desarrollo)
Clona y compila desde GitHub:
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install
npm run build
npm start
```
**Beneficios:**
- ✅ Últimas características de desarrollo
- ✅ Contribuir al desarrollo
- ✅ Modificaciones personalizadas
---
## Primera ejecución
### Iniciar el servidor
```bash
9router
```
**Qué sucede:**
1. El servidor inicia en `http://localhost:20128`
2. El dashboard se abre automáticamente en el navegador
3. Se crea el directorio de datos en `~/.9router`
4. API key generada automáticamente
### Login del dashboard
**Credenciales por defecto:**
- Contraseña: `123456`
**⚠️ Cambia la contraseña inmediatamente:**
1. Inicia sesión en el dashboard
2. Settings → Change Password
3. Usa una contraseña fuerte
### Obtén tu API key
```
Dashboard → Settings → API Keys
→ Copia tu API key
→ Úsala en herramientas CLI
```
**Ejemplo de formato de API key:**
```
9r_1234567890abcdef1234567890abcdef
```
---
## Verificar la instalación
### Verifica el estado del servidor
```bash
curl http://localhost:20128/health
```
**Respuesta esperada:**
```json
{
"status": "ok",
"version": "1.0.0"
}
```
### Lista los modelos disponibles
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer your-api-key"
```
**Respuesta esperada:**
```json
{
"object": "list",
"data": [
{
"id": "cc/claude-opus-4-5-20251101",
"object": "model",
"created": 1234567890,
"owned_by": "claude-code"
}
]
}
```
### Prueba el 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!"}
]
}'
```
---
## Configuración
### Variables de entorno
Crea un archivo `.env` o establece variables de entorno:
```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"
```
### Directorio de datos
**Ubicación por defecto:** `~/.9router`
**Contenido:**
```
~/.9router/
├── db.json # Database (providers, combos, usage)
├── api-keys.json # API keys
└── logs/ # Request logs (if enabled)
```
**Cambiar ubicación:**
```bash
export DATA_DIR="/custom/path"
9router
```
### Configuración de puerto
**Puerto por defecto:** `20128`
**Cambiar puerto:**
```bash
export PORT="3000"
9router
```
**O usa la línea de comandos:**
```bash
9router --port 3000
```
---
## Solución de problemas
### Puerto ya en uso
**Error:**
```
Error: listen EADDRINUSE: address already in use :::20128
```
**Solución 1: Mata el proceso existente**
```bash
# Encuentra proceso usando el puerto 20128
lsof -i :20128
# Mata el proceso
kill -9 <PID>
```
**Solución 2: Usa otro puerto**
```bash
9router --port 3000
```
### Permiso denegado
**Error:**
```
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
```
**Solución: Usa sudo (no recomendado) o corrige los permisos de npm**
```bash
# Corregir permisos de npm (recomendado)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Luego instalar nuevamente
npm install -g 9router
```
### Versión de Node.js muy antigua
**Error:**
```
Error: The engine "node" is incompatible with this module
```
**Solución: Actualizar Node.js**
```bash
# Usando nvm (recomendado)
nvm install 20
nvm use 20
# O descargar desde nodejs.org
```
### El dashboard no se abre
**Problema:** El dashboard no se abre automáticamente
**Solución 1: Abrir manualmente**
```
http://localhost:20128
```
**Solución 2: Verifica el firewall**
```bash
# macOS: Permitir Node.js en System Preferences → Security
# Linux: Verificar iptables
# Windows: Verificar Windows Firewall
```
### No se puede conectar a proveedores
**Problema:** El login OAuth falla o la API key es inválida
**Solución 1: Verifica la conexión a internet**
```bash
ping google.com
```
**Solución 2: Verifica el estado del proveedor**
- Claude Code: [status.anthropic.com](https://status.anthropic.com)
- OpenAI: [status.openai.com](https://status.openai.com)
- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
**Solución 3: Regenera la API key**
```
Dashboard → Provider → Disconnect → Reconnect
```
### Uso alto de memoria
**Problema:** 9Router usa demasiada RAM
**Solución: Reinicia el servidor**
```bash
# Detener
pkill -f 9router
# Iniciar
9router
```
**O usa PM2 para auto-reinicio:**
```bash
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
```
---
## Opciones de despliegue
### Desarrollo local
```bash
npm install -g 9router
9router
```
**Caso de uso:** Codificación personal, pruebas
### Servidor VPS/Cloud
```bash
# Instalar
npm install -g 9router
# Configurar
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"
# Iniciar con PM2
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
pm2 startup
```
**Caso de uso:** Acceso de equipo, codificación remota
### 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
```
**Caso de uso:** Despliegue containerizado, Kubernetes
### Proxy reverso (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;
}
}
```
**Caso de uso:** HTTPS, dominio personalizado, balanceo de carga
---
## Desinstalación
### Eliminar instalación global
```bash
npm uninstall -g 9router
```
### Eliminar el directorio de datos
```bash
rm -rf ~/.9router
```
### Eliminar la configuración
```bash
# Eliminar variables de entorno del archivo de configuración del shell
nano ~/.bashrc # o ~/.zshrc
# Eliminar exports relacionados con 9router
```
---
## Próximos pasos
- [Guía para empezar](../getting-started.md) - Conecta proveedores y comienza a codificar
- [Características](../features/) - Explora seguimiento de cuota, combos, despliegue
- [Solución de problemas](../troubleshooting.md) - Resuelve problemas comunes
---
## ¿Necesitas ayuda?
- **Sitio web**: [9router.com](https://9router.com)
- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
gitbook/content/es/getting-started/quick-start.md
+247
View File
@@ -0,0 +1,247 @@
# Empezar
Pon en marcha 9Router en 5 minutos y comienza a enrutar solicitudes de IA de forma inteligente.
---
## Inicio rápido
### 1. Instalar
```bash
npm install -g 9router
```
**Requisitos:** Node.js 20+ ([Detalles de instalación](getting-started/installation.md))
### 2. Iniciar
```bash
9router
```
🎉 **El dashboard se abre automáticamente** en `http://localhost:20128`
- Contraseña por defecto: `123456` (cámbiala en el dashboard)
- API key generada automáticamente
- Listo para conectar proveedores
### 3. Conectar proveedores
Tienes 3 formas de conectar proveedores:
#### Opción A: OAuth (Proveedores de suscripción)
**Ideal para:** Claude Code, Codex, Gemini CLI, GitHub Copilot
```
Dashboard → Providers → Connect [Provider]
→ Login OAuth → Refresh automático de token
→ Seguimiento de cuota habilitado
```
**Ejemplo: Claude Code**
1. Clic en "Connect Claude Code"
2. Inicia sesión con tu cuenta de Claude
3. Autoriza 9Router
4. ✅ ¡Listo! Usa el modelo: `cc/claude-opus-4-5-20251101`
#### Opción B: API Key (Proveedores baratos)
**Ideal para:** GLM, MiniMax, Kimi, OpenRouter
```
Dashboard → Providers → Add API Key
→ Selecciona proveedor
→ Pega API key
→ Guardar
```
**Ejemplo: GLM-4.7**
1. Regístrate en [Zhipu AI](https://open.bigmodel.cn/)
2. Obtén la API key del Coding Plan
3. Dashboard → Add API Key → Provider: `glm` → Pega la key
4. ✅ ¡Listo! Usa el modelo: `glm/glm-4.7`
#### Opción C: Proveedores gratis (Sin costo)
**Ideal para:** iFlow, Qwen, Kiro
```
Dashboard → Providers → Connect [Free Provider]
→ Device code u OAuth
→ Uso ilimitado
```
**Ejemplo: iFlow**
1. Clic en "Connect iFlow"
2. Inicia sesión con tu cuenta de iFlow
3. Autoriza
4. ✅ ¡Listo! Usa 8 modelos: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
---
## 4. Usar en herramientas CLI
Apunta tu herramienta de codificación a 9Router:
### Cursor IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [desde el dashboard de 9router]
Model: cc/claude-opus-4-5-20251101
```
### Claude Desktop
Edita `~/.claude/config.json`:
```json
{
"anthropic_api_base": "http://localhost:20128/v1",
"anthropic_api_key": "your-9router-api-key"
}
```
### Cline / Continue / RooCode
```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [desde el dashboard]
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. Crear combos inteligentes (Opcional)
Los combos habilitan el fallback automático entre modelos:
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101 (Suscripción principal)
2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
3. if/kimi-k2-thinking (Fallback gratis)
Usar en CLI: premium-coding
```
**Cómo funciona:**
1. Intenta primero Claude Opus (tu suscripción)
2. Si la cuota se agota → GLM-4.7 (ultra-barato)
3. Si llega al límite de presupuesto → iFlow (gratis)
4. ¡Cero tiempo de inactividad, cambio automático!
---
## Modelos disponibles
### Modelos de suscripción (Maximiza primero)
**Claude Code (`cc/`)** - Suscripción 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/`)** - Suscripción 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/`)** - GRATIS 180K/mes:
- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
**GitHub Copilot (`gh/`)** - Suscripción:
- `gh/gpt-5` - GPT-5
- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
### Modelos baratos (Respaldo)
**GLM (`glm/`)** - $0.6/$2.2 por 1M:
- `glm/glm-4.7` - GLM 4.7 (reinicio diario 10AM)
**MiniMax (`minimax/`)** - $0.20/$1.00 por 1M:
- `minimax/MiniMax-M2.1` - MiniMax M2.1 (reinicio 5h)
**Kimi (`kimi/`)** - $9/mes (10M tokens):
- `kimi/kimi-latest` - Kimi Latest
### Modelos GRATIS (Emergencia)
**iFlow (`if/`)** - 8 modelos GRATIS:
- `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 modelos GRATIS:
- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
**Kiro (`kr/`)** - 2 modelos GRATIS:
- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
- `kr/claude-haiku-4.5` - Claude Haiku 4.5
---
## Estrategia de optimización de costos
### Presupuesto mensual: $10-20/mes
```
1. Usa el nivel gratis de Gemini CLI (180K/mes) para tareas rápidas
2. Usa la cuota de suscripción de Claude Code al máximo (ya pagas)
3. Fallback a GLM ($0.6/1M) cuando se agote la cuota
4. Emergencia: MiniMax M2.1 ($0.20/1M) o iFlow (gratis)
Ejemplo real (100M tokens/mes):
60M vía Gemini CLI: $0 (nivel gratis)
30M vía Claude Code: $0 (suscripción que ya tienes)
8M vía GLM: $4.80
2M vía MiniMax: $0.40
Total: $5.20/mes + suscripciones existentes
```
### Estrategia de reinicio de cuota
```
Rutina diaria:
1. Mañana: Cuota fresca de Claude Code (reinicio 5h)
2. Tarde: Cambia a Gemini CLI (1K/día)
3. Noche: Cuota diaria de GLM (reinicio 10AM del día siguiente)
4. Madrugada: MiniMax (rolling 5h) o iFlow (gratis)
→ ¡Codifica 24/7 con costo extra mínimo!
```
---
## Próximos pasos
- [Detalles de instalación](getting-started/installation.md) - Requisitos, troubleshooting
- [Características](features/) - Explora seguimiento de cuota, combos, despliegue
- [FAQ](faq.md) - Preguntas y respuestas comunes
- [Troubleshooting](troubleshooting.md) - Soluciona problemas comunes
---
## ¿Necesitas ayuda?
- **Sitio web**: [9router.com](https://9router.com)
- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
gitbook/content/es/index.md
+164
View File
@@ -0,0 +1,164 @@
# Bienvenido a 9Router
**Usa Claude, Codex, Gemini GRATIS • Alternativas ultra-baratas desde $0.20/1M tokens**
9Router es un router de modelos de IA que maximiza el valor de tus suscripciones y minimiza los costos mediante enrutamiento inteligente y fallback automático.
---
## ¿Qué es 9Router?
9Router es un proxy inteligente que se sitúa entre tus herramientas de codificación (Cursor, Cline, Claude Desktop) y los proveedores de IA. Enruta automáticamente las solicitudes al mejor modelo disponible según la cuota, el costo y la disponibilidad.
**Deja de desperdiciar dinero:**
- ❌ La cuota de suscripción expira sin usar cada mes
- ❌ Los límites de tasa te detienen a mitad de la codificación
- ❌ APIs costosas ($20-50/mes por proveedor)
- ❌ Cambio manual entre proveedores
**Empieza a maximizar el valor:**
- ✅ **Maximiza tus suscripciones** - Rastrea y usa cada bit de cuota de Claude Code, Codex, Gemini
- ✅ **GRATIS disponible** - Accede a modelos iFlow, Qwen, Kiro vía CLI
- ✅ **Respaldo ultra-barato** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
- ✅ **Fallback inteligente** - Suscripción → Barato → Gratis, cambio automático
---
## Características clave
### 🔄 Fallback inteligente de 3 niveles
```
Configura una vez, nunca dejes de codificar:
Nivel 1 (SUSCRIPCIÓN): Claude Code → Codex → Gemini
↓ cuota agotada
Nivel 2 (BARATO): GLM-4.7 → MiniMax M2.1 → Kimi
↓ límite de presupuesto
Nivel 3 (GRATIS): iFlow → Qwen → Kiro
→ Cambio automático, sin tiempo de inactividad!
```
### 📊 Seguimiento de cuota
- Consumo de tokens en tiempo real por proveedor
- Cuenta regresiva de reinicio (5 horas, diario, semanal, mensual)
- Estimación de costos para niveles de pago
- Reportes de gasto mensual
### 🎯 Soporte universal de CLI
Funciona con cualquier herramienta que soporte endpoints personalizados de OpenAI:
✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Cualquier herramienta compatible con OpenAI**
### 💰 Optimización de costos
**Ejemplo real (100M tokens/mes):**
```
60M vía Gemini CLI: $0 (nivel gratis)
30M vía Claude Code: $0 (suscripción que ya tienes)
8M vía GLM: $4.80
2M vía MiniMax: $0.40
Total: $5.20/mes vs $2000 en ChatGPT API!
```
---
## ¿Por qué elegir 9Router?
### Maximiza tus suscripciones
¿Ya pagas Claude Code ($20-100/mes) o Codex ($20-200/mes)? Obtén el valor completo:
- Rastrea el uso de cuota en tiempo real
- Cambio automático cuando se reinicia la cuota (5 horas, semanal)
- Usa cada token antes de que expire
- Gemini CLI: 180K completados/mes **GRATIS**
### Respaldo ultra-barato
Cuando se agota la cuota de suscripción, paga centavos:
| Proveedor | Costo por 1M tokens | Reinicio |
|----------|-------------------|-------|
| **GLM-4.7** | $0.60 entrada / $2.20 salida | Diario 10:00 AM |
| **MiniMax M2.1** | $0.20 entrada / $1.00 salida | 5 horas rolling |
| **Kimi K2** | $9/mes (10M tokens) | Mensual |
**~90% más barato que ChatGPT API ($20/1M)!**
### Fallback gratis para siempre
Respaldo de emergencia cuando todo lo demás está limitado por cuota:
- **iFlow**: 8 modelos (Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2)
- **Qwen**: 3 modelos (Qwen3 Coder Plus/Flash, Vision)
- **Kiro**: Claude Sonnet 4.5, Haiku 4.5 (AWS Builder ID)
---
## Inicio rápido
Comienza en 2 minutos:
```bash
# Instala globalmente
npm install -g 9router
# Inicia (el dashboard se abre automáticamente)
9router
```
🎉 **Se abre el dashboard** → Conecta proveedores → ¡Empieza a codificar!
**Úsalo en tu herramienta CLI:**
```
Endpoint: http://localhost:20128/v1
API Key: [desde el dashboard]
Model: cc/claude-opus-4-5-20251101
```
[→ Guía completa para empezar](getting-started.md)
---
## Casos de uso
### Para desarrolladores individuales
- Maximiza tu suscripción de Claude Code/Codex
- Usa el nivel gratis de Gemini CLI (180K/mes)
- Fallback a modelos ultra-baratos ($0.20/1M)
- Codifica 24/7 sin límites de tasa
### Para equipos
- Despliega en VPS/Cloud para acceso compartido
- Rastrea el gasto del equipo en tiempo real
- Establece límites de presupuesto por nivel
- Gestión centralizada de proveedores
### Para codificación móvil/remota
- Usa el despliegue en la nube (https://9router.com)
- Accede desde iPad, teléfono, donde sea
- Sin limitaciones de localhost
- Red edge de Cloudflare (300+ ubicaciones)
---
## ¿Qué sigue?
- [Empezar](getting-started.md) - Instala y configura en 5 minutos
- [Guía de instalación](getting-started/installation.md) - Instrucciones detalladas
- [Características](features/) - Explora todas las capacidades
- [FAQ](faq.md) - Preguntas comunes
---
<div align="center">
<sub>Construido con ❤️ para desarrolladores que maximizan el valor de la IA</sub>
</div>
gitbook/content/es/integration/claude-code.md
+109
View File
@@ -0,0 +1,109 @@
# Integración con Claude Code
Integra 9Router con Claude Code CLI para enrutar tus solicitudes de la API de Anthropic a través del sistema de enrutamiento inteligente de 9Router.
## Requisitos previos
- Claude Code CLI instalado
- 9Router ejecutándose localmente o endpoint en la nube configurado
- API key del dashboard de 9Router
## Configuración
### 1. Configurar variables de entorno
Establece las siguientes variables de entorno en tu archivo de configuración del shell (`~/.bashrc`, `~/.zshrc`, o `~/.bash_profile`):
```bash
# Base URL for 9Router
export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
# Optional: Set default models for aliases
export ANTHROPIC_DEFAULT_OPUS_MODEL="cc/claude-opus-4-5-20251101"
export ANTHROPIC_DEFAULT_SONNET_MODEL="cc/claude-sonnet-4-5-20250929"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="cc/claude-haiku-4-5-20251001"
```
### 2. Recargar la configuración del shell
```bash
source ~/.zshrc # o ~/.bashrc
```
### 3. Verificar la configuración
Verifica que las variables de entorno estén configuradas correctamente:
```bash
echo $ANTHROPIC_BASE_URL
```
## Aliases de modelos
Claude Code soporta los siguientes aliases de modelos que mapean a modelos de 9Router:
| Alias | Modelo | Variable de entorno |
|-------|-------|---------------------|
| `opus` | Claude Opus 4.5 | `ANTHROPIC_DEFAULT_OPUS_MODEL` |
| `sonnet` | Claude Sonnet 4.5 | `ANTHROPIC_DEFAULT_SONNET_MODEL` |
| `haiku` | Claude Haiku 4.5 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` |
## Ejemplos de uso
### Usando aliases de modelos
```bash
# Usar modelo Opus
claude --model opus "Explain quantum computing"
# Usar modelo Sonnet
claude --model sonnet "Write a Python function"
# Usar modelo Haiku
claude --model haiku "Quick code review"
```
### Usando nombres completos de modelos
```bash
claude --model cc/claude-opus-4-5-20251101 "Your prompt here"
```
## Archivo de configuración
Claude Code almacena su configuración en `~/.claude/settings.json`. Puedes editar este archivo manualmente si es necesario:
```json
{
"baseUrl": "http://localhost:20128/v1",
"defaultModel": "sonnet"
}
```
## Solución de problemas
### Problemas de conexión
Si encuentras errores de conexión:
1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
2. Verifica que las variables de entorno estén configuradas correctamente
3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
### Modelo no encontrado
Si obtienes errores de "modelo no encontrado":
1. Verifica que el nombre del modelo coincida con tu configuración de 9Router
2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
## Endpoint en la nube
Para usar el endpoint en la nube de 9Router en lugar de localhost:
```bash
export ANTHROPIC_BASE_URL="https://9router.com"
```
Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router.
gitbook/content/es/integration/cline.md
+201
View File
@@ -0,0 +1,201 @@
# Integración con Cline
Integra 9Router con la extensión Cline de VSCode para enrutar tus solicitudes de IA a través del sistema de enrutamiento inteligente de 9Router.
## Requisitos previos
- Visual Studio Code instalado
- Extensión Cline instalada desde el marketplace de VSCode
- 9Router ejecutándose localmente o endpoint en la nube configurado
- API key del dashboard de 9Router
## Configuración
### 1. Abrir la configuración de Cline
1. Abre Visual Studio Code
2. Abre el panel de la extensión Cline (clic en el ícono de Cline en la barra lateral)
3. Clic en el ícono de **Settings** (engranaje) en el panel de Cline
### 2. Seleccionar el proveedor de API
1. En la configuración de Cline, encuentra el dropdown **API Provider**
2. Selecciona **Ollama** de la lista
- Nota: Usamos el tipo de proveedor Ollama porque es compatible con APIs estilo OpenAI
### 3. Configurar Base URL
Establece la URL base a tu endpoint de 9Router:
**Para 9Router local:**
```
http://localhost:20128/v1
```
**Para 9Router en la nube:**
```
https://9router.com
```
**Pasos:**
1. En el campo **Base URL**, ingresa tu endpoint de 9Router
2. Asegúrate de incluir `/v1` al final
### 4. Agregar API Key
1. En el campo **API Key**, ingresa tu API key de 9Router
2. Puedes encontrar tu API key en el dashboard de 9Router en **Settings → API Keys**
3. La key debe comenzar con `sk-9router-`
### 5. Seleccionar modelo
1. En el dropdown **Model**, puedes:
- Seleccionar de los modelos disponibles (si Cline los auto-detecta)
- Ingresar manualmente el nombre del modelo desde tu configuración de 9Router
2. Nombres comunes de modelos:
- `gpt-4`
- `gpt-4o`
- `claude-opus-4-5`
- `claude-sonnet-4-5`
- `gemini-2.0-flash`
### 6. Guardar la configuración
Clic en **Save** o cierra el panel de configuración. Cline guardará automáticamente tu configuración.
## Ejemplo de configuración
Tu configuración de Cline debería verse así:
```
API Provider: Ollama
Base URL: http://localhost:20128/v1
API Key: sk-9router-xxxxxxxxxxxxx
Model: gpt-4
```
## Modelos disponibles
Puedes usar cualquier modelo configurado en tu dashboard de 9Router. Ejemplos comunes:
| Nombre del modelo | Proveedor | Descripción |
|------------|----------|-------------|
| `gpt-4` | OpenAI | GPT-4 Turbo |
| `gpt-4o` | OpenAI | GPT-4 Optimized |
| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
## Uso
### Chat con IA
1. Abre el panel de Cline en VSCode
2. Escribe tu mensaje en el input del chat
3. Presiona Enter para enviar
4. Cline usará 9Router para procesar tu solicitud
### Generación de código
1. Pide a Cline que genere código: "Create a React component for a login form"
2. Cline generará código usando 9Router
3. Revisa y acepta el código generado
### Explicación de código
1. Selecciona código en tu editor
2. Pregunta a Cline: "Explain this code"
3. Obtén explicaciones potenciadas por IA a través de 9Router
### Operaciones con archivos
1. Pide a Cline que cree, modifique o elimine archivos
2. Cline usará 9Router para entender el contexto y hacer cambios
3. Revisa los cambios antes de aceptar
## Solución de problemas
### Error "Connection Failed"
1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
2. Verifica que la URL base sea correcta e incluya `/v1`
3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
4. Intenta reiniciar VSCode
### Error "Invalid API Key"
1. Verifica tu API key en el dashboard de 9Router
2. Asegúrate de haber copiado la key completa incluyendo el prefijo `sk-9router-`
3. Verifica que la API key no haya expirado
4. Intenta regenerar una nueva API key
### Error "Model Not Found"
1. Verifica que el nombre del modelo coincida exactamente con tu configuración de 9Router
2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
4. Intenta usar el nombre completo del modelo (ej. `openai/gpt-4` en lugar de `gpt-4`)
### Cline no responde
1. Revisa el panel de output de Cline para mensajes de error
2. Verifica que tu instancia de 9Router esté ejecutándose y saludable
3. Intenta recargar la ventana de VSCode (Cmd/Ctrl + Shift + P → "Reload Window")
4. Revisa los logs de 9Router para cualquier error
## Configuración avanzada
### Usar endpoint en la nube
Para usar el endpoint en la nube de 9Router en lugar de localhost:
1. En la configuración de Cline, establece Base URL a: `https://9router.com`
2. Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router
3. Asegúrate de que tu endpoint en la nube esté activo y accesible
### Múltiples modelos
Puedes cambiar rápidamente entre modelos:
1. Abre la configuración de Cline
2. Cambia el campo **Model** a otro modelo
3. Guarda y continúa chateando con el nuevo modelo
### Timeout personalizado
Si experimentas problemas de timeout con solicitudes grandes:
1. Abre la configuración de VSCode (Cmd/Ctrl + ,)
2. Busca "Cline timeout"
3. Aumenta el valor de timeout (por defecto suele ser 30 segundos)
## Mejores prácticas
1. **Usa modelos apropiados**: Elige modelos rápidos (como Haiku o Flash) para tareas simples, y modelos más potentes (como Opus o GPT-4) para tareas complejas
2. **Monitorea el uso**: Revisa el dashboard de 9Router para estadísticas de uso y costos
3. **Gestión de contexto**: Mantén tus conversaciones enfocadas para reducir el uso de tokens
4. **Cambio de modelo**: Cambia modelos según la complejidad de la tarea para optimizar costo y rendimiento
5. **Seguridad de API Key**: Nunca subas tu API key al control de versiones
## Integración con características de 9Router
### Enrutamiento de modelos
9Router enruta automáticamente tus solicitudes al mejor proveedor disponible según:
- Disponibilidad del modelo
- Estado de salud del proveedor
- Optimización de costos
- Balanceo de carga
### Soporte de fallback
Si un proveedor falla, 9Router automáticamente cambia a proveedores alternativos configurados en tu dashboard.
### Seguimiento de uso
Monitorea tu uso de Cline a través del dashboard de 9Router:
- Total de solicitudes
- Uso de tokens
- Costo por modelo
- Distribución por proveedor
gitbook/content/es/integration/codex.md
+136
View File
@@ -0,0 +1,136 @@
# Integración con OpenAI Codex CLI
Integra 9Router con OpenAI Codex CLI para enrutar tus solicitudes de la API de OpenAI a través del sistema de enrutamiento inteligente de 9Router.
## Requisitos previos
- OpenAI Codex CLI instalado
- 9Router ejecutándose localmente o endpoint en la nube configurado
- API key del dashboard de 9Router
## Configuración
### 1. Configurar variables de entorno
Establece las siguientes variables de entorno en tu archivo de configuración del shell (`~/.bashrc`, `~/.zshrc`, o `~/.bash_profile`):
```bash
# Base URL for 9Router
export OPENAI_BASE_URL="http://localhost:20128/v1"
# API Key from 9Router dashboard
export OPENAI_API_KEY="your-9router-api-key"
```
### 2. Recargar la configuración del shell
```bash
source ~/.zshrc # o ~/.bashrc
```
### 3. Verificar la configuración
Verifica que las variables de entorno estén configuradas correctamente:
```bash
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY
```
## Modelos disponibles
9Router proporciona los siguientes modelos de Codex:
| ID del modelo | Descripción |
|----------|-------------|
| `cx/gpt-5.2-codex` | GPT-5.2 Codex - Última versión |
| `cx/gpt-5.1-codex-max` | GPT-5.1 Codex Max - Contexto extendido |
## Ejemplos de uso
### Uso básico
```bash
# Usar GPT-5.2 Codex
codex --model cx/gpt-5.2-codex "Write a function to sort an array"
# Usar GPT-5.1 Codex Max
codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"
```
### Generación de código
```bash
codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"
```
### Explicación de código
```bash
codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"
```
## Archivo de configuración
También puedes configurar Codex CLI usando un archivo de configuración. Crea o edita `~/.codex/config.json`:
```json
{
"baseUrl": "http://localhost:20128/v1",
"apiKey": "your-9router-api-key",
"defaultModel": "cx/gpt-5.2-codex"
}
```
## Solución de problemas
### Errores de autenticación
Si encuentras errores de autenticación:
1. Verifica que tu API key sea correcta en el dashboard de 9Router
2. Verifica que la variable de entorno `OPENAI_API_KEY` esté configurada
3. Asegúrate de que la API key no haya expirado
### Problemas de conexión
Si encuentras errores de conexión:
1. Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
2. Verifica que las variables de entorno estén configuradas correctamente
3. Asegúrate de que ningún firewall esté bloqueando el puerto 20128
### Modelo no disponible
Si obtienes errores de "modelo no disponible":
1. Verifica que el nombre del modelo coincida con tu configuración de 9Router
2. Verifica que la conexión del proveedor de OpenAI esté activa en el dashboard de 9Router
3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
## Endpoint en la nube
Para usar el endpoint en la nube de 9Router en lugar de localhost:
```bash
export OPENAI_BASE_URL="https://9router.com"
```
Asegúrate de haber configurado tu API key en el dashboard en la nube de 9Router.
## Configuración avanzada
### Timeout personalizado
```bash
export OPENAI_TIMEOUT=60 # segundos
```
### Modo debug
Habilita el modo debug para ver logs detallados de request/response:
```bash
export CODEX_DEBUG=true
codex --model cx/gpt-5.2-codex "Your prompt"
```
gitbook/content/es/integration/continue.md
+249
View File
@@ -0,0 +1,249 @@
# Integración con la extensión Continue de VSCode
Integra 9Router con la extensión Continue para llevar la asistencia de IA directamente a Visual Studio Code.
## Requisitos previos
- Visual Studio Code instalado
- Extensión Continue instalada desde el marketplace de VSCode
- API key de 9Router desde el [dashboard](https://9router.com/dashboard)
- 9Router ejecutándose (local o en la nube)
## Pasos de configuración
### 1. Abrir la configuración de Continue
1. Abre VSCode
2. Presiona `Cmd+Shift+P` (Mac) o `Ctrl+Shift+P` (Windows/Linux)
3. Escribe "Continue: Open Config" y selecciónalo
4. Esto abre `~/.continue/config.json`
### 2. Agregar configuración de modelo de 9Router
Agrega la siguiente configuración a tu `config.json`:
**Configuración de un solo modelo:**
```json
{
"models": [
{
"title": "9Router - Claude Opus",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
}
]
}
```
**Configuración de múltiples modelos:**
```json
{
"models": [
{
"title": "9Router - Claude Opus (Best)",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - Claude Sonnet (Balanced)",
"provider": "openai",
"model": "cc/claude-sonnet-4-20250514",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - DeepSeek Chat (Code)",
"provider": "openai",
"model": "cx/deepseek-chat",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
},
{
"title": "9Router - Claude Haiku (Fast)",
"provider": "openai",
"model": "cc/claude-haiku-4-20250514",
"apiKey": "your-api-key-from-dashboard",
"apiBase": "http://localhost:20128/v1"
}
]
}
```
**Para 9Router en la nube:**
Reemplaza `apiBase` con:
```json
"apiBase": "https://9router.com/v1"
```
### 3. Guardar y recargar
1. Guarda el archivo de configuración
2. Recarga la ventana de VSCode: `Cmd+Shift+P` → "Developer: Reload Window"
3. La extensión Continue cargará la nueva configuración
### 4. Seleccionar modelo
1. Abre la barra lateral de Continue (clic en el ícono de Continue en el panel izquierdo)
2. Clic en el dropdown selector de modelo en la parte superior
3. Elige tu modelo preferido de 9Router
## Modelos disponibles
### Modelos Claude (Anthropic)
- `cc/claude-opus-4-5-20251101` - El más capaz, ideal para tareas complejas
- `cc/claude-sonnet-4-20250514` - Rendimiento y velocidad equilibrados
- `cc/claude-haiku-4-20250514` - El más rápido, bueno para tareas simples
### Modelos DeepSeek
- `cx/deepseek-chat` - Excelente para generación de código
- `cx/deepseek-reasoner` - Mejor para resolución de problemas complejos
### Modelos GLM (Zhipu AI)
- `glm/glm-4-plus` - Chino e inglés avanzado
- `glm/glm-4-flash` - Respuestas rápidas
## Ejemplos de uso
### Explicación de código
1. Selecciona código en el editor
2. Abre la barra lateral de Continue
3. Escribe: "Explain this code"
4. Modelo: `cc/claude-sonnet-4-20250514`
### Generación de código
1. Abre la barra lateral de Continue
2. Escribe: "Create a React component for user profile card"
3. Modelo: `cx/deepseek-chat`
### Refactorización
1. Selecciona código para refactorizar
2. Escribe: "Refactor this to use async/await"
3. Modelo: `cc/claude-sonnet-4-20250514`
### Corrección de bugs
1. Selecciona código problemático
2. Escribe: "Find and fix the bug in this code"
3. Modelo: `cx/deepseek-reasoner`
## Configuración avanzada
### Prompts de sistema personalizados
Agrega prompts de sistema personalizados para comportamientos específicos:
```json
{
"models": [
{
"title": "9Router - Code Expert",
"provider": "openai",
"model": "cx/deepseek-chat",
"apiKey": "your-api-key",
"apiBase": "http://localhost:20128/v1",
"systemMessage": "You are an expert programmer. Always provide clean, well-documented code with best practices."
}
]
}
```
### Temperatura y parámetros
Ajusta el comportamiento del modelo con parámetros:
```json
{
"models": [
{
"title": "9Router - Creative Writer",
"provider": "openai",
"model": "cc/claude-opus-4-5-20251101",
"apiKey": "your-api-key",
"apiBase": "http://localhost:20128/v1",
"temperature": 0.9,
"topP": 0.95
}
]
}
```
### Proveedores de contexto
Configura qué contexto envía Continue al modelo:
```json
{
"contextProviders": [
{
"name": "code",
"params": {
"maxLines": 100
}
},
{
"name": "diff",
"params": {}
},
{
"name": "terminal",
"params": {}
}
]
}
```
## Atajos de teclado
- `Cmd+L` (Mac) / `Ctrl+L` (Windows/Linux) - Abrir chat de Continue
- `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - Edición inline
- `Cmd+Shift+R` (Mac) / `Ctrl+Shift+R` (Windows/Linux) - Regenerar respuesta
## Solución de problemas
### El modelo no responde
- Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
- Verifica la API key en config.json
- Revisa la consola de desarrollador de VSCode por errores: `Help` → `Toggle Developer Tools`
### Modelo incorrecto seleccionado
- Clic en el dropdown de modelo en la barra lateral de Continue
- Selecciona el modelo correcto de 9Router
- El nombre del modelo debe coincidir exactamente (sensible a mayúsculas)
### La configuración no se carga
- Verifica que la sintaxis JSON sea válida (usa un validador de JSON)
- Verifica la ubicación del archivo: `~/.continue/config.json`
- Recarga la ventana de VSCode después de cambios
### Rendimiento lento
- Cambia a modelos más rápidos (haiku, flash)
- Reduce el tamaño del contexto en contextProviders
- Verifica la latencia de red hacia 9Router
## Mejores prácticas
### Estrategia de selección de modelo
- **Ediciones rápidas**: Usa `cc/claude-haiku-4-20250514`
- **Generación de código**: Usa `cx/deepseek-chat`
- **Refactoring complejo**: Usa `cc/claude-opus-4-5-20251101`
- **Resolución de problemas**: Usa `cx/deepseek-reasoner`
### Gestión de contexto
- Selecciona solo el código relevante antes de preguntar
- Usa prompts específicos y claros
- Divide tareas complejas en pasos más pequeños
### Optimización de costos
- Usa modelos más rápidos/baratos para tareas simples
- Limita el tamaño del contexto cuando sea posible
- Cachea respuestas usadas con frecuencia
## Próximos pasos
- [Configurar Cursor](cursor.md) para integración mejorada con IDE
- [Configurar Roo](roo.md) para asistente de IA
- [Explorar uso de CLI](../cli/basic-usage.md)
- [Aprende sobre la selección de modelos](../models/overview.md)
gitbook/content/es/integration/cursor.md
+149
View File
@@ -0,0 +1,149 @@
# Integración con Cursor
Integra 9Router con Cursor IDE para enrutar tus solicitudes de IA a través del sistema de enrutamiento inteligente de 9Router.
## Requisitos previos
- Cursor IDE instalado
- Cuenta Cursor Pro (requerida para endpoints de API personalizados)
- Endpoint en la nube de 9Router configurado
- API key del dashboard de 9Router
## ⚠️ Notas importantes
> **Endpoint en la nube requerido**: Cursor enruta solicitudes a través de su propio servidor y no soporta endpoints localhost. Debes usar el endpoint en la nube de 9Router: `https://9router.com`
> **Cursor Pro requerido**: Esta característica requiere una cuenta Cursor Pro para usar endpoints de API personalizados.
## Configuración
### 1. Abrir la configuración de Cursor
1. Abre Cursor IDE
2. Ve a **Settings** (Cmd/Ctrl + ,)
3. Navega a la sección **Models**
### 2. Habilitar OpenAI API
1. Encuentra la opción **OpenAI API key**
2. Activa el toggle para habilitar la configuración de API personalizada
### 3. Configurar Base URL
Establece la URL base al endpoint en la nube de 9Router:
```
https://9router.com
```
**Pasos:**
1. En la configuración de Models, localiza el campo **Base URL**
2. Ingresa: `https://9router.com`
3. Clic en **Save**
### 4. Agregar API Key
1. En el campo **API Key**, ingresa tu API key de 9Router
2. Puedes encontrar tu API key en el dashboard de 9Router en **Settings → API Keys**
3. Clic en **Save**
### 5. Agregar modelo personalizado
1. Clic en el botón **View All Models**
2. Clic en **Add Custom Model**
3. Ingresa el nombre del modelo desde tu configuración de 9Router (ej. `gpt-4`, `claude-opus-4-5`, etc.)
4. Clic en **Add**
### 6. Seleccionar modelo
1. En la interfaz de chat de Cursor, clic en el dropdown selector de modelo
2. Elige tu modelo personalizado de la lista
3. ¡Empieza a usar 9Router con Cursor!
## Ejemplo de configuración
Tu configuración de Cursor debería verse así:
```
OpenAI API: ✓ Enabled
Base URL: https://9router.com
API Key: sk-9router-xxxxxxxxxxxxx
Custom Models: gpt-4, claude-opus-4-5, gemini-2.0-flash
```
## Modelos disponibles
Puedes usar cualquier modelo configurado en tu dashboard de 9Router. Ejemplos comunes:
| Nombre del modelo | Proveedor | Descripción |
|------------|----------|-------------|
| `gpt-4` | OpenAI | GPT-4 Turbo |
| `gpt-4o` | OpenAI | GPT-4 Optimized |
| `claude-opus-4-5` | Anthropic | Claude Opus 4.5 |
| `claude-sonnet-4-5` | Anthropic | Claude Sonnet 4.5 |
| `gemini-2.0-flash` | Google | Gemini 2.0 Flash |
## Uso
### Interfaz de chat
1. Abre el chat de Cursor (Cmd/Ctrl + L)
2. Selecciona tu modelo del dropdown
3. Comienza a chatear con IA a través de 9Router
### Generación de código inline
1. Selecciona código en tu editor
2. Presiona Cmd/Ctrl + K
3. Ingresa tu prompt
4. Cursor usará 9Router para generar código
### Explicación de código
1. Selecciona código en tu editor
2. Presiona Cmd/Ctrl + L
3. Pregunta "Explain this code"
4. Obtén explicaciones potenciadas por IA a través de 9Router
## Solución de problemas
### Error "Invalid API Key"
1. Verifica tu API key en el dashboard de 9Router
2. Asegúrate de haber copiado la key completa incluyendo el prefijo `sk-9router-`
3. Verifica que la API key no haya expirado
4. Intenta regenerar una nueva API key
### Error "Model Not Found"
1. Verifica que el nombre del modelo coincida exactamente con tu configuración de 9Router
2. Verifica que la conexión del proveedor esté activa en el dashboard de 9Router
3. Asegúrate de que el modelo esté disponible en tus proveedores conectados
4. Intenta usar el nombre completo del modelo (ej. `openai/gpt-4` en lugar de `gpt-4`)
### Problemas de conexión
1. Verifica que estés usando el endpoint en la nube: `https://9router.com`
2. Verifica tu conexión a internet
3. Asegúrate de que el servicio en la nube de 9Router esté operativo
4. Intenta deshabilitar VPN o proxy si está habilitado
### Localhost no funciona
> **Recuerda**: Cursor no soporta endpoints localhost. Debes usar el endpoint en la nube `https://9router.com`. Si necesitas usar una instancia local de 9Router, considera usar un servicio de tunneling como ngrok para exponer tu endpoint local.
## Configuración del endpoint en la nube
Si estás ejecutando 9Router localmente y quieres usarlo con Cursor:
1. Habilita el endpoint en la nube en la configuración de 9Router
2. Configura tu URL del endpoint en la nube en el dashboard de 9Router
3. Usa la URL en la nube en la configuración de Cursor
4. Asegúrate de que tu instancia local de 9Router sea accesible desde internet
## Mejores prácticas
1. **Usa aliases de modelos**: Crea aliases cortos para modelos usados con frecuencia en 9Router
2. **Monitorea el uso**: Revisa el dashboard de 9Router para estadísticas de uso y costos
3. **Rota las API Keys**: Rota tus API keys regularmente por seguridad
4. **Prueba modelos**: Prueba diferentes modelos para encontrar el mejor para tu caso de uso
gitbook/content/es/integration/other-tools.md
+416
View File
@@ -0,0 +1,416 @@
# Integración con otras herramientas
9Router es compatible con cualquier herramienta que soporte el formato de API de OpenAI. Esta guía cubre patrones de integración genéricos para varias herramientas y aplicaciones personalizadas.
## Resumen
9Router proporciona un endpoint de API compatible con OpenAI que funciona con:
- Scripts y aplicaciones personalizadas
- Clientes de API y herramientas de testing
- Herramientas CLI y utilidades
- Integraciones de terceros
- Frameworks de desarrollo
## Patrón de configuración genérico
Cualquier herramienta compatible con OpenAI puede conectarse a 9Router usando estas configuraciones:
**9Router local:**
```
Base URL: http://localhost:20128/v1
API Key: your-api-key-from-dashboard
Model: cualquier modelo de 9Router (cc/*, cx/*, glm/*, etc.)
```
**9Router en la nube:**
```
Base URL: https://9router.com/v1
API Key: your-api-key-from-dashboard
Model: cualquier modelo de 9Router (cc/*, cx/*, glm/*, etc.)
```
## Modelos disponibles
### Modelos Claude (Anthropic)
- `cc/claude-opus-4-5-20251101`
- `cc/claude-sonnet-4-20250514`
- `cc/claude-haiku-4-20250514`
### Modelos DeepSeek
- `cx/deepseek-chat`
- `cx/deepseek-reasoner`
### Modelos GLM (Zhipu AI)
- `glm/glm-4-plus`
- `glm/glm-4-flash`
## Ejemplos de integración
### Python con OpenAI SDK
```python
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[
{"role": "user", "content": "Hello, how are you?"}
]
)
print(response.choices[0].message.content)
```
### Node.js con OpenAI SDK
```javascript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
const response = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [
{ role: "user", content: "Hello, how are you?" }
]
});
console.log(response.choices[0].message.content);
```
### Comando cURL
```bash
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-from-dashboard" \
-d '{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
]
}'
```
### Cliente HTTP (Postman, Insomnia)
**Solicitud:**
```
POST http://localhost:20128/v1/chat/completions
```
**Headers:**
```
Content-Type: application/json
Authorization: Bearer your-api-key-from-dashboard
```
**Body:**
```json
{
"model": "cc/claude-sonnet-4-20250514",
"messages": [
{"role": "user", "content": "Hello, how are you?"}
],
"temperature": 0.7,
"max_tokens": 1000
}
```
### Integración con LangChain
```python
from langchain.chat_models import ChatOpenAI
from langchain.schema import HumanMessage
llm = ChatOpenAI(
model_name="cc/claude-sonnet-4-20250514",
openai_api_key="your-api-key-from-dashboard",
openai_api_base="http://localhost:20128/v1",
temperature=0.7
)
messages = [HumanMessage(content="Explain quantum computing")]
response = llm(messages)
print(response.content)
```
### Integración con LlamaIndex
```python
from llama_index.llms import OpenAI
llm = OpenAI(
model="cc/claude-sonnet-4-20250514",
api_key="your-api-key-from-dashboard",
api_base="http://localhost:20128/v1"
)
response = llm.complete("What is machine learning?")
print(response.text)
```
## Ejemplos de scripts personalizados
### Script de procesamiento por lotes
```python
import openai
import json
openai.api_key = "your-api-key-from-dashboard"
openai.api_base = "http://localhost:20128/v1"
def process_batch(prompts, model="cx/deepseek-chat"):
results = []
for prompt in prompts:
response = openai.ChatCompletion.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
results.append({
"prompt": prompt,
"response": response.choices[0].message.content
})
return results
prompts = [
"Explain AI in one sentence",
"What is machine learning?",
"Define neural networks"
]
results = process_batch(prompts)
print(json.dumps(results, indent=2))
```
### Manejador de respuestas streaming
```javascript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-api-key-from-dashboard",
baseURL: "http://localhost:20128/v1"
});
async function streamResponse(prompt) {
const stream = await client.chat.completions.create({
model: "cc/claude-sonnet-4-20250514",
messages: [{ role: "user", content: prompt }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || "";
process.stdout.write(content);
}
}
streamResponse("Write a short story about AI");
```
### Comparación multi-modelo
```python
from openai import OpenAI
client = OpenAI(
api_key="your-api-key-from-dashboard",
base_url="http://localhost:20128/v1"
)
models = [
"cc/claude-sonnet-4-20250514",
"cx/deepseek-chat",
"glm/glm-4-plus"
]
prompt = "Explain quantum computing in simple terms"
for model in models:
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
print(f"\n=== {model} ===")
print(response.choices[0].message.content)
```
## Patrones comunes de integración
### Variables de entorno
Almacena credenciales de forma segura:
```bash
# .env file
ROUTER_API_KEY=your-api-key-from-dashboard
ROUTER_BASE_URL=http://localhost:20128/v1
ROUTER_MODEL=cc/claude-sonnet-4-20250514
```
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("ROUTER_API_KEY"),
base_url=os.getenv("ROUTER_BASE_URL")
)
```
### Manejo de errores
```python
from openai import OpenAI, OpenAIError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)
except OpenAIError as e:
print(f"Error: {e}")
```
### Lógica de reintentos
```python
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
api_key="your-api-key",
base_url="http://localhost:20128/v1"
)
def chat_with_retry(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="cc/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
except RateLimitError:
if attempt < max_retries - 1:
time.sleep(2 ** attempt) # Exponential backoff
else:
raise
```
## Solución de problemas
### Problemas de conexión
**Problema:** No se puede conectar a 9Router
```bash
# Verifica si 9Router está corriendo
curl http://localhost:20128/health
# Respuesta esperada:
{"status": "ok"}
```
**Solución:**
- Verifica que 9Router esté corriendo
- Verifica que el puerto 20128 no esté bloqueado
- Asegúrate de tener la URL base correcta (incluir `/v1`)
### Errores de autenticación
**Problema:** 401 Unauthorized
```
Error: Invalid API key
```
**Solución:**
- Verifica la API key desde el dashboard
- Verifica el formato del header de Authorization: `Bearer your-api-key`
- Asegúrate de no tener espacios extras o saltos de línea en la API key
### Modelo no encontrado
**Problema:** 404 Model not found
```
Error: Model 'cc/claude-opus' not found
```
**Solución:**
- Usa el nombre exacto del modelo (sensible a mayúsculas)
- Verifica los modelos disponibles: `curl http://localhost:20128/v1/models`
- Verifica que el modelo esté habilitado en tu plan
### Problemas de timeout
**Problema:** Request timeout
```
Error: Request timed out after 30s
```
**Solución:**
- Aumenta el timeout en la configuración del cliente
- Usa modelos más rápidos para tareas sensibles al tiempo
- Verifica la conexión de red a 9Router
### Rate limiting
**Problema:** 429 Too Many Requests
```
Error: Rate limit exceeded
```
**Solución:**
- Implementa exponential backoff
- Reduce la frecuencia de solicitudes
- Verifica los límites de tasa en el dashboard
- Considera actualizar tu plan
## Mejores prácticas
### Seguridad
- Almacena las API keys en variables de entorno
- Nunca subas las API keys al control de versiones
- Usa HTTPS para despliegues en la nube
- Rota las API keys regularmente
### Rendimiento
- Usa modelos apropiados para la complejidad de la tarea
- Implementa caché para consultas repetidas
- Usa streaming para respuestas largas
- Agrupa solicitudes cuando sea posible
### Manejo de errores
- Siempre implementa bloques try-catch
- Agrega lógica de reintento con exponential backoff
- Registra errores para debugging
- Proporciona mecanismos de fallback
### Optimización de costos
- Elige modelos costo-efectivos para tareas simples
- Cachea respuestas cuando sea apropiado
- Monitorea el uso en el dashboard
- Establece límites de solicitudes en el código
## Próximos pasos
- [Configurar Cursor](cursor.md) para integración con IDE
- [Configurar Continue](continue.md) para VSCode
- [Explorar uso de CLI](../cli/basic-usage.md)
- [Aprende sobre la selección de modelos](../models/overview.md)
- [Referencia de API](../api/reference.md)
gitbook/content/es/integration/roo.md
+127
View File
@@ -0,0 +1,127 @@
# Integración con Roo AI Assistant
Integra 9Router con Roo AI Assistant para acceder a múltiples modelos de IA a través de una interfaz unificada.
## Requisitos previos
- Roo AI Assistant instalado
- API key de 9Router desde el [dashboard](https://9router.com/dashboard)
- 9Router ejecutándose (local o en la nube)
## Pasos de configuración
### 1. Abrir la configuración de Roo
Inicia Roo AI Assistant y abre el panel de configuración.
### 2. Configurar el proveedor de API
1. Navega a la configuración de **API Provider**
2. Selecciona **Ollama** como tipo de proveedor
3. Configura los siguientes ajustes:
**Para 9Router local:**
```
Base URL: http://localhost:20128/v1
API Key: your-api-key-from-dashboard
```
**Para 9Router en la nube:**
```
Base URL: https://9router.com/v1
API Key: your-api-key-from-dashboard
```
### 3. Seleccionar modelo
Elige entre los modelos disponibles de 9Router:
**Modelos Claude:**
- `cc/claude-opus-4-5-20251101` - El más capaz
- `cc/claude-sonnet-4-20250514` - Equilibrado
- `cc/claude-haiku-4-20250514` - Rápido
**Modelos DeepSeek:**
- `cx/deepseek-chat` - Propósito general
- `cx/deepseek-reasoner` - Razonamiento complejo
**Modelos GLM:**
- `glm/glm-4-plus` - Avanzado
- `glm/glm-4-flash` - Respuestas rápidas
### 4. Probar la conexión
Envía un mensaje de prueba para verificar la integración:
```
Hello! Can you confirm you're connected through 9Router?
```
## Ejemplos de uso
### Chat básico
```
Pregunta a Roo: "Explain quantum computing in simple terms"
Modelo: cc/claude-sonnet-4-20250514
```
### Generación de código
```
Pregunta a Roo: "Write a Python function to calculate Fibonacci numbers"
Modelo: cx/deepseek-chat
```
### Razonamiento complejo
```
Pregunta a Roo: "Analyze the trade-offs between microservices and monolithic architecture"
Modelo: cx/deepseek-reasoner
```
## Consejos de selección de modelo
- **Tareas rápidas**: Usa `cc/claude-haiku-4-20250514` o `glm/glm-4-flash`
- **Rendimiento equilibrado**: Usa `cc/claude-sonnet-4-20250514` o `cx/deepseek-chat`
- **Razonamiento complejo**: Usa `cc/claude-opus-4-5-20251101` o `cx/deepseek-reasoner`
- **Optimización de costos**: Usa modelos DeepSeek o GLM
## Solución de problemas
### Connection Failed
- Verifica que 9Router esté corriendo: `curl http://localhost:20128/health`
- Verifica que la API key sea correcta
- Asegúrate de que la Base URL incluya el sufijo `/v1`
### Modelo no disponible
- Verifica que el nombre del modelo coincida exactamente (sensible a mayúsculas)
- Verifica que el modelo esté habilitado en tu plan de 9Router
- Intenta otro modelo de la lista
### Respuestas lentas
- Cambia a modelos más rápidos (haiku, flash)
- Verifica la conexión de red
- Monitorea los logs de 9Router por problemas
## Configuración avanzada
### Aliases personalizados de modelos
Puedes crear atajos para modelos usados con frecuencia en la configuración de Roo:
```
Alias: "fast" → cc/claude-haiku-4-20250514
Alias: "smart" → cc/claude-opus-4-5-20251101
Alias: "code" → cx/deepseek-chat
```
### Múltiples perfiles
Configura diferentes perfiles para distintos casos de uso:
- **Desarrollo**: Modelos DeepSeek para código
- **Escritura**: Modelos Claude para contenido
- **Investigación**: Modelos reasoner para análisis
## Próximos pasos
- [Configurar Cursor](cursor.md) para integración con IDE
- [Configurar Continue](continue.md) para VSCode
- [Explorar uso de CLI](../cli/basic-usage.md)

Some files were not shown because too many files have changed in this diff Show More