首页 OmniRoute 速查表
2.4.1 2026-03-13 diegosouzapw/OmniRoute 打开 Zread
340px

🚦 快速定位 / 入口 >>>

它是什么

  • 面向 AI 编码工具的统一网关，把 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw 等都接到同一个 OpenAI 兼容入口。
  • 核心价值不是“再包一层 API”，而是把订阅额度、API Key、廉价模型、免费模型串成自动回退链，尽量做到不断流。
  • Chat Completions

两个常用入口

本地网关: http://localhost:20128/v1
云端网关: http://cloud.omniroute.online/v1

模型名的阅读方式

cc/claude-opus-4-6          # Claude Code 订阅模型
cx/gpt-5.2-codex            # Codex 订阅模型
gc/gemini-3-flash-preview   # Gemini CLI 免费层
glm/glm-4.7                 # 低成本 API Key 模型
if/kimi-k2-thinking         # 免费 iFlow 模型

最小可用验证

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

🔀 核心路由链路 >>>

默认思路

订阅模型 -> API Key 模型 -> 低价模型 -> 免费模型

典型四层

Tier 1: Subscription
  Claude Code / Codex / Gemini CLI / Copilot

Tier 2: API Key
  DeepSeek / Groq / xAI / Mistral / NVIDIA NIM / Together AI

Tier 3: Cheap
  GLM-4.7 / MiniMax M2.1 / Kimi K2

Tier 4: Free
  iFlow / Qwen / Kiro

什么时候最值钱

  • 你已经有一个或多个订阅，但经常在高强度编码时撞到 5 小时或周配额。
  • 你不想每个 IDE / CLI 都单独换 base URL、API 协议和模型名。
  • 你需要“先榨干订阅，再自动退到便宜层和免费层”。

🧭 起手工作流 >>>

建议顺序

1. 连接至少一个订阅或免费提供商
2. 新建一个 combo
3. 从 Dashboard 取 OmniRoute API Key
4. 把你的 IDE / CLI 指到 http://localhost:20128/v1
5. 用一个真实请求验证回退链

本地单请求冒烟

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "if/kimi-k2-thinking",
    "messages": [
      { "role": "user", "content": "用一句话解释 OmniRoute 的用途" }
    ]
  }'

建 combo 时的心法

  • 第一个位置放你最希望优先消耗的资源，通常是已付费订阅。
  • glm/glm-4.7 minimax/MiniMax-M2.1
  • 最后一层放真正的兜底免费模型，不追求最强，只追求不断流。

🧪 高频 Recipes >>>

方案 1: 零成本编码

combo: free-forever
1. gc/gemini-3-flash-preview
2. if/kimi-k2-thinking
3. qw/qwen3-coder-plus

方案 2: 先吃满 Claude 订阅

combo: maximize-claude
1. cc/claude-opus-4-6
2. glm/glm-4.7
3. if/kimi-k2-thinking

方案 3: 24/7 不停机

combo: always-on
1. cc/claude-opus-4-6
2. cx/gpt-5.2-codex
3. glm/glm-4.7
4. minimax/MiniMax-M2.1
5. if/kimi-k2-thinking

低价层怎么选

  • glm/glm-4.7：适合放在订阅后的第一层便宜回退。
  • minimax/MiniMax-M2.1：更偏“最低单价兜底”。
  • kimi/kimi-latest：成本更可预测，适合月预算固定的团队。

🔌 CLI / IDE 接入 >>>

OpenAI 兼容类工具的共同配置

Base URL: http://localhost:20128/v1
API Key:  从 OmniRoute Dashboard 获取
Model:    任意已接入模型或 combo 名

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="$OMNIROUTE_API_KEY"

codex "review this repository"

Cursor / Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key:  OmniRoute 的 key
Model:    cc/claude-opus-4-6 或 free-forever

Claude Code

优先走 Dashboard -> CLI Tools 页面一键配置。
如果手改配置，目标仍然是把请求指向 OmniRoute 的 OpenAI 兼容入口。

OpenClaw 手动接入

{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}

OpenClaw 的特殊点

  • 127.0.0.1 localhost
  • 如果只是想“快接入”，先用 CLI Tools 页面生成配置，再回头细调。

🛠️ 常用接口与管理动作 >>>

列出模型

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

Chat Completions

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "maximize-claude",
    "messages": [
      { "role": "user", "content": "生成一个 bash 备份脚本" }
    ]
  }'

音频转写

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=deepgram/nova-3"

导出数据库

curl -o backup.sqlite \
  http://localhost:20128/api/db-backups/export

设置预算

curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key-123",
    "limit": 50,
    "period": "monthly"
  }'

⚖️ 组合与调度策略 >>>

常见策略

Priority        总是优先第一个，失败才回退
Round-Robin     顺序轮转
Random          随机挑一个
Weighted        按权重分流
Least-Used      优先最近使用最少的模型
Cost-Optimized  优先更便宜的模型

经验法则

  • Priority
  • Cost-Optimized
  • Round-Robin Least-Used

🚑 易错点 / 故障排查 >>>

Base URL 常见错法

对 OpenAI 兼容客户端:
  正确: http://localhost:20128/v1

对某些只认根地址的客户端:
  可能需要: http://localhost:20128

几个高频坑

  • Invalid /models
  • localhost 127.0.0.1
  • redirect_uri_mismatch
  • ENABLE_REQUEST_LOGS=true
  • INITIAL_PASSWORD 123456

配额或限流时的标准处理

1. 先看 Dashboard 的 quota / health / costs
2. 把 combo 末尾补一个免费层
3. 再把中间层补一个低价层
4. 最后再调策略，而不是先怀疑客户端配置