Remote Mode (Русский)

Как это работает

ваш ноутбук                              удалённый OmniRoute (VPS)
┌────────────────────┐                   ┌───────────────────────────────┐
│ omniroute CLI      │  POST /api/cli/connect  (пароль → токен)           │
│  контекст: vps     │ ───────────────►  │ создаёт токен доступа с       │
│  baseUrl, token    │  Authorization: Bearer oma_live_…                  │
│                    │ ───────────────►  │ ограниченными правами; каждый │
│ записывает конфиги │ ◄───────────────  │ маршрут управления проверяет │
│ ЛОКАЛЬНО           │                   │ права токена                  │
└────────────────────┘                   └───────────────────────────────┘

• Контексты хранят по одному серверу каждый (~/.omniroute/config.json, chmod 600). omniroute contexts use <name> переключает активный сервер; default является локальным.
• Токены доступа (oma_live_…) авторизуют команды управления. Они отличаются от API-ключей для инференса (sk-…, используемых для /v1/chat/completions).
• На стороне сервера хранится только SHA-256-хеш токена. Токен в открытом виде показывается один раз при создании.

---

Подключение

С помощью пароля управления (первоначальная настройка)

omniroute connect 192.168.0.15
# Пароль управления для http://192.168.0.15:20128: ********
# ✔ Подключено к http://192.168.0.15:20128 — контекст '192.168.0.15' (уровень доступа: admin)

По умолчанию при входе с паролем создаётся токен уровня admin (раз у вас есть пароль, у вас уже есть полный контроль). Ограничить права можно с помощью --scope:

omniroute connect 192.168.0.15 --scope write

Параметры: --port <p> (если в адресе хоста не указан порт), --name <ctx> (имя контекста), --scope read|write|admin. Полный URL используется без изменений: omniroute connect https://omni.example.com.

С помощью предварительно созданного токена

Создайте токен с ограниченными правами в панели управления (или с помощью omniroute tokens create) и вставьте его — пароль не требуется:

omniroute connect 192.168.0.15 --key oma_live_xxxxxxxx

CLI проверит его через GET /api/cli/whoami и сохранит как активный контекст.

---

Уровни доступа

Три иерархических уровня (admin ⊃ write ⊃ read):

Уровень	Разрешённые действия
read	просмотр — models list, providers status, logs, usage, cost
write	read + настройка/применение — setup-codex, keys add, config set, комбинации
admin	write + управление — CRUD для tokens, добавление провайдеров, сервисы, политики, oauth

Сервер определяет необходимый для каждого маршрута уровень доступа на основе метода HTTP (GET→read, изменения→write), а также списка административных исключений для критически важных разделов (изменения /api/cli/tokens, /api/providers, а также /api/oauth, /api/services, …). Если у токена недостаточно прав, сервер возвращает 403 с понятным сообщением.

