OmniRoute Remote Mode: устранение сбоев в 2026

Статус выглядит обманчиво: omniroute connect завершается успешно, но Claude Code или другой CLI продолжает отправлять запросы в локальный экземпляр.

Самое быстрое решение — не переустанавливать OmniRoute, а сначала подтвердить health-ответ удалённого узла и активный context, затем проверить адрес, область действия токена, обратный прокси и клиентский конфигурационный файл. Если сервис доступен только внутри локальной сети, сначала создайте защищённый HTTPS- или приватный сетевой вход; не открывайте административный интерфейс без аутентификации.

Эта статья предназначена для трёх групп читателей:

• разработчиков, которые подключаются к удалённому OmniRoute с ноутбука и получают тайм-аут или пустой каталог моделей;
• команд, использующих один удалённый AI-шлюз из Claude Code и других инструментов;
• специалистов, запускающих OmniRoute на облачном или постоянно работающем Mac и проверяющих восстановление после перезапуска, обрыва связи и длинного потокового запроса.

Карта неисправности

Remote Mode состоит не из одного соединения. В реальном запросе участвуют серверный процесс, сетевой путь, токен доступа, контекст CLI, локально создаваемая конфигурация инструмента и, иногда, обратный прокси. Успешная команда connect подтверждает только часть цепочки.

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

1. удалённый процесс не слушает нужный интерфейс или не восстановил конфигурацию;
2. имя, порт, firewall, туннель или TLS не позволяют пройти до приложения;
3. токен доступа OmniRoute недействителен либо не имеет нужной области действия;
4. CLI продолжает использовать локальный context или старый конфигурационный файл;
5. обратный прокси обрывает SSE-поток, переписывает путь или не передаёт заголовки.

Это разделение важно из-за скрытых затрат. Первая ошибка — потеря времени на переустановку приложения, хотя проблема находится в DNS или прокси. Вторая — случайное расширение прав токена ради одной команды. Третья — ложное ощущение удалённой работы: интерфейс показывает знакомое имя модели, но запрос фактически идёт в localhost.

Официальная документация OmniRoute указывает, что активный context, созданный через omniroute connect, используется командами CLI автоматически, а явные параметры --remote и --api-key имеют приоритет. Конфигурация для Claude Code или другого инструмента при этом записывается на локальной машине, даже если каталог моделей получен с удалённого сервера. (официальная Wiki по CLI-интеграциям)

Первый уровень: состояние сервера

Сигнал

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

Команды для сбора данных

Ниже используются условные значения. Замените <REMOTE_HOST>, <REMOTE_PORT>, <REMOTE_USER> и пути на собственные, не вставляя реальные токены в историю shell:

ssh <REMOTE_USER>@<REMOTE_HOST>

ps aux | grep -i '[o]mniroute'
omniroute --help
omniroute doctor

curl -i --max-time 10 \
  https://<REMOTE_HOST>/health

