Cursor、Claude Code、Codex、Gemini CLI 各認各的地址和金鑰。供應商一多，限額、帳單和「這家今天 429」就散落在每套配置裡。OmniRoute 把這件事收成你自己機器上的一個 OpenAI 相容入口：客戶端只記 http://127.0.0.1:20128/v1，Claude、GPT、Gemini、DeepSeek 以及目錄裡的其他模型從儀表板接進去。軟體是 MIT，倉庫目前在 release/v3.8.53 這條發布線上；下面的埠、命令和路由規則以該版 README 為準，供應商數量會隨版本變。
「免費」指的是閘道器本身不收費。額度在你接上的供應商帳上。官方把第三方免費檔做成儀表板上的 /dashboard/free-tiers 估算，並寫明那是彙總，不是 OmniRoute 發給你的 token。已經在付費的訂閱，也可以走你自己的帳號流程，讓程式設計工具共用這一條地址。若你更關心各家 API 標價，可以對照 程式設計工具月帳單 和 OpenRouter 計價：那是託管路由，OmniRoute 是你本機上的閘道器。
閘道器放在哪一層
把它想成一臺只跑在你機器上的翻譯插座。上游仍是 OpenAI、Anthropic、Google、DeepSeek 或目錄裡的其他供應商；下游是任何認 OpenAI Chat Completions 或 Responses 的客戶端。v3.8.53 文件口徑是約 375 家供應商、約 1475 個原始模型 ID，其中一部分帶免費檔發現標記。這些數字兩週會重審，以儀表板目錄為準，不要抄舊截圖。
- 你保管兩把鑰匙。供應商 API key（或 OAuth）只放進 OmniRoute。給 Cursor / 指令碼用的是 Dashboard → Endpoints 裡的閘道器金鑰。
- 模型名在連上之後才有意義。先調
/v1/models，再用返回的 ID。README 裡的示例寫成openai/gpt-5.4、glm/glm-5.2這種「供應商/型號」，以你列表裡實際出現的為準。 - 相容面很寬。官方點名 Claude Code、Codex、Cursor、Cline、Continue、OpenCode、Copilot、OpenClaw 等。認自定義 Base URL 的，填地址即可；官方還提供
omniroute run拉起其中 7 個 CLI。
README 寫的是 Bring your own provider accounts。免費檔可能要註冊、審核或綁定支付方式，也可能隨時關閉。標記 tos: avoid 的供應商預設不進 auto，連上帳號也不會自動改掉這條策略。
從 0 安裝：npm 與 Docker
需要本機有 Node.js。最快的一條路：
npm install -g omniroute
omniroute看到 npm warn ERESOLVE 或 peer 依賴警告，按官方說明可以先忽略。啟動後瀏覽器開啟 http://127.0.0.1:20128，API 在 http://127.0.0.1:20128/v1。無頭、只要代理時用 omniroute serve --headless（或環境變數 OMNIROUTE_HEADLESS=1），儀表板和只給面板用的子系統會關掉。
npm 11 要放行安裝指令碼
npm 11 可能攔住包的生命週期指令碼。OmniRoute 的 postinstall 要跑，才會準備好原生執行時檔案。3.8.53 文件給出的允許列表是：
npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute若 npm 提示的包名和上面不一致，以那次警告裡的名字為準。允許指令碼意味著這些包的安裝指令碼會執行，只在你確認來源後再做。CI 或慢機器可以設 OMNIROUTE_SKIP_POSTINSTALL=1，那隻跳過原生 SQLite 預熱，二進位制複製那一步仍會跑。
Docker 要按程式設計負載加記憶體
映像名仍是文件裡的 diegosouzapw/omniroute。:latest 跟蹤已發布的最高穩定 SemVer，不跟蹤 git main。生產請釘具體版本。官方示例把埠綁在迴環上：
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest映像預設堆只有 1024MB，夠面板和短對話。Claude Code、Codex 走 POST /v1/responses 時，官方寫明需要更大的 V8 堆，否則長上下文會把行程打到記憶體致命錯誤。一個程式設計代理的示例是堆 8192、容器至少 10g。兩路重疊的長請求要到 10240–12288 的堆，容器 12–16g。Apple Silicon 走映像的 arm64 構建即可。卷 omniroute-data 裡有金鑰，備份和刪除都按機密處理。
接入 Claude、GPT、Gemini、DeepSeek
開啟儀表板的 Providers，選一家你現在有資格用的，貼 API key 或走它的帳號流程。四家實驗室的鑰匙分別在各自控制台申請，OmniRoute 不代你開通：
| 供應商 | 你準備什麼 | 接到哪裡 |
|---|---|---|
| OpenAI（GPT） | platform.openai.com 的 API key | Providers → OpenAI |
| Anthropic（Claude） | console.anthropic.com 的 key，或你已經在付的 Claude 訂閱帳號流程 | Providers → Anthropic / 對應 OAuth |
| Gemini | Google AI Studio 的 key，或 Gemini CLI 的 OAuth | Providers → Gemini |
| DeepSeek | platform.deepseek.com 的 API key | Providers → DeepSeek |
免費檔是另一張清單，不是這四把鑰匙的同義詞。儀表板第一次嚮導裡可以出現「設定免費供應商」，它按當前免認證目錄列出，讓你逐個勾選後才建立連線，不會在你點完成時偷偷加一家。目錄裡出現過 Pollinations、Cloudflare AI、SiliconFlow 的 DeepSeek 免費檔等，條款、地區和是否還在都由對方決定。舊文裡的「免金鑰 Claude」若標了 tos: avoid，預設進不了 auto。用之前開啟 Free Tiers 頁看當天的資格說明。
網頁 Cookie 類供應商（例如 Gemini Web）還要額外的瀏覽器執行時。npm 包帶了 Playwright，不帶 Chromium 二進位制；第一次呼叫前按倉庫裡的 Playwright Chromium 說明準備，否則請求會在瀏覽器層失敗。
讓 IDE 和 CLI 共用一個地址
在 Endpoints 複製閘道器金鑰。然後：
Base URL: http://127.0.0.1:20128/v1
API Key: （Dashboard → Endpoints）
Model: auto先確認模型列表，再讓 IDE 說話：
curl http://127.0.0.1:20128/v1/models \
-H "Authorization: Bearer YOUR_KEY"
curl http://127.0.0.1:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'Cursor、Cline、Continue 以及任何能改 OpenAI Base URL 的外掛，填上面三行即可。發不出自定義請求頭的客戶端，可以用文件裡的令牌化相容地址，例如 http://127.0.0.1:20128/vscode/YOUR_KEY/chat/completions。能帶頭的，仍優先 Authorization: Bearer。
命令列不必手改每個工具的配置檔案。官方的一鍵啟動會按行程注入憑據，Qwen / Gemini 還會用一次性的隔離 home：
omniroute run claude --model auto
omniroute run codex --model auto
omniroute run gemini --model auto
omniroute configure codexomniroute run 覆蓋 Claude Code、Codex、Aider、Goose、OpenCode、Qwen Code、Gemini CLI。configure 會把供應商和模型寫進該工具自己的配置，文件列出的目標包括 codex、claude、opencode、qwen、aider、goose、gemini、cline、continue、kilo。--dry-run 只列印將要使用的環境變數和引數。--api-key-env NAME 讓金鑰留在環境變數名裡，不進 shell 歷史。
auto、回退，以及誰不會進自動路由
auto 在已經接入且合格的連線之間選。剛裝完、一家都沒接時，它可以沒有任何合格目標，這是預期行為。選中的策略、供應商和延遲會回到響應頭 X-OmniRoute-Decision，排錯時先看這一頭，再看客戶端日誌。
- 額度感知的回退。某條連線打滿限額後，排程可以改走仍有餘量的連線。v3.8.53 還加了按剩餘額度加權的策略，並儘量把同一段對話釘在原連線上。
- 訂閱路線可以失敗關閉。文件裡的 subscription 組合只用你已經在付的訂閱額度，失敗就停，不會悄悄落到另一把會計費的鑰匙上。付費鑰匙和訂閱鑰匙不要放進同一個「隨便 fallback」的組合裡。
tos: avoid預設排除。連上不等於進入auto。要固定某把閘道器金鑰只用一個模型，用該金鑰的forcedModel，而不是在客戶端寫死一個上游地址。
壓縮是可選流水線，對客戶端透明。文件把它做成可組合引擎，實際用了哪一套會寫在 X-OmniRoute-Compression 響應頭裡。省多少取決於模型和請求，不要把 README 上的區間當成每條請求的承諾。記憶功能預設關閉。憑證脫敏也是選開的。
放在 Cloud Mac 上：迴環加 SSH
閘道器適合掛在一臺一直開著的 Mac 上：本機迴環聽 20128，你的筆記本用 SSH 把埠轉回來。Cloud Mac 的區域固定、可以 SSH，Apple Silicon 也能跑官方 arm64 映像。管理介面不要綁 0.0.0.0。
ssh -N -L 20128:127.0.0.1:20128 user@your-cloud-mac隧道起來之後，筆記本上的 Cursor 或 omniroute run 仍填 http://127.0.0.1:20128/v1。看起來是本機，流量走到雲端那臺 Mac 的迴環。供應商金鑰留在雲端資料卷或本機使用者目錄，不進 Git。若你已經在同一臺機器上跑 OpenClaw，把它的模型地址指到這同一個 /v1，金鑰仍只留一份在閘道器裡。
需要面板登入時，文件提供可選的 OIDC；密碼登入仍然保留。遠端驅動另有帶範圍的 token（connect / contexts / tokens），按官方 Remote Mode 使用，不要為了省事把儀表板掛到公網 IP。
卡住時先查這幾處
/v1/models是空的。Providers 裡還沒有成功的連線，或客戶端用錯了鑰匙（把供應商 key 當成了閘道器 key）。auto說沒有路線。只接了被排除的供應商，或免費檔當天沒有資格。換一個你確認可用的付費 key，或在模型欄填/v1/models裡的具體 ID。- npm 全域性安裝後命令找不到原生模組。回到 npm 11 的
--allow-scripts，用警告裡的包名重灌。 - Docker 裡程式設計代理中途退出。把
OMNIROUTE_MEMORY_MB和--memory提到程式設計負載那一檔，而不是維持 1024MB。 - 網頁供應商第一次請求失敗。補 Playwright 的 Chromium，再重試，不要先改路由策略。
- 版本對不上。375 家、1475 個模型 ID 是 v3.8.53 文件當時的口徑。升級後以儀表板和 倉庫 README 為準。
FAQ
短答：軟體免費，額度在供應商；地址是本機 20128 的 /v1；auto 只走合格連線；程式設計代理在 Docker 裡要加大記憶體；埠留在迴環，遠端用 SSH 轉發。完整問答在頁頭的 FAQ 結構化資料裡。