OmniRoute - бесплатный AI-шлюз для разработчиков: полное руководство

Репозиторий: github.com/diegosouzapw/OmniRoute
npm-пакет: npmjs.com/package/omniroute
Сайт: omniroute.online
Звёзды на GitHub: 6 900+ | Форки: 1 200+

Что такое OmniRoute?

OmniRoute — это открытый универсальный AI-прокси, который объединяет более 160 провайдеров (включая Anthropic, OpenAI, Google, DeepSeek, Groq и десятки бесплатных) за одним локальным эндпоинтом http://localhost:20128/v1. Проект написан полностью на TypeScript, покрыт более чем 4 600 автоматизированными тестами и распространяется под лицензией MIT.

Основная идея проста: вместо того чтобы каждый раз перенастраивать Claude Code, Codex, Cursor, Kiro или любой другой AI-инструмент под конкретного провайдера, вы один раз устанавливаете OmniRoute и направляете все инструменты на его локальный адрес. OmniRoute сам занимается маршрутизацией, трансляцией форматов API, сжатием промптов и автоматическим переключением между провайдерами.

Девиз проекта: Never stop coding — никогда не прерывайтесь из-за исчерпанной квоты, заблокированного провайдера или технического сбоя.

Зачем нужен OmniRoute: 7 ключевых проблем, которые он решает

1. Квоты заканчиваются в самый неподходящий момент

Разработчики платят $20–200 в месяц за Claude Pro, Codex Pro или GitHub Copilot, но даже при платной подписке есть ограничения: 5 часов использования, недельные лимиты, rate limits в минуту. Когда квота заканчивается, весь рабочий поток прерывается.

OmniRoute реализует 4-уровневый автофоллбэк:

Подписка (Claude Code, Codex) 
  → API-ключ (DeepSeek, Groq, xAI) 
    → Дешёвые модели (GLM, MiniMax) 
      → Бесплатные (Qoder, Qwen, Kiro) — без остановки

2. У каждого провайдера свой API

OpenAI, Anthropic и Google используют принципиально разные форматы запросов. OmniRoute автоматически транслирует между форматами в обоих направлениях: OpenAI ↔ Claude ↔ Gemini ↔ Responses API — прозрачно для любого клиентского инструмента.

3. Геоблокировки и санкционные ограничения

Для пользователей из России, Китая, Ирана и ряда других стран многие AI-провайдеры недоступны или работают нестабильно. OmniRoute предлагает 3-уровневую систему проксирования:

• Глобальный прокси (весь трафик)
• Прокси на уровне провайдера (только нужный)
• Прокси на уровне конкретного API-ключа

Поддерживаются HTTP/HTTPS и SOCKS5. Встроена подмена TLS-отпечатка через wreq-js — что делает трафик похожим на запросы из браузера, а не от автоматизированного клиента. Отдельно реализовано сопоставление с нативными сигнатурами CLI-утилит (Claude Code, Codex), чтобы максимально снизить риск блокировки аккаунта.

Также встроена интеграция с 1proxy — маркетплейсом сотен бесплатных прокси с фильтрацией по стране, оценкой качества и автоматической ротацией.

4. Дорогие подписки при ограниченном бюджете

OmniRoute поддерживает 11 полностью бесплатных провайдеров без необходимости вводить данные карты:

5. Сложность управления OAuth-токенами

Claude Code, Codex, Gemini CLI и Copilot используют OAuth 2.0 с истекающими токенами. OmniRoute автоматически обновляет токены в фоне, поддерживает мультиаккаунты с round-robin ротацией, исправляет проблемы с OAuth за NAT/прокси.

6. Нет единого обзора расходов

В OmniRoute встроена аналитика: отслеживание стоимости на уровне токена, лимиты бюджета по тирам, статистика по каждому API-ключу, перцентили латентности p50/p95/p99.

7. Сложная настройка каждого инструмента отдельно

Дашборд CLI Tools даёт возможность одним кликом настроить Claude Code, Codex CLI, Kiro, Cursor, OpenClaw, Kilo Code и ещё десяток инструментов. После настройки OmniRoute всё работает через единый адрес http://localhost:20128/v1.

