OmniRoute：自托管 AI 网关，Claude Code 与 Codex 接入指南

OmniRoute 是 MIT 许可的自托管 AI 网关，用一个兼容 OpenAI 的本地接口接入多家模型供应商，额度用完或被限流时自动切换。本文整理 npm 和 Docker 安装、控制台配置、Claude Code 与 Codex CLI 接入方法、与 LiteLLM 和 OpenRouter 的区别、常见坑，以及它在 AI Rank 上的排名。

📊 查看 OmniRoute 排名

📱 下载 AI Rank App

手里同时有几家模型的订阅和 API key，Claude Code、Codex、各种编辑器插件又各要配一遍，额度用完还得手动切换。OmniRoute 想解决的就是这件事：在自己的电脑或服务器上跑一个 AI 网关，把各家账号接进去，所有工具只认一个本地地址 http://localhost:20128/v1。某家限流、额度耗尽或者报错时，请求自动转给下一个可用的供应商。

项目在 GitHub 上是 diegosouzapw/OmniRoute，MIT 许可。官方文档专门写了 Claude Code 和 Codex CLI 的接入方法，各有一键启动命令。

AI Rank 把它归在“基础设施”类（可观测性、网关）。2026 年 10 月 16 日的日榜快照里，它在全部项目中排第 31，10 月 19 日排第 42，星标 77,885。

路由与故障切换

/v1 接口接收 OpenAI 格式的请求，README 说同一位置也兼容 Claude、Gemini 和 Responses API。请求里可以写具体模型，比如 openai/gpt-4o，也可以写一个组合（combo），即一串备选模型，前一个失败就换下一个。

不想自己配组合，把模型写成 auto 就行，OmniRoute 会按已接入的供应商临时拼一个。README 列出的几种变体：

模型 ID	侧重
`auto`	默认均衡，优先沿用上一次成功的供应商
`auto/coding`	写代码时质量优先
`auto/fast`	延迟最低
`auto/cheap`	单价最低
`auto/subscription`	只用已付费的订阅额度，不会转到按量计费的路线

切换机制分三层：按供应商的熔断器，只在 408 和 5xx 错误时触发；按 key 或账号的冷却，遇到 429 会遵守 Retry-After；按模型的锁定，只锁出错的那个模型。自定义组合有 20 种路由策略可选。

凭据在本地用 AES-256-GCM 加密存储，遥测默认关闭。提示词仍会发给实际处理请求的那家供应商。

安装

npm 包名就是 omniroute，目前 npm 上最新的是 3.8.51 版，2026 年 9 月 30 日发布。Node.js 要求 22.22.2 及以上的 22.x，或 24.x 到 26.x。

npm install -g omniroute
omniroute

启动后控制台在 http://localhost:20128，接口在 http://localhost:20128/v1。也可以用 Docker：

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

装好后可以跑 omniroute doctor，检查供应商、端口和原生依赖。

基本配置

配置都在控制台里完成，分三步：

在 Dashboard → Providers 接入供应商，填 API key 或登录账号，再测试连接。
在 API Keys 页面新建一个 OmniRoute key，只显示一次，要自己存好。这个 key 是给你的工具连 OmniRoute 用的，不是上游供应商的 key。
在工具里把接口地址设为 http://localhost:20128/v1，填上这个 key，模型写 auto 或具体的 provider/model。

用下面的命令列出模型，能看到已接入的模型就说明通了：

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

之后的请求都能在控制台的 Monitoring → Logs 里看到。

接入 Claude Code

Claude Code 没有 --base-url 参数，靠启动时读取环境变量来换接口，改完要重启。最省事的是用 OmniRoute 自带的启动命令，它会设好变量、检查服务器状态，再启动 claude：

omniroute launch

想自己配的话，控制台 CLI Code 页面的 Claude 卡片会给出一段 settings.json，本地实例大致如下，把占位符换成你的 key：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

ANTHROPIC_BASE_URL 只写到端口，不加 /v1，Claude Code 会自己拼上 /v1/messages。omniroute setup-claude 会按模型生成配置，写到 ~/.claude/profiles/<name>/settings.json，再用 omniroute launch --profile <name> 启动对应的一套。

Claude Code 的 /model 菜单只显示以 claude 或 anthropic 开头的模型。要让其他模型出现在菜单里，得打开 OmniRoute 的发现别名（默认关闭），位置在 Settings → Feature Flags → EXPOSE_CC_DISCOVERY_ALIASES，也可以只对某个供应商或模型打开。打开后，glm/glm-5.2 会以 claude/glm/glm-5.2 的名字出现。

