OmniRoute с нуля: бесплатный локальный AI-шлюз для Claude, GPT, Gemini и DeepSeek

Cursor, Claude Code, Codex и Gemini CLI помнят каждый свой адрес и свой секрет. Когда провайдеров становится больше, лимиты и «сегодня 429» расползаются по конфигурациям. OmniRoute собирает это в один OpenAI-совместимый адрес на вашей машине. Клиенты запоминают http://127.0.0.1:20128/v1. Claude, GPT, Gemini, DeepSeek и остальные модели каталога подключаются в панели. Лицензия — MIT. Этот разбор следует ветке release/v3.8.53. Порты, команды и маршрутизация взяты из того README. Число провайдеров меняется от версии к версии.

«Бесплатно» значит, что за программу шлюза не берут лицензионную плату. Квота живёт на аккаунтах провайдеров, которые вы подключаете. Проект показывает на /dashboard/free-tiers оценку чужих бесплатных уровней и прямо пишет: это сумма, а не грант токенов от OmniRoute. Подписки, которые вы уже оплачиваете, могут идти через тот же адрес своим сценарием аккаунта. Прайсы сравнивайте со счётом за инструменты для кода и с ценами OpenRouter. OpenRouter — размещённый маршрутизатор. OmniRoute — шлюз на вашей машине.

Где стоит шлюз

Это розетка, которая работает только на вашей машине. Выше по потоку по-прежнему OpenAI, Anthropic, Google, DeepSeek или другой провайдер каталога. Ниже — любой клиент, который говорит на OpenAI Chat Completions или Responses. Документация v3.8.53 называет около 375 провайдеров и около 1475 сырых идентификаторов моделей; у части есть пометка бесплатного уровня. Цифры пересматривают: смотрите живой каталог панели, а не старый снимок экрана.

• Ключей два.API-ключ провайдера или сессия OAuth остаётся внутри OmniRoute. Cursor и скрипты берут ключ шлюза из Dashboard → Endpoints.
• Имена моделей имеют смысл после подключения.Сначала вызовите /v1/models. Примеры в README выглядят как openai/gpt-5.4 и glm/glm-5.2. Берите идентификатор, который реально вернул ваш список.
• Список клиентов широкий.Названы Claude Code, Codex, Cursor, Cline, Continue, OpenCode, Copilot, OpenClaw и другие. У кого настраивается OpenAI Base URL, тому достаточно адреса. omniroute run запускает семь CLI.

Установка с нуля: npm и Docker

На машине нужен Node.js. Короткий путь:

npm install -g omniroute
omniroute

npm warn ERESOLVE и предупреждения peer-зависимостей документация разрешает сначала не трогать. Панель открывается на http://127.0.0.1:20128, API — на http://127.0.0.1:20128/v1. Прокси без панели: omniroute serve --headless или OMNIROUTE_HEADLESS=1.

npm 11 должен разрешить скрипты установки

npm 11 может блокировать скрипты жизненного цикла пакета. postinstall OmniRoute должен отработать, иначе не подготовятся нативные файлы среды. Список для 3.8.53 такой:

npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute

Если npm называет другие пакеты, берите имена из того предупреждения. Разрешение означает, что установочные скрипты этих пакетов выполнятся — делайте это после проверки источника. В CI или на медленной машине OMNIROUTE_SKIP_POSTINSTALL=1 пропускает только прогрев нативного SQLite. Копирование бинарников всё равно идёт.

Память Docker под агента для кода

Имя образа в документации по-прежнему diegosouzapw/omniroute. :latest следует высшей опубликованной стабильной SemVer и не следует git main. Для постоянной установки зафиксируйте версию. Опубликованный пример слушает loopback:

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

У образа heap по умолчанию 1024 МБ — хватает на панель и короткий диалог. Claude Code и Codex ходят в POST /v1/responses. Длинным контекстам нужен больший heap V8, иначе процесс падает с фатальной нехваткой памяти. Один агент для кода — это heap 8192 и контейнер не меньше 10 ГБ в команде выше. Два длинных запроса одновременно — heap 10240–12288 и контейнер 12–16 ГБ. Apple Silicon берёт сборку arm64. В томе omniroute-data лежат секреты. Резервную копию и удаление делайте как для конфиденциальных данных.

Подключить Claude, GPT, Gemini и DeepSeek

Откройте Providers, выберите того, кем вам можно пользоваться, вставьте API-ключ или завершите сценарий аккаунта. Четыре лаборатории выдают ключи в своих консолях. OmniRoute счета за вас не открывает:

Бесплатные уровни — отдельный список, а не другое имя этих четырёх ключей. Мастер первого запуска может предложить настроить бесплатных провайдеров. Он строит список из текущего каталога без входа и создаёт подключение только после вашего подтверждения каждого пункта. В каталоге встречались Pollinations, Cloudflare AI и бесплатный уровень DeepSeek у SiliconFlow. Условия, регион и то, жив ли уровень, решает сам провайдер. Старый текст про «Claude без ключа» не попадёт в auto, если провайдер помечен tos: avoid. Перед использованием откройте Free Tiers и прочитайте условия этого дня.

Провайдерам на веб-cookie, например Gemini Web, нужен ещё браузерный рантайм. В npm-пакете есть Playwright, но нет бинарника Chromium. До первого вызова пройдите заметку про Playwright Chromium в репозитории, иначе запрос упадёт на слое браузера.

