Установка OmniRoute: быстрый старт и Claude Code

OmniRoute — это AI-шлюз, совместимый с OpenAI API. Он собирает множество провайдеров моделей за одним локальным API, поэтому Claude Code, Codex CLI, расширения для IDE и ваши скрипты настраиваются один раз. Эта страница — кратчайший путь от установки до первого успешного запроса; полные тематические руководства находятся на отдельном сайте.

Запомните два адреса

• Панель управления: http://localhost:20128
• Base URL, совместимый с OpenAI: http://localhost:20128/v1

В клиентах указывается второй адрес, а не адрес панели.

Требования

• Node.js >=22.22.2 <23 или >=24.0.0 <27; рекомендуется Node.js 24 LTS. Вне этого диапазона панель может показывать пустую страницу или ошибки нативных модулей. При необходимости сначала установите Node.js.
• Локальный порт 20128 свободен.
• Хотя бы один аккаунт или ключ апстрим-провайдера, который вы собираетесь маршрутизировать через OmniRoute.

Установка и запуск

Выберите один способ:

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

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

Также можно скачать установщик Desktop для Windows, macOS или Linux на странице OmniRoute GitHub Releases. Тег :latest указывает на последний опубликованный стабильный релиз; для воспроизводимых развёртываний фиксируйте точную версию.

После запуска откройте http://localhost:20128. Пароль для входа задаётся переменной окружения INITIAL_PASSWORD; в самохостинг-конфигурации апстрима он генерируется при первом запуске и выводится в логи, а в Docker его можно найти командой docker logs omniroute | grep -i password. Прежде чем открывать сервис в сеть, задайте собственный надёжный пароль.

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

1. В панели откройте Providers → Add Provider и подключите своего провайдера.
2. На странице API Keys создайте новый ключ и сохраните его: он показывается только один раз. Этот ключ нужен клиентам для доступа к OmniRoute, а не является ключом апстрим-провайдера.

В документации апстрима перечислены бесплатные провайдеры, которым ключ не нужен. Их доступность и условия меняются, поэтому перед использованием проверьте условия соответствующего сервиса.

Проверка работы

export OMNIROUTE_API_KEY="вставьте ключ, созданный на странице API Keys"

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

Если вернулся список моделей, значит, совместимая с OpenAI конечная точка и аутентификация работают. Затем отправьте минимальный запрос в чат, чтобы убедиться, что модель действительно маршрутизируется:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto позволяет OmniRoute выбирать провайдера по скорости, стоимости и доступности. Можно указать и конкретный идентификатор модели из ответа /v1/models.

Подключение инструментов

В любом инструменте, работающем с форматом OpenAI, укажите:

Base URL: http://localhost:20128/v1
API Key:  созданный вами ключ OmniRoute
Model:    auto

В OmniRoute есть и команды запуска в одну строку, например omniroute launch-codex --model auto; общая форма omniroute run <target> поддерживает claude, codex, aider, goose, opencode, qwen и gemini. Если вы хотите использовать Agent CLI в HagiCode, сначала настройте его по странице Установка AI Agent CLI.

Частые проблемы

• Пустая панель или предупреждение о неподдерживаемой версии Node.js: перейдите на Node.js 24 LTS, снова выполните npm install -g omniroute, затем omniroute.
• better-sqlite3 не найден в npm 11: npm 11 по умолчанию блокирует скрипты установки необязательных зависимостей; пересоберите модуль вручную по руководству по устранению неполадок.
• slice is not valid mach-o file на macOS: выполните npm rebuild better-sqlite3 в каталоге $(npm root -g)/omniroute/app и запустите снова.

Полная документация

Документация OmniRoute на русском языке

• Быстрый старт: OmniRoute за 3 минуты
• Настройка OmniRoute для Claude Code
• Развёртывание OmniRoute в Docker
• Настройка OmniRoute для Codex CLI
• Устранение неполадок