OmniRoute 安裝教學:快速開始與 Claude Code 設定

OmniRoute 是一個相容 OpenAI 的 AI 閘道：把多個上游模型供應商統一成一個本機 API，Claude Code、Codex CLI、IDE 外掛和你自己的腳本只需要設定一次位址。本文給出從安裝到第一次成功請求的最短路徑，完整的專題指南在獨立網站維護。

先記住這兩個位址

儀表板：http://localhost:20128
相容 OpenAI 的 Base URL：http://localhost:20128/v1

設定用戶端時填的是第二個，不是儀表板位址。

前置條件

Node.js >=22.22.2 <23 或 >=24.0.0 <27，建議使用 24 LTS。版本不在這個範圍內，儀表板可能白屏或出現原生模組錯誤。需要時請先安裝 Node.js。
本機連接埠 20128 未被占用。
至少一個你打算透過 OmniRoute 路由的上游供應商帳號或金鑰。

安裝並啟動

任選一種方式：

# npm（建議）
npm install -g omniroute
omniroute

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

也可以從 OmniRoute GitHub Releases 下載 Windows、macOS 或 Linux 的 Desktop 安裝程式。:latest 指向最新已發布的穩定版，需要可重現的部署時請固定到具體版本號。

啟動後開啟 http://localhost:20128。登入密碼由 INITIAL_PASSWORD 環境變數決定；在上游的自行託管設定裡，首次啟動會自動產生並輸出到日誌，Docker 部署時可以用 docker logs omniroute | grep -i password 查到。要讓服務對外可達，務必先把它設成你自己的強密碼。

連接供應商並建立金鑰

在儀表板進入 Providers → Add Provider，選擇並連接你的供應商。
在 API Keys 頁面建立一個新金鑰並妥善保存，它只會顯示一次。這個金鑰是用戶端存取 OmniRoute 用的，不是上游供應商的金鑰。

上游文件列出了一些無需金鑰的免費供應商，可用性和條款會隨時變化，使用前請自行核對對應服務的條款。

驗證服務

export OMNIROUTE_API_KEY="貼上你在 API Keys 頁面建立的金鑰"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

回傳模型清單，表示相容 OpenAI 的端點和驗證都正常。再送出一個最小的聊天請求，確認模型真的能被路由：

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto 讓 OmniRoute 依速度、成本和可用性自動選擇供應商；也可以改成 /v1/models 回傳的具體模型 ID。

接入你的工具

在任何支援 OpenAI 格式的工具裡填入：

Base URL: http://localhost:20128/v1
API Key:  你建立的 OmniRoute 金鑰
Model:    auto

OmniRoute 自帶一鍵啟動指令，例如 omniroute launch-codex --model auto，通用形式 omniroute run <target> 支援 claude、codex、aider、goose、opencode、qwen、gemini。想在 HagiCode 裡使用的 Agent CLI，請先依 AI Agent CLI 安裝準備好。

常見問題

儀表板白屏或提示 Node 版本不受支援：切換到 Node.js 24 LTS，重新執行 npm install -g omniroute，再執行 omniroute。
npm 11 下回報找不到 better-sqlite3：npm 11 預設攔截選用相依套件的安裝腳本，請依疑難排解指南裡的步驟手動重新建置。
macOS 回報 slice is not valid mach-o file：在 $(npm root -g)/omniroute/app 下執行 npm rebuild better-sqlite3，再啟動。