Настройка OmniRoute для Cursor в 2026: общий шлюз

Строка http://localhost:20128/v1 вставлена и в Cursor, и в Claude Code, но один клиент отвечает ошибкой, а второй не видит модели.

Быстрое решение: используйте один экземпляр OmniRoute, но разные правила адресации — Claude Code получает корневой URL без /v1, а Cursor настраивается отдельно для Desktop, CLI или MCP.

Кому нужен этот разбор

Материал рассчитан на разработчиков, которые одновременно используют Cursor и Claude Code и хотят поддерживать одну систему ключей, моделей и правил отказоустойчивости.

Он также пригодится инженерам, запускающим AI Gateway на удалённом Mac, и техническим руководителям, которым нужны разделение доступа, повторяемая проверка fallback и понятные критерии приёмки.

Важно: общий шлюз — это единая точка маршрутизации. Это не означает, что каждый клиент должен получить одинаковый endpoint. Протокол запроса определяет сам клиент.

Последняя проверка документации: 12 августа 2026 года. Команды и параметры сверены с актуальными материалами OmniRoute, Cursor и Anthropic; перед внедрением проверьте текущую ветку и release проекта.

Один экземпляр — два разных входа

Типичная ошибка выглядит логично:

Cursor       → http://localhost:20128/v1
Claude Code  → http://localhost:20128/v1
OmniRoute    → провайдеры моделей

Проблема в том, что Cursor и Claude Code не обязательно используют один и тот же формат API. OmniRoute действительно может выступать общей точкой маршрутизации, но клиент формирует конечный путь самостоятельно.

Рабочая схема для Claude Code выглядит так:

Claude Code
  → ANTHROPIC_BASE_URL=http://localhost:20128
  → /v1/messages
  → OmniRoute
  → выбранный provider

Для OpenAI-совместимого клиента путь обычно выглядит иначе:

Cursor CLI или совместимый клиент
  → http://localhost:20128/v1
  → OmniRoute OpenAI-compatible API
  → модель или fallback-цепочка

Именно поэтому строку с /v1 нельзя механически переносить в ANTHROPIC_BASE_URL. Claude Code сам формирует путь к Messages API после получения базового адреса шлюза. Это соответствует описанию в конфигурации Claude Code для OmniRoute и официальной документации Anthropic о подключении через LLM Gateway.

У этой ошибки есть несколько скрытых причин:

• Неверный путь API. Клиент добавляет собственный суффикс, и итоговый маршрут становится несовместимым.
• Разный способ авторизации. Claude Code использует переменные Anthropic, а Cursor CLI — собственные параметры входа и ключ.
• Разные каталоги моделей. Наличие модели в /v1/models не означает, что она будет показана во встроенном выборе Claude Code или Cursor.
• Разные границы функций. Cursor Desktop может продолжать использовать встроенные модели для отдельных возможностей, даже если пользовательский API-ключ успешно проверен.
• Разный момент чтения переменных. Изменение переменной в уже открытом процессе не перенастраивает работающий клиент.

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

Минимальный запуск OmniRoute без лишней диагностики

Для первого теста не начинайте с удалённого доступа, reverse proxy и командной интеграции. Сначала добейтесь рабочего цикла на одной машине.

Шаг 1. Установите и запустите шлюз

Официальный quick start OmniRoute предлагает установку через npm или запуск контейнера. Для локальной проверки можно использовать установленный CLI:

npm install -g omniroute
omniroute

Вариант с Docker:

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  -p 20128:20128 \
  diegosouzapw/omniroute:latest

Команды установки и порт сверяйте с текущим release проекта в руководстве по быстрому запуску OmniRoute.

Шаг 2. Создайте отдельный ключ для клиентов

Не подставляйте в Cursor или Claude Code административный пароль от панели. Создайте inference API key с минимально необходимыми правами.

Для команды удобно выпускать отдельные ключи:

developer-a-cursor
developer-a-claude
ci-agent

Так вы сможете отключить один доступ, не останавливая весь шлюз. На удалённом Mac это особенно важно: общий ключ в shell-профиле быстро становится неконтролируемым секретом.

Шаг 3. Проверьте здоровье сервиса

Начните с HTTP-доступности:

