Omniroute Guide

OmniRoute — Полная справка (RU)

OmniRoute — локальный AI-шлюз и dashboard на Next.js 16. Один OpenAI-совместимый endpoint (/v1/*) маршрутизирует запросы через 237 провайдеров с переводом форматов, fallback, OAuth/API-key управлением, usage tracking, MCP (94 tools) и A2A v0.3.

Версия в репозитории: 3.8.44 · Порт по умолчанию: 20128 · Runtime: Node.js >=22.0.0 <23 || >=24.0.0 <27

Структура репозитория

OmniRoute/
├── src/                    # Next.js App Router (dashboard + /api/*)
│   ├── app/api/v1/         # OpenAI-совместимые API routes
│   ├── app/(dashboard)/    # Dashboard UI
│   ├── lib/db/             # SQLite domain modules (95 файлов)
│   ├── server/authz/       # Authorization pipeline
│   └── sse/                # SSE handlers (обёртка open-sse)
├── open-sse/               # Streaming engine (executors, translators, MCP)
│   ├── handlers/           # chatCore, embeddings, search, ...
│   ├── executors/          # Provider-specific HTTP dispatch
│   ├── services/           # combo, compression, rate limits, ...
│   └── mcp-server/         # 94 MCP tools, 3 transports
├── bin/omniroute.mjs       # CLI entry point
├── electron/               # Desktop app
└── docs/                   # Официальная документация

Ключевые возможности

Навигация по справке

Быстрый старт

Установка

# npm (рекомендуется)
npm install -g omniroute
omniroute

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

# Из исходников
git clone https://github.com/diegosouzapw/OmniRoute.git && cd OmniRoute
npm install && npm run dev

Dashboard: http://localhost:20128

Первичная настройка секретов

cp .env.example .env
# Обязательно сгенерировать:
openssl rand -base64 48   # JWT_SECRET
openssl rand -hex 32      # API_KEY_SECRET

INITIAL_PASSWORD — пароль первого входа в dashboard (сменить после login).

Подключение бесплатного провайдера

Dashboard → Providers → Add Provider → Kiro AI / OpenCode Free / Pollinations → Connect (без API key).

Подключение IDE/CLI

Base URL: http://localhost:20128/v1
API Key:  [Dashboard → Endpoints → скопировать ключ]
Model:    auto

Проверка:

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

Автонастройка CLI

omniroute setup-claude
omniroute setup-codex
omniroute setup-opencode --remote http://VPS:20128 --api-key sk-...
omniroute launch          # Claude Code с env
omniroute launch-codex    # Codex CLI

Request Pipeline (кратко)

Client → /v1/chat/completions
  → CORS → Zod validation → auth? → policy → prompt injection guard
  → handleChatCore()
    → cache → rate limit → combo routing?
      → resolveComboTargets() → handleSingleModel() per target
    → translateRequest() → getExecutor() → fetch upstream
    → response translation → SSE или JSON

Подробнее: references/architecture.md

Auth (два режима)

Классы маршрутов: PUBLIC → CLIENT_API → MANAGEMENT (fail-closed).

API key с scope manage — доступ к management API и remote MCP bypass.

MCP — быстрое подключение

stdio (Cursor, Cline)

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"],
      "env": {
        "OMNIROUTE_API_KEY": "sk-..."
      }
    }
  }
}

HTTP Streamable (Claude Code)

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

Включить MCP: Dashboard → Endpoints → MCP toggle + выбрать transport (sse или streamable-http).

Remote access: Bearer key со scope manage — единственный способ к /api/mcp/* с non-loopback.

Полная справка: references/mcp.md

A2A — быстрое подключение

# Agent Card
curl http://localhost:20128/.well-known/agent.json

# Задача
curl -X POST http://localhost:20128/a2a \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"skill":"smart-routing","messages":[{"role":"user","content":"Hello"}]}}'

Включить: Dashboard → Endpoints → A2A toggle.

Skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report, list-capabilities.

Auto-Combo (model: auto)

При падении провайдера — автоматический fallback на следующий в combo.

Resilience — 3 слоя (не путать!)

Отладка: /dashboard/health, omniroute_get_health (MCP), GET /api/monitoring/health.

Важные env-переменные

Полный список: references/config.md (синхронизирован с .env.example).

CLI команды

omniroute                    # Запуск сервера
omniroute --mcp              # MCP stdio transport
omniroute --port 3000        # Другой порт
omniroute --no-open          # Без автооткрытия браузера
omniroute doctor             # Диагностика
omniroute setup --non-interactive --password "$PASS"
omniroute provider list      # Список провайдеров

Security Guardrails (для агента)

• PII redaction — opt-in (PII_REDACTION_ENABLED, PII_RESPONSE_SANITIZATION = false по умолчанию). Не включать без явного запроса оператора.
• Error sanitization — ответы через buildErrorBody() / sanitizeErrorMessage(), никогда raw stack.
• LOCAL_ONLY routes — /api/mcp/, /api/services/, /api/cli-tools/runtime/ только loopback (или manage scope для MCP).
• Public upstream OAuth creds — только через resolvePublicCred(), не string literals.

Официальная документация (source of truth)

При расхождении со skill — верить репозиторию:

Workflow для агента

1. Вопрос "как подключить X" → references/cli-tools.md или references/mcp.md
2. Ошибка маршрутизации → references/resilience.md + references/routing.md
3. Настройка env/deploy → references/config.md
4. API интеграция → references/api.md
5. Dashboard "где найти" → references/dashboard.md
6. Не работает → references/troubleshooting.md + omniroute doctor

Перед утверждением фактов о коде — grep по src/, open-sse/, bin/. Если 0 hits — не документировать.