tail -n 200 ~/.omniroute/*.log

Если используется прямой адрес без прокси, порт и путь должны соответствовать текущей версии CLI и выводу omniroute --help. В официальных материалах для локального режима упоминается API-порт 20128, однако этот параметр нельзя переносить на каждую установку без проверки фактической конфигурации. (README официального репозитория)

Проверьте четыре факта:

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

Обработка

Если процесс отсутствует, сначала исправьте способ запуска и автозапуск. Если процесс присутствует, но health недоступен, не переходите к диагностике Claude Code: клиент не может исправить неработающий серверный слой. Если health отвечает, сохраните тело ответа, время проверки и фрагмент журнала — это будет базовым доказательством для следующих уровней.

Проверка после исправления

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

Второй уровень: адрес и сетевой путь

Сигнал

omniroute connect или последующая команда завершается по тайм-ауту, а локальный запуск работает. Важно различать:

• DNS или маршрут не найден;
• TCP-порт закрыт;
• TLS не проходит проверку;
• TCP соединение устанавливается, но приложение не отвечает;
• прокси отвечает, однако передаёт запрос не в тот путь.

Эти случаи требуют разных действий. Открытие всех портов или отключение аутентификации не является диагностикой и создаёт отдельную уязвимость.

Команды для сбора данных

getent hosts <REMOTE_HOST>
nc -vz <REMOTE_HOST> <REMOTE_PORT>

curl -vk --connect-timeout 5 \
  https://<REMOTE_HOST>/health

curl -vk -H "Authorization: Bearer <OMNIROUTE_TOKEN>" \
  https://<REMOTE_HOST>/v1/models

На macOS вместо getent можно использовать dscacheutil -q host -a name <REMOTE_HOST> или nslookup <REMOTE_HOST>. Результаты нужно сравнивать с проверкой непосредственно на удалённой машине:

curl -i http://127.0.0.1:<REMOTE_PORT>/health

Если localhost на удалённом Mac отвечает, а внешний HTTPS-адрес нет, проблема находится между приложением и клиентом: bind-адрес, firewall, туннель, DNS или reverse proxy. Если не отвечает даже localhost, возвращайтесь к серверному уровню.

Обработка

Для удалённого AI-шлюза предпочтительны два безопасных варианта:

• HTTPS через обратный прокси с аутентификацией и ограничением источников;
• приватная сеть или туннель, через который порт не публикуется в общий Интернет.

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

Проверка после исправления

Проверка должна идти с той же машины, где запускается CLI. Выполните health через конечный HTTPS-адрес, затем запрос каталога с токеном. Если прямой локальный запрос проходит, а запрос через прокси возвращает 404, 401 или зависает, неисправен именно входной слой. В отчёте зафиксируйте DNS-имя, схему, путь, результат TCP и HTTP-код, не раскрывая секрет.

Важно: успешный curl к /health ещё не доказывает, что пройдёт запрос модели. Health подтверждает доступность приложения, но не права токена, корректность маршрута API или устойчивость SSE-потока.

Третий уровень: токен и права

Сигнал

Удалённый адрес отвечает, но CLI получает 401, 403, ошибку «invalid token» или видит только часть операций. Распространённая причина — смешение ключа верхнего провайдера с токеном доступа OmniRoute. Это разные секреты: первый используется шлюзом для обращения к модели, второй разрешает клиенту обращаться к самому удалённому OmniRoute.

Официальный README описывает scoped tokens с уровнями read, write и admin; отдельные маршруты, связанные с запуском процессов, остаются ограниченными loopback-доступом. Поэтому отказ операции записи при успешном чтении может быть штатным результатом минимальных прав, а не поломкой. (описание Remote Mode в официальном репозитории)

Команды для сбора данных

omniroute contexts list
omniroute contexts current
omniroute tokens --help

env | grep '^OMNIROUTE_API_KEY='

curl -i \
  -H "Authorization: Bearer <OMNIROUTE_TOKEN>" \
  https://<REMOTE_HOST>/v1/models

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

Обработка

Сначала восстановите правильный токен, затем проверьте его действительность и scope. Не выдавайте admin, если задаче требуется только каталог и вызов модели. Для команды, которая лишь читает модели и запускает запросы, необходимый минимум может отличаться от прав, требуемых для изменения маршрутов или провайдеров; точный набор проверяется по текущей версии CLI и API.

Проверка после исправления

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

1. чтение каталога моделей;
2. безопасная проверка текущего context;
3. короткий вызов модели;
4. тест изменения конфигурации только отдельным токеном с разрешённой областью;
5. отзыв тестового токена и повтор запроса.

Так обнаруживается не только «рабочий» секрет, но и избыточные права. Для команды полезно иметь отдельные токены для личного ноутбука, CI и административных операций.

Четвёртый уровень: локальный context и клиент

Сигнал

Подключение прошло, но Remote Mode показывает локальные модели, Claude Code не видит удалённый каталог или после setup-claude новый профиль продолжает использовать старый endpoint. Это самый коварный сценарий: соединение с control-командой успешно, а рабочий запрос идёт не туда.

OmniRoute указывает, что --remote <url> переопределяет активный context, а --api-key <key> передаёт credential для удалённого сервера. Команды setup-* получают каталог удалённо, но создают конфигурацию локально. (таблица CLI-интеграций OmniRoute)

Команды для сбора данных

omniroute contexts list
omniroute contexts current

omniroute models list \
  --remote https://<REMOTE_HOST> \
  --api-key <OMNIROUTE_TOKEN>

omniroute setup-claude \
  --remote https://<REMOTE_HOST> \
  --api-key <OMNIROUTE_TOKEN> \
  --dry-run

Проверьте созданный профиль:

grep -R "ANTHROPIC_BASE_URL\|ANTHROPIC_MODEL" \
  ~/.claude/profiles/<PROFILE_NAME>/

echo "$CLAUDE_CONFIG_DIR"
echo "$ANTHROPIC_BASE_URL"

Для Claude Code официальный пример использует Anthropic-совместимый базовый адрес без добавления /v1; этот путь добавляется клиентом для Messages API. Неправильное добавление суффикса может привести к ошибке маршрута или игнорированию шлюза. (официальная инструкция Claude Code Configuration)

Обработка

На время диагностики используйте явные параметры вместо неясного состояния context. Это позволяет доказать, что каталог пришёл с нужного узла. После этого можно вернуть удобный постоянный context.

Для Claude Code также учитывайте, что обнаружение моделей зависит от версии клиента и отдельной переменной окружения. Если список пуст, но принудительный ANTHROPIC_MODEL=<MODEL_ID> работает, проблема относится к discovery, а не к сетевому соединению. Официальная документация отдельно отмечает ограничения отображения идентификаторов моделей в picker. (раздел диагностики Claude Code)

Проверка после исправления

Сравните четыре источника:

Ключевой критерий — запись в журнале удалённого экземпляра во время тестового вызова. Название профиля, окно Claude Code или результат локальной команды не заменяют эту проверку.

Условия выбора способа подключения

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

• Если health не отвечает даже на удалённой машине, выбирайте исправление запуска, bind-адреса или постоянного хранилища; к клиенту переходить рано.
• Если localhost на удалённом узле отвечает, а HTTPS с ноутбука нет, выбирайте проверку DNS, firewall, туннеля и reverse proxy; токен пока не меняйте.
• Если /health проходит, а /v1/models возвращает 401 или 403, выбирайте проверку токена OmniRoute и scope; ключ провайдера не подставляйте.
• Если явный --remote показывает правильный каталог, а обычная команда — локальный, выбирайте исправление context или локального файла конфигурации.
• Если обычный запрос проходит, а потоковый обрывается, выбирайте анализ SSE, буферизации и idle timeout в прокси.
• Если после перезапуска исчезает каталог или context, выбирайте восстановление каталога конфигурации и автозапуска, а не новый токен.

Пятый уровень: обратный прокси и SSE

Сигнал

Через прямой защищённый адрес короткий запрос работает, но через reverse proxy Claude Code не подключается, ответ приходит с задержкой или длинная генерация обрывается. Причины обычно связаны с переписыванием пути, отсутствующим Authorization, TLS, буферизацией ответа и ограничением простоя соединения.

Для Anthropic-совместимого клиента особенно важно не превращать корректный корневой base URL в URL с лишним /v1. Для OpenAI-совместимых интеграций, напротив, путь /v1 может быть частью ожидаемой схемы. Это различие зафиксировано в таблице интеграций OmniRoute. (официальная таблица базовых URL)

Команды для сбора данных

Сначала сравните прямой и проксированный запросы:

curl -vk -N \
  -H "Authorization: Bearer <OMNIROUTE_TOKEN>" \
  -H "Accept: text/event-stream" \
  https://<REMOTE_HOST>/v1/models

curl -vk -N \
  -H "Authorization: Bearer <OMNIROUTE_TOKEN>" \
  -H "Accept: text/event-stream" \
  https://<PROXY_HOST>/v1/models

Проверьте конфигурацию прокси на предмет:

• точного proxy_pass и переписывания пути;
• передачи Host, Authorization и необходимых заголовков;
• отключения буферизации для SSE;
• ограничения времени ожидания заголовков и простоя;
• корректной обработки Connection и HTTP-версии.

Если используется Nginx, параметры нужно сверять с официальной документацией директивы proxy_read_timeout, а не копировать универсальные значения из форумов. На стороне OmniRoute параметры длительных потоков также меняются между версиями; в официальной справке описаны REQUEST_TIMEOUT_MS и STREAM_IDLE_TIMEOUT_MS, причём второй параметр наследует первый, если заданное значение отсутствует. (справка OmniRoute по длительным потоковым тайм-аутам)

Обработка

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

В журнале нужно сопоставить время отправки запроса, первый байт ответа, последовательность SSE-событий и момент обрыва. Если прокси не получает ни одного события, проблема находится до приложения. Если события появляются и прекращаются через одинаковый интервал, подозревайте idle timeout или буферизацию. Если OmniRoute фиксирует полный ответ, но клиент его не получает, исследуйте прокси и клиентский процесс.

Проверка после исправления

Проведите короткий и длинный тест отдельно, используя один и тот же удалённый токен. Успешная приёмка означает, что:

• прямой и проксированный URL дают ожидаемые HTTP-ответы;
• заголовок авторизации не исчезает;
• поток начинается без длительного молчания;
• завершение запроса фиксируется в журнале удалённого OmniRoute;
• Claude Code после перезапуска использует тот же endpoint.

Таблица быстрой локализации

Приёмка после исправления

Техническая команда должна закрывать неисправность не фразой «подключилось», а матрицей проверок. Минимальная последовательность выглядит так:

1. Пользователь с правами чтения получает каталог моделей с удалённого адреса.
2. Пользователь с правами записи выполняет разрешённое изменение, а пользователь чтения получает предсказуемый отказ.
3. Claude Code запускается с удалённым профилем и оставляет запись на удалённом узле.
4. Локальный context переключается обратно, после чего команда явно показывает, какой сервер выбран.
5. Удалённый процесс перезапускается, а health и каталог восстанавливаются без ручной переустановки.
6. Один токен отзывается, и запрос с ним перестаёт проходить.
7. Длинный поток проверяется через тот же HTTPS-вход, который будет использовать команда.
8. Для обрыва ноутбука или краткого разрыва туннеля заранее определён способ повторного запуска, переключения context и проверки незавершённой задачи.

Результат следует записать в короткий эксплуатационный отчёт:

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

Что записать перед закрытием инцидента

Перед тем как объявить OmniRoute Remote Mode исправным, сохраните:

• версию OmniRoute и вывод omniroute --help;
• активный context без значения секретного токена;
• конечный HTTPS-адрес и ожидаемый API-путь;
• результаты health и каталога моделей;
• фрагмент серверного журнала с тестовым запросом;
• настройки обратного прокси, относящиеся к SSE;
• результат проверки после перезапуска;
• состояние отозванного токена;
• имя локального профиля Claude Code и фактический base URL.

Такой набор позволяет отличить повторную сетевую аварию от возврата старого context. Он также сокращает время передачи проблемы другому специалисту: вместо субъективного «Remote Mode снова не работает» появляется последовательность проверяемых фактов.

Частые вопросы

Почему команда подключения к OmniRoute постоянно завершается по тайм-ауту?

Сначала отделите сетевую проблему от зависшего приложения. С ноутбука проверьте разрешение имени, маршрут до узла и TCP-порт, затем запросите health-эндпоинт через тот же HTTPS-адрес, который использует CLI. Если TCP не устанавливается, проверяйте firewall, туннель и DNS. Если TCP открыт, но health не отвечает, исследуйте процесс, bind-адрес и журнал сервера.

Что делать, если Remote Mode подключился, но список моделей пуст?

Проверьте, какой context активен, и повторите запрос с явными параметрами --remote и --api-key. Команды настройки читают каталог с указанного сервера, но конфигурационный файл создаётся локально. Для Claude Code дополнительно проверьте версию клиента, включение обнаружения моделей шлюза и идентификатор выбранной модели. Название профиля в интерфейсе само по себе не доказывает удалённый маршрут.

Как исправить ошибку аутентификации удалённого OmniRoute?

Не подставляйте ключ провайдера вместо токена доступа OmniRoute. Проверьте источник токена, заголовок Authorization, срок действия и scope. После исправления выполните отдельно операцию чтения каталога, действие изменения конфигурации и реальный вызов модели. Если чтение работает, а запись запрещена, это обычно корректное ограничение прав, а не неисправность сети.

Почему Claude Code перестаёт подключаться после установки обратного прокси?

Проверьте, не добавляет ли прокси лишний путь /v1 к Anthropic-совместимому адресу, корректно ли переписывается URL и передаётся ли Authorization. Для потоковых запросов важны SSE, отсутствие буферизации и согласованный idle timeout. Сравните прямой защищённый запрос к OmniRoute с запросом через прокси, а затем перезапустите Claude Code: переменные окружения считываются при старте процесса.

Как вернуть клиент к удалённому OmniRoute после перезапуска сервера?

Сначала подтвердите, что после перезапуска восстановились процесс, база конфигурации и сетевой вход, а не только имя процесса. Затем проверьте активный context и срок действия его токена, выполните чтение списка моделей и короткий вызов. Если context указывает на localhost, переключите его на удалённый профиль либо используйте явные --remote и --api-key, после чего заново сгенерируйте клиентскую конфигурацию.

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

Блог

• SSH-туннель или прямое WSS-подключение: проверка удалённого узла и состояния демона
• Инструменты командной строки для удалённой разработки на Mac: подключение и диагностика