@yina-npm/openrouterx 0.4.38 → 0.4.52

package/README.md

@@ -1,473 +1,1318 @@
-# openrouterX
+<div align="center">
+  <img src="./images/9router.png?1" alt="9Router Dashboard" width="800"/>
+  
+  # 9Router - FREE AI Router & Token Saver
+  
+  **Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.**
+  
+  **Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.**
+  
+  [![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
+  [![Docker Pulls](https://img.shields.io/docker/pulls/decolua/9router.svg?logo=docker&label=Docker%20pulls)](https://hub.docker.com/r/decolua/9router)
+  [![GHCR](https://img.shields.io/badge/GHCR-decolua%2F9router-blue?logo=github)](https://github.com/decolua/9router/pkgs/container/9router)
+  [![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/decolua/9router/blob/main/LICENSE)
 
-面向 AI 编码工具的本地统一路由服务。
+  <a href="https://trendshift.io/repositories/22628" target="_blank"><img src="https://trendshift.io/api/badge/repositories/22628" alt="decolua%2F9router | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+  
+  [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Setup](#-setup-guide) • [🌐 Website](https://9router.com)
 
-> 当前代码分支：[`feat/openrouterx-release`](https://github.com/hackyinge/9router/tree/feat/openrouterx-release)  
-> GitHub 仓库：[`hackyinge/9router`](https://github.com/hackyinge/9router)  
-> 如果这个项目对你有帮助，欢迎点一个 Star，后续会继续更新更多 AI 编码工具、MITM、账号切换和团队网关能力。
+  [🇻🇳 Tiếng Việt](./i18n/README.vi.md) • [🇨🇳 中文](./i18n/README.zh-CN.md) • [🇯🇵 日本語](./i18n/README.ja-JP.md)
+</div>
 
-`openrouterX` 可以把 Claude Code、Codex、Cursor、OpenCode、OpenClaw、Cline、Continue、Roo 等客户端统一接到一个本地 OpenAI-compatible 接口，并提供 Dashboard、模型路由、API Key 管理、Usage 分析、组合模型与自动 fallback。
+---
 
-## 为什么用 openrouterX
+## 🤔 Why 9Router?
 
-- 统一本地接口：`http://localhost:20502/v1`
-- 统一管理后台：`http://localhost:20502/dashboard`
-- 同时接入订阅型供应商、API Key 供应商、免费供应商
-- 支持组合模型与自动 fallback
-- 支持 Codex 账号一键激活到本机 Codex，并自动刷新 token、写入 macOS Keychain、重启 Codex App
-- 支持子用户在授权范围内切换 Codex 账号，适合团队共用多账号额度
-- 支持 Antigravity MITM，带上游解析修复，避免依赖固定 IP 导致网络漂移后失效
-- 默认端口前移到 `20502`，安装和启动时会迁移旧的 `20128` MITM router 配置
-- 配额刷新请求做了分散调度，降低多个账号集中请求触发风控的概率
-- 内置 `RTK`，适合 `git diff`、`grep`、日志等重工具调用场景
-- 支持管理员创建子用户，并精细限制子用户可用供应商与 API Key
+**Stop wasting money, tokens and hitting limits:**
 
-## 新增功能速览
+- ❌ Subscription quota expires unused every month
+- ❌ Rate limits stop you mid-coding
+- ❌ Tool outputs (git diff, grep, ls...) burn tokens fast
+- ❌ Expensive APIs ($20-50/month per provider)
+- ❌ Manual switching between providers
 
-### Codex 账号一键激活
+**9Router solves this:**
 
-在配额页面的 Codex 账号卡片上点击 `Activate`，即可把该账号应用到本机 Codex：
+- ✅ **RTK Token Saver** - Auto-compress tool_result content, save 20-40% tokens per request
+- ✅ **Maximize subscriptions** - Track quota, use every bit before reset
+- ✅ **Auto fallback** - Subscription → Cheap → Free, zero downtime
+- ✅ **Multi-account** - Round-robin between accounts per provider
+- ✅ **Universal** - Works with Claude Code, Codex, Cursor, Cline, any CLI tool
 
-- 检测本机是否安装 Codex CLI 或 macOS Codex.app
-- 使用账号的 `refresh_token` 刷新最新 `access_token` / `id_token`
-- 写入 `~/.codex/auth.json`
-- 在 macOS 上同步写入 `Codex Auth` Keychain
-- 自动重启 Codex.app，让新账号立即生效
+---
 
-如果本机没有安装 Codex，会提示安装方式：
+## 🔄 How It Works
 
-```bash
-npm install -g @openai/codex
-# macOS 也可以：
-brew install --cask codex
 ```
+┌─────────────┐
+│  Your CLI   │  (Claude Code, Codex, OpenClaw, Cursor, Cline...)
+│   Tool      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────────┐
+│           9Router (Smart Router)            │
+│  • RTK Token Saver (cut tool_result tokens) │
+│  • Format translation (OpenAI ↔ Claude)     │
+│  • Quota tracking                           │
+│  • Auto token refresh                       │
+└──────┬──────────────────────────────────────┘
+       │
+       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot
+       │   ↓ quota exhausted
+       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ budget limit
+       └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits)
+
+Result: Never stop coding, minimal cost + 20-40% token savings via RTK
+```
+
+---
 
-### 子用户也能切换 Codex 账号
+## ⚡ Quick Start
 
-子用户在配额页面仍然保持只读，不能编辑、删除或启停供应商连接，但可以对自己被授权看到的 Codex 账号点击 `Activate`。后端会做连接级权限校验，手写未授权的 `connectionId` 会返回 `403`。
+**1. Install globally:**
 
-注意：Codex 激活修改的是当前机器的本地 Codex 登录态，是机器级状态，不是每个子用户隔离一份本地 Codex 状态。
+```bash
+npm install -g 9router
+9router
+```
 
-### Antigravity MITM 更稳定
+🎉 Dashboard opens at `http://localhost:20128`
 
-MITM 不再依赖固定上游 IP 列表。解析上游地址时会跳过本机 alias、回环路由和已失败地址，减少这类错误：
+**2. Connect a FREE provider (no signup needed):**
+
+Dashboard → Providers → Connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → Done!
+
+**3. Use in your CLI tool:**
 
-```txt
-Passthrough error: connect EADDRNOTAVAIL ...
-Router fetch failed for http://localhost:20128/v1/chat/completions
+```
+Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
+  Endpoint: http://localhost:20128/v1
+  API Key: [copy from dashboard]
+  Model: kr/claude-sonnet-4.5
 ```
 
-同时默认端口已从 `20128` 迁移到 `20502`，升级安装和启动时会刷新旧配置，避免其他机器升级后继续指向旧端口。
+**That's it!** Start coding with FREE AI models.
 
-## 安装
+**Alternative: run from source (this repository):**
 
-从 npm 全局安装：
+This repository package is private (`9router-app`), so source/Docker execution is the expected local development path.
 
 ```bash
-npm install -g @yina-npm/openrouterx
-openrouterX
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
 ```
 
-开发者在验证本地改动时，必须区分“源码启动”和“npm 包安装测试”。发布、CLI、MITM、安装布局相关改动请先阅读 [Local npm Package Testing](docs/LOCAL_NPM_TESTING.md)。
+Production mode:
 
-启动后默认地址：
+```bash
+npm run build
+PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start
+```
 
-- Dashboard：`http://localhost:20502/dashboard`
-- OpenAI-compatible API：`http://localhost:20502/v1`
+Default URLs:
+- Dashboard: `http://localhost:20128/dashboard`
+- OpenAI-compatible API: `http://localhost:20128/v1`
+
+---
+
+## Video Guides
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=raEyZPg5xE0">
+        <img src="https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg" alt="9Router Setup Tutorial" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>9Router + Claude Code FREE Setup<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=X69n5Lm06Yw">
+        <img src="https://img.youtube.com/vi/X69n5Lm06Yw/maxresdefault.jpg" alt="Tiết kiệm chi phí LLM với 9Router" width="300"/>
+      </a><br/>
+      <b>🇻🇳 Tiếng Việt</b><br/>
+      <sub>Tiết kiệm chi phí LLM cho OpenClaw với 9Router<br/>by <a href="https://www.youtube.com/c/M%C3%ACAIblog">Mì AI</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=o3qYCyjrFYg">
+        <img src="https://img.youtube.com/vi/o3qYCyjrFYg/maxresdefault.jpg" alt="Claude Code FREE Forever" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>Claude Code FREE Forever — Unlimited Models<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=Ttpc26m39Dw">
+        <img src="https://img.youtube.com/vi/Ttpc26m39Dw/maxresdefault.jpg" alt="Claude CLI Free Setup" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>Claude CLI Free Setup with 9Router 🚀<br/>by <a href="https://www.youtube.com/@CodeVerseSoban">CodeVerse Soban</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=G-5A_D5Pm6Y">
+        <img src="https://img.youtube.com/vi/G-5A_D5Pm6Y/maxresdefault.jpg" alt="Cài đặt OpenClaw Free A-Z" width="300"/>
+      </a><br/>
+      <b>🇻🇳 Tiếng Việt</b><br/>
+      <sub>Cài Đặt OpenClaw Free Từ A-Z + 9Router<br/>by <a href="https://www.youtube.com/@maigia">Mai Gia</a></sub>
+    </td>
+    <td align="center" width="320">
+      <a href="https://www.youtube.com/watch?v=JXmg8_gccgE">
+        <img src="https://img.youtube.com/vi/JXmg8_gccgE/maxresdefault.jpg" alt="FREE OpenClaw with Claude Opus" width="300"/>
+      </a><br/>
+      <b>🇺🇸 English</b><br/>
+      <sub>FREE OpenClaw + Claude Opus 4.6<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub>
+    </td>
+  </tr>
+</table>
+
+</div>
+
+> 🎬 **Made a video about 9Router?** Submit a [Pull Request](https://github.com/decolua/9router/pulls) adding your video to this section — we'll merge it!
+
+---
+
+## 🛠️ Supported CLI Tools
+
+9Router works seamlessly with all major AI coding tools:
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/>
+        <b>OpenClaw</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/opencode.png" width="60" alt="OpenCode"/><br/>
+        <b>OpenCode</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/cline.png" width="60" alt="Cline"/><br/>
+        <b>Cline</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/continue.png" width="60" alt="Continue"/><br/>
+        <b>Continue</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/droid.png" width="60" alt="Droid"/><br/>
+        <b>Droid</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/roo.png" width="60" alt="Roo"/><br/>
+        <b>Roo</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/copilot.png" width="60" alt="Copilot"/><br/>
+        <b>Copilot</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/>
+        <b>Kilo Code</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🌐 Supported Providers
+
+### 🔐 OAuth Providers
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="120">
+        <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/>
+        <b>Claude-Code</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/>
+        <b>Antigravity</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/>
+        <b>Codex</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/github.png" width="60" alt="GitHub"/><br/>
+        <b>GitHub</b>
+      </td>
+      <td align="center" width="120">
+        <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/>
+        <b>Cursor</b>
+      </td>
+    </tr>
+  </table>
+</div>
+
+### 🆓 Free Providers
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="150">
+        <img src="./public/providers/kiro.png" width="70" alt="Kiro"/><br/>
+        <b>Kiro AI</b><br/>
+        <sub>Claude 4.5 + GLM-5 + MiniMax<br/>Unlimited FREE</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/opencode.png" width="70" alt="OpenCode Free"/><br/>
+        <b>OpenCode Free</b><br/>
+        <sub>No auth • Auto-fetch models<br/>Unlimited FREE</sub>
+      </td>
+      <td align="center" width="150">
+        <img src="./public/providers/gemini.png" width="70" alt="Vertex AI"/><br/>
+        <b>Vertex AI</b><br/>
+        <sub>Gemini 3 Pro + GLM-5 + DeepSeek<br/>$300 credits free</sub>
+      </td>
+    </tr>
+  </table>
+</div>
+
+> **Note:** iFlow, Qwen and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead.
+
+### 🔑 API Key Providers (40+)
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/>
+        <sub>OpenRouter</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/glm.png" width="50" alt="GLM"/><br/>
+        <sub>GLM</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/kimi.png" width="50" alt="Kimi"/><br/>
+        <sub>Kimi</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/minimax.png" width="50" alt="MiniMax"/><br/>
+        <sub>MiniMax</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/openai.png" width="50" alt="OpenAI"/><br/>
+        <sub>OpenAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/anthropic.png" width="50" alt="Anthropic"/><br/>
+        <sub>Anthropic</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/gemini.png" width="50" alt="Gemini"/><br/>
+        <sub>Gemini</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/>
+        <sub>DeepSeek</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/groq.png" width="50" alt="Groq"/><br/>
+        <sub>Groq</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/xai.png" width="50" alt="xAI"/><br/>
+        <sub>xAI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/mistral.png" width="50" alt="Mistral"/><br/>
+        <sub>Mistral</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/perplexity.png" width="50" alt="Perplexity"/><br/>
+        <sub>Perplexity</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="100">
+        <img src="./public/providers/together.png" width="50" alt="Together"/><br/>
+        <sub>Together AI</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/fireworks.png" width="50" alt="Fireworks"/><br/>
+        <sub>Fireworks</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cerebras.png" width="50" alt="Cerebras"/><br/>
+        <sub>Cerebras</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/cohere.png" width="50" alt="Cohere"/><br/>
+        <sub>Cohere</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/>
+        <sub>NVIDIA</sub>
+      </td>
+      <td align="center" width="100">
+        <img src="./public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/>
+        <sub>SiliconFlow</sub>
+      </td>
+    </tr>
+  </table>
+  <p><i>...and 20+ more providers including Nebius, Chutes, Hyperbolic, and custom OpenAI/Anthropic compatible endpoints</i></p>
+</div>
+
+---
+
+## 💡 Key Features
+
+| Feature | What It Does | Why It Matters |
+|---------|--------------|----------------|
+| 🚀 **RTK Token Saver** ([RTK](https://github.com/rtk-ai/rtk) ⭐40K) | Compress tool outputs (`git diff`, `grep`, `ls`, `tree`...) before sending to LLM | Save **20-40% input tokens** per request |
+| 🪨 **Caveman Mode** ([Caveman](https://github.com/JuliusBrussee/caveman) ⭐52K) | Inject caveman-speak prompt → LLM replies terse, technical substance preserved | Save **up to 65% output tokens** |
+| 🎯 **Smart 3-Tier Fallback** | Auto-route: Subscription → Cheap → Free | Never stop coding, zero downtime |
+| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown | Maximize subscription value |
+| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex | Works with any CLI tool |
+| 👥 **Multi-Account Support** | Multiple accounts per provider | Load balancing + redundancy |
+| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically | No manual re-login needed |
+| 🎨 **Custom Combos** | Create unlimited model combinations | Tailor fallback to your needs |
+| 📝 **Request Logging** | Debug mode with full request/response logs | Troubleshoot issues easily |
+| 💾 **Cloud Sync** | Sync config across devices | Same setup everywhere |
+| 📊 **Usage Analytics** | Track tokens, cost, trends over time | Optimize spending |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloudflare Workers | Flexible deployment options |
+
+<details>
+<summary><b>📖 Feature Details</b></summary>
+
+### 🚀 RTK Token Saver
+
+Tool outputs (`git diff`, `grep`, `find`, `ls`, `tree`, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression **before** the request hits the LLM:
+
+- **Filters:** `git-diff`, `git-status`, `grep`, `find`, `ls`, `tree`, `dedup-log`, `smart-truncate`, `read-numbered`, `search-list`
+- **Auto-detect:** No config needed — RTK peeks the first 1KB of each `tool_result` and picks the right filter.
+- **Safe by design:** If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request.
+- **Universal:** Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs **before** any format translation.
+- **Default ON:** Toggle anytime in Dashboard → Endpoint settings.
 
-## 快速开始
+```
+Without RTK: 47K tokens sent to LLM
+With RTK:    28K tokens sent to LLM   (40% saved · same context · same answer)
+```
 
-### 1. 启动本地服务
+### 🎯 Smart 3-Tier Fallback
 
-```bash
-openrouterX
+Create combos with automatic fallback:
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        (your subscription)
+  2. glm/glm-4.7               (cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking       (free fallback)
+
+→ Auto switches when quota runs out or errors occur
 ```
 
-登录页默认在：
+### 📊 Real-Time Quota Tracking
+
+- Token consumption per provider
+- Reset countdown (5-hour, daily, weekly)
+- Cost estimation for paid tiers
+- Monthly spending reports
+
+### 🔄 Format Translation
+
+Seamless translation between formats:
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Cursor** ↔ **Kiro** ↔ **Vertex** ↔ **Antigravity** ↔ **Ollama** ↔ **OpenAI Responses**
+- Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format
+- Works with any tool that supports custom OpenAI endpoints
+
+### 👥 Multi-Account Support
+
+- Add multiple accounts per provider
+- Auto round-robin or priority-based routing
+- Fallback to next account when one hits quota
+
+### 🔄 Auto Token Refresh
+
+- OAuth tokens automatically refresh before expiration
+- No manual re-authentication needed
+- Seamless experience across all providers
+
+### 🎨 Custom Combos
+
+- Create unlimited model combinations
+- Mix subscription, cheap, and free tiers
+- Name your combos for easy access
+- Share combos across devices with Cloud Sync
+
+### 📝 Request Logging
+
+- Enable debug mode for full request/response logs
+- Track API calls, headers, and payloads
+- Troubleshoot integration issues
+- Export logs for analysis
+
+### 💾 Cloud Sync
+
+- Sync providers, combos, and settings across devices
+- Automatic background sync
+- Secure encrypted storage
+- Access your setup from anywhere
+
+#### Cloud Runtime Notes
+
+- Prefer server-side cloud variables in production:
+  - `BASE_URL` (internal callback URL used by sync scheduler)
+  - `CLOUD_URL` (cloud sync endpoint base)
+- `NEXT_PUBLIC_BASE_URL` and `NEXT_PUBLIC_CLOUD_URL` are still supported for compatibility/UI, but server runtime now prioritizes `BASE_URL`/`CLOUD_URL`.
+- Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable.
+
+### 📊 Usage Analytics
+
+- Track token usage per provider and model
+- Cost estimation and spending trends
+- Monthly reports and insights
+- Optimize your AI spending
 
-```txt
-http://localhost:20502/login
+> **💡 IMPORTANT - Understanding Dashboard Costs:**
+> 
+> The "cost" displayed in Usage Analytics is **for tracking and comparison purposes only**. 
+> 9Router itself **never charges** you anything. You only pay providers directly (if using paid services).
+> 
+> **Example:** If your dashboard shows "$290 total cost" while using iFlow models, this represents 
+> what you would have paid using paid APIs directly. Your actual cost = **$0** (iFlow is free unlimited).
+> 
+> Think of it as a "savings tracker" showing how much you're saving by using free models or 
+> routing through 9Router!
+
+### 🌐 Deploy Anywhere
+
+- 💻 **Localhost** - Default, works offline
+- ☁️ **VPS/Cloud** - Share across devices
+- 🐳 **Docker** - One-command deployment
+- 🚀 **Cloudflare Workers** - Global edge network
+
+</details>
+
+---
+
+## 💰 Pricing at a Glance
+
+| Tier | Provider | Cost | Quota Reset | Best For |
+|------|----------|------|-------------|----------|
+| **🚀 TOKEN SAVER** | **RTK (built-in)** | **FREE** | Always on | **Save 20-40% tokens on EVERY request** |
+| **💳 SUBSCRIPTION** | Claude Code (Pro/Max) | $20-200/mo | 5h + weekly | Already subscribed |
+| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |
+| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |
+| | Cursor IDE | $20/mo | Monthly | Cursor users |
+| **💰 CHEAP** | GLM-5.1 / GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.7 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2.5 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Kiro AI | $0 | Unlimited | Claude 4.5 + GLM-5 + MiniMax free |
+| | OpenCode Free | $0 | Unlimited | No auth, auto-fetch models |
+| | Vertex AI | $300 credits | New GCP accounts | Gemini 3 Pro + DeepSeek + GLM-5 |
+
+**💡 Pro Tip:** RTK + Kiro AI + OpenCode Free combo = **$0 cost + 20-40% token savings**!
+
+---
+
+### 📊 Understanding 9Router Costs & Billing
+
+**9Router Billing Reality:**
+
+✅ **9Router software = FREE forever** (open source, never charges)  
+✅ **Dashboard "costs" = Display/tracking only** (not actual bills)  
+✅ **You pay providers directly** (subscriptions or API fees)  
+✅ **FREE providers stay FREE** (iFlow, Kiro, Qwen = $0 unlimited)  
+❌ **9Router never sends invoices** or charges your card
+
+**How Cost Display Works:**
+
+The dashboard shows **estimated costs** as if you were using paid APIs directly. This is **not billing** - it's a comparison tool to show your savings.
+
+**Example Scenario:**
 ```
+Dashboard Display:
+• Total Requests: 1,662
+• Total Tokens: 47M
+• Display Cost: $290
+
+Reality Check:
+• Provider: iFlow (FREE unlimited)
+• Actual Payment: $0.00
+• What $290 Means: Amount you SAVED by using free models!
+```
+
+**Payment Rules:**
+- **Subscription providers** (Claude Code, Codex): Pay them directly via their websites
+- **Cheap providers** (GLM, MiniMax): Pay them directly, 9Router just routes
+- **FREE providers** (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges
+- **9Router**: Never charges anything, ever
 
-### 2. 登录
+---
 
-- `Super Admin`：完整管理权限
-- `Sub User`：受限使用权限，适合团队成员或子账号
+## 🎯 Use Cases
 
-### 3. 连接供应商
+### Case 1: "I have Claude Pro subscription"
 
-进入 Dashboard 后可以接入：
+**Problem:** Quota expires unused, rate limits during heavy coding
 
-- 订阅型供应商：Claude Code、Codex、Copilot、Cursor
-- API Key 供应商：OpenAI、Anthropic、OpenRouter、GLM、Gemini、DeepSeek、Groq、Mistral、MiniMax、Kimi 等
-- 免费或低成本供应商：Kiro、OpenCode Free、Vertex AI
+**Solution:**
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-7        (use subscription fully)
+  2. glm/glm-5.1               (cheap backup when quota out)
+  3. kr/claude-sonnet-4.5      (free emergency fallback)
 
-### 4. 创建或复制 API Key
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
 
-在 Dashboard 中创建 API Key，然后把它配置到你的编码工具里。
+### Case 2: "I want zero cost"
 
-### 5. 把工具接到 openrouterX
+**Problem:** Can't afford subscriptions, need reliable AI coding
 
-```txt
-Base URL: http://localhost:20502/v1
-API Key:  你的 Dashboard API Key
-Model:    任意可用模型或 combo
+**Solution:**
 ```
+Combo: "free-forever"
+  1. kr/claude-sonnet-4.5      (Claude 4.5 free unlimited)
+  2. kr/glm-5                  (GLM-5 free via Kiro)
+  3. oc/<auto>                 (OpenCode Free, no auth)
 
-## 工作方式
+Monthly cost: $0
+Quality: Production-ready models + RTK saves 20-40% tokens
+```
 
-```txt
-你的工具
-  -> Claude Code / Codex / Cursor / OpenCode / OpenClaw / Cline / Continue
+### Case 3: "I need 24/7 coding, no interruptions"
 
-openrouterX
-  -> 本地 OpenAI-compatible 接口
-  -> 请求格式适配
-  -> 模型路由与 fallback
-  -> 配额感知切换
-  -> Usage 统计
-  -> API Key 与子用户隔离
+**Problem:** Deadlines, can't afford downtime
 
-上游供应商
-  -> 订阅账号
-  -> API Key 供应商
-  -> 免费供应商
+**Solution:**
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-7        (best quality)
+  2. cx/gpt-5.5                (second subscription)
+  3. glm/glm-5.1               (cheap, resets daily)
+  4. minimax/MiniMax-M2.7      (cheapest, 5h reset)
+  5. kr/claude-sonnet-4.5      (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
 ```
 
-## 核心能力
+### Case 4: "I want FREE AI in OpenClaw"
 
-### 统一本地接口
+**Problem:** Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free
 
-多个工具共享同一个本地入口：
+**Solution:**
+```
+Combo: "openclaw-free"
+  1. kr/claude-sonnet-4.5      (Claude 4.5 free)
+  2. kr/glm-5                  (GLM-5 free)
+  3. kr/MiniMax-M2.5           (MiniMax free)
 
-```txt
-http://localhost:20502/v1
+Monthly cost: $0
+Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
 ```
 
-### Dashboard 驱动配置
+---
 
-Dashboard 可以完成：
+## ❓ Frequently Asked Questions
 
-- 连接供应商
-- 创建 API Key
-- 测试模型
-- 配置 combo
-- 查看 Usage 和请求明细
-- 生成各类 CLI Tools 的手动配置
+<details>
+<summary><b>📊 Why does my dashboard show high costs?</b></summary>
 
-### RTK Token Saver
+The dashboard tracks your token usage and displays **estimated costs** as if you were using paid APIs directly. This is **not actual billing** - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router.
 
-`RTK` 会在请求发送到上游模型前，对冗长的工具输出进行压缩，尤其适合：
+**Example:**
+- **Dashboard shows:** "$290 total cost"
+- **Reality:** You're using iFlow (FREE unlimited)
+- **Your actual cost:** **$0.00**
+- **What $290 means:** Amount you **saved** by using free models instead of paid APIs!
 
-- `git diff`
-- `grep`
-- `ls`
-- 构建日志
-- 长文本工具输出
+The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.
 
-### Combo 与自动 fallback
+</details>
 
-你可以创建一个命名 combo，让多个模型串联：
+<details>
+<summary><b>💳 Will I be charged by 9Router?</b></summary>
 
-```txt
-premium-coding
-  1. cc/claude-opus
-  2. glm/glm-5
-  3. kr/claude-sonnet-4.5
-```
+**No.** 9Router is free, open-source software that runs on your own computer. It never charges you anything.
+
+**You only pay:**
+- ✅ **Subscription providers** (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
+- ✅ **Cheap providers** (GLM, MiniMax) → Pay them directly, 9Router just routes your requests
+- ❌ **9Router itself** → **Never charges anything, ever**
 
-主模型不可用时，可以自动切到后备模型。
+9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.
 
-### 子用户权限隔离
+</details>
 
-管理员可以为子用户单独控制：
+<details>
+<summary><b>🆓 Are FREE providers really unlimited?</b></summary>
 
-- 可使用哪些供应商
-- 可见哪些 API Key
-- Usage 是否只看自己的数据
-- 是否仅能查看 `CLI Tools` 手动配置，而不能修改本地工具设置
+**Yes!** The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free with **no hidden charges**.
 
-这适合团队共用部署、代运营账号、或敏感 API Key 隔离场景。
+These are free services offered by those respective companies:
+- **Kiro AI**: Free unlimited Claude 4.5 + GLM-5 + MiniMax via AWS Builder ID / Google / GitHub OAuth
+- **OpenCode Free**: No-auth passthrough proxy, models auto-fetched from `opencode.ai/zen/v1/models`
+- **Vertex AI**: $300 free credits for new Google Cloud accounts (90 days)
 
-### 团队共享网关
+9Router just routes your requests to them - there's no "catch" or future billing. They're truly free services, and 9Router makes them easy to use with fallback support.
 
-`openrouterX` 不只是单人使用工具，也可以作为团队内部统一网关：
+**Discontinued free tiers (no longer recommended):**
+- ❌ **iFlow**: Was free unlimited, now changed to paid (2026)
+- ❌ **Qwen Code**: Free OAuth tier discontinued by Alibaba on 2026-04-15
+- ❌ **Gemini CLI**: Still works, but using it with non-CLI tools (Claude, Codex, Cursor...) may result in account bans — only use if you stick to Gemini CLI itself
 
-- 管理员统一管理供应商、API Key、用户、combo
-- 子用户只看到分配给自己的 API Key 和允许使用的供应商
-- 子用户的 Usage 页面只展示自己的调用数据
-- 子用户可以在 `CLI Tools` 页面复制配置，但不会拿到完整管理权限
-- 上游供应商凭证不会暴露给普通成员
+</details>
 
-### Usage 分析
+<details>
+<summary><b>💰 How do I minimize my actual AI costs?</b></summary>
 
-Dashboard 支持查看：
+**Free-First Strategy:**
 
-- 请求数
-- tokens
-- estimated cost
-- 按 API Key 的使用情况
-- 请求明细
+1. **Start with 100% free combo:**
+   ```
+   1. gc/gemini-3-flash (180K/month free from Google)
+   2. if/kimi-k2-thinking (unlimited free from iFlow)
+   3. qw/qwen3-coder-plus (unlimited free from Qwen)
+   ```
+   **Cost: $0/month**
 
-其中成本展示主要用于统计和对比，`openrouterX` 本身不会向你收费。
+2. **Add cheap backup** only if you need it:
+   ```
+   4. glm/glm-4.7 ($0.6/1M tokens)
+   ```
+   **Additional cost: Only pay for what you actually use**
 
-## 支持的工具
+3. **Use subscription providers last:**
+   - Only if you already have them
+   - 9Router helps maximize their value through quota tracking
 
-`openrouterX` 面向各类 AI 编码工具和 OpenAI-compatible 客户端，包括：
+**Result:** Most users can operate at $0/month using only free tiers!
 
-- Claude Code
-- Codex CLI
-- Cursor
-- OpenCode
-- OpenClaw
-- Cline
-- Continue
-- Roo
-- 兼容 Copilot 的相关流程
-- 其他支持 OpenAI-compatible 接口的自定义工具
+</details>
 
-## 支持的供应商类型
+<details>
+<summary><b>📈 What if my usage suddenly spikes?</b></summary>
 
-### 订阅型供应商
+9Router's smart fallback prevents surprise charges:
 
-- Claude Code
-- Codex
-- GitHub Copilot
-- Cursor
+**Scenario:** You're on a coding sprint and blow through your quotas
 
-### API Key 供应商
+**Without 9Router:**
+- ❌ Hit rate limit → Work stops → Frustration
+- ❌ Or: Accidentally rack up huge API bills
 
-- OpenAI
-- Anthropic
-- OpenRouter
-- GLM
-- Gemini
-- DeepSeek
-- Groq
-- Mistral
-- MiniMax
-- Kimi
-- 以及其他兼容供应商
+**With 9Router:**
+- ✅ Subscription hits limit → Auto-fallback to cheap tier
+- ✅ Cheap tier gets expensive → Auto-fallback to free tier
+- ✅ Never stop coding → Predictable costs
 
-### 免费或低成本供应商
+**You're in control:** Set spending limits per provider in dashboard, and 9Router respects them.
 
-- Kiro
-- OpenCode Free
-- Vertex AI
+</details>
 
-实际可用性取决于上游服务当前状态和你的本地配置。
+---
 
-## CLI Tools 配置
+## 📖 Setup Guide
 
-Dashboard 内置了 `CLI Tools` 页面，可以直接生成可复制的配置。
+<details>
+<summary><b>🔐 Subscription Providers (Maximize Value)</b></summary>
 
-### 通用 OpenAI-compatible 配置
+### Claude Code (Pro/Max)
 
-```txt
-Base URL: http://localhost:20502/v1
-API Key:  你的 Dashboard API Key
-Model:    你选择的模型或 combo
+```bash
+Dashboard → Providers → Connect Claude Code
+→ OAuth login → Auto token refresh
+→ 5-hour + weekly quota tracking
+
+Models:
+  cc/claude-opus-4-7
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-6
+  cc/claude-haiku-4-5-20251001
 ```
 
-### Codex CLI
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!
+
+### OpenAI Codex (Plus/Pro)
 
 ```bash
-export OPENAI_BASE_URL="http://localhost:20502/v1"
-export OPENAI_API_KEY="your-dashboard-api-key"
+Dashboard → Providers → Connect Codex
+→ OAuth login (port 1455)
+→ 5-hour + weekly reset
+
+Models:
+  cx/gpt-5.5
+  cx/gpt-5.4
+  cx/gpt-5.3-codex
+  cx/gpt-5.2-codex
 ```
 
-### Claude Code
+### GitHub Copilot
 
-直接使用 `CLI Tools -> Claude Code` 中生成的手动配置。
+```bash
+Dashboard → Providers → Connect GitHub
+→ OAuth via GitHub
+→ Monthly reset (1st of month)
+
+Models:
+  gh/gpt-5.4
+  gh/claude-opus-4.7
+  gh/claude-sonnet-4.6
+  gh/gemini-3.1-pro-preview
+  gh/grok-code-fast-1
+```
 
-### OpenClaw
+### Cursor IDE
 
-直接使用 `CLI Tools -> OpenClaw` 中生成的手动配置。
+```bash
+Dashboard → Providers → Connect Cursor
+→ OAuth login
+→ Monthly subscription
+
+Models:
+  cu/claude-4.6-opus-max
+  cu/claude-4.5-sonnet-thinking
+  cu/gpt-5.3-codex
+```
 
-### OpenCode
+</details>
 
-直接使用 `CLI Tools -> OpenCode` 中生成的手动配置。
+<details>
+<summary><b>💰 Cheap Providers (Backup)</b></summary>
 
-## 管理员与子用户
+### GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M)
 
-`openrouterX` 内置两种角色：
+1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key:
+   - Provider: `glm`
+   - API Key: `your-key`
 
-- `super_admin`
-- `sub_user`
+**Use:** `glm/glm-5.1`, `glm/glm-5`, `glm/glm-4.7`
 
-### `super_admin`
+**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
 
-可以管理：
+### MiniMax M2.7 (5h reset, $0.20/1M)
 
-- providers
-- API keys
-- combos
-- users
-- usage analytics
-- 本地工具集成配置
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key
+3. Dashboard → Add API Key
 
-### `sub_user`
+**Use:** `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.5`
 
-可以被限制为：
+**Pro Tip:** Cheapest option for long context (1M tokens)!
 
-- 只能使用分配给自己的 API Key
-- 只能访问被允许的供应商
-- 只能查看自己的 Usage 数据
-- 只显示精简版 `CLI Tools`
-- 可以复制手动配置，但不能管理供应商
-- 页面范围聚焦在自己的可见资源内
+### Kimi K2.5 ($9/month flat)
 
-这使得一个部署可以服务多个用户，同时避免把所有供应商和凭证暴露给每个人。
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key
+3. Dashboard → Add API Key
 
-## 本地开发
+**Use:** `kimi/kimi-k2.5`, `kimi/kimi-k2.5-thinking`
 
-从源码运行：
+**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+</details>
+
+<details>
+<summary><b>🆓 FREE Providers (Recommended)</b></summary>
+
+### Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE)
 
 ```bash
-cp .env.example .env
-npm install
-PORT=20502 NEXT_PUBLIC_BASE_URL=http://localhost:20502 npm run dev
+Dashboard → Connect Kiro
+→ AWS Builder ID, AWS IAM Identity Center, Google, or GitHub
+→ Unlimited usage
+
+Models:
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+  kr/glm-5
+  kr/MiniMax-M2.5
+  kr/qwen3-coder-next
+  kr/deepseek-3.2
 ```
 
-生产构建：
+**Pro Tip:** Best free option for Claude. No API key, no payment, fully unlimited.
+
+### OpenCode Free (No auth, auto-fetch models)
 
 ```bash
-npm run build
-PORT=20502 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20502 npm run start
+Dashboard → Connect OpenCode Free
+→ No login required (passthrough proxy)
+→ Models auto-fetched from opencode.ai/zen/v1/models
 ```
 
-### 切换端口
+**Pro Tip:** Fastest setup. Just connect and start coding.
 
-默认端口是 `20502`。临时切到其他端口时，同时设置 `PORT` 和对外 base URL：
+### Vertex AI ($300 free credits for new GCP accounts)
 
 ```bash
-PORT=20600 NEXT_PUBLIC_BASE_URL=http://localhost:20600 npm run dev
+Dashboard → Connect Vertex AI
+→ Upload Google Cloud Service Account JSON
+→ Enable Vertex AI API in your GCP project
+
+Models:
+  vertex/gemini-3.1-pro-preview
+  vertex/gemini-3-flash-preview
+  vertex/gemini-2.5-flash
+
+Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex):
+  vertex-partner/glm-5-maas
+  vertex-partner/deepseek-v3.2-maas
+  vertex-partner/qwen3-next-80b-a3b-thinking-maas
 ```
 
-生产模式同理：
+**Pro Tip:** New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding.
 
-```bash
-PORT=20600 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20600 npm run start
+</details>
+
+<details>
+<summary><b>🎨 Create Combos</b></summary>
+
+### Example 1: Maximize Subscription → Cheap Backup
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-7 (Subscription primary)
+  2. glm/glm-5.1 (Cheap backup, $0.6/1M)
+  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M)
+
+Use in CLI: premium-coding
+
+Monthly cost example (100M tokens):
+  80M via Claude (subscription): $0 extra
+  15M via GLM: $9
+  5M via MiniMax: $1
+  Total: $10 + your subscription
+```
+
+### Example 2: Free-Only (Zero Cost)
+
+```
+Name: free-combo
+Models:
+  1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited)
+  2. kr/glm-5 (GLM-5 free via Kiro)
+  3. vertex/gemini-3.1-pro-preview ($300 free credits)
+
+Cost: $0 forever (+ 20-40% token savings via RTK)!
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI Integration</b></summary>
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-7
+```
+
+Or use combo: `premium-coding`
+
+### Claude Code
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
 ```
 
-如果使用全局安装的 `openrouterX`，端口来自 CLI 内置默认值或启动时的 `PORT` 环境变量。修改默认端口后需要重新 npm 全局安装并重启：
+### Codex CLI
 
 ```bash
-npm run release:npm:install-local
-openrouterX restart --no-browser --skip-update
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**Option 1 — Dashboard (recommended):**
+
+```
+Dashboard → CLI Tools → OpenClaw → Select Model → Apply
 ```
 
-切换端口后，CLI 工具里的 Base URL 也要同步改成新端口，例如 `http://localhost:20600/v1`。
+**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "9router/kr/claude-sonnet-4.5"
+      }
+    }
+  },
+  "models": {
+    "providers": {
+      "9router": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_9router",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "kr/claude-sonnet-4.5",
+            "name": "Claude Sonnet 4.5 (Kiro Free)"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> **Note:** OpenClaw only works with local 9Router. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.
+
+### Cline / Continue / RooCode
 
-## 部署
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-7
+```
 
-### PM2
+</details>
+
+<details>
+<summary><b>🚀 Deployment</b></summary>
+
+### VPS Deployment
 
 ```bash
+# Clone and install
+git clone https://github.com/decolua/9router.git
+cd 9router
 npm install
 npm run build
-pm2 start npm --name openrouterx -- start
+
+# Configure
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+export DATA_DIR="/var/lib/9router"
+export PORT="20128"
+export HOSTNAME="0.0.0.0"
+export NODE_ENV="production"
+export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
+export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
+export API_KEY_SECRET="endpoint-proxy-api-key-secret"
+export MACHINE_ID_SALT="endpoint-proxy-salt"
+
+# Start
+npm run start
+
+# Or use PM2
+npm install -g pm2
+pm2 start npm --name 9router -- start
+pm2 save
+pm2 startup
 ```
 
 ### Docker
 
-```bash
-docker build -t openrouterx .
+Published images (multi-platform `linux/amd64` + `linux/arm64`):
+- Docker Hub: [`decolua/9router`](https://hub.docker.com/r/decolua/9router)
+- GHCR: [`ghcr.io/decolua/9router`](https://github.com/decolua/9router/pkgs/container/9router)
 
+**Quick start (use published image):**
+
+```bash
 docker run -d \
-  --name openrouterx \
-  -p 20502:20502 \
-  --env-file ./.env \
-  -v openrouterx-data:/app/data \
-  openrouterx
-```
-
-## 环境变量
-
-| 变量 | 说明 |
-| --- | --- |
-| `JWT_SECRET` | Dashboard 登录鉴权使用的 JWT secret |
-| `INITIAL_PASSWORD` | 初始登录密码，在没有已保存 hash 时使用 |
-| `DATA_DIR` | 主数据库目录 |
-| `PORT` | 服务端口 |
-| `HOSTNAME` | 监听地址 |
-| `BASE_URL` | 服务端内部使用的 base URL |
-| `CLOUD_URL` | 云端同步使用的 base URL |
-| `NEXT_PUBLIC_BASE_URL` | 前端可见的 base URL |
-| `NEXT_PUBLIC_CLOUD_URL` | 前端可见的云端 URL |
-| `API_KEY_SECRET` | 生成 API Key 时使用的签名 secret |
-| `MACHINE_ID_SALT` | 机器标识计算使用的 salt |
-| `ENABLE_REQUEST_LOGS` | 是否开启请求日志 |
-| `AUTH_COOKIE_SECURE` | 是否强制使用安全 Cookie |
-| `REQUIRE_API_KEY` | 是否要求 `/v1/*` 必须携带 Bearer API Key |
-
-## API 示例
+  --name 9router \
+  -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" \
+  -e DATA_DIR=/app/data \
+  decolua/9router:latest
+```
+
+→ Open http://localhost:20128
+
+**Build from source (dev):**
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+docker build -t 9router .
+docker run -d --name 9router -p 20128:20128 \
+  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router
+```
+
+**Container defaults:**
+- `PORT=20128`
+- `HOSTNAME=0.0.0.0`
+
+**Useful commands:**
+
+```bash
+docker logs -f 9router
+docker restart 9router
+docker stop 9router && docker rm 9router
+docker pull decolua/9router:latest   # update to latest
+```
+
+**Data persistence:** `$HOME/.9router/db/data.sqlite` on host ↔ `/app/data/db/data.sqlite` in container.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generated (`~/.9router/jwt-secret`) | JWT signing secret for dashboard auth cookie (override to share across instances) |
+| `INITIAL_PASSWORD` | `123456` | First login password when no saved hash exists |
+| `DATA_DIR` | `~/.9router` | Main app data location (SQLite at `$DATA_DIR/db/data.sqlite`) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL used by cloud sync jobs |
+| `CLOUD_URL` | `https://9router.com` | Server-side cloud sync endpoint base URL |
+| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Backward-compatible/public base URL (prefer `BASE_URL` for server runtime) |
+| `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | Backward-compatible/public cloud URL (prefer `CLOUD_URL` for server runtime) |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | Salt for stable machine ID hashing |
+| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs under `logs/` |
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (set `true` behind HTTPS reverse proxy) |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` routes (recommended for internet-exposed deploys) |
+| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | empty | Optional outbound proxy for upstream provider calls |
+
+Notes:
+- Lowercase proxy variables are also supported: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`.
+- `.env` is not baked into Docker image (`.dockerignore`); inject runtime config with `--env-file` or `-e`.
+- On Windows, `APPDATA` can be used for local storage path resolution.
+- `INSTANCE_NAME` appears in older docs/env templates, but is currently not used at runtime.
+
+### Runtime Files and Storage
+
+- Main app state: `${DATA_DIR}/db/data.sqlite` (SQLite — providers, combos, aliases, keys, settings, usage history)
+- Auto backups: `${DATA_DIR}/db/backups/`
+- Optional request/translator logs: `<repo>/logs/...` when `ENABLE_REQUEST_LOGS=true`
+- Both `${DATA_DIR}` and `~/.9router` resolve to the same location in a Docker container — the symlink `/root/.9router -> /app/data` is created at build time.
+
+</details>
+
+---
+
+## 📊 Available Models
+
+<details>
+<summary><b>View all available models</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+- `cc/claude-opus-4-7`
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+- `cx/gpt-5.5`
+- `cx/gpt-5.4`
+- `cx/gpt-5.3-codex`
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**GitHub Copilot (`gh/`)**:
+- `gh/gpt-5.4`
+- `gh/claude-opus-4.7`
+- `gh/claude-sonnet-4.6`
+- `gh/gemini-3.1-pro-preview`
+- `gh/grok-code-fast-1`
+
+**Cursor (`cu/`)** - Subscription:
+- `cu/claude-4.6-opus-max`
+- `cu/claude-4.5-sonnet-thinking`
+- `cu/gpt-5.3-codex`
+- `cu/kimi-k2.5`
+
+**GLM (`glm/`)** - $0.6/1M:
+- `glm/glm-5.1`
+- `glm/glm-5`
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+- `minimax/MiniMax-M2.7`
+- `minimax/MiniMax-M2.5`
+
+**Kimi (`kimi/`)** - $9/mo flat:
+- `kimi/kimi-k2.5`
+- `kimi/kimi-k2.5-thinking`
+
+**Kiro (`kr/`)** - FREE unlimited:
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+- `kr/glm-5`
+- `kr/MiniMax-M2.5`
+- `kr/qwen3-coder-next`
+- `kr/deepseek-3.2`
+
+**OpenCode Free (`oc/`)** - FREE no-auth:
+- Auto-fetched from `opencode.ai/zen/v1/models`
+
+**Vertex AI (`vertex/`)** - $300 free credits:
+- `vertex/gemini-3.1-pro-preview`
+- `vertex/gemini-3-flash-preview`
+- `vertex/gemini-2.5-flash`
+- `vertex-partner/glm-5-maas`
+- `vertex-partner/deepseek-v3.2-maas`
+
+</details>
+
+---
+
+## 🐛 Troubleshooting
+
+**"Language model did not provide messages"**
+- Provider quota exhausted → Check dashboard quota tracker
+- Solution: Use combo fallback or switch to cheaper tier
+
+**Rate limiting**
+- Subscription quota out → Fallback to GLM/MiniMax
+- Add combo: `cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5`
+
+**OAuth token expired**
+- Auto-refreshed by 9Router
+- If issues persist: Dashboard → Provider → Reconnect
+
+**High costs**
+- Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens)
+- Check usage stats in Dashboard
+- Switch primary model to GLM/MiniMax
+- Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks
+
+**Dashboard opens on wrong port**
+- Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**First login not working**
+- Check `INITIAL_PASSWORD` in `.env`
+- If unset, fallback password is `123456`
+
+**No request logs under `logs/`**
+- Set `ENABLE_REQUEST_LOGS=true`
+
+---
+
+## 🛠️ Tech Stack
+
+- **Runtime**: Node.js 20+
+- **Framework**: Next.js 16
+- **UI**: React 19 + Tailwind CSS 4
+- **Database**: SQLite (better-sqlite3 / node:sqlite / sql.js fallback)
+- **Streaming**: Server-Sent Events (SSE)
+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
+
+---
+
+## 📝 API Reference
 
 ### Chat Completions
 
 ```bash
-curl http://localhost:20502/v1/chat/completions \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "kr/claude-sonnet-4.5",
-    "messages": [
-      { "role": "user", "content": "Write a Node.js hello world server." }
-    ],
-    "stream": false
-  }'
+POST http://localhost:20128/v1/chat/completions
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "cc/claude-opus-4-6",
+  "messages": [
+    {"role": "user", "content": "Write a function to..."}
+  ],
+  "stream": true
+}
 ```
 
-### 列出模型
+### List Models
 
 ```bash
-curl http://localhost:20502/v1/models \
-  -H "Authorization: Bearer YOUR_API_KEY"
+GET http://localhost:20128/v1/models
+Authorization: Bearer your-api-key
+
+→ Returns all models + combos in OpenAI format
 ```
 
-## 常见问题
+## 📧 Support
+
+- **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)
+
+---
+
+## 👥 Contributors
+
+Thanks to all contributors who helped make 9Router better!
+
+[![Contributors](https://contrib.rocks/image?repo=decolua/9router&max=150&columns=15&anon=1&v=20260309)](https://github.com/decolua/9router/graphs/contributors)
 
-### Dashboard 打不开
+---
 
-- 检查 `20502` 端口是否被占用
-- 启动前显式设置 `PORT=20502`
+## 📊 Star Chart
 
-### 登录失败
+[![Star Chart](https://starchart.cc/decolua/9router.svg?variant=adaptive)](https://starchart.cc/decolua/9router)
 
-- 初始化环境时检查 `INITIAL_PASSWORD`
-- 如果已经有历史数据，请使用当前保存的管理员密码，不要假设存在默认密码
 
-### 工具看不到模型
 
-- 确认供应商已连接
-- 确认当前 API Key 属于当前用户
-- 如果是子用户，检查 `Admin -> Users` 中配置的 allowed providers
+## 🔀 Forks
 
-### Usage 没有数据
+**[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker.
 
-- 确认工具接入的是 `http://localhost:20502/v1`
-- 确认使用的是 Dashboard 中生成的 Bearer API Key
+---
 
-### 上游报错或配额不足
+## 🙏 Acknowledgments
 
-- 重新连接供应商
-- 切换到其他模型
-- 创建带 fallback 的 combo
+Built on the shoulders of giants:
 
-## 包信息
+- **CLIProxyAPI(https://github.com/router-for-me/CLIProxyAPI)** — original Go implementation that inspired this JavaScript port.
+- **[RTK](https://github.com/rtk-ai/rtk)** ![Stars](https://img.shields.io/github/stars/rtk-ai/rtk?style=flat&color=yellow) — Rust token-saver. 9Router ports its compression pipeline to JS → **−20-40% input tokens** on every request.
+- **[Caveman](https://github.com/JuliusBrussee/caveman)** ![Stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=flat&color=yellow) by **[@JuliusBrussee](https://github.com/JuliusBrussee)** — viral *"why use many token when few token do trick"*. 9Router adapts its prompt → **−65% output tokens**.
 
-- npm 包：[`@yina-npm/openrouterx`](https://www.npmjs.com/package/@yina-npm/openrouterx)
-- 启动命令：`openrouterX`
-- 代码仓库：[`hackyinge/9router`](https://github.com/hackyinge/9router)
-- 当前分支：[`feat/openrouterx-release`](https://github.com/hackyinge/9router/tree/feat/openrouterx-release)
-- 协议：MIT
+Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub!
 
-## 作者
+---
 
-如果你喜欢这个项目，欢迎到 GitHub 给 [`hackyinge/9router`](https://github.com/hackyinge/9router) 点个 Star。Star 会直接决定作者继续摸鱼写功能的速度。
+## 📄 License
 
-作者除了写 AI 工具，也在番茄小说写小说。感兴趣可以在番茄小说搜索作者：**首席摸鱼**。
+MIT License - see [LICENSE](LICENSE) for details.
 
-## License
+---
 
-MIT，见 [LICENSE](LICENSE)。
+<div align="center">
+  <sub>Built with ❤️ for developers who code 24/7</sub>
+</div>