Установка OmniRoute: все способы

Через npm (рекомендуется)

npm install -g omniroute
omniroute

Дашборд откроется на http://localhost:20128, API доступно на http://localhost:20128/v1.

Через pnpm

pnpm install -g omniroute
pnpm approve-builds -g   # важно: выбрать все пакеты и подтвердить
omniroute

Через Docker

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

Docker Compose с профилями:

# Базовый (без CLI-инструментов)
docker compose --profile base up -d

# С Claude Code, Codex, OpenClaw
docker compose --profile cli up -d

Docker-образ весит ~250 МБ, доступен для AMD64 и ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi).

Из исходного кода

cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev

Arch Linux (AUR)

yay -S omniroute-bin
systemctl --user enable --now omniroute.service

Android через Termux

pkg update && pkg install nodejs-lts python build-essential git
npx -y omniroute@latest

После этого OmniRoute доступен по локальной сети на http://ВАШ_IP:20128/v1 — ваш телефон становится AI-сервером.

Как удалить OmniRoute

# Удалить, сохранив данные и конфиги в ~/.omniroute
npm run uninstall

# Полное удаление, включая базы данных и все настройки
npm run uninstall:full

# Или просто убрать глобальный пакет
npm uninstall -g omniroute

Настройка пароля и API-ключей

OmniRoute защищает дашборд и API через встроенную систему управления ключами:

Создание API-ключа:

1. Откройте Dashboard → Endpoints
2. Нажмите «Create API Key»
3. Укажите разрешённые модели (или оставьте «Allow All»)
4. Скопируйте сгенерированный ключ

После этого в любом инструменте указывайте:

Base URL: http://localhost:20128/v1
API Key:  ваш-ключ-из-дашборда
Model:    if/kimi-k2-thinking  (или любой другой)

Если нужна простая работа в локальной сети без авторизации — при подключении провайдера через http://localhost:20128/v1 можно использовать произвольную строку в поле API Key.

Дополнительные механизмы безопасности:

• IP-фильтрация — whitelist/blacklist адресов
• Rate limiting — ограничение запросов по IP
• Шифрование учётных данных — AES-256-GCM
• CSRF-защита — все роуты дашборда защищены
• Защита от prompt injection — санитизация входящих запросов

Провайдеры: 160+ источников за одним эндпоинтом

OAuth-провайдеры (подписки)

Бесплатные провайдеры без ключа

• Pollinations AI — GPT-5, Claude, Gemini, DeepSeek, Llama 4 без регистрации (1 запрос/15с)

API-ключи: платные с бесплатными тирами

Более 120 провайдеров с API-ключами, включая бесплатные тиры:

• NVIDIA NIM — ~40 RPM навсегда, 70+ моделей
• Cerebras — 1 млн токенов/день, самый быстрый инференс
• Groq — 14 400 запросов/день бесплатно
• DeepSeek V3.2 — $0.27/$1.10 за 1М токенов
• xAI Grok-4 Fast — $0.20/$0.50 за 1М токенов

Самохостинг

Поддерживаются: Ollama, LM Studio, vLLM, Llamafile, ComfyUI, Stable Diffusion WebUI, NVIDIA Triton, XInference, oobabooga и другие.

Префиксы моделей

Модели указываются через формат префикс/название-модели:

Сжатие промптов: экономия 15–95% токенов

Одна из самых уникальных возможностей OmniRoute — встроенный конвейер сжатия промптов. Он работает прозрачно: клиент отправляет полный промпт, OmniRoute сжимает его перед отправкой провайдеру.

Вдохновение — проекты RTK (Rust Token Killer) и Caveman.

7 режимов сжатия

Как работает Stacked (78–95%)

combined = 1 - (1 - RTK) × (1 - Caveman_input)
average  = 1 - (1 - 0.80) × (1 - 0.46) = 89.2%
range    = 78.4–94.6%

Пример до/после (режим Standard)

До (69 токенов):

"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."

