🚀 OmniRoute 完整操作手冊

0.可行性評估結論

評估面向

依據

1.OmniRoute 是什麼？

OmniRoute 是一個安裝在你自己電腦（或伺服器）上的 AI Gateway（AI 閘道／路由器）。它對外提供一個與 OpenAI、Claude、Gemini API 相容的統一端點，對內則幫你管理與調度多達 290+ 家 AI 供應商。

核心賣點

• 永不中斷：某家供應商掛掉或額度用盡時，毫秒級自動切換到下一家（auto-fallback）。
• $0 起步：內建免金鑰的免費供應商，裝完立刻能用；再串接各家免費額度，官方統計每月合計約 15 億免費 token。
• Token 壓縮：RTK + Caveman 疊加壓縮，官方宣稱可省 15–95% token（工具密集型工作平均約 89%）。
• 一個端點通吃：同時相容 OpenAI、Anthropic（Claude）、Gemini、Responses API 格式，33+ 種 coding agent 皆可直接串接。
• 本機優先、隱私可控：所有金鑰與資料存在本機（~/.omniroute），不經第三方伺服器。
• 進階功能：19 種路由策略、Combo 備援鏈、MCP 伺服器（100+ 工具）、A2A 協定、用量儀表板、成本追蹤。

2.系統需求

node --version   # 需 ≥ v22.22.2，若太舊請到 https://nodejs.org 下載 LTS 版

3.安裝方式（四選一）

方式 A：npm 全域安裝（官方推薦）

npm install -g omniroute
omniroute

安裝完成後執行 omniroute，服務會啟動在 http://localhost:20128，並自動開啟儀表板網頁。

方式 B：Docker

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

適合伺服器或不想安裝 Node.js 的環境。進階用法（Compose、HTTPS）見第 9 節。

方式 C：桌面應用程式（Electron）

到 GitHub Releases 下載對應平台的安裝檔：Windows（NSIS 安裝檔／免安裝版）、macOS（dmg，支援 Apple Silicon 與 Intel）、Linux（AppImage / deb / rpm）。適合完全不想碰指令列的使用者。

方式 D：從原始碼執行（開發者）

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install     # 首次會自動從 .env.example 產生 .env
npm run dev

# pnpm（必須加 --allow-build 才能編譯原生模組）
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core

# Arch Linux（AUR，附 systemd 使用者服務）
yay -S omniroute-bin
systemctl --user enable --now omniroute.service

解除安裝

4.啟動與初始設定

1. 啟動服務

   omniroute

   瀏覽器會自動開啟儀表板 http://localhost:20128（不想自動開啟可加 --no-open）。也可以改用引導式設定：omniroute setup，會一步步帶你設定管理密碼與第一個供應商。

2. 設定管理密碼

   首次進入儀表板會要求建立密碼，保護你的設定與金鑰。忘記密碼時可用 omniroute-reset-password 重設。

3. 驗證安裝是否正常

   omniroute doctor        # 本機健康檢查（不需啟動伺服器）
   omniroute status        # 離線狀態總覽：版本、資料庫、工具、設定

4. 零設定測試（免金鑰）

   全新安裝就內建免金鑰的免費供應商（如 OpenCode Free），auto 模型開箱即可回應：

   curl http://localhost:20128/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

5. 建立 API 金鑰（給工具用）

   到儀表板 API Keys（/dashboard/api-manager）建立一組金鑰。金鑰只會顯示一次，請立即保存。注意：這組金鑰是給「你的工具連 OmniRoute」用的，不是上游供應商的金鑰。

   curl http://localhost:20128/v1/models -H "Authorization: Bearer 你的金鑰"

   能列出模型清單即代表設定成功。

5.連接 AI 供應商

「供應商（Provider）」就是一條通往某家 AI 服務的連線。OmniRoute 把供應商分成四類：

操作步驟（儀表板）

1. 開啟 http://localhost:20128，點左側 Providers
2. 點 + Add Provider，瀏覽或搜尋供應商
3. 依類型填入憑證：免費供應商直接按 Connect；API 金鑰型貼上金鑰；OAuth 型按 Connect with OAuth 登入
4. 按 Test Connection 確認連線正常
5. 完成！模型會自動加入 auto 的候選池

建議的免費起手式

常用金鑰申請入口

• OpenAI：platform.openai.com/api-keys
• Anthropic：console.anthropic.com
• Google Gemini：aistudio.google.com/apikey
• DeepSeek：platform.deepseek.com
• Groq：console.groq.com

6.auto 智慧路由與 Combo

把模型名稱設成 auto，OmniRoute 就會替每一次請求自動挑選最合適的供應商——依健康度、剩餘額度、成本、速度、任務適配度等 12 項因素評分，失敗自動換下一家。

auto 變體

三層容錯保護

• 自動備援：最佳供應商失敗 → 立刻改派次佳者。
• 自我修復：持續失敗的供應商（評分 < 0.2 或斷路器開啟）會被暫時排除 5–30 分鐘。
• 緊急後備：全部失敗時，改路由到穩定的免費供應商，確保服務不中斷。