curl -i http://localhost:20128/

Затем запросите каталог моделей:

curl -s \
  -H "Authorization: Bearer <OMNIROUTE_API_KEY>" \
  http://localhost:20128/v1/models

В ответе должен прийти JSON, а не HTML панели. Если открывается только Dashboard, это подтверждает доступность интерфейса, но не готовность inference API.

Шаг 4. Выполните минимальный запрос

Используйте модель из реально возвращённого каталога:

curl -s http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <OMNIROUTE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID_FROM_CATALOG>",
    "messages": [
      {"role": "user", "content": "Ответьте одним словом: готово"}
    ]
  }'

Если этот запрос не проходит, рано настраивать клиентов. Сначала проверьте provider, upstream-ключ, выбранный combo и журнал OmniRoute.

Шаг 5. Отделите локальный и удалённый режим

localhost подходит только тогда, когда шлюз и клиент работают на одной машине. Если OmniRoute размещён на удалённом Mac, на ноутбуке разработчика нужно использовать доступный по сети адрес:

http://mac-gateway.internal:20128

или защищённый адрес через VPN. Не публикуйте порт шлюза в открытый интернет без ограничения источников, TLS и ключевой авторизации.

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

В документации OmniRoute команды setup-* поддерживают подключение к удалённому серверу через --remote и --api-key. Это позволяет оставить конфигурацию клиента локально, а сам шлюз держать на другой машине. Общая матрица интеграций приведена в CLI-документации OmniRoute.

Claude Code: корневой endpoint вместо /v1

Для Claude Code основная настройка должна идти первой. Она проще проверяется и яснее показывает, работает ли Anthropic-совместимый вход OmniRoute.

Основной путь — запуск через OmniRoute

Если CLI установлен и сервер уже доступен:

omniroute launch \
  --remote http://<REMOTE_MAC_HOST>:20128 \
  --api-key <OMNIROUTE_API_KEY>

Для локального экземпляра достаточно:

omniroute launch

Эта команда запускает Claude Code с необходимыми переменными окружения. Такой вариант безопаснее ручного копирования ключа в постоянный файл настроек.

Если вы предпочитаете ручной запуск, используйте:

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<OMNIROUTE_API_KEY>"
export ANTHROPIC_MODEL="<MODEL_ID_FROM_CATALOG>"

claude

Критически важно:

Правильно:   http://localhost:20128
Неправильно: http://localhost:20128/v1

ANTHROPIC_AUTH_TOKEN используется для передачи токена шлюзу. В некоторых сценариях применяется ANTHROPIC_API_KEY; конкретный вариант должен соответствовать настройкам OmniRoute и способу проверки ключа.

Перезапустите Claude Code после изменения переменных:

exit
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<OMNIROUTE_API_KEY>"
claude

Если шлюз «игнорируется», проверьте три пункта:

1. В окружении процесса действительно есть ANTHROPIC_BASE_URL.
2. В адресе нет /v1.
3. Запущен новый процесс claude, а не старое окно терминала или ранее открытая сессия.

Почему список моделей может быть неполным

Каталог Claude Code не обязан отображать все модели, которые OmniRoute возвращает через /v1/models. Встроенное обнаружение может фильтровать модели по идентификаторам Claude или Anthropic.

Для нестандартной модели используйте явное значение:

export ANTHROPIC_MODEL="<EXACT_MODEL_ID>"
claude

Или создайте профиль через команду настройки:

omniroute setup-claude \
  --remote http://<REMOTE_MAC_HOST>:20128 \
  --api-key <OMNIROUTE_API_KEY>

omniroute launch --profile <PROFILE_NAME>

Не приписывайте нестандартной модели свойства оригинальной модели без отдельной проверки. Совместимость зависит от формата запроса, поддержки инструментов, потоковой передачи и ограничений конкретного upstream-провайдера.

Опыт эксплуатации: пустой список моделей и ошибка авторизации — разные неисправности. Сначала смотрите HTTP-ответ /v1/models, затем переменные окружения, и только после этого проверяйте фильтры модели.

Cursor Desktop, Cursor CLI и MCP — три разные интеграции

Cursor Desktop

В Cursor Desktop путь обычно настраивается через параметры моделей и API-ключей. Но это не универсальная замена основного backend для всех функций редактора.