Маршруты, запускающие процессы (/api/services/*, /api/mcp/*, …), остаются доступными только через loopback — удалённый токен никогда не сможет обратиться к ним независимо от уровня доступа.

---

Подключение Antigravity при удалённой установке

Antigravity использует экран согласия Google для firstparty/nativeapp. Google выдаёт код авторизации, только когда циклическое перенаправление (http://127.0.0.1:<port>/callback) доступно из браузера, в котором подтверждается вход. При установке на удалённом VPS этот loopback-адрес относится к серверу, а не к вашему компьютеру, поэтому экран согласия зависает навсегда и не выдаёт код — в обычном резервном сценарии с «вставкой URL обратного вызова» нечего вставлять. (Это ограничение на стороне Google: такое же зависание происходит в любом прокси, использующем встроенный настольный клиент Antigravity, а не только в OmniRoute.)

Панель управления обнаруживает это до того, как вы столкнётесь с зависанием: если открыть Providers → Antigravity → Connect не с localhost-адреса, общее уведомление «скопируйте URL обратного вызова» будет заменено двумя приведёнными ниже способами решения, причём адрес вашего хоста и порт уже будут подставлены. (Адрес локальной сети тоже учитывается — 192.168.x.x не является localhost для этого обратного вызова.)

Есть два поддерживаемых способа подключить Antigravity к удалённому OmniRoute.

Вариант A — локальный помощник входа (рекомендуется)

Запустите OAuth на своём компьютере, где доступен 127.0.0.1. Помощник взаимодействует с Google напрямую, поэтому процесс подтверждения завершается там, где версия из панели управления завершиться не может.

Если вы уже подключены (omniroute connect <host>), ничего копировать не нужно — помощник сам передаст учётные данные в эту установку:

# На вашем ЛОКАЛЬНОМ компьютере (требуются Node.js и браузер):
omniroute connect 192.168.0.15        # один раз — создаёт контекстный токен с правами администратора
npx omniroute login antigravity
#   ↳ открывает экран согласия Google, принимает обратный вызов на локальном loopback-порту,
#     выполняет обмен и отправляет учётные данные POST-запросом в активный контекст:
#
#   Antigravity подключён по адресу http://192.168.0.15:20128 (подключение abc123).
#   Вставлять ничего не нужно — этот терминал можно закрыть.

Отправка выполняется автоматически, когда активный контекст указывает на другой компьютер. Принудительно включить или отключить её можно с помощью --push / --no-push, а выбрать определённый контекст — с помощью --context <name>.

Если ваш компьютер не может подключиться к VPS (из-за межсетевого экрана, отсутствия SSH или изолированного рабочего места), помощник всё равно работает — ему необходим только доступ к Google. Используйте --no-push или просто позвольте отправке завершиться ошибкой: вместо удаления уже полученной авторизации помощник выведет blob.

npx omniroute login antigravity --no-push
#   omniroute-cred-v1.eyJ2IjoxLCJ...

Затем в удалённой панели управления откройте Providers → Antigravity → Connect и вставьте blob omniroute-cred-v1.… в поле Step 2 (оно принимает как URL обратного вызова, так и blob с учётными данными). OmniRoute декодирует его, выполнит настройку Cloud Code на стороне сервера и сохранит подключение.

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

Флаги: --no-browser (вывести URL вместо автоматического открытия), --port <n> (зафиксировать loopback-порт), --timeout <ms>, --push / --no-push (переопределить автоматическую доставку), --context <name> (выбрать определённый контекст).

Вариант B — туннель с локальным перенаправлением SSH

Если у вас есть SSH-доступ к VPS, перенаправьте порт панели управления, чтобы loopback-вызов возвращался на сервер через туннель:

# На вашем ЛОКАЛЬНОМ компьютере:
ssh -L 20128:127.0.0.1:20128 user@your-vps
# затем откройте http://localhost:20128 в ЛОКАЛЬНОМ браузере и подключите Antigravity
# обычным способом — перенаправление 127.0.0.1:20128/callback теперь достигает VPS через SSH.

Поскольку вы открываете панель управления по адресу localhost:20128, процесс согласия Google завершается, а обратный вызов доставляется на сервер через тот же туннель — blob не требуется. Не закрывайте туннель, пока подключение не станет активным.

В отличие от перечисленных ниже провайдеров с фиксированным loopback-адресом, здесь достаточно одного перенаправления: обратный вызов Antigravity проходит через порт самой панели управления, поэтому туннелировать второй порт, специфичный для провайдера, не нужно.

Полностью безголовая альтернатива (без помощника и туннеля) — настроить собственные веб-учётные данные Google OAuth и общедоступный базовый URL; см. переменные окружения OAuth этого провайдера. Для двух описанных выше вариантов дополнительная настройка Google не требуется.

---

Подключение Codex / Grok к удалённой установке (провайдеры с фиксированным loopback-адресом)

Codex, xAI (xai-oauth) и Grok CLI (grok-cli) регистрируют фиксированный loopback-адрес redirect_uri в своём OAuth-приложении у внешнего провайдера. OmniRoute не может его изменить — провайдер всегда перенаправляет браузер на один и тот же жёстко заданный адрес:

Провайдер	Фиксированный callback-адрес, на который перенаправляет провайдер
codex	http://localhost:1455/auth/callback
xai-oauth	http://127.0.0.1:56121/callback
grok-cli	http://127.0.0.1:56122/callback

В данном случае localhost означает компьютер, на котором запущен браузер, тогда как сервер callback-запросов PKCE OmniRoute прослушивает loopback-интерфейс сервера. Если открыть панель управления по адресу локальной сети, например http://192.168.0.15:20128, эти две точки никогда не соединятся: код авторизации будет отправлен на localhost:1455 вашего ноутбука, где ничего не прослушивает порт, и провайдер завершит вход с ошибкой, не отобразив её.

Панель управления обнаруживает эту ситуацию до открытия всплывающего окна и показывает команду для создания туннеля, не позволяя процессу входа завершиться незаметной ошибкой (#8046).

Решение — пробросьте оба порта

# На компьютере, где запущен БРАУЗЕР:
ssh -L 20128:127.0.0.1:20128 -L 1455:127.0.0.1:1455 <user>@192.168.0.15
# затем откройте http://localhost:20128 и подключите Codex оттуда

Необходимо пробросить два порта; проброс только одного из них всё равно не сработает:

• 20128 (порт панели управления) обеспечивает origin с настоящим localhost, что позволяет OmniRoute вообще запустить сервер callback-запросов PKCE — origin из локальной сети никогда не попадает в эту ветку.
• 1455 (фиксированный порт callback-запросов провайдера) — это порт, на который возвращается браузер; он должен быть перенаправлен через туннель на loopback-интерфейс сервера.

При подключении xAI или Grok CLI замените 1455 на 56121/56122, а 20128 — на фактический порт вашей панели управления. Не закрывайте туннель, пока подключение не будет показано как активное.

Нет доступа по SSH? Codex и Grok CLI также позволяют вставить токен — вкладка Вставить API-ключ / Импортировать auth.json в диалоговом окне подключения. Этот способ не использует loopback-адрес для callback-запросов, поэтому работает с любым origin. Codex также принимает обычный токен доступа или данные сеанса из ~/.codex/auth.json.

---

Управление токенами

omniroute tokens create --name "laptop" --scope write [--expires 30]
#   ↳ выводит секрет ОДИН РАЗ — скопируйте его сейчас
omniroute tokens list                 # с маскированием: идентификатор, имя, область действия, префикс, состояние, срок действия
omniroute tokens revoke <id|prefix>   # немедленно отозвать
omniroute tokens scopes               # описание трёх областей действия

Команды tokens требуют учётные данные с правами администратора. Управлять токенами также можно в панели управления в разделе Настройки → Токены доступа (создание, отзыв, однократное копирование).

---

Настройка CLI для программирования из удалённого каталога

omniroute configure считывает актуальный каталог моделей активного сервера и записывает конфигурацию на ваш компьютер.

glm/glm-5.2

omniroute configure codex
#   Провайдеры: glm, kmc, ollamacloud, opencode-go, …
#   Провайдер: glm
#   ✔ Записан ~/.codex/glm52.config.toml
#   Использование:  codex --profile glm52

# неинтерактивный режим
omniroute configure codex --provider glm --model glm/glm-5.2 --name glm52

# оставить часто используемую модель в верхней части интерактивного списка выбора
omniroute configure codex --provider glm --model glm/glm-5.2 --favorite --yes

Средство выбора сохраняет в локальном файле model-preferences.json только идентификаторы моделей (но никогда не URL-адреса или учётные данные), сгруппированные по контексту и целевому CLI. Избранные модели отображаются перед недавно выбранными; используйте --unfavorite, чтобы удалить выбранную модель из списка для соответствующего контекста и целевого CLI.

Записанный профиль ссылается на ключ инференса через переменную среды (OMNIROUTE_API_KEY) — секрет никогда не записывается на диск. Однократная базовая настройка Codex (блок [model_providers.omniroute]) описана в документе CODEX-CLI-CONFIGURATION.md.

Запуск CLI для работы с удалённым сервером (без записи конфигурации)

omniroute run <target> также учитывает активный контекст: базовый URL-адрес удалённого сервера и учётные данные контекста передаются только в запускаемый процесс.

omniroute connect 192.168.0.15
omniroute run claude   --model openai/gpt-5.4          # Claude Code → удалённый сервер
omniroute run gemini   --model glm/glm-5.2 -- --skip-trust -p "hello"
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"

# Предварительный просмотр того, что именно будет запущено (только ИМЕНА КЛЮЧЕЙ переменных среды, без значений):
omniroute run codex --dry-run --json

Целевые CLI: claude, codex, aider, goose, opencode, qwen, gemini (единый источник: bin/cli/cli-manifest.mjs). Qwen и Gemini запускаются во временной изолированной домашней директории, которая удаляется после завершения работы, поэтому запуск никогда не изменяет — и не затрагивает — вашу личную конфигурацию инструментов.

Команды настройки для отдельных CLI

Для каждого поддерживаемого CLI предусмотрена команда настройки с поддержкой удалённого сервера (все они учитывают активный контекст либо параметры --remote <url> --api-key <key>):

CLI	Команда	Что записывается
Codex	omniroute setup-codex	Профили ~/.codex/<name>.config.toml (для каждой модели)
Claude Code	omniroute setup-claude	~/.claude/profiles/<name>/settings.json (для каждой модели)
OpenCode	omniroute setup-opencode	~/.config/opencode/opencode.json — OpenAI-совместимый провайдер omniroute со всеми моделями каталога (запуск: opencode -m omniroute/<model>)
Cline	omniroute setup-cline	~/.cline/data/{globalState,secrets}.json (режим CLI) + выводит настройки расширения VS Code, которые нужно вставить (OpenAI-совместимые, базовый URL без /v1)
Kilo Code	omniroute setup-kilo	~/.local/share/kilo/auth.json (CLI) + настройки VS Code kilocode.* — OpenAI-совместимые, базовый URL с /v1
Continue	omniroute setup-continue	~/.continue/config.yaml (VS Code/JetBrains + CLI cn) — provider: openai, apiBase с /v1, ключ через ${{ secrets.OMNIROUTE_API_KEY }}
Cursor	omniroute setup-cursor	выводит инструкции для настройки в приложении (Settings → Models → Override OpenAI Base URL с /v1 + ключ + модель). Конфигурация Cursor хранится в непрозрачной базе SQLite — только панель чата
Roo Code	omniroute setup-roo	записывает импортируемый JSON Roo (~/.omniroute/roo-settings.json) + задаёт roo-cline.autoImportSettingsPath + выводит инструкции для интерфейса (OpenAI-совместимые, базовый URL с /v1)
Crush	omniroute setup-crush	~/.config/crush/crush.json — провайдер openai-compat, base_url с /v1, ключ через $OMNIROUTE_API_KEY
Goose	omniroute setup-goose	~/.config/goose/config.yaml (GOOSE_PROVIDER=openai + OPENAI_HOST без /v1 + GOOSE_MODEL) + инструкция по переменным окружения
Aider	omniroute setup-aider	~/.aider.conf.yml (openai-api-base без /v1 + model: openai/<id>) + инструкция по переменным окружения (aider --message --yes)
Qwen Code	omniroute setup-qwen	Запись V4 modelProviders.openai в ~/.qwen/settings.json + OMNIROUTE_API_KEY в ~/.qwen/.env

# OpenCode (OpenAI-совместимый провайдер, все модели каталога, удалённый VPS)
omniroute setup-opencode --remote http://192.168.0.15:20128 --api-key oma_live_xxx
omniroute setup-opencode --only glm,kimi        # оставить только соответствующие модели
opencode -m omniroute/glm/glm-5.2 "..."          # сначала экспортируйте OMNIROUTE_API_KEY

OpenCode также поддерживает более функциональную интеграцию через плагин: omniroute setup opencode (теперь с поддержкой удалённых подключений через --remote) устанавливает @omniroute/opencode-plugin. setup-opencode — облегчённая OpenAI-совместимая альтернатива. Ключ API указывается через {env:OMNIROUTE_API_KEY} и никогда не записывается на диск.

В OpenCode v2 вместо этого используйте @omniroute/opencode-plugin-v2: тот же каталог, но другой контракт загрузчика. Когда интеграция подключена, он считывает ключ из собственного хранилища учётных данных OpenCode, поэтому для удалённого шлюза ключ в opencode.json вообще не требуется.

---

Управление контекстами (переключение между серверами)

Контекст — это сохраненный сервер (baseUrl + учетные данные + область действия). omniroute connect создает его и делает активным; с этого момента каждая команда нацелена на него. Управляйте и переключайтесь между ними с помощью omniroute contexts:

omniroute contexts list            # все контексты; активный помечен ●
omniroute contexts current         # активный сервер, статус аутентификации, область действия

  | Name    | Base URL                  | Auth  | Scope | Description
● | vps     | http://100.67.86.91:20128 | token | admin | Remote OmniRoute (…)
  | default | http://localhost:20128    | ✗     |       |

Переключение серверов — каждая последующая команда следует активному контексту:

omniroute contexts use vps         # → все команды теперь обращаются к удаленному VPS
omniroute tokens list              #   (выполняется на VPS)

omniroute contexts use default     # → обратно к localhost
omniroute tokens list              #   (выполняется на локальном сервере)

Добавить контекст вручную (вместо connect), просмотреть или переименовать:

omniroute contexts add staging --url https://staging.example.com:20128 \
  --access-token oma_live_xxxx --scope write --description "staging box"
omniroute contexts show staging    # полные сведения для одного контекста
omniroute contexts rename staging stg

Удалить контекст — запрашивает подтверждение; передайте --yes, чтобы пропустить его (требуется для скриптов / неинтерактивных оболочек, которые в противном случае безопасно отклоняют):

omniroute contexts remove stg --yes

default (localhost) не может быть удален. Удаление активного контекста приводит к default. Совет: удаление контекста только удаляет локальные сохраненные учетные данные — отзовите токен на сервере с помощью omniroute tokens revoke <id>, чтобы фактически прекратить доступ.

Экспорт / импорт контекстов (например, для перемещения их между машинами). Экспорт по умолчанию опускает учетные данные, включая учетные данные, хранящиеся в файловом резервном хранилище. Используйте --include-secrets явно, когда требуется переносимая резервная копия, содержащая учетные данные:

omniroute contexts export --out contexts.json     # отредактировано; место назначения по умолчанию: stdout
omniroute contexts export --include-secrets --out private-contexts.json
omniroute contexts import contexts.json            # перезаписать; --merge для сохранения существующих
omniroute contexts migrate --yes                  # переместить устаревшие токены в виде обычного текста в связку ключей

--include-secrets разрешает ссылки на связку ключей перед экспортом и завершается с ошибкой, если какие-либо указанные учетные данные не могут быть прочитаны. --no-secrets всегда имеет приоритет. Файлы экспорта записываются атомарно с режимом 0600. Рассматривайте явный экспорт, содержащий секреты, как секретный материал. На безголовых системах без пригодной для использования связки ключей ОС CLI возвращается к config.json с режимом 0600 и выводит одноразовое предупреждение; экспорт по умолчанию остается отредактированным в этом режиме.

---

Быстрая сквозная проверка

Готовый для копирования и вставки сценарий полного жизненного цикла для проверки удалённой конфигурации с нуля: подключение, создание токена с ограниченной областью доступа, выполнение команды, переключение обратно и очистка. Замените 192.168.0.15 именем хоста или IP-адресом своего сервера (Tailscale, локальная сеть или общедоступный URL https://…).

# 1. Подключение (пароль → токен администратора, сохранённый как контекст, который становится активным)
omniroute connect 192.168.0.15                 # или: --key oma_live_xxxx  (без пароля)
omniroute contexts current                     # показывает удалённый сервер и область доступа

# 2. Использование — теперь команды управления выполняются на удалённом сервере
omniroute tokens create --name laptop --scope read   # создать токен с более узкой областью доступа
omniroute tokens list                                 # список с замаскированными значениями с удалённого сервера

# 3. Переключение туда и обратно
omniroute contexts use default                 # → локальный сервер
omniroute contexts use 192-168-0-15            # → снова удалённый сервер (имя из `contexts list`)

# 4. Очистка. ВНИМАНИЕ: `contexts remove` удаляет только ЛОКАЛЬНЫЕ учётные данные —
#    эта команда НЕ отзывает токен на сервере. Если требуется действительно закрыть
#    доступ, сначала отзовите токен на сервере.
omniroute tokens revoke <id|prefix>            # закрывает доступ на сервере
omniroute contexts remove 192-168-0-15 --yes   # удаляет локальный контекст (даже если он активен → возврат к default), без запроса

--yes делает contexts remove неинтерактивной командой (это необходимо в скриптах/CI; без него неинтерактивная оболочка безопасно отклонит операцию, а не зависнет). При удалении активного контекста автоматически выполняется возврат к default.

---

Примечания по безопасности

• Открытый текст токена отображается один раз; сохраняется только хеш SHA-256 (как и для ключей API).
• omniroute connect использует тот же механизм блокировки при переборе пароля и журналирование аудита, что и вход в систему.
• Для передачи данных рекомендуется использовать HTTPS или Tailnet; для удобства работы в локальной сети/Tailscale адрес, содержащий только имя хоста, по умолчанию использует http:// — для TLS укажите полный URL-адрес https://….
• Предпочтительный локальный файл контекста — ~/.omniroute/config.json (chmod 600), содержащий только credentialRef; сам токен хранится в системном хранилище учётных данных (keytar) и никогда не выводится в журналы. В установках без графического интерфейса, где работоспособное нативное хранилище учётных данных недоступно, в качестве явно обозначенного резервного варианта используется тот же файл с правами 0600, а предупреждение выводится один раз. После установки бэкенда хранилища учётных данных выполните omniroute contexts migrate --yes.

---

Конечные точки API (справочник)

Метод	Маршрут	Аутентификация	Область действия
POST	/api/cli/connect	пароль управления	— (публичная, защищена паролем)
GET	/api/cli/whoami	токен доступа	чтение
GET	/api/cli/tokens	токен доступа	администрирование
POST	/api/cli/tokens	токен доступа	администрирование
DELETE	/api/cli/tokens/:id	токен доступа	администрирование

Полные схемы см. в openapi.yaml.

---

Исходный код OmniRoute (a58000c7685f)