# User Guide (中文 (繁體))
🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md)
---
🌐 **語言：** 🇺🇸 [English](./USER_GUIDE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/guides/USER_GUIDE.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/USER_GUIDE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/guides/USER_GUIDE.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/USER_GUIDE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/guides/USER_GUIDE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/guides/USER_GUIDE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/USER_GUIDE.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/USER_GUIDE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/USER_GUIDE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/guides/USER_GUIDE.md) | 🇪🇸 [Español](../i18n/es/docs/guides/USER_GUIDE.md) | 🇪🇪 [Eesti](../i18n/et/docs/guides/USER_GUIDE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/guides/USER_GUIDE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/USER_GUIDE.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/USER_GUIDE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/guides/USER_GUIDE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/guides/USER_GUIDE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/guides/USER_GUIDE.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/guides/USER_GUIDE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/guides/USER_GUIDE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/USER_GUIDE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/guides/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/USER_GUIDE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/guides/USER_GUIDE.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/USER_GUIDE.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/USER_GUIDE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/guides/USER_GUIDE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/guides/USER_GUIDE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/guides/USER_GUIDE.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/USER_GUIDE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/guides/USER_GUIDE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/guides/USER_GUIDE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/guides/USER_GUIDE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/guides/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/USER_GUIDE.md) | 🇲🇹 [Malti](../i18n/mt/docs/guides/USER_GUIDE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/guides/USER_GUIDE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/guides/USER_GUIDE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/USER_GUIDE.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/USER_GUIDE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/guides/USER_GUIDE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/guides/USER_GUIDE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/USER_GUIDE.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/USER_GUIDE.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/USER_GUIDE.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/USER_GUIDE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/guides/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/USER_GUIDE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/guides/USER_GUIDE.md) | 🇷🇸 [Српски](../i18n/sr/docs/guides/USER_GUIDE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/USER_GUIDE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/guides/USER_GUIDE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/guides/USER_GUIDE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/guides/USER_GUIDE.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/USER_GUIDE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/guides/USER_GUIDE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/USER_GUIDE.md) | 🇵🇰 [اردو](../i18n/ur/docs/guides/USER_GUIDE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/guides/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/USER_GUIDE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/guides/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/USER_GUIDE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/guides/USER_GUIDE.md)
設定提供者、建立組合、整合 CLI 工具及部署 OmniRoute 的完整指南。
---
## 目錄
- [定價一覽](#-pricing-at-a-glance)
- [使用案例](#-use-cases)
- [提供者設定](#-provider-setup)
- [CLI 整合](#-cli-integration)
- [部署](#-deployment)
- [可用模型](#-available-models)
- [進階功能](#-advanced-features)
- [自動路由（零設定）](#-auto-routing-zero-config)
- [MCP 與 A2A 整合](#-mcp--a2a-integration)
- [Skills 系統](#-skills-system)
- [記憶系統](#-memory-system)
- [Webhooks](#-webhooks)
- [雲端代理](#-cloud-agents)
- [程式化管理](#-programmatic-management)
- [內部 CLI](#-internal-cli)
- [桌面應用程式（Electron）](#-desktop-application-electron)
---
## 💰 定價一覽
| 方案 | 提供者 | 費用 | 配額重設週期 | 最適合 |
| --------------- | ----------------- | ----------- | ---------------- | -------------------- |
| **💳 訂閱制** | Claude Code (Pro) | $20/月 | 5 小時 + 每週 | 已訂閱的使用者 |
| | Codex (Plus/Pro) | $20-200/月 | 5 小時 + 每週 | OpenAI 使用者 |
| | GitHub Copilot | $10-19/月 | 每月 | GitHub 使用者 |
| **🔑 API 金鑰** | DeepSeek | 依用量付費 | 無 | 低成本推理 |
| | Groq | 依用量付費 | 無 | 超高速推論 |
| | xAI (Grok) | 依用量付費 | 無 | Grok 4 推理 |
| | Mistral | 依用量付費 | 無 | 託管於歐盟的模型 |
| | Perplexity | 依用量付費 | 無 | 搜尋增強 |
| | Together AI | 依用量付費 | 無 | 開放原始碼模型 |
| | Fireworks AI | 依用量付費 | 無 | 快速產生 FLUX 圖像 |
| | Cerebras | 依用量付費 | 無 | 晶圓級速度 |
| | Cohere | 依用量付費 | 無 | Command R+ RAG |
| | NVIDIA NIM | 依用量付費 | 無 | 企業級模型 |
| | Baidu Qianfan | 依用量付費 | 無 | ERNIE 模型 |
| **💰 低價** | GLM-4.7 | $0.6/1M | 每日上午 10 點 | 低預算備援 |
| | MiniMax M2.1 | $0.2/1M | 5 小時滾動重設 | 最便宜的選項 |
| | Kimi K2 | $9/月固定費 | 10M tokens/月 | 可預測的成本 |
| **🆓 免費** | Qoder | $0 | 依提供者限制而定 | 請確認目前的模型目錄 |
| | Kiro | $0 | 約 50 點數/月 | 免費使用 Claude |
---
## 🎯 使用案例
### 案例 1：「我有 Claude Pro 訂閱」
**問題：** 配額尚未使用便過期，大量編寫程式碼時會遇到速率限制
```
組合：「maximize-claude」
1. cc/claude-opus-4-7 （充分利用訂閱）
2. glm/glm-4.7 （配額用盡時的低成本備援）
3. if/qwen3.8-max-preview （免費的緊急後備方案）
每月費用：$20（訂閱）+ 約 $5（備援）= 總計 $25
相較之下，僅支付 $20 卻遇到限制，會令人感到挫折
```
### 案例 2：「我想要零成本」
**問題：** 無法負擔訂閱費用，但需要可靠的 AI 程式開發工具
```
組合：「zero-cost」
1. if/kimi-k2.7-code （列為可免費使用；可能有速率限制）
2. kr/qwen3-coder-next （Kiro 免費後備方案）
每月費用：$0
品質：請針對您的工作負載確認模型、限制、隱私權及 SLA
```
### 案例 3：「我需要全天候編寫程式碼，不可中斷」
**問題：** 有截止期限，無法承受停機
```
組合：「always-on」
1. cc/claude-opus-4-7 （最佳品質）
2. cx/gpt-5.5 （第二個訂閱）
3. glm/glm-4.7 （低成本，每日重設）
4. minimax/MiniMax-M2.1 （最便宜，5 小時重設）
5. if/deepseek-v4-flash （列為可免費使用；可能有速率限制）
結果：5 層後備方案可提高韌性；不保證上游服務的可用性
每月費用：$20-200（訂閱）+ $10-20（備援）
```
### 案例 4：「我想在 OpenClaw 中使用免費 AI」
**問題：** 需要可用於通訊應用程式且完全免費的 AI 助理
```
組合：「openclaw-free」
1. if/qwen3.8-max-preview （列為可免費使用；可能有速率限制）
2. if/deepseek-v4-flash （列為可免費使用；可能有速率限制）
3. if/kimi-k2.7-code （列為可免費使用；可能有速率限制）
每月費用：$0
可透過以下平台存取：WhatsApp、Telegram、Slack、Discord、iMessage、Signal……
```
---
## 📖 提供者設定
若要從 CSV 或 JSON 檔案批次新增 API 金鑰連線，請使用 **控制台 → 提供者 → 從檔案匯入**。欄位採用固定位置順序（`provider,name,apiKey,baseUrl,priority`）；`provider` 必須已作為受管理的提供者或相容節點存在。請參閱[從 CSV 或 JSON 檔案匯入提供者](../providers/CSV-IMPORT.md)。
### 🔐 訂閱型提供者
#### Claude Code (Pro/Max)
```bash
控制台 → 提供者 → 連線 Claude Code
→ OAuth 登入 → 自動重新整理權杖
→ 5 小時 + 每週配額追蹤
模型：
cc/claude-opus-4-7
cc/claude-sonnet-4-6
cc/claude-haiku-4-5-20251001
```
**專業提示：**複雜任務使用 Opus，追求速度則使用 Sonnet。OmniRoute 會追蹤各模型的配額！
OmniRoute 主機上沒有瀏覽器？請在任何已登入 Claude Code 的環境執行 `claude setup-token`，並將一年期權杖貼到 **Setup Token** 分頁中。請參閱[使用設定權杖的 Claude Code](../providers/CLAUDE_CODE_SETUP_TOKEN.md)。
Claude 與 Claude Code 相容路由會保留 Opus 和 Sonnet 模型的 `max` 思考強度。Haiku 模型不接受 `max` 強度層級，因此 OmniRoute 會在將該要求傳送至上游之前，將其降級為高思考預算。
#### OpenAI Codex (Plus/Pro)
```bash
控制台 → 提供者 → 連線 Codex
→ OAuth 登入（連接埠 1455）
→ 每 5 小時 + 每週重設
模型：
cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.3-codex-spark
```
#### GitHub Copilot
```bash
控制台 → 提供者 → 連線 GitHub
→ 透過 GitHub 進行 OAuth
→ 每月重設（每月 1 日）
模型：
gh/gpt-5.5
gh/gpt-5.4
gh/claude-sonnet-4.6
gh/claude-opus-4.7
gh/gemini-3.1-pro-preview
```
### 💰 平價提供者
#### GLM-4.7（每日重設，$0.6/1M）
1. 註冊：[Zhipu AI](https://open.bigmodel.cn)
2. 從 Coding Plan 取得 API 金鑰
3. 控制台 → 新增 API 金鑰：提供者：`glm`，API 金鑰：`your-key`
**使用方式：**`glm/glm-4.7` — **專業提示：**Coding Plan 以 1/7 的成本提供 3 倍配額！每日上午 10:00 重設。
#### MiniMax M2.1（每 5 小時重設，$0.20/1M）
1. 註冊：[MiniMax](https://www.minimax.io)
2. 取得 API 金鑰 → 控制台 → 新增 API 金鑰
**使用方式：**`minimax/MiniMax-M2.1` — **專業提示：**這是長上下文（1M 個權杖）最便宜的選項！
#### Kimi K2（每月固定 $9）
1. 訂閱：[Moonshot AI](https://platform.kimi.ai?aff=omniroute)
2. 取得 API 金鑰 → 控制台 → 新增 API 金鑰
**使用方式：**`kimi/kimi-k2.5` — **專業提示：**每月固定 $9 可使用 10M 個權杖，實際成本為 $0.90/1M！
#### Baidu Qianfan / ERNIE
1. 註冊：[Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop)
2. 建立 Qianfan API 金鑰 → 控制台 → 新增 API 金鑰：提供者：`qianfan`
**使用方式：**`qianfan/ernie-5.1`、`qianfan/ernie-x1.1`，或其他與 OpenAI 相容的 Qianfan 模型 ID。
### 🆓 免費提供者
無須驗證的免費提供者，其提供者頁面上的 **不需要驗證** 旁設有開關。
關閉該開關會停用該提供者、將其從「已設定的提供者」／精簡檢視中移除，並從 `/v1/models` 移除其模型。
#### Qoder（9 個免費模型）
```bash
控制台 → 連線 Qoder → OAuth 登入 → 存取權受目前提供者限制約束
模型：if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3
```
#### Kiro（免費 Claude）
```bash
控制台 → 連線 Kiro → AWS Builder ID 或 Google/GitHub → 每月約 50 點額度
模型：kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 組合
你可以在 **儀表板 → 組合** 中拖曳每張卡片上的控點，直接重新排列組合卡片。順序會儲存在 SQLite 中，並在重新載入時還原。
### 範例 1：最大化運用訂閱 → 低價備援
```
儀表板 → 組合 → 建立新組合
名稱：premium-coding
模型：
1. cc/claude-opus-4-7（主要訂閱模型）
2. glm/glm-4.7（低價備援，$0.6/1M）
3. minimax/MiniMax-M2.7（最便宜的後備模型，$0.3/1M）
在 CLI 中使用：premium-coding
```
### 範例 2：僅使用免費模型（零成本）
```
名稱：free-combo
模型：
1. if/kimi-k2.7-code（列為免費存取；可能受提供者限制）
2. kr/qwen3-coder-next（Kiro 免費後備模型）
成本：目前列為 $0；條款與可用性可能有所變更
```
---
## 🔧 CLI 整合
### Cursor IDE
**將 Cursor 作為 OmniRoute 用戶端使用**（透過 OmniRoute 路由 Cursor 聊天）：
```
設定 → 模型 → 進階：
OpenAI API 基礎 URL：http://localhost:20128/v1
OpenAI API 金鑰：[來自 OmniRoute 儀表板]
模型：cc/claude-opus-4-7
```
**將 OmniRoute 作為 Cursor 提供者使用**（OmniRoute 呼叫上游 Cursor）：建議使用
**儀表板 → 提供者 → Cursor → 使用 Cursor 登入**。若使用 Docker，請參閱
[`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md)。
### Claude Code
編輯 `~/.claude/settings.json`：
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
}
}
```
請在此使用與 Claude 相容的根端點。請勿在 `ANTHROPIC_BASE_URL` 後附加 `/v1`。
### Codex CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### OpenClaw
編輯 `~/.openclaw/openclaw.json`：
```json
{
"agents": {
"defaults": {
"model": { "primary": "omniroute/if/kimi-k2.7-code" }
}
},
"models": {
"providers": {
"omniroute": {
"baseUrl": "http://localhost:20128/v1",
"apiKey": "your-omniroute-api-key",
"api": "openai-completions",
"models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
}
}
}
}
```
**或使用儀表板：** CLI 工具 → OpenClaw → 自動設定
### Cline / Continue / RooCode
```
提供者：OpenAI 相容
基礎 URL：http://localhost:20128/v1
API 金鑰：[來自儀表板]
模型：cc/claude-opus-4-7
```
---
## 🚀 部署
### 全域 npm 安裝（建議）
```bash
npm install -g omniroute
# 建立設定目錄
mkdir -p ~/.omniroute
# 建立 .env 檔案（請參閱 .env.example）
cp .env.example ~/.omniroute/.env
# 啟動伺服器
omniroute
# 或使用自訂連接埠：
omniroute --port 3000
```
CLI 會自動從 `~/.omniroute/.env` 或 `./.env` 載入 `.env`。
### 系統匣模式
在系統匣中啟動 OmniRoute：
```bash
omniroute serve --tray
```
伺服器與系統匣準備就緒後，此命令便會返回。
伺服器會在沒有終端機的情況下繼續執行。
系統匣模式支援 macOS、Windows 與具有圖形介面的 Linux 工作階段。系統匣模式不會自動開啟儀表板。
使用系統匣選單執行下列操作：
- 開啟儀表板。
- 開啟 `/dashboard/logs`。
- 變更自動啟動設定。
- 停止 OmniRoute。
請勿將 `--tray` 與下列選項搭配使用：
- `--daemon`
- `--log`
- `--no-recovery`
這些模式需要不同的程序擁有權。
啟用下次登入機器時自動啟動：
```bash
omniroute autostart enable
```
在 macOS、Windows 與具有圖形介面的 Linux 工作階段中，自動啟動會使用系統匣模式。無頭 Linux 則使用現有的 systemd 使用者服務。
停用登入時自動啟動：
```bash
omniroute autostart disable
```
### 解除安裝
當你不再需要 OmniRoute 時，我們提供兩個快速指令碼，可乾淨地將其移除：
| 命令 | 動作 |
| ------------------------ | ---------------------------------------------------------------- |
| `npm run uninstall` | 移除系統應用程式，但會**保留 `~/.omniroute` 中的資料庫與設定**。 |
| `npm run uninstall:full` | 移除應用程式，並永久**清除所有設定、金鑰與資料庫**。 |
> 注意：若要執行這些命令，請前往 OmniRoute 專案資料夾（如果你已複製該專案），然後執行命令。或者，若是以全域方式安裝，只需執行 `npm uninstall -g omniroute`。
### VPS 部署
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
npm run start
# 或：pm2 start npm --name omniroute -- start
```
### PM2 部署（低記憶體）
對於 RAM 有限的伺服器，請使用記憶體限制選項：
```bash
# 使用 512MB 限制（預設）
pm2 start npm --name omniroute -- start
# 或使用自訂記憶體限制
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# 或使用 ecosystem.config.js
pm2 start ecosystem.config.js
```
建立 `ecosystem.config.js`：
```javascript
module.exports = {
apps: [
{
name: "omniroute",
script: "npm",
args: "start",
env: {
NODE_ENV: "production",
OMNIROUTE_MEMORY_MB: "512",
JWT_SECRET: "your-secret",
INITIAL_PASSWORD: "your-password",
},
node_args: "--max-old-space-size=512",
max_memory_restart: "300M",
},
],
};
```
### Docker
```bash
# 建置映像檔（預設 = 預先安裝 codex/claude/droid 的 runner-cli）
docker build -t omniroute:cli .
# 可攜式模式（建議）
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
如需包含 CLI 二進位檔的主機整合模式，請參閱主要文件中的 Docker 章節。
### Void Linux (xbps-src)
Void Linux 使用者可以透過 `xbps-src` 交叉編譯框架，以原生方式封裝並安裝 OmniRoute。此框架會自動執行 Node.js 獨立建置，並包含所需的 `better-sqlite3` 原生繫結。
檢視 xbps-src 範本
```bash
# 'omniroute' 的範本檔案
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit "
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
do_build() {
# 判斷 node-gyp 的目標 CPU 架構
local _gyp_arch
case "$XBPS_TARGET_MACHINE" in
aarch64*) _gyp_arch=arm64 ;;
armv7*|armv6*) _gyp_arch=arm ;;
i686*) _gyp_arch=ia32 ;;
*) _gyp_arch=x64 ;;
esac
# 1) 安裝所有相依套件 – 略過指令碼
NODE_ENV=development npm ci --ignore-scripts
# 2) 建置 Next.js 獨立套件
npm run build
# 3) 將靜態資源複製到獨立套件中
cp -r .next/static .next/standalone/.next/static
[ -d public ] && cp -r public .next/standalone/public || true
# 4) 編譯 better-sqlite3 原生繫結
local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
# 5) 將已編譯的繫結放入獨立套件中
local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
mkdir -p "$_bs3_release"
cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
# 6) 移除架構特定的 sharp 套件
rm -rf .next/standalone/node_modules/@img
# 7) 複製 Next.js 靜態分析所遺漏的 pino 執行階段相依套件：
for _mod in pino-abstract-transport split2 process-warning; do
cp -r "node_modules/$_mod" .next/standalone/node_modules/
done
}
do_check() {
npm run test:unit
}
do_install() {
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
# 防止安裝後掛鉤移除空的 Next.js 應用程式路由器目錄
for _d in \
.next/standalone/.next/server/app/dashboard \
.next/standalone/.next/server/app/dashboard/settings \
.next/standalone/.next/server/app/dashboard/providers; do
touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done
cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
vbin "${WRKDIR}/omniroute"
}
post_install() {
vlicense LICENSE
}
```
### 環境變數
| 變數 | 預設值 | 說明 |
| --------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 簽署密鑰（**在正式環境中請務必更改**） |
| `INITIAL_PASSWORD` | `CHANGEME` | 首次登入密碼 |
| `DATA_DIR` | `~/.omniroute` | 資料目錄（資料庫、使用量、日誌） |
| `PORT` | 框架預設值 | 服務連接埠（範例中為 `20128`） |
| `HOSTNAME` | 框架預設值 | 綁定主機（Docker 預設為 `0.0.0.0`） |
| `NODE_ENV` | 執行階段預設值 | 部署時設為 `production` |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | 提供給儀表板並公開給伺服器的公開基礎 URL（取代舊版的 `BASE_URL`） |
| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | 雲端同步端點的基礎 URL（取代舊版的 `CLOUD_URL`） |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 用於產生 API 金鑰的 HMAC 密鑰 |
| `REQUIRE_API_KEY` | `false` | 強制要求在 `/v1/*` 使用 Bearer API 金鑰 |
| `ALLOW_API_KEY_REVEAL` | `false` | 允許已驗證的儀表板使用者視需要顯示完整的已儲存 API 金鑰值 |
| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | 伺服器端重新整理快取 Provider Limits 資料的頻率；UI 重新整理按鈕仍會觸發手動同步 |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | 停用寫入／匯入／還原前的自動 SQLite 快照；手動備份仍可運作 |
| `APP_LOG_TO_FILE` | `true` | 啟用將應用程式與稽核日誌輸出至磁碟 |
| `AUTH_COOKIE_SECURE` | `false` | 強制使用 `Secure` 驗證 Cookie（位於 HTTPS 反向代理之後） |
| `CLOUDFLARED_BIN` | 未設定 | 使用現有的 `cloudflared` 二進位檔，而非受管理的下載版本 |
| `CLOUDFLARED_PROTOCOL` | `http2` | 受管理 Quick Tunnels 的傳輸協定（`http2`、`quic` 或 `auto`） |
| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆積記憶體限制（MB） |
| `PROMPT_CACHE_MAX_SIZE` | `50` | 提示詞快取項目的最大數量 |
| `SEMANTIC_CACHE_MAX_SIZE` | `100` | 語意快取項目的最大數量 |
如需完整的環境變數參考，請參閱 [README](../README.md)。
---
## 📊 可用模型
檢視所有可用模型
> 以下清單整理自 v3.8.0 的 `open-sse/config/providerRegistry.ts`。雲端目錄（Gemini、OpenRouter 等）會動態同步——若要查看完整的即時目錄，請開啟 **儀表板 → 提供者 → [provider] → 可用模型**，或呼叫 `GET /api/models/catalog`。
>
> 如果提供者的內建清單已過時，請在該頁面使用 **從 /models 匯入**（或啟用 **自動同步**），以擷取上游的即時目錄。此功能已在 v3.8.50 中針對 LLM7.io（`gemini-3.1-flash-lite`）與 UncloseAI（`solidrust/Hermes-3-Llama-3.1-8B-AWQ`）完成驗證；在同一輪測試期間，Pollinations 的匿名存取仍受上游限制。
**Claude Code（`cc/`）** — Pro/Max OAuth：`cc/claude-opus-4-8`、`cc/claude-opus-4-7`、`cc/claude-opus-4-6`、`cc/claude-opus-4-5-20251101`、`cc/claude-sonnet-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001`
**Codex（`cx/`）** — Plus/Pro OAuth：`cx/gpt-5.5`（+ 推理強度層級：`gpt-5.5-xhigh`、`gpt-5.5-high`、`gpt-5.5-medium`、`gpt-5.5-low`）、`cx/gpt-5.4`、`cx/gpt-5.4-mini`、`cx/gpt-5.3-codex`、`cx/gpt-5.3-codex-spark`
**GitHub Copilot（`gh/`）** — OAuth：`gh/gpt-5.5`、`gh/gpt-5.4`、`gh/gpt-5.4-mini`、`gh/gpt-5-mini`、`gh/gpt-5.3-codex`、`gh/claude-opus-4.7`、`gh/claude-opus-4.6`、`gh/claude-opus-4-5-20251101`、`gh/claude-sonnet-4.6`、`gh/claude-sonnet-4.5`、`gh/claude-haiku-4.5`、`gh/gemini-3.1-pro-preview`、`gh/gemini-3-flash-preview`、`gh/oswe-vscode-prime`
**Kiro（`kr/`）** — 免費 OAuth：請使用 **儀表板 → 提供者 → Kiro → 可用模型** 下顯示的即時目錄。可用性取決於帳戶與方案。
**Qoder（`if/`）** — 免費 OAuth：`if/qwen3.8-max-preview`、`if/qwen3.7-max`、`if/qwen3.7-plus`、`if/kimi-k3`、`if/kimi-k2.7-code`、`if/glm-5.2`、`if/deepseek-v4-pro`、`if/deepseek-v4-flash`、`if/minimax-m3`
**GLM（`glm/`、`glm-cn/`、`zai/`、`glmt/`）** — $0.2–0.6/1M：`glm/glm-5.1`、`glm/glm-5`、`glm/glm-5-turbo`、`glm/glm-4.7`、`glm/glm-4.7-flash`、`glm/glm-4.6`、`glm/glm-4.6v`、`glm/glm-4.5`、`glm/glm-4.5v`、`glm/glm-4.5-air`
**MiniMax（`minimax/`、`minimax-cn/`）** — $0.2/1M：`minimax/MiniMax-M2.7`、`minimax/MiniMax-M2.7-highspeed`、`minimax/MiniMax-M2.5`、`minimax/MiniMax-M2.5-highspeed`
**Kimi（`kimi/`、`kimi-coding/`、`kimi-coding-apikey/`）** — 每月固定 $9 或按用量計費：`kimi/kimi-k2.6`、`kimi/kimi-k2.5`
**DeepSeek（`ds/`）** — API 金鑰：`ds/deepseek-v4-pro`、`ds/deepseek-v4-flash`
**Groq（`groq/`）** — 超高速：`groq/llama-3.3-70b-versatile`、`groq/meta-llama/llama-4-maverick-17b-128e-instruct`、`groq/qwen/qwen3-32b`、`groq/openai/gpt-oss-120b`
**xAI（`xai/`）** — 原生 Grok：`xai/grok-4.3`、`xai/grok-4.20-multi-agent-0309`、`xai/grok-4.20-0309-reasoning`、`xai/grok-4.20-0309-non-reasoning`
**Mistral（`mistral/`）** — 託管於歐盟：`mistral/mistral-large-latest`、`mistral/mistral-medium-3-5`、`mistral/mistral-small-latest`、`mistral/devstral-latest`、`mistral/codestral-latest`
**Perplexity（`pplx/`）** — 搜尋增強：`pplx/sonar-deep-research`、`pplx/sonar-reasoning-pro`、`pplx/sonar-pro`、`pplx/sonar`
**Together AI（`together/`）** — 開放原始碼：`together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free`（免費）、`together/meta-llama/Llama-Vision-Free`、`together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`、`together/deepseek-ai/DeepSeek-R1`、`together/Qwen/Qwen3-235B-A22B`、`together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`
**Fireworks AI（`fireworks/`）** — 快速推論：`fireworks/accounts/fireworks/models/kimi-k2p6`、`fireworks/accounts/fireworks/models/minimax-m2p7`、`fireworks/accounts/fireworks/models/qwen3p6-plus`、`fireworks/accounts/fireworks/models/glm-5p1`、`fireworks/accounts/fireworks/models/deepseek-v4-pro`
**Cerebras（`cerebras/`）** — 晶圓級：`cerebras/zai-glm-4.7`、`cerebras/gpt-oss-120b`
**Cohere（`cohere/`）** — 專注於 RAG：`cohere/command-a-reasoning-08-2025`、`cohere/command-a-vision-07-2025`、`cohere/command-a-03-2025`、`cohere/command-r-08-2024`
**NVIDIA NIM（`nvidia/`）** — 企業級：`nvidia/z-ai/glm-5.1`、`nvidia/minimaxai/minimax-m2.7`、`nvidia/google/gemma-4-31b-it`、`nvidia/mistralai/mistral-small-4-119b-2603`、`nvidia/mistralai/mistral-large-3-675b-instruct-2512`、`nvidia/qwen/qwen3.5-397b-a17b`、`nvidia/deepseek-ai/deepseek-v4-pro`、`nvidia/openai/gpt-oss-120b`、`nvidia/nvidia/nemotron-3-super-120b-a12b`
**Baidu Qianfan（`qianfan/`）** — ERNIE：`qianfan/ernie-5.1`、`qianfan/ernie-5.0-thinking-latest`、`qianfan/ernie-x1.1`
**Ollama Cloud（`ollama-cloud/`）**：`ollama-cloud/deepseek-v4-pro`、`ollama-cloud/deepseek-v4-flash`、`ollama-cloud/kimi-k2.6`、`ollama-cloud/glm-5.1`、`ollama-cloud/minimax-m2.7`、`ollama-cloud/gemma4:31b`、`ollama-cloud/qwen3.5:397b`
**Gemini（Google Cloud `gemini/`）**：依照 API 金鑰從 Google 即時同步——不提供靜態清單。請在 **儀表板 → 提供者** 中連接金鑰，然後使用 **可用模型** 匯入目前的目錄（例如 `gemini/gemini-3-pro`、`gemini/gemini-3-flash`）。
**其他相容的提供者**（精選）：`cohere`、`databricks`、`snowflake`、`together`、`vertex`、`alibaba`、`alibaba-cn`、`bedrock`（透過 `aws-bedrock`）、`azure-ai`、`openrouter`（直通目錄）、`siliconflow`、`hyperbolic`、`huggingface`、`featherless-ai`、`cloudflare-ai`、`scaleway`、`deepinfra`、`vercel-ai-gateway`、`bazaarlink`、`friendliai`、`nous-research`、`reka`、`volcengine`、`ai21`、`gigachat`。每個提供者都在 `providerRegistry.ts` 中維護自己的模型清單，且當提供者公開 `/models` 端點時，可以進行自動同步。
**模型 ID 注意事項：** OmniRoute 使用提供者原生 ID（`claude-opus-4-8`、`gpt-5.5`、`glm-5.1`、`MiniMax-M2.7`、`kimi-k2.5`、`grok-4.20-0309-reasoning`）。部分 ID 包含以點號分隔的版本，因為上游 API 即要求採用此格式。如果上方未列出某個模型，請執行 `omniroute models --search ` 或存取 `GET /api/models/catalog` 以確認其可用性。
---
## 🧩 進階功能
### 自訂模型
將任何模型 ID 新增至任何提供者，無須等待應用程式更新：
```bash
# 透過 API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'
# 列出：curl http://localhost:20128/api/provider-models?provider=openai
# 移除：curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"
```
或使用儀表板：**提供者 → [提供者] → 自訂模型**。
注意事項：
- OpenRouter 與 OpenAI/Anthropic 相容提供者僅透過**可用模型**進行管理。手動新增、匯入及自動同步都會進入同一份可用模型清單，因此這些提供者不會有獨立的「自訂模型」區段。
- **自訂模型**區段適用於不提供受管理可用模型匯入功能的提供者。
### 自訂 OpenAI 相容提供者
任何支援 OpenAI API 的閘道（自行託管的代理伺服器、vLLM、第三方彙整服務）
都可新增為獨立的提供者節點：
1. **提供者 → 新增 OpenAI 相容提供者**。
2. **名稱**：節點的顯示標籤。
3. **前綴**：路由名稱。用戶端會以 `/` 呼叫模型，因此前綴為
`mygw` 的節點會提供 `mygw/gpt-4o-mini`。此欄位為必填；沒有字元限制。
4. **API 類型**：閘道提供的端點系列（Chat Completions、Responses、
Embeddings、音訊、圖片）。
5. **基礎 URL**：截至並包含 `/v1` 的 API 根路徑（例如
`https://gateway.example.com/v1`），而非完整的 `/chat/completions` 路徑。若閘道使用
非標準路徑，請在**進階設定**中設定（聊天路徑、模型路徑）。
6. **API 金鑰（用於檢查）**欄位只會測試連線。建立節點後，
開啟該節點並使用**新增連線**，以儲存請求實際使用的金鑰。
節點會取得格式為 `openai-compatible--` 的內部 ID；你永遠
不需要輸入它，前綴就是公開名稱。
#### 保留前綴
前綴不得為內建提供者的 ID 或別名（例如 `openai`、`cf`），也不得為
已停用提供者的 ID。模型解析器會先檢查內建 ID 和別名，再檢查
自訂節點，因此使用這些前綴的節點永遠不會收到流量：
`/model` 會改由內建提供者處理；若該提供者已停用，則會以封閉方式失敗。
若使用這類前綴建立或編輯節點，將遭拒絕並顯示：
```text
prefix: "" 是保留的提供者前綴 — 請選擇其他前綴（保留的 ID/別名不能用於自訂節點，因為像 /model 這樣的請求會路由至內建提供者，或在該提供者停用時以封閉方式失敗）
```
請選擇不重複的前綴（`mygw`、`acme-proxy`）。如果傳送至自訂節點的請求失敗，且
錯誤訊息提及內建提供者或其認證資訊，請檢查節點的前綴是否為
保留前綴：在此規則出現之前儲存的節點仍會保留，但其前綴會路由至
內建提供者。請編輯節點並指定新的前綴。
### 串接 OmniRoute 對等節點
另一個 OmniRoute 閘道可新增為**自訂 OpenAI 相容**提供者。請使用
對等節點的 `/v1` 基礎 URL，以及由該對等節點核發、權限最小化的專用 API 金鑰。
對於雙向或多跳串接，請在每個閘道上啟用選擇加入式迴圈防護：
```bash
# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
```bash
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
```
只有傳送至明確加入允許清單之對等節點 URL 的請求，才會收到
`X-OmniRoute-Peer-Trace` 標頭。若執行個體 ID 重複或跳數
額度已用盡，閘道會以 HTTP `508 Loop Detected` 拒絕請求；一般上游提供者不會收到任何對等節點中繼資料。
對等節點串接並非資料庫複寫或主機容錯移轉。每個閘道都會保有獨立的
SQLite 狀態、快取、速率計數器及工作階段。若要實現主動／被動或主動／主動可用性，請使用具備健康狀態檢查的反向代理伺服器或用戶端
容錯移轉，且切勿將同一個 SQLite 資料庫掛載至多個執行中的 OmniRoute 執行個體。
### 專用提供者路由
將請求直接路由至特定提供者，並執行模型驗證：
```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
```
若缺少提供者前綴，系統會自動新增。模型不相符時會傳回 `400`。
### 網路代理伺服器設定
```bash
# 設定全域代理伺服器
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# 各提供者的代理伺服器
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# 測試代理伺服器
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**優先順序：**特定金鑰 → 特定組合 → 特定提供者 → 全域 → 環境。
### 模型目錄 API
```bash
curl http://localhost:20128/api/models/catalog
```
傳回依提供者分組的模型及其類型（`chat`、`embedding`、`image`）。
### 雲端同步
- 跨裝置同步提供者、組合及設定
- 自動背景同步，具備逾時與快速失敗機制
- 在正式環境中優先使用伺服器端的 `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL`
### Cloudflare 快速通道
- 適用於 Docker 與其他自行託管的部署，可在 **儀表板 → 端點** 中使用
- 建立臨時的 `https://*.trycloudflare.com` URL，並將流量轉送至您目前與 OpenAI 相容的 `/v1` 端點
- 首次啟用時僅會在需要時安裝 `cloudflared`；後續重新啟動時會重複使用相同的受管理執行檔
- OmniRoute 或容器重新啟動後，不會自動還原 Quick Tunnel；需要時請從儀表板重新啟用
- Tunnel URL 為暫時性，每次停止／啟動 Tunnel 時都會變更
- 受管理的 Quick Tunnel 預設使用 HTTP/2 傳輸，以避免在資源受限的容器中出現大量 QUIC UDP 緩衝區警告
- 若要覆寫受管理的傳輸方式，請將 `CLOUDFLARED_PROTOCOL` 設為 `quic` 或 `auto`
- 若您偏好使用預先安裝的 `cloudflared` 執行檔，而非受管理的下載版本，請設定 `CLOUDFLARED_BIN`
- Cloudflare Quick Tunnel、Tailscale Funnel 與 ngrok Tunnel 面板可在 **設定 → 外觀** 中顯示或隱藏。隱藏面板不會停止正在執行的 Tunnel。
### LLM Gateway 智慧功能（第 9 階段）
- **語意快取** — 自動快取非串流且 temperature=0 的回應（可透過 `X-OmniRoute-No-Cache: true` 略過）
- **請求冪等性** — 透過 `Idempotency-Key` 或 `X-Request-Id` 標頭，對 5 秒內的請求進行去重
- **進度追蹤** — 透過 `X-OmniRoute-Progress: true` 標頭選擇啟用 SSE `event: progress` 事件
---
### Translator Playground
可透過 **儀表板 → Translator** 存取。偵錯並視覺化 OmniRoute 如何在提供者之間轉譯 API 請求。
| 模式 | 用途 |
| ---------------- | ------------------------------------------------------- |
| **Playground** | 選取來源／目標格式、貼上請求，並立即查看轉譯後的輸出 |
| **Chat Tester** | 透過 Proxy 傳送即時聊天訊息，並檢查完整的請求／回應週期 |
| **Test Bench** | 對多種格式組合執行批次測試，以驗證轉譯的正確性 |
| **Live Monitor** | 在請求流經 Proxy 時監看即時轉譯 |
**使用案例：**
- 偵錯特定用戶端／提供者組合失敗的原因
- 驗證思考標籤、工具呼叫與系統提示是否正確轉譯
- 比較 OpenAI、Claude、Gemini 與 Responses API 格式之間的差異
---
### 路由策略
透過 **儀表板 → 設定 → 路由** 進行設定。儀表板提供六種最常用的策略；組合與自動路由器在內部支援更廣泛的策略。
**儀表板中可見的策略（帳戶層級路由）：**
| 策略 | 說明 |
| ----------------------- | ----------------------------------------------------------------------- |
| **優先填滿** | 按優先順序使用帳戶——主要帳戶會處理所有請求，直到無法使用為止 |
| **輪詢** | 循環使用所有帳戶，並採用可設定的黏著限制（預設：每個帳戶 3 次呼叫） |
| **P2C（兩個隨機選擇）** | 隨機選取 2 個帳戶，並將請求路由至健康狀況較佳者——兼顧健康狀況以平衡負載 |
| **隨機** | 使用 Fisher-Yates 洗牌，為每個請求隨機選取一個帳戶 |
| **最少使用** | 將請求路由至 `lastUsedAt` 時間戳記最早的帳戶，以平均分配流量 |
| **成本最佳化** | 將請求路由至優先順序值最低的帳戶，以選用成本最低的提供者 |
**進階組合與自動策略**（可按組合設定，或透過 `auto/*` 前綴設定——請參閱 [AUTO-COMBO.md](../routing/AUTO-COMBO.md)）：
- `priority` — 嚴格依序選用，絕不輪詢
- `weighted` — 依各模型的權重按比例分配流量
- `fill-first` — 持續使用第一個模型，直到達到限制
- `round-robin` / `strict-random` / `random`
- `p2c`（兩個隨機選擇）
- `least-used` 與 `cost-optimized`
- `auto` — 根據分數在所有候選項目中選擇
- `lkgp`（最後已知的良好提供者）— 固定使用最後一次成功的提供者，之後再依規則進行後援
- `context-optimized` — 選取可用上下文視窗最大的模型
- `context-relay` — 串接長上下文模型以處理後續對話輪次
#### 外部黏著工作階段標頭
如需外部工作階段親和性（例如位於反向 Proxy 後方的 Claude Code/Codex Agent），請傳送：
```http
X-Session-Id: your-session-key
```
OmniRoute 也接受 `x_session_id`，並在 `X-OmniRoute-Session-Id` 中傳回實際使用的工作階段金鑰。
若您使用 Nginx 並傳送底線形式的標頭，請啟用：
```nginx
underscores_in_headers on;
```
#### 萬用字元模型別名
建立萬用字元模式以重新映射模型名稱：
```
模式：claude-sonnet-* → 目標：cc/claude-sonnet-4-6
模式：gpt-* → 目標：gh/gpt-5.3-codex
```
萬用字元支援 `*`（任意字元）與 `?`（單一字元）。
#### 後援鏈
定義套用至所有請求的全域後援鏈：
```
鏈：production-fallback
1. cc/claude-opus-4-7
2. gh/gpt-5.3-codex
3. glm/glm-4.7
```
---
### 常見提供者組合與路由模式
以下是在 OmniRoute 中結合多個提供者並在其間進行路由的範例模式：
#### 1. 程式設計 Agent 組合：高階推理搭配成本／速度後援
適合程式設計 Agent（OpenCode、Claude Code、Cursor、Cline）。最初將請求路由至前沿推理模型，並在配額耗盡或發生錯誤時，後援至快速的程式設計模型。
- **儀表板**：組合 → 新增組合 → 名稱：`agent-coding` → 策略：`Priority`
- **模型**：
1. `claude/claude-sonnet-4-6`（主要程式設計 Agent）
2. `openai/gpt-4o`（次要高容量後援）
3. `deepseek/deepseek-v4-flash`（高效率、具成本效益的後援）
```bash
# 透過 API 的範例
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent-coding",
"strategy": "priority",
"models": [
{ "model": "claude/claude-sonnet-4-6" },
{ "model": "openai/gpt-4o" },
{ "model": "deepseek/deepseek-v4-flash" }
]
}'
```
#### 2. 免費方案自動容錯移轉組合
串接多個免費方案與無需金鑰的提供者，在不產生 API 成本的情況下最大化正常運作時間。
- **策略**：`Least Used` 或 `Round Robin`（將負載分散至各配額）
- **模型**：
1. `groq/llama-3.3-70b-versatile`
2. `gemini/gemini-2.5-flash`
3. `cerebras/gpt-oss-120b`
```bash
# 透過 CLI 的範例
omniroute combo create free-stack \
--models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
--strategy round-robin
```
#### 3. 多模態／視覺與文字管線
將專門的視覺模型與高速文字生成模型配對，用於涉及影像理解與程式碼生成的工作流程。
- **模式**：一個 `Priority` 組合，先列出支援視覺的模型，最後列出高輸送量的文字／程式碼模型。
- **模型**：
1. `gemini/gemini-2.5-pro`（強大的影像／多模態理解能力）
2. `openai/gpt-4o`（兼顧視覺與工具使用）
3. `deepseek/deepseek-v4-flash`（文字／程式碼生成）
---
### 韌性與斷路器
透過 **儀表板 → 設定 → 韌性** 進行設定。
OmniRoute 透過五個元件實作提供者層級的韌性：
1. **請求佇列與速率控制** — 系統層級的請求流量塑形：
- **每分鐘請求數（RPM）** — 每個帳戶每分鐘的最大請求數
- **請求之間的最短時間** — 請求之間的最小間隔（毫秒）
- **最大並行請求數** — 每個帳戶可同時執行的最大請求數
2. **連線冷卻** — 單一連線在發生可重試失敗後，依驗證類型進行設定：
- **基礎冷卻時間** — 可重試上游失敗的預設冷卻時間範圍
- **使用上游重試提示** — 若有提供，則採用具權威性的 `Retry-After` 或重設提示
- **最大退避步數** — 重複失敗時的最大指數退避層級
3. **提供者斷路器** — 追蹤端對端的提供者失敗，在達到設定的警告閾值時將提供者標記為降級，並在達到設定的失敗閾值時開啟斷路器：
- **降級閾值** — 進入 `DEGRADED` 前允許的連續提供者失敗次數
- **失敗閾值** — 進入 `OPEN` 前允許的連續提供者失敗次數
- **重設逾時** — 再次測試提供者前的等待時間範圍
- **CLOSED**（健康）— 請求正常流通
- **DEGRADED** — 請求仍會流通，同時追蹤升高的失敗率
- **OPEN** — 提供者在重複失敗後暫時遭到封鎖
- **HALF_OPEN** — 測試提供者是否已恢復
連線範圍的 `429` 速率限制會保留在**連線冷卻**中，且不會計入提供者斷路器。
提供者斷路器的執行階段狀態僅顯示於**儀表板 → 健康狀態**。
4. **等待冷卻結束** — 若所有候選連線都已處於冷卻狀態，OmniRoute 可等待最早結束的冷卻時間，並自動重試相同的用戶端請求。
5. **自動偵測速率限制** — 啟用此設定後，當上游提供者傳回明確的等待時間範圍時，這些提示會覆寫本機連線的冷卻時間。
**專業提示：**在服務中斷後，請使用**健康狀態**頁面檢查並重設即時提供者斷路器。韌性頁面僅用於變更設定。
---
### 資料庫匯出／匯入
在**儀表板 → 設定 → 系統與儲存空間**中管理資料庫備份。
| 動作 | 說明 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| **匯出資料庫** | 將目前的 SQLite 資料庫下載為 `.sqlite` 檔案 |
| **全部匯出（.tar.gz）** | 下載完整備份封存檔，包括：資料庫、設定、組合、提供者連線（不含憑證）、API 金鑰中繼資料 |
| **匯入資料庫** | 上傳 `.sqlite` 檔案以取代目前的資料庫。除非 `DISABLE_SQLITE_AUTO_BACKUP=true`，否則系統會在匯入前自動建立備份 |
```bash
# API：匯出資料庫
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API：全部匯出（完整封存檔）
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API：匯入資料庫
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**匯入驗證：**系統會驗證匯入檔案的完整性（SQLite pragma 檢查）、必要資料表（`provider_connections`、`provider_nodes`、`combos`、`api_keys`）以及大小（最大 100MB）。
**使用案例：**
- 在不同機器之間移轉 OmniRoute
- 建立外部備份以供災難復原
- 在團隊成員之間分享設定（全部匯出 → 分享封存檔）
---
### 設定儀表板
設定頁面分為 **7 個分頁**，方便瀏覽：
| 分頁 | 內容 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **一般** | 系統儲存工具、預設行為、Endpoint 通道可見性 |
| **外觀** | 佈景主題控制（淺色／深色／系統）、側邊欄可見性、Cloudflare/Tailscale/ngrok 通道卡片的面板切換 |
| **AI** | 思考預算（直通／自動移除／自訂／自適應——請參閱 [THINKING_BUDGET.md](./THINKING_BUDGET.md)）、全域系統提示詞、提示詞快取統計資料 |
| **安全性** | 登入／密碼設定、IP 存取控制、`/models` 的 API 驗證、提供者封鎖、提示詞注入防護 |
| **路由** | 全域路由策略（優先填滿／輪詢／P2C／隨機／最少使用／成本最佳化）、萬用字元模型別名、後備鏈、組合預設值 |
| **韌性** | 請求佇列、連線冷卻、提供者斷路器設定，以及等待冷卻行為 |
| **進階** | 全域代理伺服器設定（HTTP/SOCKS5）、個別提供者的代理伺服器覆寫 |
「一般」不再重複顯示唯讀的日誌與快取附註。資料庫保留與
最佳化設定會透過 `/api/settings/database` 持久儲存；手動清除快取則使用
`DELETE /api/cache`。請求與代理伺服器日誌的資料列上限由
`CALL_LOGS_TABLE_MAX_ROWS` 和 `PROXY_LOGS_TABLE_MAX_ROWS` 控制。
---
### 成本與預算管理
透過 **儀表板 → 成本** 存取。
| 分頁 | 用途 |
| -------- | ------------------------------------------------------------ |
| **預算** | 為每個 API 金鑰設定每日／每週／每月支出上限，並即時追蹤 |
| **定價** | 檢視及編輯模型定價項目——各提供者每 1K 個輸入／輸出權杖的成本 |
```bash
# API：設定預算
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API：取得目前的預算狀態
curl http://localhost:20128/api/usage/budget
```
**成本追蹤：**每個請求都會記錄權杖使用量，並使用定價表計算成本。可在 **儀表板 → 使用量** 中依提供者、模型和 API 金鑰檢視明細。
---
### 音訊轉錄
OmniRoute 透過與 OpenAI 相容的端點支援音訊轉錄：
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# 使用 curl 的範例
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@audio.mp3" \
-F "model=openai/whisper-1"
```
`deepgram/nova-3` 是 Deepgram 原生路由，需要 Deepgram API 金鑰。
如果只設定了 OpenRouter，請使用 `openrouter/deepgram/nova-3`。
**語音轉文字（轉錄）**提供者：
- `openai/`（與 whisper 相容）
- `groq/`（Groq Whisper Turbo）
- `deepgram/`（Nova 系列）
- `assemblyai/`
- `nvidia/`（Parakeet、Canary）
- `huggingface/`（whisper 變體）
- `qwen/`
**文字轉語音（`POST /v1/audio/speech`）**提供者：
- `openai/`（tts-1、tts-1-hd）
- `hyperbolic/`
- `deepgram/`（Aura）
- `nvidia/`（Magpie TTS）
- `elevenlabs/`
- `huggingface/`
- `inworld/`
- `cartesia/`
- `playht/`
- `kie/`
- `aws-polly/`
- `xiaomi-mimo/`
- `coqui/`、`tortoise/`
- `qwen/`
支援的轉錄音訊格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。TTS 輸出格式取決於提供者（mp3、wav、opus、pcm、mulaw）。
---
### 組合平衡策略
在 **儀表板 → 組合 → 建立／編輯 → 策略** 中設定個別組合的平衡方式。
| 策略 | 說明 |
| -------------- | -------------------------------------------------- |
| **輪詢** | 依序輪替使用各個模型 |
| **優先順序** | 一律先嘗試第一個模型；僅在發生錯誤時才使用後備模型 |
| **隨機** | 為每個請求從組合中隨機選擇一個模型 |
| **加權** | 根據為各模型指派的權重按比例路由 |
| **最少使用** | 路由至近期請求數最少的模型（使用組合指標） |
| **成本最佳化** | 路由至最便宜的可用模型（使用定價表） |
全域組合預設值可在 **儀表板 → 設定 → 路由 → 組合預設值** 中設定。
組合目標的逾時預設會繼承目前的請求逾時。僅當較短的個別目標限制應
更快觸發後備機制時，才在組合預設值或個別組合上使用 **目標逾時
（秒）**。
零延遲組合最佳化為選擇性啟用。停用 **零延遲最佳化**，以避免這些
延遲功能搶先競逐後備目標、根據 TTFT 歷史記錄略過目標，或壓縮後備
請求；啟用後，則允許已設定的對沖、預測性 TTFT 略過和主動後備壓縮，
以犧牲路由／請求保真度來換取較低的尾端延遲。
當上游提供者要求嚴格遵守 `max_tokens` / `maxOutputTokens` 限制時，請停用 **推理權杖緩衝區**。啟用後，組合路由僅會針對具有已知輸出上限的模型增加推理模型的預留空間；若安全緩衝後的值會超過該上限，則用戶端的權杖限制將維持不變。如果用戶端限制已高於已知上限，OmniRoute 會先將其下調至該上限，再傳送上游請求。
---
### 健康狀態儀表板
透過 **儀表板 → 健康狀態** 存取。以 6 張資訊卡即時呈現系統健康狀態概覽：
| 資訊卡 | 顯示內容 |
| ------------------ | -------------------------------------------- |
| **系統狀態** | 運作時間、版本、記憶體用量、資料目錄 |
| **提供者健康狀態** | 全域提供者斷路器的執行階段狀態 |
| **速率限制** | 各帳戶啟用中的連線冷卻狀態及剩餘時間 |
| **啟用中的鎖定** | 啟用中的模型範圍鎖定與暫時排除項目 |
| **簽章快取** | 去重複快取統計資料（啟用中的索引鍵、命中率） |
| **延遲遙測** | 各提供者的 p50/p95/p99 延遲彙總 |
**專業提示：** 健康狀態頁面每 10 秒自動重新整理一次。使用斷路器資訊卡來識別哪些提供者發生問題。
---
## 🤖 自動路由（零設定）
OmniRoute 內建**評分驅動的自動路由器**，可從所有已連線的提供者中，為每個請求選擇最佳模型，無需維護任何組合。只需使用其中一個 `auto/*` 前綴傳送請求，OmniRoute 就會即時建立虛擬組合，並根據延遲、成本、成功率、上下文適配度、模型對任務的適用性、近期失敗情況、配額及斷路器狀態為候選項目評分。
| 前綴 | 最佳化目標 |
| -------------- | ---------------------------------------------------------------------------------- |
| `auto` | 平衡的預設選項（延遲 × 成本 × 成功率） |
| `auto/coding` | 程式設計任務：優先選擇 Claude、GPT-5、GLM、Kimi、Qwen Coder、DeepSeek 程式設計模型 |
| `auto/cheap` | 最低的每 token 成本，可接受較高延遲 |
| `auto/fast` | 最低延遲，忽略成本 |
| `auto/offline` | 僅限本機提供者（Ollama、vLLM、llama.cpp）——適用於實體隔離環境 |
| `auto/smart` | 推理品質優先（Opus、GPT-5 xhigh、R1、GLM 5.1 reasoning） |
| `auto/lkgp` | 「最後已知的良好提供者」——固定使用最後成功的提供者，然後再退回至規則 |
範例：
```bash
curl -X POST http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer $OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto/coding",
"messages": [{ "role": "user", "content": "Refactor this Python function" }],
"stream": true
}'
```
[AUTO-COMBO.md](../routing/AUTO-COMBO.md) 完整說明了自動路由器，包括如何調整評分權重、將提供者加入黑名單，以及在**儀表板 → 自動組合**中檢查路由決策。
---
## 🔌 MCP 與 A2A 整合
OmniRoute 同時是 **MCP 伺服器**（Model Context Protocol，模型上下文協定）與 **A2A 伺服器**（Agent-to-Agent JSON-RPC 2.0）。任何與 MCP 相容的 IDE 或代理程式主機都能直接呼叫 OmniRoute 工具，無需額外的包裝層。
### MCP 傳輸方式
- **SSE**：`http://localhost:20128/api/mcp/sse`
- **可串流 HTTP**：`http://localhost:20128/api/mcp/stream`
- **stdio**：`omniroute --mcp`（適用於偏好 stdio 的 IDE 外掛程式）
### 連接 Claude Desktop
編輯 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS），或 Windows/Linux 上的對應檔案：
```json
{
"mcpServers": {
"omniroute": {
"command": "omniroute",
"args": ["--mcp"]
}
}
}
```
### 連接 Cursor / Continue / VS Code MCP
使用 SSE URL `http://localhost:20128/api/mcp/sse`，以及在**儀表板 → API 金鑰**中產生的 Bearer API 金鑰。
### 權限範圍
MCP 目前定義了 32 個具名權限範圍。每個 Bearer 金鑰都能限制為僅可存取特定權限範圍——如需具權威性的權限範圍與工具清單，請參閱 [MCP-SERVER.md](../frameworks/MCP-SERVER.md)；如需 JSON-RPC 結構描述，請參閱 [A2A-SERVER.md](../frameworks/A2A-SERVER.md)。
---
## 🧠 技能系統
OmniRoute 提供可擴充的**技能框架**（`src/lib/skills/`），讓代理程式與 A2A 端點能夠執行特定領域的例行作業（例如 `code-review`、`summarize`、`extract-facts`、`web-research`）。
- **市集 UI** — 從**儀表板 → 技能**瀏覽並安裝技能
- **各金鑰的作用域** — 限制哪些 API 金鑰可以叫用哪些技能
- **自訂技能** — 將 TypeScript 檔案放入 `src/lib/a2a/skills/`、進行註冊後，即可立即透過 A2A 叫用
完整參考資料：[SKILLS.md](../frameworks/SKILLS.md)。
---
## 💾 記憶系統
OmniRoute 透過混合式檢索持久保存**長期對話記憶**：
- **SQLite FTS5**，用於在過往對話輪次中進行關鍵字搜尋
- **Qdrant 向量儲存庫**（選用），用於語意回憶
- **自動事實擷取** — 在每個工作階段結束後彙整實體、偏好與決策，並儲存在 `memory_facts` 資料表中
- 記憶的作用域依 API 金鑰及工作階段劃分
在**儀表板 → 記憶**中管理記憶（搜尋、編輯、匯出、清除）。HTTP 介面（`/api/memory/*`）可讓代理程式以程式化方式推送及查詢事實 — 請參閱 [MEMORY.md](../frameworks/MEMORY.md)。
---
## 🔔 Webhook
訂閱 OmniRoute 事件，以進行即時監控與自動化。
- 在**儀表板 → Webhook**中建立 Webhook，並設定目標 URL 與 HMAC 簽署密鑰
- 可用事件：`request.completed`、`request.failed`、`provider.unavailable`、`budget.exceeded`、`combo.switched`、`circuit_breaker.opened`、`circuit_breaker.closed`
- 每個承載資料皆包含 `X-OmniRoute-Signature`（HMAC-SHA256），以供驗證
- 重試：採用指數退避進行 3 次嘗試，之後移至無效信件佇列
完整結構定義請參閱 [WEBHOOKS.md](../frameworks/WEBHOOKS.md)。
---
## ☁️ 雲端代理程式
OmniRoute 可與雲端程式設計代理程式（**OpenAI Codex Cloud**、**Devin**、**Jules**、**Antigravity**）整合，讓您能從管理本機路由的同一個儀表板派送長時間執行的任務。
- 在**儀表板 → 雲端代理程式**中建立任務，或透過 `POST /api/v1/agents/tasks` 建立
- 追蹤每個任務的狀態、日誌與成品
- 各提供者可使用自備的 API 金鑰 — 認證資料絕不會離開 OmniRoute 執行個體
完整參考資料：[CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md)。
---
## 🛠️ 程式化管理
你可以透過 HTTP，使用**具備 `manage` 範圍的 Bearer 金鑰**管理所有 OmniRoute 資源（提供者、組合、金鑰、設定）。
請前往**儀表板 → API 金鑰 → 新增金鑰 → 範圍：manage**產生金鑰，然後：
```bash
# 列出提供者
curl http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
# 新增提供者連線
curl -X POST http://localhost:20128/api/providers \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'
# 建立組合
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'
# 列出／建立 API 金鑰
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
-d '{ "name": "ci-bot", "scopes": ["chat"] }'
```
如需完整的端點目錄及請求／回應結構描述，請參閱 [API_REFERENCE.md](../reference/API_REFERENCE.md)。
---
## 💻 內部 CLI
OmniRoute 內建內部 CLI（`omniroute …`），用於設定、診斷與執行階段控制。這與儀表板中的「CLI 工具」頁面**不同**；該頁面用於設定第三方 CLI（Claude Code、Cursor、Codex、Cline 等），讓它們能與 OmniRoute 通訊。
```bash
omniroute setup # 互動式精靈（密碼、提供者、組合）
omniroute setup --non-interactive # 適用於 CI
omniroute doctor # 健康狀態診斷（資料目錄、資料庫、提供者、連接埠）
omniroute providers available # 列出支援的提供者
omniroute providers list # 列出已設定的連線
omniroute providers test # 即時測試提供者連線
omniroute combos list # 列出組合
omniroute combos switch # 設定預設組合
omniroute models # 列出可用模型（--json、--search）
omniroute keys add | list | remove # 從終端機管理 API 金鑰
omniroute backup # 建立設定與資料庫快照
omniroute restore [] # 從快照還原
omniroute health # 詳細健康狀態（斷路器、快取、記憶體）
omniroute quota # 提供者配額使用情況
omniroute mcp status # MCP 伺服器狀態
omniroute a2a status # A2A 伺服器狀態
omniroute tunnel list|create|stop # Cloudflare/Tailscale/ngrok 通道
omniroute reset-password # 重設管理員密碼
omniroute --mcp # 透過 stdio 啟動 MCP 伺服器
omniroute --port 3000 # 在自訂連接埠上啟動伺服器
```
提示：將 `omniroute doctor --json` 與監控工具搭配使用，以便在提供者連線狀態異常時發出警示。
---
## 🖥️ 桌面應用程式（Electron）
OmniRoute 提供適用於 Windows、macOS 與 Linux 的原生桌面應用程式。
### 安裝
```bash
# 從 electron 目錄執行：
cd electron
npm install
# 開發模式（連線至執行中的 Next.js 開發伺服器）：
npm run dev
# 正式環境模式（使用獨立建置）：
npm start
```
### 建置安裝程式
```bash
cd electron
npm run build # 目前平台
npm run build:win # Windows（.exe NSIS）
npm run build:mac # macOS（通用 .dmg）
npm run build:linux # Linux（.AppImage）
```
輸出 → `electron/dist-electron/`
### 主要功能
| 功能 | 說明 |
| ------------------ | ---------------------------------------------- |
| **伺服器就緒檢查** | 顯示視窗前輪詢伺服器（不會出現空白畫面） |
| **系統匣** | 最小化至系統匣、變更連接埠、從系統匣選單結束 |
| **連接埠管理** | 從系統匣變更伺服器連接埠（自動重新啟動伺服器） |
| **內容安全政策** | 透過工作階段標頭套用嚴格的 CSP |
| **單一執行個體** | 同一時間只能執行一個應用程式執行個體 |
| **離線模式** | 內附的 Next.js 伺服器無須網際網路即可運作 |
### 環境變數
| 變數 | 預設值 | 說明 |
| --------------------- | ------- | ------------------------------- |
| `OMNIROUTE_PORT` | `20128` | 伺服器連接埠 |
| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆積限制（64–16384 MB） |
📖 完整文件：[`electron/README.md`](../../electron/README.md)