# Remote Mode (Українська) 🌐 **Languages:** 🇺🇸 [English](../../../../guides/REMOTE-MODE.md) · 🇪🇹 [am](../../../am/docs/guides/REMOTE-MODE.md) · 🇸🇦 [ar](../../../ar/docs/guides/REMOTE-MODE.md) · 🇦🇿 [az](../../../az/docs/guides/REMOTE-MODE.md) · 🇧🇬 [bg](../../../bg/docs/guides/REMOTE-MODE.md) · 🇧🇩 [bn](../../../bn/docs/guides/REMOTE-MODE.md) · 🇧🇦 [bs](../../../bs/docs/guides/REMOTE-MODE.md) · 🇨🇿 [cs](../../../cs/docs/guides/REMOTE-MODE.md) · 🇩🇰 [da](../../../da/docs/guides/REMOTE-MODE.md) · 🇩🇪 [de](../../../de/docs/guides/REMOTE-MODE.md) · 🇬🇷 [el](../../../el/docs/guides/REMOTE-MODE.md) · 🇪🇸 [es](../../../es/docs/guides/REMOTE-MODE.md) · 🇪🇪 [et](../../../et/docs/guides/REMOTE-MODE.md) · 🇮🇷 [fa](../../../fa/docs/guides/REMOTE-MODE.md) · 🇫🇮 [fi](../../../fi/docs/guides/REMOTE-MODE.md) · 🇫🇷 [fr](../../../fr/docs/guides/REMOTE-MODE.md) · 🇮🇪 [ga](../../../ga/docs/guides/REMOTE-MODE.md) · 🇮🇳 [gu](../../../gu/docs/guides/REMOTE-MODE.md) · 🇳🇬 [ha](../../../ha/docs/guides/REMOTE-MODE.md) · 🇮🇱 [he](../../../he/docs/guides/REMOTE-MODE.md) · 🇮🇳 [hi](../../../hi/docs/guides/REMOTE-MODE.md) · 🇭🇷 [hr](../../../hr/docs/guides/REMOTE-MODE.md) · 🇭🇺 [hu](../../../hu/docs/guides/REMOTE-MODE.md) · 🇦🇲 [hy](../../../hy/docs/guides/REMOTE-MODE.md) · 🇮🇩 [id](../../../id/docs/guides/REMOTE-MODE.md) · 🇳🇬 [ig](../../../ig/docs/guides/REMOTE-MODE.md) · 🇮🇹 [it](../../../it/docs/guides/REMOTE-MODE.md) · 🇯🇵 [ja](../../../ja/docs/guides/REMOTE-MODE.md) · 🇬🇪 [ka](../../../ka/docs/guides/REMOTE-MODE.md) · 🇰🇭 [km](../../../km/docs/guides/REMOTE-MODE.md) · 🇮🇳 [kn](../../../kn/docs/guides/REMOTE-MODE.md) · 🇰🇷 [ko](../../../ko/docs/guides/REMOTE-MODE.md) · 🇱🇹 [lt](../../../lt/docs/guides/REMOTE-MODE.md) · 🇱🇻 [lv](../../../lv/docs/guides/REMOTE-MODE.md) · 🇮🇳 [ml](../../../ml/docs/guides/REMOTE-MODE.md) · 🇮🇳 [mr](../../../mr/docs/guides/REMOTE-MODE.md) · 🇲🇾 [ms](../../../ms/docs/guides/REMOTE-MODE.md) · 🇲🇹 [mt](../../../mt/docs/guides/REMOTE-MODE.md) · 🇲🇲 [my](../../../my/docs/guides/REMOTE-MODE.md) · 🇳🇵 [ne](../../../ne/docs/guides/REMOTE-MODE.md) · 🇳🇱 [nl](../../../nl/docs/guides/REMOTE-MODE.md) · 🇳🇴 [no](../../../no/docs/guides/REMOTE-MODE.md) · 🇮🇳 [or](../../../or/docs/guides/REMOTE-MODE.md) · 🇮🇳 [pa](../../../pa/docs/guides/REMOTE-MODE.md) · 🇵🇭 [phi](../../../phi/docs/guides/REMOTE-MODE.md) · 🇵🇱 [pl](../../../pl/docs/guides/REMOTE-MODE.md) · 🇵🇹 [pt](../../../pt/docs/guides/REMOTE-MODE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/REMOTE-MODE.md) · 🇷🇴 [ro](../../../ro/docs/guides/REMOTE-MODE.md) · 🇷🇺 [ru](../../../ru/docs/guides/REMOTE-MODE.md) · 🇱🇰 [si](../../../si/docs/guides/REMOTE-MODE.md) · 🇸🇰 [sk](../../../sk/docs/guides/REMOTE-MODE.md) · 🇸🇮 [sl](../../../sl/docs/guides/REMOTE-MODE.md) · 🇷🇸 [sr](../../../sr/docs/guides/REMOTE-MODE.md) · 🇸🇪 [sv](../../../sv/docs/guides/REMOTE-MODE.md) · 🇰🇪 [sw](../../../sw/docs/guides/REMOTE-MODE.md) · 🇮🇳 [ta](../../../ta/docs/guides/REMOTE-MODE.md) · 🇮🇳 [te](../../../te/docs/guides/REMOTE-MODE.md) · 🇹🇭 [th](../../../th/docs/guides/REMOTE-MODE.md) · 🇹🇷 [tr](../../../tr/docs/guides/REMOTE-MODE.md) · 🇵🇰 [ur](../../../ur/docs/guides/REMOTE-MODE.md) · 🇺🇿 [uz](../../../uz/docs/guides/REMOTE-MODE.md) · 🇻🇳 [vi](../../../vi/docs/guides/REMOTE-MODE.md) · 🇳🇬 [yo](../../../yo/docs/guides/REMOTE-MODE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/REMOTE-MODE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/REMOTE-MODE.md) --- Запускайте CLI `omniroute` на своєму ноутбуці, тоді як сам OmniRoute працює деінде (на VPS, домашньому сервері чи іншому комп’ютері у вашій мережі Tailnet). Ви входите один раз за допомогою `omniroute connect`, і відтоді **кожна** команда CLI спрямовується на цей віддалений сервер — ті самі команди, той самий вивід, але виконання відбувається на віддаленому сервері. Не потрібно встановлювати другий інструмент: віддалений режим — це звичайний CLI `omniroute` разом із **токенами доступу** з обмеженою областю дії. ```bash npm install -g omniroute # звичайний CLI omniroute connect 192.168.0.15 # вхід (пароль → токен з обмеженою областю дії) omniroute models list # ← тепер показує моделі ВІДДАЛЕНОГО сервера omniroute configure codex # ← створює локальний профіль Codex із віддаленого каталогу ``` --- ## Як це працює ``` ваш ноутбук віддалений OmniRoute (VPS) ┌────────────────────┐ ┌───────────────────────────────┐ │ CLI omniroute │ POST /api/cli/connect (пароль → токен) │ │ контекст: vps │ ───────────────► │ створює токен доступу з │ │ baseUrl, токен │ Authorization: Bearer oma_live_… │ │ │ ───────────────► │ обмеженою областю дії; кожен │ │ записує конфігурації│ ◄─────────────── │ маршрут керування перевіряється│ │ ЛОКАЛЬНО │ │ згідно з областю дії токена │ └────────────────────┘ └───────────────────────────────┘ ``` - **Контексти** зберігають по одному серверу (`~/.omniroute/config.json`, `chmod 600`). `omniroute contexts use ` перемикає активний сервер; `default` — локальний. - **Токени доступу** (`oma_live_…`) авторизують команди керування. Вони відрізняються від API-ключів для інференсу (`sk-…`, які використовуються для `/v1/chat/completions`). - На сервері зберігається лише SHA-256-хеш токена. Токен у відкритому вигляді показується **лише один раз** під час створення. --- ## Підключення ### За допомогою пароля керування (початкове налаштування) ```bash 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`: ```bash omniroute connect 192.168.0.15 --scope write ``` Параметри: `--port