После (19 токенов):

"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Тот же смысл. На 72% меньше токенов. Без потери точности.

Настройка сжатия

Через дашборд: Dashboard → Context & Cache → Caveman / RTK / Compression Combos

Или через конфиг combo:

{
  "comboOverrides": {
    "my-coding-combo": "standard",
    "my-free-combo": "ultra"
  }
}

Автотриггер: установите autoTriggerTokens — сжатие включится автоматически при превышении порога токенов.

Комбо и маршрутизация: 13 стратегий балансировки

Комбо (Combo) — это цепочка провайдеров с настроенной стратегией фоллбэка. Когда один провайдер недоступен или исчерпал квоту, OmniRoute автоматически переходит к следующему.

Поддерживаемые стратегии балансировки

• priority — строгий приоритет по порядку
• weighted — взвешенное распределение
• round-robin — циклическое чередование
• P2C — Power of Two Choices (учитывает квоту, задержки, ошибки)
• cost-optimized — выбор дешевейшего провайдера
• context-relay — передача контекста между сессиями
• fill-first — заполнение одного провайдера до исчерпания
• least-used — наименее загруженный
• random / strict-random — случайный выбор
• auto / lkgp / context-optimized — адаптивные режимы

Готовые сценарии комбо

Сценарий 1: Максимизация платной подписки

Combo: "maximize-claude"
  1. cc/claude-opus-4-7       (используем подписку полностью)
  2. glm/glm-5.1              (дешёвый бэкап — $0.5/1М)
  3. kr/claude-sonnet-4.5     (бесплатный Kiro как запасной)

Сжатие: standard — экономия 30% токенов = растягиваем квоту
Стоимость: $20 (подписка) + ~$3 (бэкап) = $23/мес

Сценарий 2: Полностью бесплатный стек

Combo: "free-forever"
  1. kr/claude-sonnet-4.5     (Claude 4.5 безлимитно)
  2. if/kimi-k2-thinking      (reasoning-модель безлимитно)
  3. pol/gpt-5                (GPT-5 без ключа)
  4. lc/longcat-flash-lite    (50М токенов/день бэкап)

Сжатие: aggressive — экономия 50%
Стоимость: $0

Сценарий 3: 24/7 без остановок

Combo: "always-on"
  1. cc/claude-opus-4-7       (лучшее качество)
  2. cx/gpt-5.5               (вторая подписка)
  3. glm/glm-5.1              (дешёвый, сбрасывается ежедневно)
  4. minimax/MiniMax-M2.5     (самый дешёвый из платных)
  5. kr/claude-sonnet-4.5     (бесплатный, никогда не падает)

5 уровней фоллбэка = нулевой простой

Сценарий 4: Обход геоблокировки (Россия и другие)

Combo: "unblocked-ai"
  1. kr/claude-sonnet-4.5     (Kiro + прокси)
  2. pol/deepseek-r1          (Pollinations — без геоблока)
  3. groq/llama-3.3-70b       (Groq + прокси)

Прокси: глобальный или per-provider в Settings

Интеграция с Claude Code

Claude Code — один из главных вариантов использования OmniRoute. Вот полная настройка:

# 1. Установить OmniRoute
npm install -g omniroute
omniroute

# 2. В дашборде: подключить провайдеров
# Dashboard → Providers → Connect Kiro (AWS Builder ID)
# Dashboard → Providers → Connect Qoder (Google OAuth)

# 3. Создать API-ключ
# Dashboard → Endpoints → Create API Key

# 4. Настроить Claude Code
claude config set api-base-url http://localhost:20128/v1
claude config set api-key ваш-ключ-из-дашборда

После этого Claude Code будет работать через OmniRoute, получая автоматический фоллбэк между провайдерами и сжатие промптов.

Интеграция с Kiro (AWS Kiro AI)

Kiro — IDE от Amazon (ранее известная как Kiro AI), которая предоставляет бесплатный доступ к Claude Sonnet и Haiku через AWS Builder ID.

Подключение в OmniRoute:

