# Remote Mode (አማርኛ) 🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇺🇦 [uk-UA](../../../uk-UA/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) --- OmniRoute ራሱ በሌላ ቦታ (በVPS፣ በቤት ሰርቨር፣ በTailnetዎ ላይ ባለ ሌላ ማሽን) ላይ እየሰራ፣ `omniroute` CLIን በላፕቶፕዎ ላይ ያስኪዱ። በ`omniroute connect` አንድ ጊዜ ይግቡ፤ ከዚያ በኋላ **እያንዳንዱ** የCLI ትዕዛዝ ያንን የርቀት ሰርቨር ይጠቀማል — ተመሳሳይ ትዕዛዞች፣ ተመሳሳይ ውጤት፣ በርቀት ሰርቨሩ ላይ መፈጸማቸው ብቻ ይለያል። የሚጫን ሁለተኛ መሣሪያ የለም፦ የርቀት ሁነታው መደበኛው `omniroute` CLI ከወሰን ካላቸው **የመዳረሻ ቶከኖች** ጋር ነው። ```bash npm install -g omniroute # መደበኛው CLI omniroute connect 192.168.0.15 # ይግቡ (የይለፍ ቃል → ወሰን ያለው ቶከን) omniroute models list # ← አሁን የርቀት ሰርቨሩን ሞዴሎች ይዘረዝራል omniroute configure codex # ← ከርቀት ካታሎጉ የአካባቢ Codex መገለጫ ይጽፋል ``` --- ## እንዴት እንደሚሰራ ``` የእርስዎ ላፕቶፕ የርቀት OmniRoute (VPS) ┌────────────────────┐ ┌───────────────────────────────┐ │ omniroute CLI │ POST /api/cli/connect (የይለፍ ቃል → ቶከን) │ │ ዐውድ፦ vps │ ───────────────► │ ወሰን ያለው የመዳረሻ ቶከን ይፈጥራል │ │ baseUrl, token │ Authorization: Bearer oma_live_… │ │ │ ───────────────► │ እያንዳንዱ የአስተዳደር መንገድ፣ │ │ ውቅሮችን በአካባቢው │ ◄─────────────── │ በቶከኑ ወሰን መሠረት ይፈተሻል │ │ ይጽፋል │ └───────────────────────────────┘ └────────────────────┘ ``` - **ዐውዶች** እያንዳንዳቸው አንድ ሰርቨር ያከማቻሉ (`~/.omniroute/config.json`፣ `chmod 600`)። `omniroute contexts use ` ንቁውን ሰርቨር ይቀይራል፤ `default` የአካባቢው ሰርቨር ነው። - **የመዳረሻ ቶከኖች** (`oma_live_…`) የአስተዳደር ትዕዛዞችን ይፈቅዳሉ። እነዚህ ከየመገመቻ API ቁልፎች (`sk-…`፣ ለ`/v1/chat/completions` የሚያገለግሉ) የተለዩ ናቸው። - በሰርቨር በኩል የሚከማቸው የቶከኑ SHA-256 hash ብቻ ነው። ግልጽ ጽሑፉ በሚፈጠርበት ጊዜ **አንድ ጊዜ** ብቻ ይታያል። --- ## መገናኘት ### በአስተዳደር የይለፍ ቃል (የመነሻ ማዋቀር) ```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`። ### አስቀድሞ በተፈጠረ ቶከን በዳሽቦርዱ ውስጥ (ወይም `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` | መጻፍ **+** ማስተዳደር — የ`tokens` CRUD፣ አቅራቢዎችን መጨመር፣ አገልግሎቶች፣ ፖሊሲ፣ 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 የፈቃድ ኮዱን የሚለቀው **የloopback ማዘዋወሪያው** (`http://127.0.0.1:/callback`) **መግባቱን ከሚያጸድቀው አሳሽ ሊደረስበት ሲችል ብቻ ነው**። በርቀት VPS ጭነት ላይ ያ loopback ያለው በእርስዎ ማሽን ላይ ሳይሆን በአገልጋዩ ላይ ነው፤ ስለዚህ የፈቃድ መስጫው **ለዘላለም ተንጠልጥሎ ይቀራል እና ምንም ኮድ አያወጣም** — መደበኛው የ"callback URLን ለጥፍ" አማራጭ የሚለጠፍ ነገር አይኖረውም። (ይህ ከGoogle ወገን የሆነ ገደብ ነው፦ በጥቅሉ የቀረበውን Antigravity desktop client በሚጠቀም ማንኛውም proxy ላይ ተመሳሳይ መንጠልጠል ይከሰታል፤ በOmniRoute ላይ ብቻ አይደለም።) dashboardው እርስዎ ከመቆምዎ በፊት ይህን ያውቃል፦ ከlocalhost ውጭ ከሆነ አድራሻ **Providers → Antigravity → Connect**ን ሲከፍቱ፣ አጠቃላዩን "callback URLን ቅዳ" ማሳወቂያ ከታች ባሉት ሁለት መፍትሔዎች ይተካዋል፤ በእያንዳንዱም የእርስዎ host እና port አስቀድመው ተሞልተዋል። (የLAN አድራሻም ይቆጠራል — ይህን callback በተመለከተ `192.168.x.x` localhost አይደለም።) Antigravityን ከርቀት OmniRoute ጋር ለማገናኘት ሁለት የሚደገፉ መንገዶች አሉ። ### አማራጭ A — የአካባቢ መግቢያ ረዳት (የሚመከር) OAuthን `127.0.0.1` ሊደረስበት በሚችልበት **በራስዎ ኮምፒውተር** ላይ ያሂዱ። ረዳቱ በቀጥታ ከGoogle ጋር ይገናኛል፤ ስለዚህ dashboardው ላይ ያለው ስሪት ማጠናቀቅ በማይችልበት ሁኔታ ፈቃድ መስጠቱ በአካባቢው ይጠናቀቃል። **አስቀድመው ተገናኝተው ከሆነ** (`omniroute connect `)፣ የሚቀዱት ምንም ነገር የለም — ረዳቱ credentialን ወደዚያ ጭነት ለእርስዎ ያደርሳል፦ ```bash # በእርስዎ LOCAL ማሽን ላይ (Node.js + አሳሽ ያስፈልጋል)፦ omniroute connect 192.168.0.15 # አንድ ጊዜ — የadmin ወሰን ያለው context token ይፈጥራል npx omniroute login antigravity # ↳ የGoogle ፈቃድ መስጫውን ይከፍታል፣ callbackን በአካባቢ loopback port ላይ ይይዛል፣ # ይለዋውጠዋል፣ እና credentialን ወደ ገባሪው context POST ያደርጋል፦ # # Antigravity በhttp://192.168.0.15:20128 ላይ ተገናኝቷል (ግንኙነት abc123)። # የሚለጠፍ ነገር የለም — ይህን terminal መዝጋት ይችላሉ። ``` ገባሪው context ወደ ሌላ ማሽን በሚያመለክትበት ጊዜ ሁሉ pushው በራስ-ሰር ይከናወናል። በ`--push` / `--no-push` በሁለቱም አቅጣጫ ያስገድዱት፣ ወይም በ`--context ` የተወሰነ contextን ዒላማ ያድርጉ። **የእርስዎ ማሽን VPSውን መድረስ ካልቻለ** (በfirewall የታገደ፣ SSH የሌለው፣ ከአውታረ መረብ የተለየ ዴስክ)፣ ረዳቱ አሁንም ይሠራል — በእርግጥ _የሚያስፈልገው_ Googleን ብቻ ነው። `--no-push`ን ይጠቀሙ፣ ወይም pushው እንዲከሽፍ ብቻ ይተዉት፦ አስቀድመው ያጠናቀቁትን ፈቃድ ከመጣል ይልቅ blobውን ወደ ማተም ይመለሳል። ```bash npx omniroute login antigravity --no-push # omniroute-cred-v1.eyJ2IjoxLCJ... ``` ከዚያ በ**ርቀት** dashboard ውስጥ፦ **Providers → Antigravity → Connect**፣ እና የ`omniroute-cred-v1.…` blobን በ**Step 2** መስክ ውስጥ ይለጥፉ (callback URLን ወይም credential blobን ይቀበላል)። OmniRoute ዲኮድ ያደርገዋል፣ Cloud Code onboardingን በአገልጋዩ በኩል ያስኬዳል፣ እና ግንኙነቱን በቋሚነት ያስቀምጣል። > blobው refresh token ይዟል — እንደ የይለፍ ቃል ይያዙት። በpush መንገድ ላይ > በcontextዎ የተረጋገጠ ግንኙነት በኩል አንድ ጊዜ ይላካል፤ በመለጠፍ መንገድ ላይ ደግሞ > በdashboard ግንኙነትዎ በኩል ይላካል። በሁለቱም መንገድ በማከማቻ ላይ በተመሰጠረ መልኩ > ይቀመጣል፣ እና የተሳካ push በterminalዎ ላይ ፈጽሞ አያትመውም። Flags፦ `--no-browser` (URLን በራስ-ሰር ከመክፈት ይልቅ ያትሙት)፣ `--port ` (loopback portን ይወስኑ)፣ `--timeout `፣ `--push` / `--no-push` (ራስ-ሰር ማድረሱን ይሻሩ)፣ `--context ` (የተወሰነ contextን ዒላማ ያድርጉ)። ### አማራጭ B — የSSH local-forward tunnel ወደ VPSው የSSH መዳረሻ ካለዎት፣ loopback callbackው በtunnel በኩል ወደ አገልጋዩ እንዲመለስ dashboard portን forward ያድርጉ፦ ```bash # በእርስዎ LOCAL ማሽን ላይ፦ ssh -L 20128:127.0.0.1:20128 user@your-vps # ከዚያ http://localhost:20128ን በLOCAL አሳሽዎ ይክፈቱ እና Antigravityን # በመደበኛው መንገድ ያገናኙ — የ127.0.0.1:20128/callback ማዘዋወሪያ አሁን በSSH በኩል VPSውን ይደርሳል። ``` dashboardውን እንደ `localhost:20128` ስለሚደርሱበት፣ የGoogle ፈቃድ መስጠቱ ይጠናቀቃል እና callbackው በዚያው tunnel በኩል ወደ አገልጋዩ ይደርሳል — blob አያስፈልግም። ግንኙነቱ ገባሪ እንደሆነ እስኪታይ ድረስ tunnelውን ክፍት ያድርጉት። ከታች ካሉት ቋሚ-loopback providers በተለየ፣ እዚህ **አንድ forward በቂ ነው**፦ የAntigravity callback የdashboard portን ራሱን ይጠቀማል፤ ስለዚህ tunnel ማድረግ ያለብዎት ሁለተኛ provider-specific port የለም። > ሙሉ በሙሉ headless የሆነ አማራጭ (ረዳት የሌለው፣ tunnel የሌለው)፣ የ**ራስዎን** > Google OAuth web credentials + ይፋዊ base URL ማዋቀር ነው፤ የproviderውን OAuth > environment variables ይመልከቱ። ከላይ ያሉት ሁለት አማራጮች ተጨማሪ የGoogle ማዋቀር አያስፈልጋቸውም። --- ## Codex / Grokን በርቀት ጭነት ላይ ማገናኘት (ቋሚ-loopback አቅራቢዎች) Codex፣ xAI (`xai-oauth`) እና Grok CLI (`grok-cli`) ከዋናው OAuth መተግበሪያቸው ጋር **ቋሚ** loopback `redirect_uri` ይመዘግባሉ። 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` ማለት **አሳሹን የሚያስኬደው ማሽን** ሲሆን፣ የOmniRoute PKCE callback አገልጋይ ደግሞ በ**አገልጋዩ** loopback ላይ ያዳምጣል። ዳሽቦርዱን እንደ `http://192.168.0.15:20128` ባለ LAN አድራሻ ላይ ከፈቱ፣ ሁለቱ ፈጽሞ አይገናኙም፦ የፈቃድ ኮዱ ምንም ነገር ወደማያዳምጥበት የራስዎ ላፕቶፕ `localhost:1455` ይላካል፣ እና አቅራቢው ስህተት ሳያሳይ መግባቱን ያሰናክላል። ዳሽቦርዱ popupን ከመክፈቱ በፊት ይህን በመለየት፣ መግባቱ ያለምንም ማሳወቂያ እንዲከሽፍ ከመፍቀድ ይልቅ የtunnel ትዕዛዙን ያሳያል (#8046)። ### መፍትሔ — **ሁለቱንም** ports ወደፊት ያስተላልፉ ```bash # አሳሹን በሚያስኬደው ማሽን ላይ፦ ssh -L 20128:127.0.0.1:20128 -L 1455:127.0.0.1:1455 @192.168.0.15 # ከዚያ http://localhost:20128ን ይክፈቱና Codexን ከዚያ ያገናኙ ``` ሁለት forwards ያስፈልጋሉ፣ አንዱን ብቻ ወደፊት ማስተላለፍ አሁንም አይሠራም፦ - **`20128`** (የዳሽቦርዱ port) originን ትክክለኛ-localhost ያደርገዋል፤ ይህም OmniRoute የPKCE callback አገልጋዩን እንዲያስጀምር የሚያደርገው ነው — የLAN origin ወደዚያ branch ፈጽሞ አይደርስም። - **`1455`** (የአቅራቢው ቋሚ callback port) አሳሹ የሚመለስበት ቦታ ነው፤ በtunnel በኩል ወደ አገልጋዩ loopback መድረስ አለበት። xAI ወይም Grok CLIን ሲያገናኙ `1455`ን በ`56121`/`56122`፣ `20128`ን ደግሞ በእርስዎ ትክክለኛ የዳሽቦርድ port ይቀይሩ። ግንኙነቱ active መሆኑን እስኪያሳይ ድረስ tunnelን ክፍት ያድርጉት። > **የSSH መዳረሻ የለም?** Codex እና Grok CLI የተለጠፈ tokenንም ይቀበላሉ — በconnect dialog ላይ ያለው > **Paste API Key** / **Import auth.json** tab። ይህ መንገድ loopback > callback ስለሌለው ከማንኛውም origin ይሠራል። Codex በተጨማሪ ቀላል access > token ወይም የ`~/.codex/auth.json` session blobን ይቀበላል። --- ## ቶከኖችን ማስተዳደር ```bash omniroute tokens create --name "laptop" --scope write [--expires 30] # ↳ ምስጢሩን አንድ ጊዜ ብቻ ያትማል — አሁን ይቅዱት omniroute tokens list # የተሸፈኑ፦ id, name, scope, prefix, status, expiry omniroute tokens revoke # ወዲያውኑ ይሻር omniroute tokens scopes # ሦስቱን የፈቃድ ወሰኖች ያብራራል ``` የ`tokens` ትዕዛዞች የ**admin** ማረጋገጫ ይፈልጋሉ። በዳሽቦርዱ ውስጥ በ**Settings → Access Tokens** ስርም ቶከኖችን ማስተዳደር ይችላሉ (መፍጠር፣ መሻር፣ አንድ ጊዜ ብቻ መቅዳት)። አንድ ቶከን ከፈጣሪው የፈቃድ ደረጃ የበለጠ ልዩ መብት እንዲኖረው ፈጽሞ ሊመነጭ አይችልም። የ`admin` ቶከን ሊፈጠር የሚችለው በኦፕሬተሩ ብቻ ነው — በዳሽቦርድ ክፍለ ጊዜ፣ በራሱ ሰርቨር ላይ ባለው የአካባቢ CLI፣ በይለፍ ቃሉ `omniroute connect`ን በመጠቀም፣ ወይም መግባት በተሰናከለበት ኢንስታንስ ነው። የማሽን ማረጋገጫዎች (የ`admin` መዳረሻ ቶከን፣ ወይም የ`manage`/`admin` ፈቃድ ወሰን ያለው API ቁልፍ) የ`write` እና `read` ቶከኖችን ብቻ ማመንጨት ይችላሉ፤ `--scope admin` እንዲፈጥሩ መጠየቅ `403` ይመልሳል። ቶከን ከፈጣሪው የበለጠ ፈቃድ ኖሮት ፈጽሞ ሊፈጠር አይችልም። `admin` ቶከን ሊፈጥር የሚችለው ኦፕሬተሩ ብቻ ነው፦ በዳሽቦርድ ክፍለ ጊዜ፣ በአገልጋዩ ራሱ ላይ ባለው የአካባቢ CLI፣ በይለፍ ቃል ከ `omniroute connect` ጋር፣ ወይም መግባት በተሰናከለበት ኢንስታንስ። የማሽን ማረጋገጫዎች (`admin` የመዳረሻ ቶከን ወይም `manage`/`admin` ወሰን ያለው API ቁልፍ) `write` እና `read` ቶከኖችን ብቻ ሊፈጥሩ ይችላሉ፤ በእነሱ `--scope admin` መጠየቅ `403` ይመልሳል። --- ## Coding CLIን ከርቀት catalog ማዋቀር `omniroute configure` የ**active server**ን ቀጥታ model catalog ያነባል እና በ**እርስዎ** ማሽን ላይ config ይጽፋል። ```bash omniroute configure codex # አቅራቢዎች፦ glm, kmc, ollamacloud, opencode-go, … # አቅራቢ፦ glm # Model id፦ glm/glm-5.2 # ✔ ~/.codex/glm52.config.tomlን ጽፏል # እንዲህ ይጠቀሙበት፦ codex --profile glm52 # ከመስተጋብር ውጭ omniroute configure codex --provider glm --model glm/glm-5.2 --name glm52 # በተደጋጋሚ የሚጠቀሙበትን model በinteractive picker አናት ላይ ያቆዩ omniroute configure codex --provider glm --model glm/glm-5.2 --favorite --yes ``` Pickerው model IDsን ብቻ (URLsን ወይም credentialsን ፈጽሞ ሳይሆን) በአካባቢያዊው `model-preferences.json` ፋይል ውስጥ በcontext እና CLI target ተለይተው ያቆያል። Favorites ከቅርብ ጊዜ ምርጫዎች በፊት ይታያሉ፤ የተመረጠ modelን ከዚያ context/target ዝርዝር ለማስወገድ `--unfavorite`ን ይጠቀሙ። የተጻፈው profile የinference keyውን በenv var (`OMNIROUTE_API_KEY`) ይጠቅሳል — secretው ፈጽሞ ወደ disk አይጻፍም። ለአንድ ጊዜው መሠረታዊ Codex setup (የ`[model_providers.omniroute]` block)፣ [CODEX-CLI-CONFIGURATION.md](./CODEX-CLI-CONFIGURATION.md)ን ይመልከቱ። ### CLIን ከርቀቱ ጋር ማስጀመር (ምንም config ሳይጻፍ) `omniroute run ` በተጨማሪ active contextን ያከብራል፦ የርቀቱ base URL እና የcontext credentialው በተጀመረው process ውስጥ ብቻ ይከተታሉ። ```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" # በትክክል ምን እንደሚጀመር ቅድመ-እይታ ያድርጉ (የenv KEY ስሞች ብቻ፣ values ፈጽሞ አይደሉም)፦ omniroute run codex --dry-run --json ``` Targets፦ `claude`፣ `codex`፣ `aider`፣ `goose`፣ `opencode`፣ `qwen`፣ `gemini` (ነጠላ source፦ `bin/cli/cli-manifest.mjs`)። Qwen እና Gemini ሲወጡ በሚወገድ ጊዜያዊ፣ የተነጠለ home ውስጥ ይሠራሉ፤ ስለዚህ ማስጀመሩ የግል tool configurationዎን ፈጽሞ አይነካም — ወይም ወደ ውስጡ መረጃ አያፈስም። ### ለእያንዳንዱ CLI የsetup ትዕዛዞች እያንዳንዱ የሚደገፍ CLI ርቀትን የሚያውቅ setup ትዕዛዝ አለው (ሁሉም active contextን ወይም `--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` — ሁሉንም የካታሎግ ሞዴሎች የያዘው OpenAI-ተኳኋኝ `omniroute` አቅራቢ (`opencode -m omniroute/`ን ያሂዱ) | | Cline | `omniroute setup-cline` | `~/.cline/data/{globalState,secrets}.json` (የCLI ሁነታ) + ወደ VS Code ቅጥያ ቅንብሮች የሚለጠፉትን ያትማል (OpenAI-ተኳኋኝ፣ `/v1` **የሌለበት** መሠረታዊ URL) | | Kilo Code | `omniroute setup-kilo` | `~/.local/share/kilo/auth.json` (CLI) + የVS Code `kilocode.*` ቅንብሮች — OpenAI-ተኳኋኝ፣ `/v1` **ያለበት** መሠረታዊ URL | | Continue | `omniroute setup-continue` | `~/.continue/config.yaml` (VS Code/JetBrains + `cn` CLI) — `provider: openai`፣ `/v1` **ያለበት** `apiBase`፣ ቁልፉ በ`${{ secrets.OMNIROUTE_API_KEY }}` በኩል | | Cursor | `omniroute setup-cursor` | በመተግበሪያው ውስጥ የሚከተሏቸውን ደረጃዎች ያትማል (Settings → Models → `/v1` **ያለበት** Override OpenAI Base URL + ቁልፍ + ሞዴል)። የCursor ውቅር ግልጽ ያልሆነ SQLite ነው — ለውይይት ፓነል ብቻ | | Roo Code | `omniroute setup-roo` | የRoo ማስመጫ JSON (`~/.omniroute/roo-settings.json`) ይጽፋል + `roo-cline.autoImportSettingsPath`ን ያዘጋጃል + የUI ደረጃዎችን ያትማል (OpenAI-ተኳኋኝ፣ `/v1` **ያለበት** መሠረታዊ URL) | | Crush | `omniroute setup-crush` | `~/.config/crush/crush.json` — `openai-compat` አቅራቢ፣ `/v1` **ያለበት** `base_url`፣ ቁልፉ በ`$OMNIROUTE_API_KEY` በኩል | | Goose | `omniroute setup-goose` | `~/.config/goose/config.yaml` (`GOOSE_PROVIDER=openai` + `/v1` **የሌለበት** `OPENAI_HOST` + `GOOSE_MODEL`) + የአካባቢ ተለዋዋጮች መመሪያ | | Aider | `omniroute setup-aider` | `~/.aider.conf.yml` (`/v1` **የሌለበት** `openai-api-base` + `model: openai/`) + የአካባቢ ተለዋዋጮች መመሪያ (`aider --message --yes`) | | Qwen Code | `omniroute setup-qwen` | በ`~/.qwen/settings.json` ውስጥ የV4 `modelProviders.openai` ግቤት + `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ን export ያድርጉ ``` > OpenCode የበለጠ የዳበረ **plugin** ውህደትም አለው፦ `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`ን በአገልጋይዎ host/IP (Tailscale፣ LAN ወይም ይፋዊ `https://…` URL) ይተኩ። ```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 ውስጥ ያስፈልጋል፤ > ያለሱ መስተጋብራዊ ያልሆነ shell ተንጠልጥሎ ከመቆየት ይልቅ በደህና ውድቅ ያደርጋል)። > **ንቁውን** አውድ ማስወገድ በራስ-ሰር ወደ `default` ይመልሳል። --- ## የደህንነት ማስታወሻዎች - የቶክኑ ግልጽ ጽሑፍ አንድ ጊዜ ብቻ ይታያል፤ በቋሚነት የሚቀመጠው የSHA-256 ሃሽ ብቻ ነው (እንደ API ቁልፎች)። - `omniroute connect` የመግቢያ የተደጋጋሚ የግዳጅ ሙከራ መቆለፊያን እና የኦዲት መዝገብ ማስቀመጥን እንደገና ይጠቀማል። - ለመጓጓዣው HTTPS ወይም Tailnet መጠቀም ይመረጣል፤ ፕሮቶኮል ያልተገለጸለት አስተናጋጅ ለLAN/Tailscale ምቾት በነባሪ `http://` ይጠቀማል — ለTLS ሙሉ `https://…` URL ያስገቡ። - ተመራጩ የአካባቢ አውድ ፋይል `~/.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](../openapi.yaml)ን ይመልከቱ።