` (якщо хост не має порту), `--name ` (назва контексту), `--scope read|write|admin`. Повна URL-адреса використовується без змін: `omniroute connect https://omni.example.com`. Якщо на сервері ввімкнено двофакторну автентифікацію панелі керування (Налаштування → Безпека), одного пароля буде недостатньо: CLI попросить код із застосунку-автентифікатора (або код відновлення). Для неінтерактивного використання передайте його заздалегідь за допомогою `--totp `. ### За допомогою попередньо створеного токена Створіть токен із потрібною областю доступу в панелі керування (або за допомогою `omniroute tokens create`) і вставте його — пароль не потрібен: ```bash 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` | читання **+** налаштування/застосування — `setup-codex`, `keys add`, `config set`, комбінації | | `admin` | запис **+** керування — CRUD для `tokens`, додавання провайдерів, сервіси, політики, oauth | Сервер визначає необхідну для кожного маршруту область дії на основі методу HTTP (`GET`→read, зміни→write), а також списку дозволених лише для admin чутливих ресурсів (зміни `/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:/callback`) **доступне з браузера, у якому підтверджується вхід**. У разі встановлення на віддаленому VPS ця циклічна адреса належить серверу, а не вашому комп’ютеру, тому екран згоди **зависає назавжди й ніколи не повертає код** — у звичайному резервному варіанті «вставте 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 `), нічого копіювати не потрібно — помічник сам передасть облікові дані цьому встановленню: ```bash # На вашому ЛОКАЛЬНОМУ комп’ютері (потрібні Node.js і браузер): omniroute connect 192.168.0.15 # один раз — створює токен контексту з правами адміністратора npx omniroute login antigravity # ↳ відкриває екран згоди Google, перехоплює зворотний виклик на локальному циклічному порту, # обмінює його та надсилає облікові дані методом POST до активного контексту: # # Antigravity підключено за адресою http://192.168.0.15:20128 (підключення abc123). # Нічого вставляти не потрібно — цей термінал можна закрити. ``` Надсилання відбувається автоматично щоразу, коли активний контекст указує на інший комп’ютер. Примусово ввімкніть або вимкніть його за допомогою `--push` / `--no-push` або виберіть конкретний контекст за допомогою `--context `. **Якщо ваш комп’ютер не може підключитися до VPS** (через брандмауер, відсутність SSH або ізольоване робоче місце), помічник усе одно працюватиме — фактично йому _потрібен_ лише Google. Використайте `--no-push` або просто дозвольте надсиланню завершитися помилкою: замість скасування вже завершеної авторизації помічник повернеться до виведення блоба. ```bash npx omniroute login antigravity --no-push # omniroute-cred-v1.eyJ2IjoxLCJ... ``` Потім у **віддаленій** панелі керування відкрийте **Providers → Antigravity → Connect** і вставте блоб `omniroute-cred-v1.…` у поле **Step 2** (воно приймає як URL зворотного виклику, так і блоб облікових даних). OmniRoute декодує його, виконає налаштування Cloud Code на сервері та збереже підключення. > Блоб містить токен оновлення — поводьтеся з ним як із паролем. У разі надсилання > він одноразово передається через автентифіковане з’єднання вашого контексту; у > разі вставлення — через з’єднання з панеллю керування. В обох випадках він > зберігається в зашифрованому вигляді, а в разі успішного надсилання ніколи не > виводиться у ваш термінал. Прапорці: `--no-browser` (вивести URL замість автоматичного відкриття), `--port ` (зафіксувати циклічний порт), `--timeout `, `--push` / `--no-push` (перевизначити автоматичне доставлення), `--context ` (вибрати конкретний контекст). ### Варіант B — тунель локального переспрямування SSH Якщо у вас є SSH-доступ до VPS, перенаправте порт панелі керування, щоб циклічний зворотний виклик повертався на сервер через тунель: ```bash # На вашому ЛОКАЛЬНОМУ комп’ютері: 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 завершується, а зворотний виклик доставляється на сервер через той самий тунель — блоб не потрібен. Не закривайте тунель, доки підключення не стане активним. На відміну від наведених нижче провайдерів із фіксованою циклічною адресою, **тут достатньо одного перенаправлення**: зворотний виклик 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-інтерфейс **сервера**. Якщо відкрити панель керування за LAN-адресою на кшталт `http://192.168.0.15:20128`, вони ніколи не з'єднаються: код авторизації буде доставлено на `localhost:1455` вашого ноутбука, де ніщо не прослуховує порт, і провайдер не зможе виконати вхід, не показавши помилки. Панель керування виявляє це до відкриття спливного вікна й показує команду для тунелю, замість того щоб дозволити входу завершитися невдало без повідомлення (#8046). ### Виправлення — перенаправте **обидва** порти ```bash # На машині, де запущено БРАУЗЕР: ssh -L 20128:127.0.0.1:20128 -L 1455:127.0.0.1:1455 @192.168.0.15 # потім перейдіть на http://localhost:20128 і підключіть Codex звідти ``` Потрібні два перенаправлення, і перенаправлення лише одного порту все одно не спрацює: - **`20128`** (порт панелі керування) робить origin справді локальним localhost, що взагалі дає OmniRoute змогу запустити callback-сервер PKCE — LAN-origin ніколи не потрапляє до цієї гілки. - **`1455`** (фіксований callback-порт провайдера) — це порт, на який повертається браузер; його потрібно тунелювати до loopback-інтерфейсу сервера. Замініть `1455` на `56121`/`56122` під час підключення xAI або Grok CLI, а `20128` — на фактичний порт вашої панелі керування. Не закривайте тунель, доки підключення не відобразиться як активне. > **Немає доступу через SSH?** Codex і Grok CLI також приймають вставлений токен — > вкладка **Вставити API-ключ** / **Імпортувати auth.json** у діалоговому вікні > підключення. Цей спосіб не використовує loopback callback, тому працює з будь-якого > origin. Codex також приймає звичайний токен доступу або дані сеансу > `~/.codex/auth.json`. --- ## Керування токенами ```bash omniroute tokens create --name "laptop" --scope write [--expires 30] # ↳ виводить секрет ЛИШЕ раз: скопіюйте його зараз omniroute tokens list # замаскований вивід: id, назва, scope, префікс, статус, строк дії omniroute tokens revoke # відкликати негайно omniroute tokens scopes # пояснити три області доступу ``` Команди `tokens` вимагають облікових даних із правами **admin**. Токени також можна створювати й відкликати на панелі керування: **Налаштування → Access Tokens** (створення, відкликання, копіювання один раз). Токен ніколи не може отримати більше прав, ніж має його творець. Токен з областю `admin` може створити лише оператор: сеанс панелі, локальний CLI на самому сервері або `omniroute connect` з паролем. Машинні облікові дані (токен доступу `admin` або ключ API з областю `manage`/`admin`) можуть створювати лише токени з областями `write` і `read`. Запит на `--scope admin` повертає `403`. Вимкнення входу не відкриває видачу токенів: токен доступу будь-якої області є обліковими даними, які приймають маршрути, що завжди вимагають автентифікації, тож анонімний виклик отримує `401` за будь-якої області. --- ## Налаштування CLI для програмування з віддаленого каталогу `omniroute configure` читає живий каталог моделей **активного сервера** і записує конфігурацію на **вашій** машині. ```bash omniroute configure codex # Провайдери: glm, kmc, ollamacloud, opencode-go, … # Провайдер: glm # ID моделі: glm/glm-5.2 # ✔ Записано ~/.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`, щоб прибрати вибрану модель зі списку цього контексту та цілі. Записаний профіль посилається на ключ інференсу через змінну середовища (`OMNIROUTE_API_KEY`), тож секрет ніколи не записується на диск. Одноразове базове налаштування Codex (блок `[model_providers.omniroute]`) див. у [CODEX-CLI-CONFIGURATION.md](./CODEX-CLI-CONFIGURATION.md). ### Запуск CLI проти віддаленого сервера (конфігурація не записується) `omniroute run ` також враховує активний контекст: базова URL-адреса віддаленого сервера та облікові дані контексту передаються лише процесу, що запускається. ```bash 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 ``` Цілі: `claude`, `codex`, `aider`, `goose`, `opencode`, `qwen`, `gemini` (єдине джерело: `bin/cli/cli-manifest.mjs`). Qwen і Gemini запускаються в тимчасовому ізольованому домашньому каталозі, який видаляється під час виходу, тож запуск ніколи не торкається вашої особистої конфігурації інструментів і не просочується в неї. ### Команди налаштування для кожного CLI Кожен підтримуваний CLI має команду налаштування з урахуванням віддаленого сервера (усі вони враховують активний контекст або `--remote --api-key `): | CLI | Команда | Що записується | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Codex | `omniroute setup-codex` | Профілі `~/.codex/.config.toml` (для кожної моделі) | | Claude Code | `omniroute setup-claude` | `~/.claude/profiles//settings.json` (для кожної моделі) | | OpenCode | `omniroute setup-opencode` | `~/.config/opencode/opencode.json`: провайдер `omniroute` сумісний з OpenAI, з усіма моделями каталогу (запуск: `opencode -m omniroute/`) | | Cline | `omniroute setup-cline` | `~/.cline/data/{globalState,secrets}.json` (режим CLI) + виводить налаштування розширення VS Code для вставлення (сумісність з OpenAI, Base URL **без** `/v1`) | | Kilo Code | `omniroute setup-kilo` | `~/.local/share/kilo/auth.json` (CLI) + налаштування VS Code `kilocode.*`: сумісність з OpenAI, Base 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, Base URL **з** `/v1`) | | Crush | `omniroute setup-crush` | `~/.config/crush/crush.json`: провайдер `openai-compat`, `base_url` **з** `/v1`, ключ через `$OMNIROUTE_API_KEY` | | Zed | `omniroute setup-zed` | `~/.config/zed/settings.json`: `language_models.openai_compatible.omniroute`, `api_url` **з** `/v1`, ключ Zed читає з `$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/`) + рецепт зі змінними середовища (`aider --message --yes`) | | Qwen Code | `omniroute setup-qwen` | Запис `modelProviders.openai` у `~/.qwen/settings.json` (V4) + `OMNIROUTE_API_KEY` у `~/.qwen/.env` | ```bash # 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`: ```bash omniroute contexts list # all contexts; the active one is marked ● omniroute contexts current # the active server, auth status, scope ``` ```text | Name | Base URL | Auth | Scope | Description ● | vps | http://100.67.86.91:20128 | token | admin | Remote OmniRoute (…) | default | http://localhost:20128 | ✗ | | ``` **Перемикання серверів** — кожна наступна команда використовує активний контекст: ```bash omniroute contexts use vps # → all commands now hit the remote VPS omniroute tokens list # (runs against the VPS) omniroute contexts use default # → back to localhost omniroute tokens list # (runs against the local server) ``` **Додати контекст вручну** (замість `connect`), переглянути або перейменувати: ```bash omniroute contexts add staging --url https://staging.example.com:20128 \ --access-token oma_live_xxxx --scope write --description "staging box" omniroute contexts show staging # full details for one context omniroute contexts rename staging stg ``` **Видалити контекст** — запитує підтвердження; передайте `--yes`, щоб пропустити його (необхідно для скриптів / неінтерактивних оболонок, які інакше безпечно відхиляють дію): ```bash omniroute contexts remove stg --yes ``` > `default` (localhost) не може бути видалений. Видалення активного контексту повертає до `default`. Порада: видалення контексту лише видаляє **локально** збережені облікові дані — відкличте токен на сервері за допомогою `omniroute tokens revoke `, щоб фактично припинити доступ. **Експорт / імпорт контекстів** (наприклад, для переміщення між машинами). Експорт за замовчуванням опускає облікові дані, включаючи облікові дані, збережені за допомогою файлового резервування. Використовуйте `--include-secrets` явно, коли потрібна портативна резервна копія, що містить облікові дані: ```bash omniroute contexts export --out contexts.json # redacted; default destination: stdout omniroute contexts export --include-secrets --out private-contexts.json omniroute contexts import contexts.json # overwrite; --merge to keep existing omniroute contexts migrate --yes # move legacy plaintext tokens to keychain ``` `--include-secrets` розв'язує посилання на сховище ключів перед експортом і завершується помилкою, якщо будь-які посилані облікові дані не можуть бути прочитані. `--no-secrets` завжди має пріоритет. Файли експорту записуються атомарно з режимом `0600`. Розглядайте явний експорт, що містить секрети, як секретний матеріал. На безголових системах без придатного сховища ключів ОС, CLI повертається до `config.json` з режимом `0600` і виводить одноразове попередження; експорт за замовчуванням залишається відредагованим у цьому режимі. --- ## Швидка наскрізна перевірка Готовий до копіювання життєвий цикл для перевірки віддаленого налаштування з нуля: підключення, створення токена з обмеженою областю доступу, спрямування команди, повернення назад і видалення налаштування. Замініть `192.168.0.15` на ім’я хоста/IP-адресу вашого сервера (Tailscale, LAN або загальнодоступну URL-адресу `https://…`). ```bash # 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 # скасовує доступ на сервері omniroute contexts remove 192-168-0-15 --yes # видалити локальний контекст (навіть якщо він активний → повернення до default), без запиту ``` > `--yes` робить `contexts remove` неінтерактивною командою (обов’язково для скриптів/CI; без > цього неінтерактивна оболонка безпечно відхилить операцію замість зависання). Після видалення > **активного** контексту автоматично виконується повернення до `default`. --- ## Примітки щодо безпеки - Відкритий текст токена показується лише один раз; зберігається тільки хеш SHA-256 (так само, як для ключів API). - `omniroute connect` повторно використовує блокування після спроб підбору облікових даних для входу та журналювання аудиту. - Для передавання даних надавайте перевагу HTTPS або Tailnet; для адреси без зазначення протоколу за замовчуванням використовується `http://` для зручності роботи в LAN/Tailscale — для TLS передайте повну URL-адресу `https://…`. - Рекомендований локальний файл контекстів — `~/.omniroute/config.json` (`chmod 600`), що містить лише `credentialRef`; сам токен зберігається у сховищі облікових даних ОС (`keytar`) і ніколи не виводиться в журнали. Безінтерфейсні інсталяції без працездатного нативного сховища облікових даних використовують той самий файл із правами `0600` як явно визначений резервний варіант і одноразово виводять попередження. Після встановлення бекенду сховища облікових даних скористайтеся `omniroute contexts migrate --yes`. --- ## Кінцеві точки API (довідка) | Метод | Маршрут | Автентифікація | Область | | ------ | --------------------- | --------------------------- | ------------------------------ | | POST | `/api/cli/connect` | пароль; 2FA, якщо ввімкнено | — (публічна, захищена паролем) | | GET | `/api/cli/whoami` | токен доступу | read | | GET | `/api/cli/tokens` | токен доступу | admin | | POST | `/api/cli/tokens` | токен доступу | admin | | DELETE | `/api/cli/tokens/:id` | токен доступу | admin | Див. [openapi.yaml](../openapi.yaml), щоб переглянути повні схеми.