OmniRoute 是什么？一个 API 调用 290+ AI 模型完整教程（2026）

你在 Claude Code、Cursor 或自建 Agent 里改一个 base_url，就能在同一条 OpenAI 兼容 API 上切换 Claude、GPT、Gemini、DeepSeek、Kimi 等数百个模型——这不是 OpenRouter 的专属能力。OmniRoute 是 2026 年 GitHub 上增长最快的开源 AI 网关之一：MIT 许可、自托管，官方目录宣称接入 290+ 供应商、500+ 模型（其中 90+ 带免费额度）。本文从「它是什么」讲到第一次成功调用，再到 Claude Code 接入与生产安全清单。

OmniRoute 是什么？解决什么问题

简单说：OmniRoute 是你自己机器上跑的 LLM 反向代理。它对上游暴露统一的 /v1/chat/completions（以及 Anthropic /v1/messages、Gemini /v1beta/models 等兼容面），对下游连接你配置的各厂商 API Key、OAuth 订阅或免费池。

官方 README（v3.8.x）强调的能力还包括：配额感知自动 fallback、RTK+Caveman token 压缩（宣称可省 15–95%）、MCP/A2A、桌面 PWA 等。对大多数开发者，「一个端点 + 多模型 + 可观测」 已足够作为第一天价值。

和 OpenRouter、LiteLLM 怎么选

若你主要关心各模型 token 单价对比，可先读 OpenRouter API 价格对比文；若已决定自托管并要控制 Agent 单次请求成本，再读 OmniRoute Auto Combo 预算路由。

安装与启动（Docker / npm）

以下命令在 macOS、Linux 或云端 Mac 上均可运行。确保本机或服务器已开放 20128 端口（或通过反向代理转发）。

方式 A：Docker（推荐生产）

docker run -d --name omniroute \
  -p 20128:20128 \
  -v omniroute-data:/data \
  diegosouzapw/omniroute

浏览器访问 http://localhost:20128，应跳转到 /dashboard。

方式 B：npm（本机快速试用）

npm install -g omniroute
omniroute

Dashboard 四步：Key → 供应商 → 客户端 → 监控

首次打开 Dashboard 会看到引导条，逻辑与官方文档一致，建议严格按顺序完成：

1. 创建 API Key：在 /api/keys 或 Dashboard「Keys」面板生成密钥；后续所有客户端用 Authorization: Bearer <key>。
2. 连接供应商：三种方式——OAuth（Claude Code / GitHub Copilot 订阅）、粘贴 API Key（OpenAI、Anthropic、Mistral 等）、开启免费 no-auth 池（仅适合试用）。
3. 指向客户端：把应用的 OPENAI_BASE_URL 或等价配置设为 http://<host>:20128/v1。
4. 监控用量：Dashboard 查看每次请求的路由结果、token 与失败原因；管理端点未带 Key 应返回 401。

列出全部模型：GET /v1/models

连接成功后，用 API Key 拉取模型目录（返回 OpenAI 格式的 data[] 列表，含 chat、embedding、image 及 combo 别名）：

export OMNI_KEY="你的-OmniRoute-API-Key"
curl -s http://localhost:20128/v1/models \
  -H "Authorization: Bearer $OMNI_KEY" | jq '.data | length'

在 v3.8.x 典型安装中，可见数百条记录；其中一部分为 auto/* 组合别名（见下文）。也可用管理 API GET /api/models/catalog 按供应商分组查看。

第一次 API 调用（curl / Python / Node）

模型 ID 推荐写成 provider/model 形式。若省略供应商前缀，OmniRoute 会尝试自动补全；不匹配时返回 400。

curl：非流式聊天

curl -s http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "用一句话解释 OmniRoute"}],
    "max_tokens": 256
  }' | jq '.choices[0].message.content'

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="你的-OmniRoute-API-Key",
    base_url="http://localhost:20128/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{"role": "user", "content": "Hello from OmniRoute"}],
    max_tokens=128,
)
print(resp.choices[0].message.content)
print(resp.usage)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OMNI_KEY,
  baseURL: "http://localhost:20128/v1",
});

const completion = await client.chat.completions.create({
  model: "google/gemini-3.1-pro",
  messages: [{ role: "user", content: "Ping" }],
});
console.log(completion.choices[0].message.content);

流式输出

curl -N http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-chat","messages":[{"role":"user","content":"数到5"}],"stream":true}'

Anthropic Messages 端点

若客户端原生走 Anthropic SDK，可直连 POST /v1/messages，无需强行套 OpenAI 格式。完整端点列表见 官方 API Reference（含 embeddings、images、audio、rerank 等）。

auto/* 意图别名与多供应商回退

除显式 provider/model 外，OmniRoute 提供 auto/best-coding、auto/best-free 等意图别名：你描述「要什么能力」，网关在已连接且健康的候选里自动选型。这对 Agent 客户端特别有用——换底层供应商时不必改客户端配置。

curl -s http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto/best-coding","messages":[{"role":"user","content":"写一个快速排序"}]}'

当主供应商限流或凭据失效时，OmniRoute 按策略向下回退（订阅 → API Key → 低价 → 免费池）。生产环境务必限制免费池优先级，并配合预算头或 Auto Combo 规则，避免意外降级到不稳定模型。细节见 预算路由教程。

接入 Claude Code、Cursor 与 VS Code Copilot

改完环境变量后重启终端或 IDE，发一条短 prompt 验证；若返回 401，检查 OmniRoute Key 与 Dashboard 里供应商是否已连接且健康。

生产部署与安全清单

OmniRoute 早期版本曾曝出默认凭据类漏洞（社区称 CVE-2026-49 等）。2026 年上生产前请至少完成：

• 升级到最新 release（v3.8.50+），不要使用带已知默认密码的旧镜像；
• 修改 Dashboard 管理员密码，禁用或删除任何 change-me 类默认密钥；
• 仅在内网监听，或经 Nginx/Caddy 暴露 HTTPS，禁止把 20128 裸奔到公网；
• 为每位成员签发独立 API Key，配置 Token 限额与 IP 允许列表；
• 免费池与 OAuth 订阅仅作回退层，核心任务绑定付费 Key；
• 定期备份 /data 卷（供应商配置与别名）；
• 日志脱敏：勿把上游厂商原始 Key 打进应用日志。

常见问题

返回 400 model not found 怎么办？

检查 provider/model 拼写；确认 Dashboard 已连接对应供应商且该模型在 /v1/models 列表中。试用阶段可改用 auto/best-free 验证链路。

能否只在内网用 Ollama 模型？

可以。OmniRoute 支持 Ollama 端点（POST /v1/api/chat），把本地 llama3 等与云端模型纳入同一路由表。

和 OpenRouter 能否同时用？

可以。OmniRoute 可把 OpenRouter 当作下游供应商之一（见 API Reference 中的 OpenRouter provider），实现「自托管网关 + 云端模型目录」混合架构。