Как развернуть собственный маршрутизатор AI-моделей с помощью 9router

9router — это маршрутизирующий прокси с открытым исходным кодом под лицензией MIT. Он работает на вашем компьютере или сервере и объединяет всех подключённых AI-провайдеров за единым OpenAI-совместимым эндпоинтом http://localhost:20128/v1.

Если вы работаете с Claude Code в одном терминале, с Cline в редакторе и с OpenAI SDK в стороннем проекте, у вас, скорее всего, три набора ключей и три базовых URL, а при каждой смене модели приходится отдельно перенастраивать каждый инструмент. 9router заменяет всё это одним локальным эндпоинтом. В этом руководстве мы установим его через npm или Docker, проверим работу с помощью curl, подключим к нему инструменты и защитим его, прежде чем открывать доступ извне localhost.

Что такое 9router?

9router — это self-hosted прокси, который принимает запросы в формате OpenAI, направляет их настроенному вышестоящему провайдеру и при необходимости преобразует запросы между форматами OpenAI, Claude и Gemini. Согласно README проекта, поддерживается более 40 провайдеров, а CLI распространяется в виде npm-пакета 9router.

Главное отличие 9router от OpenRouter — в том, где работает маршрутизатор. OpenRouter — это облачный сервис, которому вы отправляете запросы. 9router — это ПО, которое вы запускаете самостоятельно. При этом OpenRouter входит в список его провайдеров, так что аккаунт OpenRouter можно подключить к собственному маршрутизатору.

Зачем нужен self-hosted маршрутизатор моделей

Локальный маршрутизатор предоставляет всем инструментам один и тот же эндпоинт и хранит учётные данные провайдеров в одном месте. Благодаря этому модели можно менять, не трогая конфигурацию инструментов и код приложений.

• Один эндпоинт. Все OpenAI-совместимые клиенты используют один и тот же базовый URL.
• Ключи в одном месте. Аккаунты провайдеров добавляются один раз — в дашборде. Каждому инструменту нужен только API-ключ 9router.
• Переключение моделей одной строкой. Чтобы сменить модель, достаточно изменить значение model — и больше ничего.
• Комбо. Комбо — это именованный упорядоченный список моделей, который используется вместо имени модели. Когда у первой модели заканчивается квота, срабатывает rate limit (429) или возникает ошибка, маршрутизатор пробует следующую.

Обычно на первое место ставят предпочтительную модель, а за ней — более дешёвые. Чтобы сравнить стоимость токенов перед выбором резервных моделей, воспользуйтесь калькулятором стоимости LLM API.

Как установить и запустить 9router

9router устанавливается как глобальный npm CLI командой npm install -g 9router и запускается командой 9router. Сервер слушает порт 20128.

npm install -g 9router
9router
# Dashboard: http://localhost:20128
# API:       http://localhost:20128/v1

Если глобальная установка не нужна, выполните разовый запуск через npx 9router.

Для запуска в Docker используйте официальный образ decolua/9router, который также опубликован как ghcr.io/decolua/9router:

docker run -d --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD='change-me' \
  decolua/9router:latest

Подключённый том сохраняет базу данных SQLite (/app/data/db/data.sqlite внутри контейнера) при перезапуске контейнера. Новые релизы выходят часто, и тег latest обновляется вместе с ними, поэтому для воспроизводимых развёртываний закрепляйте конкретный тег версии.

После запуска 9router завершите настройку в дашборде:

1. Откройте http://localhost:20128 и войдите в дашборд.
2. Добавьте хотя бы один аккаунт провайдера.
3. Создайте API-ключ для своих инструментов.

Проверка маршрутизатора с помощью curl

Быстрее всего проверить работу 9router можно GET-запросом к /v1/models — ещё до настройки каких-либо инструментов. В ответ вернётся JSON-список всех моделей и комбо, которые может обслуживать маршрутизатор, в стандартном для OpenAI формате.

curl http://localhost:20128/v1/models

Список моделей возвращается без ключа. С chat-запросами иначе: настройка «Require API key» в дашборде по умолчанию включена, поэтому для них нужен ключ из дашборда. Передавать ключ и при запросе списка моделей — тоже хорошая привычка: ключ, ограниченный определёнными моделями, видит только их.

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

Если в списке есть ID модели вашего провайдера, маршрутизация работает. Если список пуст, провайдер ещё не подключён.

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

9router может использовать любой клиент, позволяющий указать собственный базовый URL OpenAI. Укажите базовый URL http://localhost:20128/v1 и API-ключ, созданный в дашборде.

OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:20128/v1",
  apiKey: process.env.NINE_ROUTER_API_KEY, // created in the 9router dashboard
});