1. Dashboard → Providers → Kiro
2. Нажмите «Connect via AWS Builder ID»
3. Авторизуйтесь на сайте AWS
4. В OmniRoute используйте модели с префиксом kr/

kr/claude-sonnet-4.5  → Claude Sonnet 4.5 бесплатно
kr/claude-haiku-4.5   → Claude Haiku 4.5 бесплатно
kr/claude-opus-4.6    → Claude Opus 4.6 бесплатно

Интеграция с OpenCode

OpenCode (106K звезд) — популярный open-source AI coding агент. Настройка через OmniRoute:

opencode config set base-url http://localhost:20128/v1
opencode config set api-key ваш-ключ

Интеграция с Codex CLI

# Настройка через переменные окружения
export OPENAI_BASE_URL=http://localhost:20128/v1
export OPENAI_API_KEY=ваш-ключ

# Или через конфиг
codex config set base-url http://localhost:20128/v1

OmniRoute поддерживает полный Responses API (/v1/responses), необходимый для Codex.

MCP Server: 37 инструментов для AI-агентов

OmniRoute включает встроенный MCP Server (Model Context Protocol) с 37 инструментами, тремя транспортами и 10 уровнями разрешений.

Запуск MCP

# stdio-транспорт (для Claude Desktop, Continue, Kilo Code)
omniroute --mcp

# Или SSE/HTTP в процессе (уже запущен вместе с основным сервером)

Примеры инструментов

omniroute_get_health       → состояние здоровья сервера
omniroute_list_combos      → список настроенных комбо
omniroute_list_providers   → доступные провайдеры
omniroute_get_analytics    → статистика использования
omniroute_toggle_combo     → включить/выключить комбо

Транспорты

• stdio — для локальных клиентов (Claude Desktop, VS Code Extensions)
• SSE — для веб-клиентов
• HTTP — для REST-интеграций

Аудит выполнения

Все вызовы MCP-инструментов логируются в SQLite с возможностью фильтрации по инструменту, результату и API-ключу — прямо из дашборда.

A2A Protocol: агент-к-агенту

OmniRoute реализует A2A (Agent-to-Agent) Protocol на базе JSON-RPC 2.0 с SSE-стримингом.

# Проверка agent card
curl http://localhost:20128/.well-known/agent.json

# Отправка задачи агенту
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "task-1",
    "method": "message/send",
    "params": {
      "skill": "quota-management",
      "messages": [{
        "role": "user",
        "content": "Дай сводку по текущим квотам провайдеров"
      }]
    }
  }'

# Стриминговая задача
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"message/stream",...}'

Мультиплатформенность

Desktop App (Electron)

npm run electron:build        # текущая платформа
npm run electron:build:win    # Windows (.exe)
npm run electron:build:mac    # macOS (.dmg)
npm run electron:build:linux  # Linux (.AppImage)

Возможности:

• Системный трей с быстрыми действиями
• Автозапуск при входе в систему
• Нативные уведомления
• Оффлайн-режим с локальными моделями

PWA (Progressive Web App)

• Android (Chrome): ⋮ → «Добавить на главный экран»
• iOS (Safari): Поделиться → «На экран Домой»
• Desktop: Иконка установки в адресной строке Chrome/Edge

Docker с HTTPS через Caddy

services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    volumes:
      - omniroute-data:/app/data
    environment:
      - NEXT_PUBLIC_BASE_URL=https://your-domain.com

  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128

Cloudflare Tunnel (публичный доступ без VPS)

В дашборде: Dashboard → Endpoints → Enable Cloudflare Quick Tunnel

OmniRoute автоматически скачает cloudflared, запустит тоннель и покажет URL вида https://*.trycloudflare.com/v1.

Разбивка по стоимости: от $0 до «всё включено»

Важно: Стоимость в аналитике OmniRoute — это не счёт от OmniRoute (он бесплатен), а трекер сэкономленных средств: сколько бы вы потратили, используя платные API напрямую.

Диагностика и отладка

Системный отчёт для bug-репортов

npm run system-info

