AI工具

OmniRoute 教程：搭建本地 AI API 网关与多模型自动切换

介绍 OmniRoute 本地 AI 网关的安装与配置，涵盖 OpenAI 兼容接口、Provider 接入、auto 模型路由、故障回退、Docker 部署及 MCP 安全。

OmniRoute 是一个本地运行的 AI API 网关，把不同模型供应商、订阅账号和免费额度放到统一接口后面。Codex、Claude Code、Cursor、Cline、OpenCode 等客户端只需连接一个 OpenAI 兼容地址，再由 OmniRoute 根据可用额度、成本、延迟和健康状态选择模型。

它适合同时使用多家模型服务、经常遇到限流，或者希望统一查看调用量的开发者。需要注意的是，网关不会凭空产生免费额度：账号注册、API 价格、速率限制和可接受使用方式仍由各上游供应商决定。

快速答案

全局安装并启动：

1
2

npm install -g omniroute
omniroute

默认地址：

1
2

Dashboard: http://localhost:20128
API:       http://localhost:20128/v1

进入 Dashboard 的 Providers 页面连接至少一个模型供应商，再到 Endpoints 页面复制本地 API Key。AI 客户端使用：

1
2
3

Base URL: http://localhost:20128/v1
API Key:  Dashboard 中生成的 Key
Model:    auto

验证模型列表：

1
2

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

如果返回已连接的模型，说明网关基本可用。正式接入编码 Agent 前，再分别测试普通对话、流式输出、工具调用和长上下文，避免只凭模型列表判断兼容性。

OmniRoute 如何工作

客户端不再直接连接每家模型 API，而是把请求发送到本地 OmniRoute。网关读取模型名和路由规则，选择当前可用的 Provider，再把响应转换为客户端能够理解的协议。

1
2
3
4
5
6
7
8
9

Codex / Claude Code / Cursor
              |
              v
 http://localhost:20128/v1
              |
              v
      OmniRoute 路由与回退
       /       |        \
   Provider A  B         C

这种架构带来三个直接效果：

  1. 客户端只维护一个 Base URL 和访问密钥；
  2. 某个 Provider 限流或故障时，可以切换到候选模型；
  3. 调用量、成本、延迟和错误集中到同一控制面观察。

代价是 OmniRoute 成为请求路径中的关键组件。它停机、配置错误或数据目录损坏时，所有经它转发的客户端都会受影响，因此生产环境需要持久化、备份、访问控制和明确的绕行方案。

环境要求与安装

官方当前要求 Node.js 22 或 24 LTS，并推荐 Node.js 24 LTS。先检查版本：

1
2

node --version
npm --version

使用 npm 安装：

1

npm install -g omniroute

第一次运行可以进入引导流程：

1

omniroute setup

启动网关与 Dashboard：

1

omniroute

交互式终端聊天：

1

omniroute chat

遇到 Provider、端口或原生依赖问题时运行诊断：

1

omniroute doctor

如果本机没有适配的 better-sqlite3 预编译文件，项目会尝试使用其他 SQLite 实现。安装异常时应先看完整日志，不要直接关闭所有安装脚本或用管理员权限反复重装。

使用 Docker 运行

官方提供多架构 Docker 镜像：

1
2
3
4
5
6
7

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

检查状态和日志：

1
2

docker ps --filter name=omniroute
docker logs -f omniroute

omniroute-data 保存配置、数据库和运行状态，升级或重建容器时不要随意删除。生产环境还应把 latest 换成经过验证的明确版本标签，并在升级前备份卷。

上面的 -p 20128:20128 可能把端口发布到宿主机所有网络接口。只在本机使用时，可以限制到环回地址：

1
2
3
4
5
6
7

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

需要远程访问时，应使用 HTTPS、强认证、IP 限制或私有网络，不要把 Dashboard 和 API 裸露到互联网。

连接模型供应商

启动后打开：

1

http://localhost:20128

进入 Providers 页面，根据实际拥有的账号或 API Key 添加 Provider。建议按以下顺序操作：

  1. 先连接一个低风险测试账号；
  2. 确认模型目录和单次对话可用；
  3. 设置预算或额度限制；
  4. 再增加第二个 Provider 验证回退；
  5. 最后才接入日常编码客户端。

不要在截图、日志或问题反馈中暴露 OAuth Token、API Key 或 Dashboard 访问密钥。仓库说明凭据会在本地加密保存，但本机被攻破、主密钥泄露或恶意扩展读取进程时，仍可能造成风险。

使用 auto 自动路由

最简单的配置是把客户端模型设为：

1

auto

OmniRoute 还提供面向不同目标的自动模型名：

模型名 路由侧重点
auto 平衡选择，并倾向最近成功路径
auto/coding 优先代码生成质量
auto/fast 优先低延迟
auto/cheap 优先较低调用成本
auto/offline 优先剩余额度或限流空间
auto/smart 质量优先，并保留少量探索流量

自动路由不保证不同模型的行为完全一致。工具调用格式、上下文窗口、推理能力和输出风格可能变化。关键任务应固定模型或限定候选集合，避免在一次长任务中无提示地切换到能力明显不同的模型。

自定义回退链与路由策略

OmniRoute 把一组模型回退目标称为 combo。可以按优先级、权重、成本、剩余额度、延迟或最近成功状态选择目标。

常见策略包括：

  • priority：按固定顺序使用，失败后转下一个；
  • round-robin：在目标间轮询；
  • cost-optimized：倾向价格更低的可用模型；
  • headroom：倾向剩余额度更多的连接；
  • context-optimized：按当前上下文大小选择模型；
  • lkgp：保持在最近已验证成功的路径。