7.串接你的開發工具

通用原則：任何支援 OpenAI 相容 API 的工具，只要設定三個值即可——

Base URL : http://localhost:20128/v1
API Key  : （儀表板 API Keys 頁建立的金鑰）
Model    : auto   # 或任何 供應商/模型 格式，如 deepseek/deepseek-chat

7.1 Claude Code

最簡單的方式是用內建啟動器，全部環境變數自動幫你設好：

omniroute launch                       # 以 OmniRoute 為後端啟動 Claude Code
omniroute setup-claude                 # 依線上模型目錄產生每個模型的 profile
omniroute launch --profile glm52       # 用特定模型 profile 啟動

手動設定則使用環境變數（Claude Code 沒有 --base-url 參數）：

export ANTHROPIC_BASE_URL="http://localhost:20128"   # 注意：結尾「不要」加 /v1
export ANTHROPIC_AUTH_TOKEN="你的OmniRoute金鑰"
claude

7.2 Codex CLI

# 先把金鑰設成環境變數（Windows 用 setx OMNIROUTE_API_KEY 你的金鑰）
export OMNIROUTE_API_KEY="你的金鑰"

omniroute launch-codex --model auto    # 一鍵啟動，端點與金鑰自動注入
omniroute setup-codex                  # 或：產生 ~/.codex/*.config.toml 設定檔

7.3 VSCode（Continue.dev 擴充）

安裝 Continue.dev 擴充後，在 ~/.continue/config.yaml 加入：

  - name: OmniRoute - Auto
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: 你的金鑰

之後在 Continue 聊天面板選擇「OmniRoute - Auto」即可。也可直接執行 omniroute setup-continue 自動寫入。

7.4 其他工具一鍵設定

OmniRoute 內建多數主流工具的自動設定指令，會直接把設定寫進各工具自己的設定檔：

omniroute setup-cursor      # Cursor（顯示 App 內設定步驟）
omniroute setup-cline       # Cline（CLI + VSCode 擴充）
omniroute setup-opencode    # OpenCode
omniroute setup-kilo        # Kilo Code
omniroute setup-roo         # Roo Code
omniroute setup-aider       # Aider
omniroute setup-goose       # Goose
omniroute setup-qwen        # Qwen Code

每個指令都支援 --dry-run（預覽不寫入）與 --remote <url> --api-key <key>（指向遠端的 OmniRoute 伺服器）。

7.5 無法送 Authorization Header 的編輯器

部分編輯器無法自訂 Bearer 標頭，可改用「金鑰內嵌網址」的相容端點：

Base URL : http://localhost:20128/api/v1/vscode/你的金鑰/

7.6 MCP 伺服器（給 AI Agent 用）

# Claude Code 加入 OmniRoute MCP（HTTP 串流）
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream

# 或以 stdio 模式啟動（Cursor / Cline 設定 command: omniroute, args: ["--mcp"]）
omniroute --mcp

7.7 確認流量真的有走 OmniRoute

在儀表板左側點 Monitoring / Logs（/dashboard/logs），每一筆請求的來源工具、路由到哪家供應商、token 用量都看得到——除錯與學習都很好用。

8.常用 CLI 指令速查

omniroute setup --non-interactive --password "$OMNIROUTE_PASSWORD"
omniroute setup --non-interactive --add-provider --provider openai \
  --api-key "$OPENAI_API_KEY" --test-provider
omniroute providers test-batch

9.Docker 與伺服器部署

單容器快速啟動

docker run -d --name omniroute \
  -p 20128:20128 \
  -v omniroute-data:/data \
  diegosouzapw/omniroute:latest

Docker Compose（多種 profile）

docker compose --profile base up -d   # 精簡版（無內建 CLI 工具）
docker compose --profile cli up -d    # 內建 Claude Code / Codex 等 CLI
docker compose -f docker-compose.prod.yml up -d --build   # 正式環境

API 與儀表板分埠（反向代理場景）

PORT=20128 DASHBOARD_PORT=20129 omniroute
# API:       http://localhost:20128/v1
# Dashboard: http://localhost:20129

遠端模式（一台伺服器、多台電腦共用）

# 在你的筆電上連到 VPS 上的 OmniRoute：
omniroute connect http://192.168.0.15:20128
omniroute launch          # 之後 launch / setup-* 都自動指向遠端

10.疑難排解

更完整的清單見官方 Troubleshooting 文件，或執行 omniroute doctor 自動診斷。

11.風險與注意事項（採用前必讀）

12.官方資源連結

• GitHub 專案：github.com/diegosouzapw/OmniRoute
• 官方網站：omniroute.online
• 繁體中文 README：docs/i18n/zh-TW/README.md
• 快速開始：QUICK-START.md
• 供應商指南：PROVIDERS-GUIDE.md
• 免費額度方法論：FREE_TIERS.md
• Docker 指南：DOCKER_GUIDE.md
• npm 套件：npmjs.com/package/omniroute
• 社群支援：Discord・Telegram