Создаёт system-info.txt с версией Node.js, версией OmniRoute, деталями ОС, установленными CLI-инструментами, статусом Docker/PM2.

Команды CLI

omniroute                    # Запуск (порт 20128)
omniroute --port 3000        # Другой порт
omniroute --mcp              # MCP-транспорт (stdio)
omniroute --no-open          # Без автооткрытия браузера
omniroute setup              # Мастер настройки
omniroute doctor             # Диагностика
omniroute providers available # Список доступных провайдеров
omniroute providers list     # Подключённые провайдеры
omniroute --help             # Справка

Разделённые порты

PORT=20128 DASHBOARD_PORT=20129 omniroute
# API:       http://localhost:20128/v1
# Дашборд:   http://localhost:20129

Полезно при работе за reverse proxy (Nginx, Caddy) или в контейнерной среде.

Таймауты для длинных стримов

REQUEST_TIMEOUT_MS=600000     # Базовый таймаут (10 минут)
STREAM_IDLE_TIMEOUT_MS=...    # Макс. пауза между чанками

Сравнение с аналогами

Архитектура и технический стек

• Язык: TypeScript (100%)
• Frontend: Next.js (App Router)
• Desktop: Electron
• База данных: SQLite (WAL-режим) через better-sqlite3
• Тесты: Vitest (unit/integration), Playwright (E2E), 4 600+ тестов в 517 файлах
• Протоколы: OpenAI API, Anthropic API, Gemini API, Responses API, MCP (stdio/SSE/HTTP), A2A (JSON-RPC 2.0)
• Безопасность: AES-256-GCM для хранения ключей, CSRF, IP-фильтрация, rate limiting
• Docker: Multi-arch (AMD64 + ARM64), Compose с профилями
• Deployment: npm global, Docker, Electron, AUR, Void Linux, Fly.io, Termux

Структура маршрутизации запроса

Ваш инструмент (Claude Code, Cursor, Codex...)
  │
  │ http://localhost:20128/v1
  ▼
┌─────────────────────────────────────────────┐
│              OmniRoute                      │
│  • Аутентификация API-ключа                 │
│  • Сжатие промпта (RTK+Caveman)             │
│  • Трансляция формата (OpenAI↔Claude↔Gemini)│
│  • Отслеживание квоты                       │
│  • Управление проксированием                │
│  • Circuit breaker + rate limit detection   │
└──────────────────────┬──────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
  [Подписка]      [API-ключ]     [Бесплатно]
  Claude Code     DeepSeek       Kiro (Claude)
  Codex           Groq           Qoder
  Gemini CLI      xAI Grok       Pollinations

Комьюнити и поддержка

• GitHub: github.com/diegosouzapw/OmniRoute
• Issues: github.com/diegosouzapw/OmniRoute/issues
• WhatsApp: Группа сообщества
• Сайт: omniroute.online
• Видеогайд на русском: YouTube

Проект активно развивается: более 2 400 коммитов, 740+ форков и сообщество в WhatsApp. Принимаются pull requests, есть метки good first issue для начинающих контрибьюторов.

Итог: стоит ли использовать OmniRoute?

OmniRoute решает реальные проблемы, с которыми сталкиваются разработчики каждый день:

Подходит, если вы:

• Пользуетесь AI-инструментами (Claude Code, Cursor, Codex, Kiro) и устали от прерываний из-за квот
• Находитесь в регионе с геоблокировкой AI-сервисов
• Хотите использовать AI-ассистентов бесплатно ($0/мес)
• Нужен единый эндпоинт для нескольких инструментов и провайдеров
• Работаете с агентами и нуждаетесь в MCP/A2A протоколах

Минусы:

• Требует локальной установки и первоначальной настройки
• OAuth-подключение некоторых провайдеров может потребовать настройки прокси в регионах с ограничениями
• Часть бесплатных провайдеров (Kiro, Qoder) может изменить условия в будущем

Для большинства разработчиков, работающих с AI-инструментами, OmniRoute — это разумная инвестиция в 10–15 минут установки, которая возвращается многократной экономией токенов, денег и потерянного рабочего времени.