Пользовательский ключ подходит для стандартной чат-модели. Специализированные функции могут использовать встроенные модели Cursor. Поэтому проверка «Verify» доказывает только валидность ключа для выбранного типа запроса.

Команда OmniRoute setup-cursor не записывает готовый конфигурационный файл. Она выводит шаги для ручной настройки, поскольку конфигурация Cursor Desktop хранится во внутреннем формате. Это отражено в таблице CLI-интеграций OmniRoute.

Практический порядок проверки:

1. Выберите стандартную чат-модель.
2. Укажите API-ключ OmniRoute.
3. Используйте endpoint, который принимает именно это поле Cursor.
4. Нажмите Verify.
5. Отправьте короткий запрос.
6. Проверьте журнал OmniRoute, а не только интерфейс Cursor.

Если Verify проходит, но Tab Completion не меняется, это не обязательно ошибка шлюза. Сначала выясните, относится ли функция к стандартному чату или к встроенной возможности Cursor.

Cursor CLI

Cursor CLI — отдельный клиент. Для него предусмотрены собственные параметры входа и endpoint. Минимальная проверка может выглядеть так:

export CURSOR_API_KEY="<OMNIRoute_API_KEY>"

cursor-agent \
  --endpoint http://localhost:20128/v1 \
  --model "<MODEL_ID_FROM_CATALOG>" \
  "Проверьте структуру проекта и назовите главный риск"

Точный синтаксис и доступные флаги сверяйте по официальной документации Cursor CLI.

Здесь /v1 может быть необходим, потому что CLI обращается к OpenAI-совместимому пути. Это не противоречит настройке Claude Code: речь идёт о другом клиенте и другом формате запроса.

MCP

MCP не является третьим способом указать основной endpoint генерации. Он подключает инструменты OmniRoute к клиенту через MCP-транспорт.

Пример подключения:

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

Для локального процесса можно использовать конфигурацию:

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

Успешный MCP-вызов доказывает, что клиент видит инструмент. Он не доказывает, что обычные сообщения Cursor идут через тот же inference endpoint. Для этого нужен отдельный тест модели.

Как выбрать совместимую схему

Используйте следующие условия вместо попытки подключить всё одновременно:

• Если нужен Claude Code через OmniRoute, выберите omniroute launch или ручные переменные и укажите корневой URL без /v1.
• Если нужен Cursor CLI с явным endpoint, используйте --endpoint и OpenAI-совместимый адрес с /v1, затем проверяйте точный ID модели.
• Если нужен Cursor Desktop, настройте стандартную чат-модель и не рассчитывайте, что все специализированные функции пройдут через OmniRoute.
• Если нужны инструменты OmniRoute внутри клиента, подключайте MCP отдельно. Не используйте успешный MCP-вызов как доказательство работы inference-маршрута.
• Если клиент не поддерживает требуемый формат endpoint, откатитесь к совместимому CLI-пути или оставьте этот клиент на собственном backend.
• Если OmniRoute должен быть доступен с нескольких устройств, переносите его на удалённый Mac только после локальной проверки и закрывайте порт сетевым контуром.

Fallback: почему переключение не происходит

Есть три разных режима, которые часто смешивают:

1. Прямой вызов одной модели. Запрос всегда отправляется в один provider. При квоте или ошибке вы получаете отказ.
2. Автоматический маршрут. OmniRoute выбирает подходящую цель по правилам проекта.
3. Явная fallback-цепочка. Вы заранее указываете порядок целей: первая модель, затем вторая, затем третья.

Автоматическая маршрутизация не создаёт резерв сама по себе. Для проверяемого переключения нужно минимум два реально подключённых provider. OmniRoute заявляет автоматический переход к следующей цели при отказе, но это характеристика проекта, а не независимый результат тестирования. Подробности приведены в официальном репозитории OmniRoute.

Проведите повторяемое испытание отказоустойчивости:

1. Выберите основную модель A и резервную модель B.
2. Проверьте, что обе цели имеют действующие ключи и проходят отдельный запрос.
3. Отправьте обычный запрос через Cursor CLI или Claude Code.
4. Запишите активную модель и provider из журнала.
5. Временно отключите модель A или сделайте недействительным только тестовый upstream-ключ.
6. Отправьте тот же запрос ещё раз.
7. Проверьте решение маршрутизатора, код ошибки, итоговую модель и содержимое ответа.
8. Восстановите модель A и повторите запрос.