接入 Codex CLI

快速上手文档的做法是把 key 放进环境变量，再通过 OmniRoute 启动 Codex：

export OMNIROUTE_API_KEY="<YOUR_KEY>"
omniroute launch-codex --model auto

要长期使用就写配置文件。新版 Codex 只读 ~/.codex/config.toml，旧的 config.yaml 会被忽略。Codex 指南给的供应商配置：

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

文件开头再加一行 model_provider = "omniroute"。omniroute setup-codex 可以按模型批量生成配置，omniroute configure codex 则是交互式选模型后替你写好。

与 LiteLLM、OpenRouter 的对比

OmniRoute 仓库里有一份自己写的对比页，标注为 2026 年第二季度核查。这是项目方的说法，功能项最好当作宣传口径看。下表只留容易核实的几行：

	OmniRoute	LiteLLM	OpenRouter
自托管	是	是	否（托管服务）
许可	MIT	MIT	专有
故障切换	20 种组合策略	按优先级	按层级
内置 MCP 服务器	有	无	无

对比页也写了各自适合的人：以 Python 为主、想用 litellm.completion()、需要成熟 Kubernetes 或 Helm 部署方案的团队选 LiteLLM；不想自己运维、希望所有供应商用一个付款方式的选 OpenRouter。供应商数量在 OmniRoute 自己的文档里也不统一，对比表写 329，README 写 375，别太当真。

常见坑

npm 拦截安装脚本。 npm 11 及以后的版本可能拦下安装脚本，OmniRoute 的 postinstall 负责把原生 SQLite 驱动放到位，被拦后会退到更慢的驱动。按 npm 警告里列出的包名用 --allow-scripts 放行。README 和排错文档给的名单不一样，排错文档建议别放行约 300 MB 的可选包 onnxruntime-node，以你实际看到的警告为准。
Node.js 版本不对。 不在 22.22.2 以上的 22.x 或 24 到 26 范围内，登录页可能报 “Module did not self-register”。换成 Node.js 24，重装后重启。
auto 无路可走。 新装的实例可能还没有可用的供应商。标记为 tos: avoid 的供应商（包括 Kiro）即使接入了，默认也不参与 auto。
Claude Code 地址多写了 /v1。 Claude Code 自己会拼 /v1/messages，地址里再加 /v1 就会出错。
上下文窗口对不上。 Claude Code 对不认识的模型一律按 200K 窗口处理，窗口更大的模型要把 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设得比实际窗口小一些。setup-claude 生成的配置已经处理好了。
免费额度频繁返回 429、400、401。 排错文档建议在 OmniRoute 进程环境里设 OMNIROUTE_ROTATE_ON_400=true；额度真的耗尽，就得再接一个账号。
Windows 上找不到 omniroute 命令。 把 npm 全局目录（npm config get prefix）加进 PATH。

常见问题

OmniRoute 收费吗？ 软件本身 MIT 许可、免费。费用来自你实际调用的供应商，免费额度也有各家自己的条款和上限。

哪个 key 填在哪里？ 工具里填控制台生成的 OmniRoute key，各家供应商的 key 和账号登录只放在 OmniRoute 里。

能装在服务器上吗？ 可以。omniroute connect <host> 让本机命令行用受限令牌登录远程实例，omniroute launch --remote 则让 Claude Code 连到远程实例。

Cursor 能用吗？ README 的兼容列表里有 Cursor CLI，并说明任何兼容 OpenAI 接口的工具都可以接 /v1。

继续探索： 在 AI Rank 的开源项目排名查看今天增长最快的 AI 开源项目。

或 📱 下载 AI Rank App 在手机上随时查看。

来源

OmniRoute README、LICENSE
快速上手
Claude Code 配置指南
Codex CLI 配置指南
OmniRoute 对比页
排错指南
npm 上的 omniroute、发布页、omniroute.online
OmniRoute 的 AI Rank 页面（2026 年 10 月 16、18、19 日日榜快照）

本文使用自动化编辑辅助，于 2026 年 10 月 19 日依据 OmniRoute 仓库与文档、npm 仓库和指定日期的 AI Rank 快照核对，未安装或测试 OmniRoute。

封面图片：官方产品素材；由 AI Rank 编辑排版。