const res = await client.chat.completions.create({
  model: "<an id or combo name from /v1/models>",
  messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);

Чтобы переключиться на другую модель или комбо, измените строку model. Остальной код остаётся без изменений.

Агенты для программирования

В Cline выберите OpenAI Compatible в качестве API-провайдера и заполните три поля: базовый URL http://localhost:20128/v1, API-ключ из дашборда и ID модели, скопированный из /v1/models. Терминальные агенты, позволяющие подключать собственного провайдера, — например, OpenCode, — принимают те же три значения.

Pi с расширением pi-9router-ext

Расширение pi-9router-ext подключает агента для программирования Pi к 9router через две переменные окружения:

pi install npm:pi-9router-ext
NINE_ROUTER_BASE_URL=http://localhost:20128 NINE_ROUTER_API_KEY=<key> pi
# inside Pi:
/9router-models

При запуске расширение считывает chat-модели из /v1/models. Начиная с релиза 0.2.4 оно также опрашивает /v1/models/web, чтобы обнаружить маршруты 9router для веб-поиска и загрузки страниц. Выполните /9router-models внутри Pi, чтобы увидеть, что было найдено.

Как защитить 9router перед открытием доступа?

Прежде чем 9router станет доступен с другой машины, задайте пароль дашборда, секреты для JWT и API-ключей и не отключайте «Require API key». Значения по умолчанию приемлемы для localhost, но не за его пределами. Если INITIAL_PASSWORD не задан, для первого входа в дашборд используется 123456, пока не будет сохранён другой пароль. Задайте эти значения по образцу официального .env.example, прежде чем открывать порт или развёртывать маршрутизатор на публичном хосте:

INITIAL_PASSWORD=<long-random-string>   # first login otherwise uses 123456
JWT_SECRET=<long-random-string>         # listed under "Required" in .env.example
API_KEY_SECRET=<long-random-string>     # the example default is publicly known
AUTH_COOKIE_SECURE=true                 # set when serving behind an HTTPS reverse proxy

Сама проверка API-ключа — это настройка дашборда. Откройте страницу Endpoint и убедитесь, что параметр Require API key включён: тогда запросы без действительного ключа будут отклоняться. По умолчанию он включён, а если эндпоинт доступен с удалённого хоста без него, дашборд выводит предупреждение.

Устанавливайте AUTH_COOKIE_SECURE=true только в том случае, если TLS терминируется перед 9router. При работе по обычному HTTP браузер не будет отправлять обратно cookie аутентификации.

Заключение

Self-hosted маршрутизатор вроде 9router даёт всем вашим инструментам один эндпоинт и один набор учётных данных, а смена модели сводится к изменению строки model. Установите его, убедитесь, что /v1/models возвращает модели вашего провайдера, а затем подключите один из инструментов к http://localhost:20128/v1. Прежде чем маршрутизатор станет доступен за пределами localhost, задайте пароль и секреты и не отключайте «Require API key».

Часто задаваемые вопросы

Как запустить 9router на порту, отличном от 20128?

Чтобы использовать другой порт, запустите npm CLI командой 9router --port 8080. При запуске из исходного кода задайте переменную окружения PORT, а также NEXT_PUBLIC_BASE_URL, указывающую на тот же порт. В Docker измените порт хоста в пробросе портов, например -p 8080:20128. После этого во всех инструментах нужно указать новый базовый URL, например http://localhost:8080/v1.

Где 9router хранит конфигурацию и данные?

9router хранит данные в каталоге, заданном переменной DATA_DIR (по умолчанию ~/.9router), а базу данных SQLite — в файле db/data.sqlite внутри этого каталога. Если JWT_SECRET не задан, там же сохраняется автоматически сгенерированный секрет для подписи — в ~/.9router/jwt-secret. Официальный Docker-образ устанавливает DATA_DIR в /app/data, поэтому для сохранения всех данных достаточно подключить том к /app/data.

Как подключить инструменты на другой машине к удалённому серверу 9router?

Выполните на клиентской машине команду npx 9router connect http://server-host:20128. Эта команда не запускает локальный сервер. Она выполняет вход с паролем дашборда, использует существующий или создаёт новый API-ключ с именем cli-, за которым следует имя хоста, и записывает конфигурацию каждого выбранного инструмента. Исходная конфигурация каждого инструмента однократно сохраняется в резервную копию с суффиксом .bak-9router. Чтобы сразу выбрать инструменты, используйте --tools claude,codex, а чтобы откатить изменения — --reset.

Может ли 9router использовать несколько аккаунтов одного провайдера?

Да. 9router поддерживает несколько аккаунтов для одного провайдера и распределяет между ними запросы по принципу round-robin или с учётом приоритетов. Когда один аккаунт исчерпывает квоту, маршрутизатор переключается на следующий. Это не то же самое, что комбо: при ротации аккаунтов модель остаётся прежней, а меняются стоящие за ней учётные данные, тогда как комбо переключает на другую модель.