omniroute 0.8.8 → 1.0.0

package/README.zh-CN.md

@@ -0,0 +1,995 @@
+<div align="center">
+  <img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
+  
+  # 🚀 OmniRoute — 免费 AI 网关
+
+### 永不停止编程。智能路由至**免费和低成本 AI 模型**，自动故障转移。
+
+_您的通用 API 代理 — 一个端点，36+ 提供商，零停机时间。_
+
+**Chat Completions • Embeddings • 图像生成 • 音频 • Reranking • 100% TypeScript**
+
+---
+
+### 🤖 为您最爱的编程代理提供免费 AI
+
+_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API 网关，无限编程。_
+
+  <table>
+    <tr>
+      <td align="center" width="110">
+        <a href="https://github.com/cline/cline">
+          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
+          <b>OpenClaw</b>
+        </a><br/>
+        <sub>⭐ 205K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/HKUDS/nanobot">
+          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
+          <b>NanoBot</b>
+        </a><br/>
+        <sub>⭐ 20.9K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/sipeed/picoclaw">
+          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
+          <b>PicoClaw</b>
+        </a><br/>
+        <sub>⭐ 14.6K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/zeroclaw-labs/zeroclaw">
+          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
+          <b>ZeroClaw</b>
+        </a><br/>
+        <sub>⭐ 9.9K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/nearai/ironclaw">
+          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
+          <b>IronClaw</b>
+        </a><br/>
+        <sub>⭐ 2.1K</sub>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" width="110">
+        <a href="https://github.com/anomalyco/opencode">
+          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
+          <b>OpenCode</b>
+        </a><br/>
+        <sub>⭐ 106K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/openai/codex">
+          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
+          <b>Codex CLI</b>
+        </a><br/>
+        <sub>⭐ 60.8K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/anthropics/claude-code">
+          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
+          <b>Claude Code</b>
+        </a><br/>
+        <sub>⭐ 67.3K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/google-gemini/gemini-cli">
+          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
+          <b>Gemini CLI</b>
+        </a><br/>
+        <sub>⭐ 94.7K</sub>
+      </td>
+      <td align="center" width="110">
+        <a href="https://github.com/Kilo-Org/kilocode">
+          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
+          <b>Kilo Code</b>
+        </a><br/>
+        <sub>⭐ 15.5K</sub>
+      </td>
+    </tr>
+  </table>
+
+<sub>📡 所有代理通过 <code>http://localhost:20128/v1</code> 或 <code>http://cloud.omniroute.online/v1</code> 连接 — 一个配置，无限模型和配额</sub>
+
+---
+
+[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
+[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
+[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
+
+[🌐 网站](https://omniroute.online) • [🚀 快速开始](#-快速开始) • [💡 功能特性](#-核心功能) • [📖 文档](#-文档) • [💰 定价](#-定价概览)
+
+🌐 **多语言版本：** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
+
+</div>
+
+---
+
+## 🤔 为什么选择 OmniRoute？
+
+**停止浪费金钱和遭遇限制：**
+
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 订阅配额每月未使用就过期
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 速率限制在编程中途停止你
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 昂贵的 API（每个提供商 $20-50/月）
+- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 手动在提供商间切换
+
+**OmniRoute 解决这些问题：**
+
+- ✅ **最大化订阅** — 追踪配额，在重置前用完每一点
+- ✅ **自动故障转移** — 订阅 → API Key → 低价 → 免费，零停机
+- ✅ **多账号** — 每个提供商的账号轮询
+- ✅ **通用** — 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、任何 CLI 工具
+
+---
+
+## 🔄 工作原理
+
+```
+┌─────────────┐
+│  您的 CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│   工具      │
+└──────┬──────┘
+       │ http://localhost:20128/v1
+       ↓
+┌─────────────────────────────────────────┐
+│         OmniRoute（智能路由器）           │
+│  • 格式转换（OpenAI ↔ Claude）          │
+│  • 配额追踪 + Embeddings + 图像         │
+│  • 自动令牌刷新                         │
+└──────┬──────────────────────────────────┘
+       │
+       ├─→ [第1层: 订阅] Claude Code, Codex, Gemini CLI
+       │   ↓ 配额用完
+       ├─→ [第2层: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM 等
+       │   ↓ 预算限制
+       ├─→ [第3层: 低价] GLM ($0.6/1M), MiniMax ($0.2/1M)
+       │   ↓ 预算限制
+       └─→ [第4层: 免费] iFlow, Qwen, Kiro（无限制）
+
+结果：永不停止编程，成本最低
+```
+
+---
+
+## ⚡ 快速开始
+
+**1. 全局安装：**
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+🎉 仪表板在 `http://localhost:20128` 打开
+
+| 命令                    | 描述                         |
+| ----------------------- | ---------------------------- |
+| `omniroute`             | 启动服务器（默认端口 20128） |
+| `omniroute --port 3000` | 使用自定义端口               |
+| `omniroute --no-open`   | 不自动打开浏览器             |
+| `omniroute --help`      | 显示帮助                     |
+
+**2. 连接免费提供商：**
+
+仪表板 → 提供商 → 连接 **Claude Code** 或 **Antigravity** → OAuth 登录 → 完成！
+
+**3. 在 CLI 工具中使用：**
+
+```
+Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline 设置：
+  Endpoint: http://localhost:20128/v1
+  API Key: [从仪表板复制]
+  Model: if/kimi-k2-thinking
+```
+
+**完成！** 开始使用免费 AI 模型编程。
+
+**替代方案 — 从源代码运行：**
+
+```bash
+cp .env.example .env
+npm install
+PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+```
+
+---
+
+## 🐳 Docker
+
+OmniRoute 作为公共 Docker 镜像在 [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) 上可用。
+
+**快速运行：**
+
+```bash
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**使用环境文件：**
+
+```bash
+# 先复制并编辑 .env
+cp .env.example .env
+
+docker run -d \
+  --name omniroute \
+  --restart unless-stopped \
+  --env-file .env \
+  -p 20128:20128 \
+  -v omniroute-data:/app/data \
+  diegosouzapw/omniroute:latest
+```
+
+**使用 Docker Compose：**
+
+```bash
+# 基础配置（无 CLI 工具）
+docker compose --profile base up -d
+
+# CLI 配置（内置 Claude Code、Codex、OpenClaw）
+docker compose --profile cli up -d
+```
+
+| 镜像                     | 标签     | 大小   | 描述       |
+| ------------------------ | -------- | ------ | ---------- |
+| `diegosouzapw/omniroute` | `latest` | ~250MB | 最新稳定版 |
+| `diegosouzapw/omniroute` | `0.9.0`  | ~250MB | 当前版本   |
+
+---
+
+## 💰 定价概览
+
+| 层级           | 提供商            | 费用                  | 配额重置        | 最适合       |
+| -------------- | ----------------- | --------------------- | --------------- | ------------ |
+| **💳 订阅**    | Claude Code (Pro) | $20/月                | 5小时 + 每周    | 已订阅用户   |
+|                | Codex (Plus/Pro)  | $20-200/月            | 5小时 + 每周    | OpenAI 用户  |
+|                | Gemini CLI        | **免费**              | 180K/月 + 1K/天 | 所有人！     |
+|                | GitHub Copilot    | $10-19/月             | 每月            | GitHub 用户  |
+| **🔑 API KEY** | NVIDIA NIM        | **免费**（1000 积分） | 一次性          | 免费测试     |
+|                | DeepSeek          | 按使用量              | 无              | 最佳性价比   |
+|                | Groq              | 免费层 + 付费         | 限速            | 超快推理     |
+|                | xAI (Grok)        | 按使用量              | 无              | Grok 模型    |
+|                | Mistral           | 免费层 + 付费         | 限速            | 欧洲 AI      |
+|                | OpenRouter        | 按使用量              | 无              | 100+ 模型    |
+| **💰 低价**    | GLM-4.7           | $0.6/1M               | 每日 10时       | 经济备用     |
+|                | MiniMax M2.1      | $0.2/1M               | 5小时滚动       | 最便宜选项   |
+|                | Kimi K2           | $9/月固定             | 每月 10M Token  | 可预测成本   |
+| **🆓 免费**    | iFlow             | $0                    | 无限制          | 8 个免费模型 |
+|                | Qwen              | $0                    | 无限制          | 3 个免费模型 |
+|                | Kiro              | $0                    | 无限制          | 免费 Claude  |
+
+**💡 专业建议：** 从 Gemini CLI（每月 180K 免费）+ iFlow（无限免费）开始 = $0 成本！
+
+---
+
+## 🎯 使用场景
+
+### 场景 1："我有 Claude Pro 订阅"
+
+**问题：** 配额未使用就过期，编程高峰期遇到速率限制
+
+```
+Combo: "maximize-claude"
+  1. cc/claude-opus-4-6        （充分使用订阅）
+  2. glm/glm-4.7               （配额用完时的便宜备用）
+  3. if/kimi-k2-thinking       （免费应急后备）
+
+每月成本：$20（订阅）+ ~$5（备用）= $25 总计
+对比：$20 + 遇到限制 = 受挫
+```
+
+### 场景 2："我想要零成本"
+
+**问题：** 无法承担订阅费用，需要可靠的 AI 编程
+
+```
+Combo: "free-forever"
+  1. gc/gemini-3-flash         （每月 180K 免费）
+  2. if/kimi-k2-thinking       （无限免费）
+  3. qw/qwen3-coder-plus       （无限免费）
+
+每月成本：$0
+质量：生产级模型
+```
+
+### 场景 3："我需要 24/7 编程，不中断"
+
+**问题：** 截止日期紧迫，不能有停机时间
+
+```
+Combo: "always-on"
+  1. cc/claude-opus-4-6        （最佳质量）
+  2. cx/gpt-5.2-codex          （第二个订阅）
+  3. glm/glm-4.7               （便宜，每日重置）
+  4. minimax/MiniMax-M2.1      （最便宜，5小时重置）
+  5. if/kimi-k2-thinking       （免费无限制）
+
+结果：5 层故障转移 = 零停机
+```
+
+### 场景 4："我想在 OpenClaw 中使用免费 AI"
+
+**问题：** 需要在消息应用中使用 AI 助手，完全免费
+
+```
+Combo: "openclaw-free"
+  1. if/glm-4.7                （无限免费）
+  2. if/minimax-m2.1           （无限免费）
+  3. if/kimi-k2-thinking       （无限免费）
+
+每月成本：$0
+访问方式：WhatsApp、Telegram、Slack、Discord、iMessage、Signal...
+```
+
+---
+
+## 💡 核心功能
+
+### 🧠 路由与智能
+
+| 功能                      | 功能描述                                                                   |
+| ------------------------- | -------------------------------------------------------------------------- |
+| 🎯 **智能 4 层故障转移**  | 自动路由：订阅 → API Key → 低价 → 免费                                     |
+| 📊 **实时配额追踪**       | 实时 Token 计数 + 每个提供商的重置倒计时                                   |
+| 🔄 **格式转换**           | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换                          |
+| 👥 **多账号支持**         | 每个提供商多个账号，智能选择                                               |
+| 🔄 **自动令牌刷新**       | OAuth 令牌自动刷新并重试                                                   |
+| 🎨 **自定义组合**         | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized |
+| 🧩 **自定义模型**         | 为任何提供商添加任何模型 ID                                                |
+| 🌐 **通配符路由**         | 动态路由 `provider/*` 模式到任何提供商                                     |
+| 🧠 **推理预算**           | passthrough、auto、custom 和 adaptive 模式用于推理模型                     |
+| 💬 **System Prompt 注入** | 全局 System Prompt 应用于所有请求                                          |
+| 📄 **Responses API**      | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex                 |
+
+### 🎵 多模态 API
+
+| 功能              | 功能描述                                       |
+| ----------------- | ---------------------------------------------- |
+| 🖼️ **图像生成**   | `/v1/images/generations` — 4 个提供商，9+ 模型 |
+| 📐 **Embeddings** | `/v1/embeddings` — 6 个提供商，9+ 模型         |
+| 🎤 **音频转录**   | `/v1/audio/transcriptions` — Whisper 兼容      |
+| 🔊 **文字转语音** | `/v1/audio/speech` — 多提供商音频合成          |
+| 🛡️ **内容审核**   | `/v1/moderations` — 内容安全检查               |
+| 🔀 **重排序**     | `/v1/rerank` — 文档相关性重排序                |
+
+### 🛡️ 弹性与安全
+
+| 功能                  | 功能描述                               |
+| --------------------- | -------------------------------------- |
+| 🔌 **断路器**         | 每个提供商自动打开/关闭，可配置阈值    |
+| 🛡️ **反惊群**         | Mutex + 信号量限速用于 API Key 提供商  |
+| 🧠 **语义缓存**       | 两层缓存（签名 + 语义）降低成本和延迟  |
+| ⚡ **请求幂等性**     | 5 秒去重窗口防止重复请求               |
+| 🔒 **TLS 指纹伪装**   | 通过 wreq-js 绕过基于 TLS 的机器人检测 |
+| 🌐 **IP 过滤**        | 白名单/黑名单用于 API 访问控制         |
+| 📊 **可编辑速率限制** | 可配置的 RPM、最小间隔和最大并发       |
+
+### 📊 可观察性与分析
+
+| 功能               | 功能描述                                   |
+| ------------------ | ------------------------------------------ |
+| 📝 **请求日志**    | 调试模式，完整的请求/响应日志              |
+| 💾 **SQLite 日志** | 持久化代理日志，服务器重启后仍然保留       |
+| 📊 **分析仪表板**  | Recharts：统计卡片、使用量图表、提供商表格 |
+| 📈 **进度追踪**    | 流式传输的 SSE 进度事件（可选）            |
+| 🧪 **LLM 评估**    | 黄金集测试，4 种匹配策略                   |
+| 🔍 **请求遥测**    | p50/p95/p99 延迟聚合 + X-Request-Id 追踪   |
+| 📋 **日志 + 配额** | 专用页面用于日志浏览和配额追踪             |
+| 🏥 **健康仪表板**  | 运行时间、断路器状态、锁定、缓存统计       |
+| 💰 **成本追踪**    | 预算管理 + 每模型定价配置                  |
+
+### ☁️ 部署与同步
+
+| 功能                  | 功能描述                                                   |
+| --------------------- | ---------------------------------------------------------- |
+| 💾 **Cloud Sync**     | 通过 Cloudflare Workers 在设备间同步配置                   |
+| 🌐 **随处部署**       | Localhost、VPS、Docker、Cloudflare Workers                 |
+| 🔑 **API Key 管理**   | 按提供商生成、轮换和设定 API Key 范围                      |
+| 🧙 **配置向导**       | 4 步引导式设置，面向新用户                                 |
+| 🔧 **CLI 工具仪表板** | 一键配置 Claude、Codex、Cline、OpenClaw、Kilo、Antigravity |
+| 🔄 **数据库备份**     | 自动备份和恢复所有设置                                     |
+
+<details>
+<summary><b>📖 功能详情</b></summary>
+
+### 🎯 智能 4 层故障转移
+
+创建带自动故障转移的组合：
+
+```
+Combo: "my-coding-stack"
+  1. cc/claude-opus-4-6        （您的订阅）
+  2. nvidia/llama-3.3-70b      （免费 NVIDIA API）
+  3. glm/glm-4.7               （便宜备用，$0.6/1M）
+  4. if/kimi-k2-thinking       （免费后备）
+
+→ 配额用完或出错时自动切换
+```
+
+### 📊 实时配额追踪
+
+- 每个提供商的 Token 消耗
+- 重置倒计时（5 小时、每日、每周）
+- 付费层级的成本估算
+- 月度支出报告
+
+### 🔄 格式转换
+
+格式间的无缝转换：
+
+- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
+- 您的 CLI 发送 OpenAI 格式 → OmniRoute 转换 → 提供商接收原生格式
+- 适用于任何支持自定义 OpenAI 端点的工具
+
+### 👥 多账号支持
+
+- 每个提供商添加多个账号
+- 自动轮询或基于优先级的路由
+- 当一个账号达到配额时自动切换到下一个
+
+### 🔄 自动令牌刷新
+
+- OAuth 令牌在过期前自动刷新
+- 无需手动重新认证
+- 所有提供商的无缝体验
+
+### 🎨 自定义组合
+
+- 创建无限模型组合
+- 6 种策略：fill-first、round-robin、power-of-two-choices、random、least-used、cost-optimized
+- 通过 Cloud Sync 在设备间共享组合
+
+### 🏥 健康仪表板
+
+- 系统状态（运行时间、版本、内存使用）
+- 每个提供商的断路器状态（Closed/Open/Half-Open）
+- 速率限制状态和活动锁定
+- 签名缓存统计
+- 延迟遥测（p50/p95/p99）+ 提示缓存
+- 一键重置健康状态
+
+### 🔧 翻译器 Playground
+
+- 调试、测试和可视化 API 格式转换
+- 发送请求并查看 OmniRoute 如何在提供商格式间转换
+- 对排查集成问题非常有价值
+
+### 💾 Cloud Sync
+
+- 在设备间同步提供商、组合和设置
+- 自动后台同步
+- 安全加密存储
+
+</details>
+
+---
+
+## 📖 设置指南
+
+<details>
+<summary><b>💳 订阅提供商</b></summary>
+
+### Claude Code (Pro/Max)
+
+```bash
+仪表板 → 提供商 → 连接 Claude Code
+→ OAuth 登录 → 自动令牌刷新
+→ 5 小时 + 每周配额追踪
+
+模型：
+  cc/claude-opus-4-6
+  cc/claude-sonnet-4-5-20250929
+  cc/claude-haiku-4-5-20251001
+```
+
+**专业建议：** 复杂任务用 Opus，追求速度用 Sonnet。OmniRoute 按模型追踪配额！
+
+### OpenAI Codex (Plus/Pro)
+
+```bash
+仪表板 → 提供商 → 连接 Codex
+→ OAuth 登录（端口 1455）
+→ 5 小时 + 每周重置
+
+模型：
+  cx/gpt-5.2-codex
+  cx/gpt-5.1-codex-max
+```
+
+### Gemini CLI（免费 180K/月！）
+
+```bash
+仪表板 → 提供商 → 连接 Gemini CLI
+→ Google OAuth
+→ 每月 180K completions + 每天 1K
+
+模型：
+  gc/gemini-3-flash-preview
+  gc/gemini-2.5-pro
+```
+
+**最佳价值：** 巨大的免费额度！在付费层级之前使用。
+
+### GitHub Copilot
+
+```bash
+仪表板 → 提供商 → 连接 GitHub
+→ 通过 GitHub OAuth
+→ 每月重置（每月 1 日）
+
+模型：
+  gh/gpt-5
+  gh/claude-4.5-sonnet
+  gh/gemini-3-pro
+```
+
+</details>
+
+<details>
+<summary><b>🔑 API Key 提供商</b></summary>
+
+### NVIDIA NIM（免费 1000 积分！）
+
+1. 注册：[build.nvidia.com](https://build.nvidia.com)
+2. 获取免费 API key（包含 1000 推理积分）
+3. 仪表板 → 添加提供商 → NVIDIA NIM：
+   - API Key：`nvapi-your-key`
+
+**模型：** `nvidia/llama-3.3-70b-instruct`、`nvidia/mistral-7b-instruct` 及 50+ 更多
+
+**专业建议：** OpenAI 兼容的 API — 与 OmniRoute 的格式转换完美配合！
+
+### DeepSeek
+
+1. 注册：[platform.deepseek.com](https://platform.deepseek.com)
+2. 获取 API key
+3. 仪表板 → 添加提供商 → DeepSeek
+
+**模型：** `deepseek/deepseek-chat`、`deepseek/deepseek-coder`
+
+### Groq（免费层可用！）
+
+1. 注册：[console.groq.com](https://console.groq.com)
+2. 获取 API key（包含免费层）
+3. 仪表板 → 添加提供商 → Groq
+
+**模型：** `groq/llama-3.3-70b`、`groq/mixtral-8x7b`
+
+**专业建议：** 超快推理 — 最适合实时编程！
+
+### OpenRouter（100+ 模型）
+
+1. 注册：[openrouter.ai](https://openrouter.ai)
+2. 获取 API key
+3. 仪表板 → 添加提供商 → OpenRouter
+
+**模型：** 通过一个 API key 访问所有主要提供商的 100+ 模型。
+
+</details>
+
+<details>
+<summary><b>💰 低价提供商（备用）</b></summary>
+
+### GLM-4.7（每日重置，$0.6/1M）
+
+1. 注册：[Zhipu AI](https://open.bigmodel.cn/)
+2. 从 Coding Plan 获取 API key
+3. 仪表板 → 添加 API Key：
+   - 提供商：`glm`
+   - API Key：`your-key`
+
+**使用：** `glm/glm-4.7`
+
+**专业建议：** Coding Plan 以 1/7 的价格提供 3 倍配额！每日 10:00 AM 重置。
+
+### MiniMax M2.1（5 小时重置，$0.20/1M）
+
+1. 注册：[MiniMax](https://www.minimax.io/)
+2. 获取 API key
+3. 仪表板 → 添加 API Key
+
+**使用：** `minimax/MiniMax-M2.1`
+
+**专业建议：** 长上下文（1M Token）最便宜的选项！
+
+### Kimi K2（$9/月固定）
+
+1. 订阅：[Moonshot AI](https://platform.moonshot.ai/)
+2. 获取 API key
+3. 仪表板 → 添加 API Key
+
+**使用：** `kimi/kimi-latest`
+
+**专业建议：** 固定 $9/月 10M Token = $0.90/1M 有效成本！
+
+</details>
+
+<details>
+<summary><b>🆓 免费提供商（应急备用）</b></summary>
+
+### iFlow（8 个免费模型）
+
+```bash
+仪表板 → 连接 iFlow
+→ iFlow OAuth 登录
+→ 无限使用
+
+模型：
+  if/kimi-k2-thinking
+  if/qwen3-coder-plus
+  if/glm-4.7
+  if/minimax-m2
+  if/deepseek-r1
+```
+
+### Qwen（3 个免费模型）
+
+```bash
+仪表板 → 连接 Qwen
+→ 设备码授权
+→ 无限使用
+
+模型：
+  qw/qwen3-coder-plus
+  qw/qwen3-coder-flash
+```
+
+### Kiro（免费 Claude）
+
+```bash
+仪表板 → 连接 Kiro
+→ AWS Builder ID 或 Google/GitHub
+→ 无限使用
+
+模型：
+  kr/claude-sonnet-4.5
+  kr/claude-haiku-4.5
+```
+
+</details>
+
+<details>
+<summary><b>🎨 创建组合</b></summary>
+
+### 示例 1：最大化订阅 → 便宜备用
+
+```
+仪表板 → 组合 → 创建新的
+
+名称：premium-coding
+模型：
+  1. cc/claude-opus-4-6（订阅主力）
+  2. glm/glm-4.7（便宜备用，$0.6/1M）
+  3. minimax/MiniMax-M2.1（最便宜的后备，$0.20/1M）
+
+在 CLI 中使用：premium-coding
+```
+
+### 示例 2：仅免费（零成本）
+
+```
+名称：free-combo
+模型：
+  1. gc/gemini-3-flash-preview（每月 180K 免费）
+  2. if/kimi-k2-thinking（无限制）
+  3. qw/qwen3-coder-plus（无限制）
+
+成本：永远 $0！
+```
+
+</details>
+
+<details>
+<summary><b>🔧 CLI 集成</b></summary>
+
+### Cursor IDE
+
+```
+设置 → 模型 → 高级：
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [从 OmniRoute 仪表板获取]
+  Model: cc/claude-opus-4-6
+```
+
+### Claude Code
+
+使用仪表板中的 **CLI Tools** 页面一键配置，或手动编辑 `~/.claude/settings.json`。
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+
+codex "your prompt"
+```
+
+### OpenClaw
+
+**选项 1 — 仪表板（推荐）：**
+
+```
+仪表板 → CLI Tools → OpenClaw → 选择模型 → 应用
+```
+
+**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "models": {
+    "providers": {
+      "omniroute": {
+        "baseUrl": "http://127.0.0.1:20128/v1",
+        "apiKey": "sk_omniroute",
+        "api": "openai-completions"
+      }
+    }
+  }
+}
+```
+
+> **注意：** OpenClaw 仅支持本地 OmniRoute。使用 `127.0.0.1` 而非 `localhost` 以避免 IPv6 解析问题。
+
+### Cline / Continue / RooCode
+
+```
+设置 → API 配置：
+  提供商：OpenAI Compatible
+  Base URL: http://localhost:20128/v1
+  API Key: [从 OmniRoute 仪表板获取]
+  Model: if/kimi-k2-thinking
+```
+
+</details>
+
+---
+
+## 📊 可用模型
+
+<details>
+<summary><b>查看所有可用模型</b></summary>
+
+**Claude Code (`cc/`)** - Pro/Max:
+
+- `cc/claude-opus-4-6`
+- `cc/claude-sonnet-4-5-20250929`
+- `cc/claude-haiku-4-5-20251001`
+
+**Codex (`cx/`)** - Plus/Pro:
+
+- `cx/gpt-5.2-codex`
+- `cx/gpt-5.1-codex-max`
+
+**Gemini CLI (`gc/`)** - 免费:
+
+- `gc/gemini-3-flash-preview`
+- `gc/gemini-2.5-pro`
+
+**GitHub Copilot (`gh/`)**:
+
+- `gh/gpt-5`
+- `gh/claude-4.5-sonnet`
+
+**NVIDIA NIM (`nvidia/`)** - 免费积分:
+
+- `nvidia/llama-3.3-70b-instruct`
+- `nvidia/mistral-7b-instruct`
+- 50+ 更多模型在 [build.nvidia.com](https://build.nvidia.com)
+
+**GLM (`glm/`)** - $0.6/1M:
+
+- `glm/glm-4.7`
+
+**MiniMax (`minimax/`)** - $0.2/1M:
+
+- `minimax/MiniMax-M2.1`
+
+**iFlow (`if/`)** - 免费:
+
+- `if/kimi-k2-thinking`
+- `if/qwen3-coder-plus`
+- `if/deepseek-r1`
+- `if/glm-4.7`
+- `if/minimax-m2`
+
+**Qwen (`qw/`)** - 免费:
+
+- `qw/qwen3-coder-plus`
+- `qw/qwen3-coder-flash`
+
+**Kiro (`kr/`)** - 免费:
+
+- `kr/claude-sonnet-4.5`
+- `kr/claude-haiku-4.5`
+
+**OpenRouter (`or/`)** - 100+ 模型:
+
+- `or/anthropic/claude-4-sonnet`
+- `or/google/gemini-2.5-pro`
+- [openrouter.ai/models](https://openrouter.ai/models) 上的任何模型
+
+</details>
+
+---
+
+## 🧪 评估 (Evals)
+
+OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。
+
+### 内置黄金集
+
+预加载的「OmniRoute Golden Set」包含 10 个测试用例：
+
+- 问候、数学、地理、代码生成
+- JSON 格式合规性、翻译、markdown
+- 安全拒绝（有害内容）、计数、布尔逻辑
+
+### 评估策略
+
+| 策略       | 描述                             | 示例                             |
+| ---------- | -------------------------------- | -------------------------------- |
+| `exact`    | 输出必须完全匹配                 | `"4"`                            |
+| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"`                        |
+| `regex`    | 输出必须匹配正则表达式模式       | `"1.*2.*3"`                      |
+| `custom`   | 自定义 JS 函数返回 true/false    | `(output) => output.length > 10` |
+
+---
+
+## 🐛 故障排除
+
+<details>
+<summary><b>点击展开故障排除指南</b></summary>
+
+**"Language model did not provide messages"**
+
+- 提供商配额已耗尽 → 检查仪表板配额追踪器
+- 解决方案：使用组合故障转移或切换到更便宜的层级
+
+**速率限制**
+
+- 订阅配额耗尽 → 回退到 GLM/MiniMax
+- 添加组合：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
+
+**OAuth 令牌过期**
+
+- OmniRoute 自动刷新
+- 如果问题持续：仪表板 → 提供商 → 重新连接
+
+**高成本**
+
+- 在仪表板 → 成本中检查使用统计
+- 将主要模型切换为 GLM/MiniMax
+- 对非关键任务使用免费层（Gemini CLI、iFlow）
+
+**仪表板在错误端口打开**
+
+- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
+
+**Cloud sync 错误**
+
+- 验证 `BASE_URL` 指向您正在运行的实例
+- 验证 `CLOUD_URL` 指向预期的云端点
+- 保持 `NEXT_PUBLIC_*` 值与服务器端值一致
+
+**首次登录不工作**
+
+- 检查 `.env` 中的 `INITIAL_PASSWORD`
+- 如未设置，默认密码为 `123456`
+
+**没有请求日志**
+
+- 在 `.env` 中设置 `ENABLE_REQUEST_LOGS=true`
+
+**兼容 OpenAI 的提供商连接测试显示 "Invalid"**
+
+- 许多提供商不暴露 `/models` 端点
+- OmniRoute v0.9.0+ 包含通过 chat completions 的回退验证
+- 确保 base URL 包含 `/v1` 后缀
+
+</details>
+
+---
+
+## 🛠️ 技术栈
+
+- **运行时**: Node.js 20+
+- **语言**: TypeScript 5.9 — `src/` 和 `open-sse/` 中 **100% TypeScript**（v0.9.0）
+- **框架**: Next.js 16 + React 19 + Tailwind CSS 4
+- **数据库**: LowDB (JSON) + SQLite（领域状态 + 代理日志）
+- **流式传输**: Server-Sent Events (SSE)
+- **认证**: OAuth 2.0 (PKCE) + JWT + API Keys
+- **测试**: Node.js test runner（368+ 单元测试）
+- **CI/CD**: GitHub Actions（发布时自动 npm 发布 + Docker Hub）
+- **网站**: [omniroute.online](https://omniroute.online)
+- **包**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
+- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
+- **弹性**: 断路器、指数退避、反惊群、TLS 伪装
+
+---
+
+## 📖 文档
+
+| 文档                                | 描述                         |
+| ----------------------------------- | ---------------------------- |
+| [用户指南](docs/USER_GUIDE.md)      | 提供商、组合、CLI 集成、部署 |
+| [API 参考](docs/API_REFERENCE.md)   | 所有端点及示例               |
+| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案           |
+| [架构](docs/ARCHITECTURE.md)        | 系统架构和内部机制           |
+| [贡献指南](CONTRIBUTING.md)         | 开发设置和指南               |
+| [OpenAPI 规范](docs/openapi.yaml)   | OpenAPI 3.0 规范             |
+| [安全策略](SECURITY.md)             | 漏洞报告和安全实践           |
+
+---
+
+## 📧 支持
+
+- **网站**: [omniroute.online](https://omniroute.online)
+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
+
+---
+
+## 👥 贡献者
+
+[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+
+### 如何贡献
+
+1. Fork 仓库
+2. 创建功能分支（`git checkout -b feature/amazing-feature`）
+3. 提交更改（`git commit -m 'Add amazing feature'`）
+4. 推送到分支（`git push origin feature/amazing-feature`）
+5. 打开 Pull Request
+
+详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+### 发布新版本
+
+```bash
+# 创建发布 — npm 发布自动完成
+gh release create v0.9.0 --title "v0.9.0" --generate-notes
+```
+
+---
+
+## 📊 Star 历史
+
+<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
+ </picture>
+</a>
+
+---
+
+## 🙏 致谢
+
+特别感谢 **[decolua](https://github.com/decolua)** 的 **[9router](https://github.com/decolua/9router)** — 启发了本 fork 的原始项目。OmniRoute 在这个令人难以置信的基础上添加了额外功能、多模态 API 和完整的 TypeScript 重写。
+
+特别感谢 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — 启发了本 JavaScript 移植的原始 Go 实现。
+
+---
+
+## 📄 许可证
+
+MIT 许可证 — 详见 [LICENSE](LICENSE)。
+
+---
+
+<div align="center">
+  <sub>用 ❤️ 为 24/7 编程的开发者打造</sub>
+  <br/>
+  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
+</div>