Если переключения нет, ищите причину в следующем порядке:

• в цепочке указан только один provider;
• fallback настроен для другого типа запроса;
• ошибка не считается переключаемой;
• резервная модель не поддерживает нужный формат;
• ключ есть в панели, но не передан процессу;
• клиент использует собственный endpoint и вообще не обращается к OmniRoute.

Бесплатные лимиты, количество доступных provider и заявленный эффект встроенного сжатия следует считать данными проекта или сторонних обзоров. Не используйте такие сведения как независимое доказательство производительности или экономии.

Удалённый Mac: критерии приёмки для двух клиентов

Переносить шлюз на удалённый Mac имеет смысл не ради самого факта удалённого запуска. Причина должна быть операционной: клиентский компьютер часто засыпает, сеть меняется, требуется доступ с нескольких устройств или нужно оставить долгую задачу работающей без открытого ноутбука.

Проверьте среду по списку:

• адрес клиента не содержит localhost;
• с рабочего устройства проходит запрос к корню OmniRoute;
• /v1/models возвращает ожидаемый JSON;
• Claude Code работает с ANTHROPIC_BASE_URL без /v1;
• Cursor CLI получает совместимый endpoint;
• Cursor Desktop проверен только для поддерживаемой чат-функции;
• MCP проверен отдельно, если он используется;
• основная и резервная цели проходят индивидуальные запросы;
• отказ первой цели фиксируется в журнале;
• после отказа видны новый маршрут и итоговая модель;
• после перезапуска MacHTML-шлюз запускается автоматически;
• ключи не лежат в общедоступном профиле;
• удалённый порт ограничен VPN, локальной сетью или межсетевым экраном;
• разрыв SSH или закрытие терминала не останавливает сервис;
• после восстановления сети клиент может повторить запрос.

Для короткого личного теста локальная машина обычно проще. Для постоянного доступа, работы с нескольких устройств и небольшой команды лучше использовать контролируемый удалённый Mac. Перед миграцией проверьте сетевой сценарий и восстановление через справочные материалы MacHTML, а затем сравните доступные варианты аренды Mac в MacHTML.

Локальный ноутбук или удалённый Mac

Локальная схема удобна, пока всё происходит на одном устройстве. Но у неё есть реальные ограничения:

• сон ноутбука останавливает локальный шлюз или делает его недоступным;
• смена Wi-Fi меняет доступность адреса;
• ключи Cursor и Claude Code часто оказываются разбросаны по нескольким профилям;
• другой разработчик не может повторить маршрут без копирования окружения;
• после перезагрузки приходится вручную восстанавливать процессы и туннели.

Удалённый Mac устраняет не все проблемы, но меняет точку отказа. OmniRoute остаётся запущенным независимо от состояния рабочего ноутбука, а клиенты получают единый сетевой адрес. Цена такой схемы — необходимость управлять доступом, обновлениями, журналами и сетевыми ограничениями.

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

Главный практический вывод такой: не пытайтесь лечить несовместимость одинаковой строкой URL. Сначала определите клиент, затем формат API, затем проверьте минимальный запрос и только после этого добавляйте маршруты и fallback.

Ваш текущий локальный вариант удобен для проверки, но сон Mac, смена сети, разрозненные ключи и отсутствие общего адреса быстро мешают долгим задачам. В такой ситуации аренда удалённого Mac через MacHTML обычно удобнее: шлюз остаётся доступным, Cursor и Claude Code можно проверять с разных устройств, а восстановление и доступы оформляются как отдельная операционная процедура. Если нагрузка кратковременная и физические интерфейсы нужны постоянно, покупка собственного Mac может быть рациональнее; если нужна временная AI-среда или стабильный удалённый узел, начните с контролируемого размещения и повторной приёмки по этому списку.

FAQ

Читайте также: Cursor, Copilot и Claude Code: как выбрать вычислительную среду для AI-разработки Claude Code и MCP в macOS: настройка моделей и подключение инструментов