症狀：你把 http://localhost:20128/v1 同時填入 Cursor 與 Claude Code，結果一端連不上，另一端不斷回傳鑑權錯誤。
最快解法：保留同一個 OmniRoute 執行個體，但分開設定入口；Claude Code 使用不帶 /v1 的網關根地址，Cursor 再按桌面端或 CLI 的能力選擇相容入口。
最後更新於 2026 年 8 月 12 日；版本、命令與 endpoint 已核對 OmniRoute 最新 release 頁、CLI 工具矩陣、Cursor 文件及 Claude Code 網關文件。正式部署前仍應以你的實際版本文件為準。 (github.com)
這篇適合以下三類讀者：
- 同時使用 Cursor 與 Claude Code，只想維護一套模型憑據和路由規則的個人開發者。
- 要在遠端 Mac 持續執行 AI Gateway 與編碼 Agent 的工程師。
- 正為小團隊設計多 provider 容錯、權限隔離和統一驗收流程的技術負責人。
同一個網關，不等於兩個用戶端使用同一條 URL
典型錯誤配置是：
OmniRoute:
http://localhost:20128/v1
Cursor:
http://localhost:20128/v1
Claude Code:
ANTHROPIC_BASE_URL=http://localhost:20128/v1
問題不在於 OmniRoute 不能同時服務兩個工具，而在於兩者預期的協定入口不同。
請把請求路徑理解成兩條線：
Cursor CLI
→ OpenAI 相容入口
→ http://127.0.0.1:20128/v1
→ OmniRoute
→ Provider A / Provider B / Provider C
Claude Code
→ Anthropic Messages 入口
→ http://127.0.0.1:20128
→ OmniRoute 追加 /v1/messages
→ Provider A / Provider B / Provider C
OmniRoute 的通用 OpenAI 相容入口是 /v1，模型目錄則是 /v1/models。但 Claude Code 的 ANTHROPIC_BASE_URL 應該填網關根地址，不能自行加上 /v1；Claude Code 會在請求時處理 Messages 路徑。(github.com)
這裡要分清兩個概念：
- 共用同一個 OmniRoute 實例：兩個工具都將請求送到同一個路由層。
- 使用完全相同的 URL：兩個工具的 base URL 字串和 API 格式完全一致。
前者可行。後者不一定可行。
如果你希望先確認整個架構，再開始改設定，可以先閱讀 MacHTML 的 AI 開發環境支援說明，把本機、遠端 Mac 和團隊共用的權限邊界先定好。
第一步：先讓 OmniRoute 具備可驗收的最小閉環
不要先在 Cursor 裡反覆按 Verify。先把網關本身驗證完成。
1. 安裝並啟動
本機測試可使用 npm：
npm install -g omniroute
omniroute
OmniRoute 預設會在 http://localhost:20128 啟動控制台與 API。若使用 Docker，則需要把容器的 20128 port 映射到主機。這些是專案文件目前列出的預設值。(github.com)
2. 連接至少一個 provider
在控制台完成：
Providers → Add Provider
先連接一個可用 provider，再進入：
Endpoints → Create API Key
3. 執行服務診斷
omniroute doctor
omniroute health
doctor 用於檢查設定、資料庫、port 和執行環境；health 用於查看服務健康、斷路器、快取和記憶體等狀態。(github.com)
4. 驗證模型目錄
把 <OMNIROUTE_KEY> 換成你在 Endpoints 建立的 key：
curl -s http://127.0.0.1:20128/v1/models \
-H "Authorization: Bearer <OMNIROUTE_KEY>"
你至少要看到有效 JSON 回應，以及已連接 provider 提供的模型 ID。模型清單為空時，先不要碰 Cursor 或 Claude Code，直接回到 provider 狀態、API key 和路由組合檢查。
5. 發出最小推理請求
curl -s http://127.0.0.1:20128/v1/chat/completions \
-H "Authorization: Bearer <OMNIROUTE_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "<PROVIDER/MODEL>",
"messages": [
{"role": "user", "content": "只回覆：gateway-ok"}
]
}'
驗收標準不是「控制台頁面正常」，而是：
omniroute health沒有致命錯誤。/v1/models能回傳模型目錄。- 最小對話請求能取得模型回應。
- 日誌中能找到此次請求的路由結果。
Claude Code 的入口格式：根地址與 /v1 不能混用
Claude Code 應採用這條主流程：
export ANTHROPIC_BASE_URL="http://127.0.0.1:20128"
export ANTHROPIC_AUTH_TOKEN="<OMNIROUTE_KEY>"
export ANTHROPIC_MODEL="<PROVIDER/MODEL>"
claude
重點只有三個：
ANTHROPIC_BASE_URL填http://127.0.0.1:20128，不要加/v1。ANTHROPIC_AUTH_TOKEN使用 OmniRoute 的 endpoint key。- 修改環境變數後，完全退出並重新啟動 Claude Code。
OmniRoute 的 Claude Code 設定文件明確指出，Claude Code 會使用 Anthropic Messages API，並由 ANTHROPIC_BASE_URL 指向網關根地址；ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 是兩種不同的鑑權方式，若同時存在，前者優先。(github.com)
如果你不想手動維護環境變數，可以改用：
omniroute launch
遠端執行個體則使用：
omniroute launch \
--remote http://<REMOTE_MAC_OR_HOST>:20128 \
--api-key <OMNIROUTE_KEY>
另一條替代路徑是：
omniroute setup-claude
omniroute launch --profile <PROFILE_NAME>
setup-claude 會讀取即時的 /v1/models 目錄，建立每個模型的設定檔；key 不應硬編碼到公開的設定檔中。
模型清單為空，不代表模型不能使用
Claude Code 的原生模型選擇器對非 Claude 模型可能有發現限制。這時候不要只依賴 /model 選單，改用：
export ANTHROPIC_MODEL="<PROVIDER/MODEL>"
也可以讓 setup-claude 產生按模型分開的 profile，再按 profile 啟動。這種方式比在互動式選單中猜模型名稱可靠。
若你只設定
ANTHROPIC_BASE_URL，卻沒有設定網關憑據，請不要把仍然有效的訂閱登入狀態誤判成 OmniRoute 鑑權成功。官方文件提醒，base URL 和 gateway credential 是兩個不同設定。(docs.anthropic.com)
Cursor 桌面端、Cursor CLI 與 MCP：三條接入路徑要分開
Cursor 桌面端：可用自訂 key，但不要承諾所有功能都經過網關
Cursor 桌面端的自訂 API key 主要針對標準聊天模型。需要專用模型的功能，例如 Tab Completion，仍可能使用 Cursor 自身的模型，不會因為你填入 OmniRoute key 就全部改走網關。(docs.cursor.com)
因此桌面端的排查順序是：
- 打開 Cursor 設定中的 Models。
- 確認你使用的是相容的 provider 類型。
- 填入 OmniRoute 提供的相容入口和 key。
- 只先驗證標準聊天模型。
- 再逐項檢查補全、索引、Agent 和其他內建功能。
OmniRoute 的 setup-cursor 目前主要是列印應用程式內的設定步驟，不會直接寫入完整設定檔；專案文件將 Cursor 配置描述為受 SQLite 儲存限制的接入方式。
Cursor CLI：有明確的自訂 endpoint 入口
Cursor CLI 的自訂 endpoint 可使用 --endpoint：
export CURSOR_API_KEY="<OMNIROUTE_KEY>"
cursor-agent \
--endpoint http://127.0.0.1:20128/v1 \
-m "<PROVIDER/MODEL>" \
"只回覆：cursor-gateway-ok"
Cursor CLI 文件列出 --endpoint 作為自訂 API endpoint 參數，也提供 CURSOR_API_KEY 環境變數作為自動化用途的鑑權方式。(docs.cursor.com)
這就是最容易混淆的地方：
- Claude Code：根地址，不加
/v1。 - Cursor CLI：通常使用 OpenAI 相容入口，加
/v1。 - Cursor 桌面端：按其支援的自訂 key 和模型類型驗證，不能推論所有內建功能都使用相同入口。
- MCP：工具協定接入，不等於模型 API endpoint；不要把 MCP URL 當成 Cursor 或 Claude Code 的模型 base URL。
若你在桌面端驗證失敗，先退回 Cursor CLI 做最小請求。CLI 成功而桌面端部分功能失敗，通常是能力邊界，而不是 OmniRoute 整體不可達。
額度耗盡時，為什麼多模型 fallback 沒有生效？
單模型直連、設定自動路由、建立自訂 fallback chain，是三種不同狀態。
單模型直連
請求 → 指定模型 → 單一 provider
這種方式最容易驗證，但 provider 額度用完後，請求通常只會失敗，不會自動尋找下一個模型。
自動路由
請求 → OmniRoute 路由策略 → 可用 provider
這取決於目前啟用的路由設定、模型名稱和 provider 健康狀態。
自訂 fallback chain
首選模型 → 備援模型 A → 備援模型 B
這才是最適合故障演練的方式，但至少要有兩個真正可用的 provider。只有一個 provider 時，任何 fallback 測試都沒有意義。
建議按以下方式演練：
- 在 Combos 或路由設定中固定首選模型。
- 加入第二個模型，確認兩者都能通過
/v1/models和最小推理請求。 - 暫時停用首選 provider，或使用明確不可用的測試條件。
- 發出固定內容的請求。
- 檢查路由決策、錯誤日誌及最終回應中的模型標識。
- 恢復首選 provider，再重跑一次，確認路由會回到預期順序。
OmniRoute 專案文件確實提供自動路由、fallback 和 combo 設定，但專案自報的 provider 數量、免費額度或壓縮收益不能當成本站獨立實測；你應以自己的 provider 帳戶、模型目錄和日誌結果作為驗收依據。(github.com)
遠端 Mac 部署：本機回環地址不能直接給其他裝置使用
localhost 或 127.0.0.1 只代表「目前這台機器」。如果 OmniRoute 在遠端 Mac 上，而 Cursor 或 Claude Code 在另一台電腦，以下設定必然不適用：
http://localhost:20128
遠端環境應改用可達地址，例如：
http://<REMOTE_MAC_IP>:20128
或使用已配置 TLS、身份驗證和存取控制的 HTTPS 網址。
最小交付步驟如下：
- 在遠端 Mac 安裝並啟動 OmniRoute。
- 確認本機
omniroute health和/v1/models正常。 - 將 API 服務限制在受信任網卡、VPN 或內部通道。
- 為每位使用者建立獨立 endpoint key，不共用管理員憑據。
- 從開發者電腦執行
curl，驗證遠端/v1/models。 - Claude Code 使用遠端根地址；Cursor CLI 使用遠端
/v1。 - 重啟 OmniRoute，再確認資料持久化、key、provider 和 fallback 設定是否仍在。
- 以長任務測試斷線恢復，而不是只測一個短句。
遠端網關至少有三項隱性成本：
- 暴露面增加：直接把 20128 port 暴露到公網，會把管理介面和推理入口一起帶出去。
- 憑據權限難分：共用一把 key 時，無法準確撤銷某個成員，也不容易追查用量。
- 網路狀態影響長任務：本機睡眠、VPN 斷線、DNS 改變，都可能讓看似正確的 endpoint 在長時間執行中失效。
若你要比較本機常駐與 MacHTML 的遠端 Mac 使用方式，可以先從 MacHTML 遠端 Mac 服務入口 了解可用路徑，再按你的在線時長、跨裝置需求和權限要求決定部署位置。本文不代替本站實測，也不虛構節點、租期或持續運行數據。
用決策條件選擇本機或遠端 Mac
- 若你只在一台 Mac 上短時測試 OmniRoute、Cursor 和 Claude Code，選本機部署；故障範圍小，排查最快。
- 若你需要跨裝置連線，選遠端 Mac；不要把
localhost當成遠端地址。 - 若你需要每天持續執行長任務，選有自動重啟、持久化儲存和受控網路的遠端環境。
- 若團隊需要共享 provider，但不共享原始 provider key，選網關集中管理，再按成員發放不同 endpoint key。
- 若你需要物理 USB、特殊本機憑證或離線工作，回退到本機部署。
- 若 Cursor 桌面端只有部分功能成功，先改用 Cursor CLI 驗證；不要立即宣稱 OmniRoute 不相容。
最後一個驗收清單可以直接交給團隊：
- [ ] OmniRoute 服務重啟後仍能啟動。
- [ ]
/v1/models能回傳預期模型。 - [ ] Claude Code 使用不帶
/v1的根地址。 - [ ] Cursor CLI 使用帶
/v1的相容入口。 - [ ] Cursor 桌面端只按已確認支援的功能驗證。
- [ ] 至少兩個 provider 都能完成最小推理。
- [ ] 首選模型失效時，下一個模型確實接手。
- [ ] 日誌能對應請求、錯誤和最終模型。
- [ ] 每位使用者的 key 可單獨撤銷。
- [ ] 遠端連線中斷後，恢復時不會要求重新建立整套設定。
同一個 OmniRoute 實例確實能讓 Cursor 與 Claude Code 共用模型入口，但「一套路由規則」不代表「一個完全相同的 endpoint 字串」。本機方案的優點是部署快、延遲路徑短；缺點是設備休眠、網路變更和跨裝置存取會直接中斷工作。把網關放在遠端 Mac 的優點是持續在線、可集中管理和便於團隊共用；代價則是需要處理權限、TLS、備份和重啟恢復。
如果你已完成本機雙工具驗證，下一步應按在線時間、跨設備存取和團隊共享需求評估遠端 Mac；若本機經常休眠或網路變化，使用 MacHTML 的持續在線環境會比把工作綁在個人電腦上更穩妥。你可以再查看 MacHTML 的方案資訊，只在確定需要臨時算力、持續運行或遠端測試環境時選擇租用。
延伸閱讀: 多模型開發工具的記憶體與算力配置比較 模型故障轉移與供應商路由的實作演練 舊款 Mac 的遠端 AI 開發環境優化方案
為 AI 開發打造穩定的遠端 Mac 工作環境
使用 MacHTML 遠端 Mac，快速建立適合多模型開發與測試的 macOS 工作環境。 透過獨立 Mac 算力節點，支援程式編譯、模型測試及長時間任務穩定運作。 無論本機資源是否充足，都能跨裝置連線至遠端 Mac，靈活延伸開發能力。 立即選擇合適的 MacHTML 方案，為你的 AI 工作流程建立可靠而彈性的 Mac 基礎設施。