Один адрес для IDE и CLI

Скопируйте ключ шлюза в Endpoints. Затем:

Base URL: http://127.0.0.1:20128/v1
API Key:  (Dashboard → Endpoints)
Model:    auto

Сначала проверьте список моделей, потом давайте IDE говорить:

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

curl http://127.0.0.1:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Cursor, Cline, Continue и любой плагин с настраиваемым OpenAI Base URL принимают эти три строки. Клиентам, которые не умеют слать свой заголовок, подойдёт адрес совместимости с токеном, например http://127.0.0.1:20128/vscode/YOUR_KEY/chat/completions. Если заголовок отправить можно, предпочтителен Authorization: Bearer.

Править конфиг каждого CLI руками не обязательно. Запуск одной командой кладёт учётные данные в этот процесс. Qwen и Gemini получают ещё одноразовый изолированный home:

omniroute run claude --model auto
omniroute run codex  --model auto
omniroute run gemini --model auto
omniroute configure codex

omniroute run покрывает Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code и Gemini CLI. configure записывает провайдера и модель в собственный конфиг инструмента. В документации названы codex, claude, opencode, qwen, aider, goose, gemini, cline, continue и kilo. --dry-run только печатает окружение и аргументы. --api-key-env NAME оставляет секрет в имени переменной окружения и не кладёт его в историю оболочки.

auto, запасной путь и кто в него не входит

auto выбирает среди подключений, которые уже соединены и подходят. Свежая установка без единого провайдера может не иметь цели. Так и задумано. Стратегия, провайдер и задержка возвращаются в заголовке X-OmniRoute-Decision. Смотрите его раньше журнала клиента.

• Запасной путь с оглядкой на квоту.Когда одно подключение исчерпано, планировщик может перейти на другое, где запас ещё есть. В v3.8.53 есть стратегия с весом по остатку квоты; один разговор она старается держать на том же подключении.
• Маршрут подписки может остановиться, а не перелиться.Документированная связка subscription тратит только квоту подписки, которую вы уже оплачиваете. Когда она кончилась, запрос останавливается и не уходит на другой ключ, который выставит счёт. Не кладите платные API-ключи и ключи подписки в одну связку «падай куда угодно».
• tos: avoid по умолчанию снаружи.Успешное подключение не означает членство в auto. Чтобы закрепить ключ шлюза за одной моделью, задайте у этого ключа forcedModel, а не прошивайте в клиенте адрес провайдера.

Сжатие — необязательный конвейер, для клиента прозрачный. Документация описывает его как набор сочетаемых движков. Какой набор реально сработал, написано в заголовке ответа X-OmniRoute-Compression. Сколько сэкономится, зависит от модели и запроса. Диапазон в README — заявление проекта, а не обещание на каждый вызов. Память по умолчанию выключена. Маскирование учётных данных включается отдельно.

На Cloud Mac: loopback и SSH

Шлюзу подходит Mac, который не выключают: слушать 20128 на loopback, а на ноутбук забирать порт по SSH. У Cloud Mac фиксированный регион и есть SSH; Apple Silicon запускает официальный образ arm64. Не привязывайте панель к 0.0.0.0.

ssh -N -L 20128:127.0.0.1:20128 user@your-cloud-mac

Когда туннель поднят, Cursor или omniroute run на ноутбуке по-прежнему указывают http://127.0.0.1:20128/v1. С виду это локальный адрес. Байты приходят на loopback облачного Mac. Секреты провайдеров остаются в облачном томе или в каталоге пользователя, не в Git. Если на той же машине уже работает OpenClaw, направьте его адрес модели на тот же /v1 и оставьте одну копию ключей провайдеров в шлюзе.

Если панели нужен вход, в документации есть необязательный OIDC. Вход по паролю остаётся. Для удалённого управления есть токены с ограниченной областью (connect, contexts, tokens) в Remote Mode. Идите этим путём. Не вывешивайте панель на публичный IP, чтобы сэкономить шаг.

Что проверить, если встало

1. /v1/models пуст.Подключение в Providers не удалось, или клиент подставил ключ провайдера туда, где нужен ключ шлюза.
2. auto говорит, что маршрута нет.Подключены только исключённые провайдеры, или бесплатный уровень сегодня недоступен. Возьмите платный ключ, который точно работает, или конкретный идентификатор из /v1/models.
3. После глобальной установки не находится нативный модуль.Поставьте заново с --allow-scripts npm 11 и именами пакетов из того предупреждения.
4. Агент для кода в Docker обрывается на середине.Поднимите OMNIROUTE_MEMORY_MB и --memory до уровня агента. 1024 МБ оставьте панели.
5. Первый запрос веб-провайдера падает.Поставьте Chromium для Playwright и повторите. Политику маршрута меняйте после успеха.
6. Цифры устарели.375 провайдеров и 1475 идентификаторов моделей — цифры документации v3.8.53 на тот момент. После обновления смотрите панель и README.

FAQ

Коротко: программа бесплатна, квота у провайдера; адрес — /v1 на локальном порту 20128; auto ходит только по подходящим подключениям; агентам для кода в Docker нужно больше памяти; порт оставьте на loopback и пробросьте его по SSH. Полные вопросы и ответы лежат в структурированных данных FAQ в начале страницы.