OmniRoute 上手：一个本地端点接 290+ 供应商，AI IDE 统一走一处配置
数据截至 2026-07，价格与限额以各官网为准。
OmniRoute 的价值不在于它多接了几个模型，而在于它把”每个 AI 编程工具各配一套 key”这件麻烦事收敛成了一处配置：所有工具都指向 http://localhost:20128/v1，换供应商、加免费档、做回退，都在网关这一层改，IDE 那边一动不动。这是它值得花半小时试一试的真正理由——至于它宣传的”290+ 供应商、40+ 永久免费”，那部分要打折看。
先说一个常见误解。很多人第一眼把 OmniRoute 理解成”另一个 OpenRouter”，觉得又是个代收钱的中转平台。其实定位不一样：OpenRouter 是跑在别人服务器上的托管服务，你把 key 给它、它替你付上游的钱；OmniRoute 是 MIT 协议的开源项目，跑在你自己的机器上，它不经手计费，只是把你自己已有的各家账号凭证统一编排起来。这个差别决定了它的优点（本地可控、免费）和它的风险（所有凭证都堆在你本机的这个进程里）都在同一处。
它到底是什么，从哪来的
按仓库说明，OmniRoute 是一个 MIT 协议的免费 AI 网关，一个端点接 290+ 供应商、500+ 模型，覆盖 Kimi、Claude、GPT、OpenAI、Gemini、GLM、DeepSeek、MiniMax 这些常见来源。对接侧支持 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 等编码工具，另外还支持 Kiro、Command Code、Antigravity、Windsurf、AMP 以及任意 OpenAI 兼容的客户端。
血缘上它不是凭空冒出来的：它由 9router fork 而来，本身是 Go 项目 CLIProxyAPI 的 TypeScript 移植。知道这条线索有个实际好处——遇到行为疑问时，上游那两个项目的 issue 往往能给出解释。
热度方面，第三方资料称仓库有 23k+ star、500+ 贡献者，GitHub Trending 本周涨了一万多 star。但要提醒一句：供应商数量在不同来源里口径不一（有说 268+，有说 290+），星标数也在快速变动，这类数字看个量级就行，别当作选型依据写进技术方案里。
装起来只有两条命令
最快的方式是 npx 直接拉起：
npx omniroute@latest
习惯容器的用 Docker：
docker run -p 20128:20128 diegosouzapw/omniroute
跑起来之后打开 http://localhost:20128 就是管理面板。20128 这个端口要记住，后面所有工具的 base URL 都是 http://localhost:20128/v1。
仓库自述有 80+ 条命令，日常真正会用到的其实就那么几条：
omniroute—— 启动网关和面板omniroute setup—— 首次运行向导，第一次装建议走一遍omniroute chat—— 交互式 TUI 聊天，用来验证链路通没通最省事omniroute doctor—— 自检，配置有问题时先跑它omniroute models --search <term>—— 查某个模型当前可不可用；也可以直接请求GET /api/models/catalog拿完整目录
我的建议是装完先 omniroute doctor，再 omniroute chat 发一句话。这两步能过，说明网关本身没问题，之后再出错就是具体供应商或客户端配置的事，排查范围一下子小了很多。
加供应商：面板点几下的事
流程很直白：面板左侧点 Providers → + Add Provider → 搜索并点选你要的那家 → 免费供应商无需凭证，直接 Connect → 点 Test Connection 验证一下。也可以直接访问 /dashboard/providers 这个路径。
认证类型分四种，理解了这四种，你就知道每加一家会付出什么代价：
- OAuth：由 OmniRoute 代管登录流程，不用自己填 API key。
- web cookie：靠浏览器 cookie 认证。
- API key：付费型，部分供应商可能带免费额度。
- Local：本地推理，Ollama、LM Studio、vLLM 这类。
如果你只是想先跑通、不想掏钱也不想交出任何长期凭证，那 Local 一类和免费档是最安全的起点。反过来说，凡是要你贴 API key 或者交 cookie 的，都等于把一份长期有效的凭证放进了这个本地进程，后面那节会专门讲这件事。
免费档：怎么用，以及别信到什么程度
目录声称有 290 个供应商、90+ 带免费档、40+ 属于永久免费。免费选项里点名提到的有 Kiro、OpenCode Free、Pollinations，文档建议新手从 Kiro AI 起步——免费、不需要 API key、而且可以用到 Claude 系模型，作为第一个连通性验证目标很合适。
接上多个免费供应商之后，就可以启用自动回退（fallback）：一家额度耗尽或者不可用，请求自动转到下一家。
但这里必须踩一脚刹车：免费额度类信息变动极快，“无限免费”不是承诺，只是仓库文档某个版本当时的描述。上游随时可能改政策、收紧额度、关闭免费入口，而开源网关的文档更新往往滞后于上游变化。所以看到”永久免费”四个字，正确的读法是”截至文档写作时该档位免费”，实际以你连上去当天的表现和该供应商官方说明为准。别把一条依赖免费额度的链路直接推到生产环境上，也别按”零成本”去做团队预算。
路由与模型 ID 怎么写
模型字段填 "auto" 时，由 OmniRoute 自动挑选。想省心就用 auto，想可控就写死具体模型。
写死的时候有个容易踩的点：模型 ID 用供应商原生格式。仓库给的示例像 claude-opus-4-8、gpt-5.5、glm-5.1、kimi-k2.5，其中带点号版本号的写法看着别扭，但那是因为上游 API 本来就那么要求，网关只是原样透传，不要自作主张改成你觉得”更规范”的写法。拿不准某个 ID 当前能不能用，就 omniroute models --search 查一下，比对着旧教程猜靠谱得多。
仓库还给了一组零成本组合示例，思路是按优先级串成回退链：gemini-cli/gemini-3-flash-preview（每月 180K 免费）→ if/kimi-k2（无限免费）→ qw/qwen3-coder-plus（无限免费）。这个链条的设计逻辑值得借鉴——把额度有限但质量较好的放前面，把额度宽松的放后面兜底。不过同上，这组具体配置以仓库文档当前版本为准，照抄之前先自己验一遍还通不通。
其他值得留意的能力
- 配额感知的自动回退：不是等报错了才切，而是感知配额状态提前切换。
- RTK + Caveman 压缩：仓库称能省 15%–95% 的 token。这个区间跨度极大，说明效果高度依赖你的上下文形态，别按上限去估成本。
- MCP / A2A 支持：如果你已经在用 MCP 生态的工具，这条链路是通的（不了解 MCP 的可以先看 MCP 协议是什么）。
- Desktop / PWA：不想跟命令行打交道的有图形入口。
- 客户端配置文档：33 个工具的逐一配置写在仓库的
docs/reference/CLI-TOOLS.md，比在网上找二手教程准确。OpenCode 用的插件是@omniroute/opencode-provider。
两件必须先想清楚的事
第一件是凭证。 这是个第三方聚合网关，它的工作方式就是把你各家账号的凭证集中托管在本地代理里。这意味着：这个进程一旦被读取、这台机器一旦被入侵、或者你在不该开的网络环境下暴露了 20128 端口，泄露的不是一把 key，而是一串。开源可审计是它的优势，但”可审计”不等于”你审计过”。务实的做法是：只在自己完全控制的机器上跑，不要把端口暴露到公网，优先用免费档和 Local 供应商，真要贴付费 key 的话单独建一把、限额、能随时吊销，不要把主力生产 key 丢进去。另外，用聚合网关绕过某家服务的正常使用方式，是否符合该服务的条款，需要你自己核实，这篇不做判断也不背书。
第二件是大陆访问。 OmniRoute 本身是跑在你本机的开源软件，装不装得上不是问题；但它只是一层编排，上游还是各家自己的服务。OpenAI、Gemini、Anthropic 这些官方渠道并不支持中国大陆直连，这个事实不会因为中间加了一个本地网关就改变——网关不提供网络可达性，只提供配置统一。市面上确实存在第三方中转服务，能不能用、合不合规、数据怎么处理，需要你自己核实并承担风险，这篇不推荐具体渠道。选型时把这条摆在前面，能省掉很多”装好了却发不出请求”的困惑。
什么情况下不适合用它
- 团队生产环境需要稳定 SLA 和明确账单的，别用免费档拼出来的链路，走各家官方或成熟的托管聚合更省心。
- 只用一个供应商、也没有换模型需求的，多一层网关就是多一个故障点，直接接官方更简单。
- 对凭证集中风险敏感的场景（比如公司设备、涉密项目），先过内部安全评估再说。
- 想省钱但不想折腾的，可以先看看 API 聚合与中转平台怎么对比 和 OpenRouter API 怎么接入，托管方案的心智负担更低。
小结
OmniRoute 解决的是配置分散的问题，不是访问权限的问题，这个边界要先划清楚。上手成本很低，npx omniroute@latest 加 omniroute doctor、omniroute chat 三步就能判断值不值得继续。免费档从 Kiro 起步最省事，但”永久免费”只能当作文档当前版本的描述，别写进预算表。模型 ID 一律照供应商原生格式写，拿不准就用 models --search 查。最后，凭证集中在本地代理这件事的风险要自己认，能用免费档和本地模型就别贴主力 key。