omniroute 是什么 开源网关怎么接 agent

omniroute 是什么：社区开源 AI gateway，多 provider 配额切换与压缩省 token，附安全自审与接入注意。

omniroute 是什么 开源网关怎么接 agent

选本地路由层、又怕装错成「官方产品」时，先搞清 omniroute 是什么：社区维护的开源 AI gateway，不是 Anthropic / OpenAI / Cursor 官方组件。

作者：CodePass 技术编辑

结论先说清楚

diegosouzapw/OmniRoute 是 MIT 许可的开源项目，把自己定位成「一个 endpoint，聚合多 provider / 多模型」的网关。README 宣传目录规模约 290 providers、其中 90+ 带免费档，并宣称兼容 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 等。这些数字来自项目自报与仪表盘口径，会随目录审计上下浮动，不能当成合同 SLA。

2026 年 8 月 5 日查 GitHub API：星标约 4 万量级，默认分支在 release/v3.8.50 一带，近期仍有推送。社区活跃不等于供应链已替你审完；密钥会进这个进程，默认按「自建中间人」对待。

它实际卖的三块能力

第一块是统一入口。本机默认端口 20128，OpenAI 兼容路径在 /v1。装完可先不配自家 Key，用 README 写的免费 provider 试通；成熟用法是 Dashboard 里挂上多个上游，再把客户端的 Base URL 指到本地。

第二块是配额感知切换。所谓 combo：某个上游额度用尽、失败或成本飙高时，按策略滑到链上下一个模型。auto 系列让网关根据已连接 provider 现场打分；另有偏额度、偏成本等变体。团队共用账号时，README 还提到 Quota-Share 一类公平切分，细节见仓库内 Resilience 文档。

第三块是透明压缩。默认堆叠管线写明 RTK → Caveman，并给出合成节省公式；压缩引擎文档自称 12 个可组合步骤，覆盖工具输出过滤与散文压缩。项目自评单请求可省约 15%–95%，区间跨度大，实际取决于负载是不是「壳命令日志 + 长散文」。若你只想理解 Caveman 本身改说话方式，见 caveman skill 怎么省 token；OmniRoute 是把类似思路嵌进网关管线，客户端无感。

和编辑器内置路由器不是同一层。Cursor 侧「按任务复杂度选模型」那套，见 Cursor Router 如何省成本。OmniRoute 跑在你机器（或你的 VPS）上，管的是上游账号与协议兼容。

密钥与日志怎么自审

网关进程能看见完整请求体：系统提示、代码片段、工具结果、你配置的上游 API Key。本地优先只降低「流量出办公室」的概率，不消除「本机恶意插件 / 被入侵主机」风险。

上线前至少做五步自查：

  1. 读 LICENSE 与仓库所有者：个人维护者账号，不是云厂商官方 org。
  2. 确认绑定地址。README 的 Docker 示例用 -p 127.0.0.1:20128:20128，刻意不暴露到公网；若改成 0.0.0.0 或反代到公网，等于把钥匙串挂门外。
  3. 打开 Guardrails / Authorization 文档，核对 prompt-injection 防护、credential-masking 是否默认开启，以及 Dashboard 登录方式（密码 / 可选 OIDC）。
  4. 查日志与遥测落盘位置：成本头 X-OmniRoute-*、usage webhook、远程 connect 签发的 scoped token，分别谁能读。
  5. 远程模式（笔记本 CLI 打 VPS 上的 OmniRoute）只用最小 scope；README 写明 process-spawning 类路由保持 loopback。

若流量最终仍要经第三方中转，中转层明文可见范围与自查清单，对照 中转 API 会泄露代码吗。自建网关解决的是「多钥匙聚合」，不自动消灭上游不信任问题。

MITM / TPROXY 解密能力（抓无视代理环境变量的 CLI）属于高危运维特性：只在你明确需要抓包、并理解本机 CA 植入后果时再开。

Cursor、Claude Code、Codex 怎么接

通用接法（README Quick Start）：

npm install -g omniroute
omniroute

Dashboard：http://localhost:20128。客户端填：

Base URL: http://localhost:20128/v1
API Key:  （Dashboard → Endpoints 复制）
Model:    auto

验证：

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

不能自定义 Header 的客户端，可用 README 列出的 tokenized 兼容别名（/vscode/YOUR_KEY/...），官方仍建议优先 Header 鉴权。

工具侧：仓库宣称 setup-* 可配置十余种 coding 工具，omniroute launch / launch-codex 走零配置启动；omniroute configure codex 会选远程模型并写本地 Codex profile。完整清单指向仓库内 CLI-TOOLS.md（README 称覆盖数十个 CLI）。Claude Code 还可把网关本身当 MCP：

claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream

Cursor 把 Base URL 指到本地 /v1 即可；Cloud Agent 等远端执行环境能否访问你的 localhost，要单独设计（内网穿透、自建 VPS 上的 OmniRoute、或根本不走本地网关）。接之前用 omniroute doctor 看端口与原生依赖。

国内环境要自己验证什么

README 的免费档聚合、provider 目录和延迟数字，大多按作者可访问的国际网络测量。国内开发者至少本地验证三件事：目标上游在你网络下能否稳定建连；auto 选中的免费池是否对你的账号地区开放；压缩管线打开后，中文日志与补丁输出有没有被裁坏。

免费额度与模型列表两周一审计一类说法写在 README，数字会涨也会跌。把「290 providers」抄进团队规范之前，用你自己的 Key 跑通一条真实补全，比星标数管用。

需要托管中转或按量计费时，把「谁持有上游 Key、日志留多久」写成书面要求，再选型；本文不绑定具体厂商。

Docker 部署时优先跟 README 绑定 127.0.0.1，数据卷单独挂载；从源码跑则先复制 .env.example。Node 版本要求写在 Tech Stack（22.x / 24.x LTS 一带），装不上先对照 omniroute doctor 输出，再决定要不要动系统代理。

常见问题

OmniRoute 是 OpenAI 或 Anthropic 官方产品吗？

不是。它是 GitHub 用户 diegosouzapw 维护的社区 MIT 项目，官网与文档由项目自行发布，与模型厂商无官方从属关系。

不配任何 API Key 也能用吗？

README 写安装后可用部分免费后端试通（例如文中点名的 OpenCode Free / 部分无需注册通道），并可用 model: auto。生产用法仍应显式接入你信任的上游，并限制 Dashboard 暴露面。

压缩省 token 能当账单承诺吗？

不能。15%–95% 是项目在不同引擎与负载下的自评区间；壳命令输出偏 RTK，聊天散文偏 Caveman。上线前用你们真实会话抽样对比开关压缩的用量头。

参考资料