配置回退链时，不要只比较模型名称。还要统一考虑输入输出价格、上下文限制、工具调用、图片能力、数据区域和供应商条款。对必须保持模型一致的会话，应启用合适的粘性策略或直接固定 Provider。

接入 OpenAI 兼容客户端

能自定义 OpenAI Base URL 的工具通常可以使用：

1

http://localhost:20128/v1

推荐通过请求头传递访问密钥：

1

Authorization: Bearer YOUR_KEY

无法添加自定义 Header 的客户端，可以使用带 Token 的兼容别名，但 URL 会包含密钥，更容易进入浏览器历史、代理日志或截图。只有确实无法使用 Header 认证时才使用该方式，并定期轮换密钥。

验证聊天接口时，可以发送一个最小请求：

1
2
3
4

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

Windows PowerShell 中 curl 的别名和引号行为可能不同，建议使用 curl.exe 或按当前 PowerShell 版本构造请求。

MCP 接入与权限风险

OmniRoute 不仅能转发模型请求，还提供 MCP，让 Agent 管理 Provider、路由、combo、缓存、压缩和其他网关功能。

stdio 模式：

1

omniroute --mcp

HTTP MCP 地址：

1

http://localhost:20128/api/mcp/stream

Claude Code 示例：

1
2
3

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

MCP 权限比普通模型调用更敏感，因为 Agent 可能修改路由或连接配置。接入前应使用最小 scope、独立访问 Token 和审计日志；删除 Provider、轮换密钥或调整团队配额等操作应保留人工确认。

Token 压缩应该怎么评估

仓库提供多级压缩和 RTK、Caveman 等处理管线，官方展示的节省比例范围很大。实际效果取决于工具输出、重复内容、上下文结构和压缩档位，不能把 README 中的比例直接当作每个项目的保证。

建议用固定任务做 A/B 测试：

  1. 保存原始 Prompt、工具输出和最终结果；
  2. 关闭压缩运行一次；
  3. 使用标准或 RTK 配置再运行一次；
  4. 比较输入 Token、延迟、成本和答案正确性；
  5. 对代码修改运行同一套测试或验证命令。

压缩可能删除被判定为低相关的信息。安全审计、长日志诊断和精确代码评审不应只看 Token 节省，还要检查遗漏率并保留查看原始输出的路径。

免费额度与供应商条款

OmniRoute 汇总多家供应商公开的免费层、试用额度和限流信息。数字会随供应商政策、地区、账号类型和时间变化，因此文章不固定引用某个“每月免费 Token 总数”。应以 Dashboard 当前目录和上游官方价格页为准。

还要区分三类资源：

  1. 长期免费层；
  2. 注册后一次性试用额度；
  3. 需要付费或订阅才能解锁的额外额度。

使用订阅账号、非标准 OAuth 流程或多个账号聚合前，必须核对供应商服务条款。技术上能够接入不代表供应商允许把个人订阅共享给团队、自动化调用或规避额度限制。

远程部署注意事项

把 OmniRoute 部署到 VPS 后，所有客户端 Prompt、代码上下文和模型响应都会经过该主机。至少需要：

  • 使用 HTTPS，避免明文传输 Token 和 Prompt；
  • 限制 Dashboard、API 与 MCP 的访问来源；
  • 为不同用户或客户端签发不同 scope 的 Key；
  • 备份数据目录，同时加密备份；
  • 设置日志保留周期，避免长期保存敏感代码；
  • 监控调用成本、失败率、延迟和异常登录。

不要把本地示例中的 http://localhost:20128 简单替换成公网 IP 就投入使用。推荐先通过 Tailscale、WireGuard 或 SSH Tunnel 验证，再决定是否配置反向代理和公开域名。

常见问题

Dashboard 打不开

运行诊断并检查端口：

1

omniroute doctor

确认进程仍在运行，20128 没有被其他应用占用。Docker 用户查看容器日志和端口映射。

/v1/models 返回 401

确认请求使用的是 Dashboard → Endpoints 生成的本地 Key，并包含：

1

Authorization: Bearer YOUR_KEY

不要误把上游 Provider Key 当作 OmniRoute Endpoint Key。

auto 选到了不合适的模型

先固定一个已验证模型确认客户端兼容，再调整 combo 候选、策略、预算和上下文要求。关键工作流可以使用 auto/coding，但仍应限制不满足工具调用或上下文要求的模型。

路由回退后回答风格突然变化

不同模型的系统指令遵循能力和工具格式存在差异。启用会话粘性、缩小候选模型差距，并在切换时保留必要的任务状态。对需要确定性的任务直接固定模型。

OmniRoute 能降低所有 AI 成本吗？

不能保证。它可以依据定价和额度路由，并减少部分重复上下文，但网关本身无法改变上游计费规则。融合、流水线或多模型评审还可能增加总调用量。

OmniRoute 适合哪些场景

OmniRoute 适合同时维护多家模型账号、需要统一 OpenAI 兼容入口、希望在限流时自动回退，或想集中观察成本和健康状态的个人与团队。对只使用一个稳定 Provider 的简单项目，引入完整网关可能增加维护复杂度。

在团队生产环境采用前，建议先完成四项验证：客户端协议兼容、Provider 条款、密钥与权限隔离、网关故障时的降级路径。

总结

OmniRoute 用本地 http://localhost:20128/v1 把多个模型供应商接到统一 API 后面，通过 auto 和 combo 实现成本、速度、额度与健康状态驱动的路由。npm 安装适合本机体验，Docker 适合持久运行；远程部署时必须补齐 HTTPS、访问控制、备份和审计。免费额度和压缩比例都是动态指标，应结合上游条款和自己的基准测试评估。

项目地址：diegosouzapw/OmniRoute

官方网站：omniroute.online