# CLI Tools — OmniRoute (Kiswahili)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇸🇦 [ar](../../../ar/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇮🇹 [it](../../../it/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇹 [mt](../../../mt/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/CLI-TOOLS.md)

---

Ilisasishwa mwisho: 2026-08-23

OmniRoute inaunganishwa na aina tatu za zana za CLI zilizoenea katika kurasa tatu maalum za dashibodi:

| Ukurasa           | Njia                    | Dhana                                                                                  | Hesabu         |
| ----------------- | ----------------------- | -------------------------------------------------------------------------------------- | -------------- |
| **Kanuni za CLI** | `/dashboard/cli-code`   | Zana za kusimba unazoelekeza kwenye OmniRoute (Mteja → CLI → OmniRoute → Mtoa Huduma)  | 26             |
| **CLI Mawakala**  | `/dashboard/cli-agents` | Mawakala wanaojitegemea unaowaelekezea OmniRoute (mtiririko sawa, wigo mpana)          | 11             |
| **ACP Mawakala**  | `/dashboard/acp-agents` | CLIs ambayo OmniRoute hutoka kama njia ya nyuma kupitia stdio/ACP (mtiririko wa nyuma) | tazama Usajili |

Njia za urithi zimeelekezwa kwingine kupitia 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`.

---

## Jinsi Inavyofanya Kazi

```
Misimbo ya CLI / Mawakala wa CLI (mtiririko wa matumizi):
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
           │
           ▼  (zote zinaelekezwa kwa OmniRoute)
    http://YOUR_SERVER:20128/v1
           │
           ▼  (OmniRoute huelekeza kwa mtoa huduma anayefaa)
    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...

Mawakala wa ACP (mtiririko wa uanzishaji wa kinyume):
    Ombi la mteja → OmniRoute → huanzisha CLI kupitia stdio/ACP → jibu
```

**Faida:**

- Ufunguo mmoja wa API wa kudhibiti zana zote
- Ufuatiliaji wa gharama katika CLI zote kwenye dashibodi
- Kubadilisha modeli bila kusanidi upya kila zana
- Hufanya kazi ndani ya mashine na kwenye seva za mbali (VPS, Docker, Akamai, Cloudflare Tunnel)

---

## Sanidi kiotomatiki na `setup-*`

Sio lazima uandike usanidi wa kila chombo kwa mkono. OmniRoute husafirisha amri `setup-*` kwa kila CLI inayoungwa mkono ambayo inasoma faili ya** kuishi** orodha ya mfano kutoka kwa OmniRoute inayoendesha (ya ndani au ya mbali) na huandika usanidi wa chombo kwenye mashine yako:

```bash
omniroute setup-codex        omniroute setup-claude       omniroute setup-opencode
omniroute setup-cline        omniroute setup-kilo         omniroute setup-continue
omniroute setup-cursor       omniroute setup-roo          omniroute setup-crush
omniroute setup-goose        omniroute setup-qwen         omniroute setup-aider
omniroute setup-5dive        omniroute setup-zed
omniroute setup-whycodes
```

Kila mmoja anakubali `--remote <url> --api-key <key>` (sanidi zana ya ndani dhidi ya OmniRoute ya mbali ), `--dry-run` (hakiki bila kuandika), na `--port`. Zana zisizo na muundo wa ugunduzi otomatiki (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive, WhyCodes) huchukua `--model <id>` (na `--yes` kwa mikimbio zisizoingiliana). `setup-5dive` ndio kichocheo kimoja ambacho hakiandiki chini ya `$HOME`: inasanidi kundi la wakala wa 5dive kwa kuandika wasifu wa uthibitisho unaomilikiwa na mizizi kwenye seva pangishi ya meli, kwa hivyo inatekeleza tena `sudo` na haina hali yake ya mbali. Ili kuzindua CLI na env sahihi iliyochomwa na hakuna usanidi ulioandikwa hata kidogo, tumia kizindua `omniroute run <target>` cha kawaida (claude, codex, aider, goose, opencode, qwen, gemini, whycodes - shabaha na lakabu hutoka kwa `bin/cli/cli-manifest.mjs`); vizindua vya urithi kwa kila chombo `omniroute launch` ( Msimbo wa Claude ) na `omniroute launch-codex` (Codex) vinaendelea kupatikana. Gemini CLI ni ya uzinduzi pekee: ni shabaha `omniroute run` lakini haina kichocheo cha `setup-*`/`configure`.

> **Rejea kamili:** jedwali kuu - kile ambacho kila amri inaandika, kila bendera, ya ndani dhidi ya kijijini, na ni zana zipi zinazotaka kiambishi tamati `/v1` - huishi ndani** [Ushirikiano wa CLI](../guides/CLI-INTEGRATIONS.md)** .

### Kuendesha hizi ndani ya chombo

Amri `setup-*` iliyotekelezwa ndani ya kontena OmniRoute huandika kwenye nyumba ya kontena yenyewe, ambayo hakuna mwenyeji CLI anayesoma na ambayo hutoweka na kontena. OmniRoute hugundua hilo na kutoka `2` na maagizo badala ya kuandika. Njia mbili zinazotumika mbele - sakinisha CLI kwenye seva pangishi na `omniroute connect` kwenye kontena, au funga dirs za usanidi na uweke `CLI_CONFIG_HOME` (wasifu `host` ). Kila amri ya `setup-*`, pamoja na `omniroute configure` na `omniroute config set`, inakubali `--allow-container-write` wakati wa kusanidi CLIs ya chombo ndicho ulichomaanisha; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` hufanya vivyo hivyo kwa seva. Tazama [Mwongozo wa Docker → Inasanidi zana za CLI za mwenyeji](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker).

Dashibodi ya** tumia mwisho** (`POST /api/cli-tools/apply`) hutekeleza mlinzi sawa: kwenye chombo, maandishi ambayo lengo lake halijafungwa kutoka kwa majibu ya mwenyeji.**`422`** na `containerEphemeralTarget: true`, maandishi ya hitilafu salama na - kwa zana zilizo na kichocheo cha mwenyeji (claude, codex, opencode, cline, kilo, endelea) - `hostSetupCommand` (km `omniroute setup-opencode`) ili kuendeshwa kwa seva pangishi badala yake; hakuna kilichoandikwa. `dryRun: true` huendelea kufanya kazi katika modi ya kontena na hurejesha onyesho la kukagua + njia inayolengwa bila kugusa diski. Onyesho la kukagua maudhui sio usanidi unaobeba kitambulisho ili kunakili au kuleta. Omba na ingizo asilia tool/base URL/API key/model kwenye seva pangishi, au tumia amri iliyoonyeshwa ya usanidi wa upande wa mpangishi. Tazama [usalama wa usanidi wa CLI](../security/CLI-CONFIGURATION.md) kwa kichwa cha onyesho la kukagua na ombi la mkataba. Tabia hii ni ya kimakusudi na imelindwa na `tests/unit/api/cli-tools/apply-container-guard.test.ts` - kamwe "usirekebishe" 422 kwa kuondoa mlinzi.

---

## Chanzo Rasmi cha Taarifa

Katalogi iliyounganishwa ipo katika `src/shared/constants/cliTools.ts` kama `CLI_TOOLS: Record<string, CliCatalogEntry>`.

Kila ingizo lina sehemu hizi (zilizofafanuliwa katika `src/shared/schemas/cliCatalog.ts`):

| Sehemu                                          | Aina                                                         | Maelezo                                                            |
| ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| `category`                                      | `"code" \| "agent"`                                          | Ukurasa ambao zana inaonekana                                      |
| `vendor`                                        | `string`                                                     | Asili ya zana ("Anthropic", "OSS (P. Gauthier)")                   |
| `acpSpawnable`                                  | `boolean`                                                    | Pia inaweza kutumika kama ACP Agent (beji inaonyeshwa)             |
| `baseUrlSupport`                                | `"full" \| "partial" \| "none"`                              | Kiwango cha usaidizi wa endpoint maalum. `"none"` = foleni ya MITM |
| `configType`                                    | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Utaratibu wa usanidi                                               |
| `id`, `name`, `color`, `description`, `docsUrl` | kawaida                                                      | Sehemu kuu za uonyeshaji                                           |

Maingizo yenye `baseUrlSupport: "none"` **hayaonyeshwi** katika kurasa za dashibodi — yamesajiliwa kwenye foleni ya MITM kwa mpango wa 11 (angalia `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`).

### Viwango vya uwezo (vilivyoorodheshwa × vinavyotambulika × vinavyosanidika × vinavyoweza kuzinduliwa)

Si kila zana iliyoorodheshwa inaweza kutambuliwa, kusanidiwa au kuzinduliwa. Kila kiwango kina
chanzo kimoja cha utangazaji, na jaribio la mkengeuko huviweka katika uwiano:

| Kiwango                 | Maana                                                                               | Kimetangazwa katika                                                          |
| ----------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Imeorodheshwa**       | Huonekana katika katalogi ya dashibodi (jina, msambazaji, nyaraka, aina ya usanidi) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`)                             |
| **Inatambulika**        | Utambuzi wa binary/usanidi, ukaguzi wa afya, njia za usanidi                        | `src/shared/services/cliRuntime.ts` (katalogi ya utekelezaji ya `CLI_TOOLS`) |
| **Inasanidika**         | Inatumika na `omniroute configure <cli>` (kichocheo cha usanidi kipo)               | `bin/cli/cli-manifest.mjs` (`configure: true`)                               |
| **Inaweza kuzinduliwa** | Inatumika na `omniroute run <target>` (uingizaji wa env/args umefafanuliwa)         | `bin/cli/cli-manifest.mjs` (`run: true`)                                     |

`bin/cli/cli-manifest.mjs` ndiyo manifesti tekelezi rasmi kwa sehemu za amri za CLI:
`run`, `configure` na vizalishaji vya ukamilishaji wa shell vyote hupata orodha zao
za malengo, utatuzi wa majina mbadala (kwa mfano `kilocode`/`kilo-code`/`kilo_cli` → `kilo`)
na uunganishaji wa bendera ya `--model` kutoka humo. Kilinzi cha mkengeuko
`tests/unit/cli/cli-manifest-drift.test.ts` huthibitisha kwamba manifesti, katalogi ya utekelezaji,
katalogi ya UI na kila sehemu inayotumia hubaki katika uwiano — lengo lililoongezwa kwenye
sehemu moja bila nyingine husababisha mkusanyiko wa majaribio kushindwa badala ya kukengeuka kimyakimya.

---

## 1. Katalogi ya Msimbo wa CLI (zana 28)

Zana zote zinazoonekana katika `/dashboard/cli-code`. Zile zilizo na `baseUrlSupport: none` zimeunganishwa kupitia MITM au mwongozo wa mwongozo badala ya msingi maalum URL:

| kitambulisho | jina                                | mchuuzi                 | baseUrlSupport | configType    | acpSpawnable |
| ------------ | ----------------------------------- | ----------------------- | -------------- | ------------- | ------------ |
| claude       | nambari Claude                      | Anthropic               | kamili         | env           | kweli        |
| kodeksi      | OpenAI Codex CLI                    | OpenAI                  | kamili         | desturi       | kweli        |
| zcode        | ZCode ( Mpango wa Usimbaji wa GLM ) | Z.ai                    | hakuna         | desturi       | uongo        |
| cline        | Cline                               | OSS (zamani Claude Dev) | kamili         | desturi       | kweli        |
| kilo         | Msimbo wa Kilo                      | Kilo-Org                | kamili         | desturi       | uongo        |
| roo          | Msimbo wa Roo                       | Roo (OSS)               | kamili         | mwongozo      | uongo        |
| endelea      | Endelea                             | endelea.dev             | kamili         | mwongozo      | uongo        |
| msaidizi     | Msaidizi                            | OSS (P. Gauthier)       | kamili         | mwongozo      | kweli        |
| ghushi       | ForgeCode                           | Antinomy HQ             | kamili         | desturi       | kweli        |
| jcode        | jcode                               | 1 jehuang (OSS)         | kamili         | desturi       | uongo        |
| deepseek-tui | DeepSeek TUI                        | Hunter Bown (OSS)       | kamili         | desturi       | uongo        |
| codewhale    | CodeWhale                           | Hmbown (OSS)            | kamili         | desturi       | uongo        |
| msimbo wazi  | OpenCode                            | Ajabu (zamani SST)      | kamili         | mwongozo      | kweli        |
| droid        | Kiwanda cha Droid                   | Kiwanda AI              | sehemu         | mwongozo      | uongo        |
| rubani       | GitHub Copilot CLI                  | GitHub/MS               | kamili         | desturi       | uongo        |
| mshale-cli   | Cursor CLI                          | Mazingira yoyote        | sehemu         | mwongozo      | kweli        |
| kunusa       | Smelt                               | leonardcser (OSS)       | kamili         | desturi       | uongo        |
| pi           | Pi (pi-coding-wakala)               | M. Zechner (OSS)        | kamili         | desturi       | uongo        |
| grok-kujenga | Grok Kujenga                        | xAI                     | kamili         | desturi       | uongo        |
| kuponda      | Ponda                               | OSS (Upendezi)          | kamili         | desturi       | uongo        |
| qwen         | nambari Qwen                        | Alibaba                 | kamili         | mwongozo      | kweli        |
| wazi         | OpenClaude                          | Gitlawb (OSS)           | kamili         | mwongozo      | uongo        |
| zed          | Zed                                 | Zed Viwanda             | kamili         | mwongozo      | uongo        |
| mshale       | Cursor                              | Mazingira yoyote        | hakuna         | mwongozo      | uongo        |
| antigravity  | Antigravity                         | Google                  | hakuna         | mitm          | uongo        |
| hermes       | Hermes                              | Utafiti wetu            | hakuna         | mwongozo      | uongo        |
| kiro         | Kiro AI                             | Amazon                  | hakuna         | mitm          | uongo        |
| desturi      | CLI maalum                          | —                       | kamili         | mjenzi maalum | uongo        |

Zana zilizo na `baseUrlSupport: "partial"` zinaonyesha beji "⚠ Base URL parcial" kwenye kadi ya dashibodi.
---

## 2. Katalogi ya Mawakala wa CLI (zana 11)

Ajenti zinazojitegemea zinazoonekana katika `/dashboard/cli-agents`:

| kitambulisho     | jina             | mchuuzi                  | msingiUrlSupport | acpSpawnable |
| ---------------- | ---------------- | ------------------------ | ---------------- | ------------ |
| wakala wa hermes | Wakala wa Hermes | Utafiti wetu             | kamili           | uongo        |
| ukucha wazi      | OpenClaw         | OSS (P. Steinberger)     | kamili           | kweli        |
| goose            | Goose            | Block / Linux Foundation | kamili           | kweli        |
| mkalimani        | Fungua Mkalimani | OSS                      | kamili           | kweli        |
| vita             | Warp AI          | Warp Inc.                | sehemu           | kweli        |
| wakala-staha     | Sitaha ya wakala | asheshgoplani (OSS)      | kamili           | uongo        |
| omp              | Oh Pi yangu      | OSS                      | kamili           | kweli        |
| leta             | Letta CLI        | Letta                    | kamili           | uongo        |
| wakala mkuu      | Wakala Mkuu      | Akili Mkuu (OSS)         | kamili           | uongo        |
| 5 kupiga mbizi   | 5 kupiga mbizi   | OSS (5 dive-ai)          | kamili           | uongo        |
| kwa nini misimbo | WhyCodes         | Kwa nini Shirika         | kamili           | uongo        |

---

## 3. Mawakala wa ACP (/dashboard/acp-agents)

Ukurasa huu (uliobadilishwa jina kutoka `/dashboard/agents`) unaonyesha CLI ambazo OmniRoute inaweza **kuanzisha** kama injini za utekelezaji za upande wa nyuma kupitia itifaki ya stdio/ACP. Katalogi inadumishwa kando katika `src/lib/acp/registry.ts` na **si** sawa na `CLI_TOOLS`.

---

## 4. Orodha ya Kazi Zinazosubiri za MITM (haionyeshwi kwenye dashibodi)

CLI zifuatazo hazitumii URL maalum ya msingi moja kwa moja na **hazijaorodheshwa** katika kurasa za CLI Code au CLI Agents. Ni wagombea wa kunaswa na MITM katika mpango wa 11:

| CLI                 | Sababu                                                                   |
| ------------------- | ------------------------------------------------------------------------ |
| windsurf            | BYOK imewekewa mipaka kwa miundo teule ya Claude + URL/tokeni ya shirika |
| amp                 | Mfumo funge (Sourcegraph)                                                |
| amazon-q / kiro-cli | Uthibitishaji wa AWS SSO, hakuna URL maalum                              |
| cowork              | Anthropic Desktop, hakuna endpoint inayoweza kusanidiwa                  |

Tazama `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` kwa marejeleo mtambuka kamili.

---

## 5. API ya Ugunduzi wa Kundi

Ugunduzi wote wa zana unakusanywa kupitia endpoint moja:

**`GET /api/cli-tools/all-statuses`**

- Uthibitishaji: `requireCliToolsAuth(request)` (sawa na njia nyingine za `/api/cli-tools/`)
- Hurejesha: `Record<toolId, ToolBatchStatus>` (aina: `src/shared/types/cliBatchStatus.ts`)
- Mkakati: `Promise.all` kwenye zana zote, muda wa kuisha wa sekunde 5 kwa kila zana
- Akiba: LRU ya ndani ya kumbukumbu iliyoorodheshwa kwa `mtime` ya faili ya usanidi. Akiba hubatilishwa `mtime` inapobadilika. Huwekwa upya seva inapoanzishwa upya.

Muundo wa jibu kwa kila zana:

```ts
interface ToolBatchStatus {
  detection: {
    installed: boolean;
    runnable: boolean;
    version?: string;
    command?: string;
    commandPath?: string;
    reason?: string;
  };
  config: {
    status: "configured" | "not_configured" | "not_installed" | "unknown" | "other";
    endpoint?: string | null;
    lastConfiguredAt?: string | null;
  };
  error?: string; // imesafishwa, hakuna ufuatiliaji wa mrundikano
}
```

---

## 6. Vishikizi vya Mipangilio kwa Zana Mpya

Zana mpya zilizo na `configType: "custom"` zina njia maalum za mipangilio API :

| Njia                                        | Zana                                                                        |
| ------------------------------------------- | --------------------------------------------------------------------------- |
| `POST /api/cli-tools/forge-settings`        | ForgeCode (.forge.toml)                                                     |
| `POST /api/cli-tools/jcode-settings`        | jcode ( bendera --base-url )                                                |
| `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, urithi)                                      |
| `POST /api/cli-tools/codewhale-settings`    | CodeWhale (OPENAI_BASE_URL, usawazishaji wa msingi wa + `~/.deepseek` )     |
| `POST /api/cli-tools/smelt-settings`        | Smelt                                                                       |
| `POST /api/cli-tools/pi-settings`           | Wakala wa usimbaji wa Pi (`~/.pi/agent/models.json`, `providers.omniroute`) |
| `POST /api/cli-tools/grok-build-settings`   | Grok Jenga (~/.grok/config.toml, `[model.omniroute]`)                       |
| `POST /api/cli-tools/qwen-settings`         | msimbo wa Qwen (`~/.qwen/settings.json` + ufunguo maalum `.env` )           |

Njia zote hutumia `sanitizeErrorMessage()` kwa majibu ya makosa (Kanuni Ngumu #12).

---

## 7. Muundo wa Kurasa za Dashibodi

### Misimbo ya CLI (`/dashboard/cli-code`)

- `src/app/(dashboard)/dashboard/cli-code/page.tsx` — kijenzi cha seva
- `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — gridi ya mteja
- `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — ukurasa wa maelezo ya zana
- `src/app/(dashboard)/dashboard/cli-code/components/` — kadi 12 maalumu za zana + `ToolDetailClient.tsx`

### Ajenti za CLI (`/dashboard/cli-agents`)

- `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — kijenzi cha seva
- `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — gridi ya mteja
- `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — hutumia tena `ToolDetailClient`

### Ajenti za ACP (`/dashboard/acp-agents`)

- `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — kijenzi cha seva (kimehamishwa kutoka `agents/`)

### Vijenzi vya UI Vinavyoshirikiwa (`src/shared/components/cli/`)

| Faili                   | Kusudi                                                      |
| ----------------------- | ----------------------------------------------------------- |
| `CliToolCard.tsx`       | Kadi mahiri ya hali (utambuzi + usanidi + sehemu ya mwisho) |
| `CliConceptCard.tsx`    | Kadi ya ufafanuzi wa dhana kwa kila ukurasa                 |
| `CliComparisonCard.tsx` | Ulinganisho wa safu tatu kati ya aina za CLI                |
| `BaseUrlSelect.tsx`     | Orodha kunjuzi ya sehemu ya mwisho (Ya Ndani/Wingu/Maalumu) |
| `ApiKeySelect.tsx`      | Kiteuzi cha ufunguo wa API                                  |
| `ManualConfigModal.tsx` | Dirisha la msimbo wa usanidi unaoweza kunakiliwa            |

### Hook Inayoshirikiwa (`src/shared/hooks/cli/`)

| Faili                     | Kusudi                                                                           |
| ------------------------- | -------------------------------------------------------------------------------- |
| `useToolBatchStatuses.ts` | Huleta `/api/cli-tools/all-statuses`, hudhibiti hali ya upakiaji/uonyeshaji upya |

---

## 8. i18n

Nafasi mpya za majina zilizoongezwa katika mpango 14 F9:

| Nafasi ya majina | Kusudi                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `cliCommon`      | Mifuatano inayoshirikiwa (lebo za kadi, maandishi ya dhana/ulinganisho, lebo za ukurasa wa maelezo) |
| `cliCode`        | Mifuatano ya ukurasa wa CLI Code                                                                    |
| `cliAgents`      | Mifuatano ya ukurasa wa CLI Agents                                                                  |
| `acpAgents`      | Mifuatano ya ukurasa wa ACP Agents                                                                  |

Tafsiri kamili za PT-BR na EN zimetolewa. Lugha nyingine 39 hutumia EN kiotomatiki kupitia uunganishaji katika kiwango cha nafasi ya majina ndani ya `src/i18n/request.ts`.

---

## 9. Anza Haraka

### Hatua ya 1 — Pata Ufunguo wa OmniRoute API

1. Fungua `/dashboard/api-manager` →** Unda Ufunguo wa API**
2. Ipe jina (km `cli-tools`) na uchague ruhusa zote
3. Nakili ufunguo — utahitaji kwa kila CLI hapa chini

> Ufunguo wako unaonekana kama: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`

---

### Hatua ya 2 — Sakinisha Zana CLI

Zana zote za npm zinahitaji Node.js 22.22.2 + au 24.x:

```bash
# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# OpenAI Codex
npm install -g @openai/codex

# OpenCode
npm install -g opencode-ai

# Cline
npm install -g cline

# KiloCode
npm install -g kilocode

# Qwen Code
npm install -g @qwen-code/qwen-code

# Google Gemini CLI (launchable via `omniroute run gemini` → /v1beta surface)
npm install -g @google/gemini-cli

# Aider
pip install aider-chat

# Smelt
cargo install smelt  # Rust-based

# Pi coding agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# jcode
# see https://github.com/1jehuang/jcode for install
```

---

### Hatua ya 3 — Sanidi kupitia Dashibodi

1. Nenda kwa `http://localhost:20128/dashboard/cli-code`
2. Pata zana yako kwenye gridi ya taifa
3. Bofya kadi ili kufungua ukurasa wa maelezo ya zana
4. Chagua ufunguo wako API na msingi URL
5. Bofya** Tekeleza Usanidi** au nakili kijisehemu cha usanidi mwongozo

---

### Hatua ya 4 — Vigeu vya Mazingira Ulimwenguni

```bash
# OmniRoute Universal Endpoint
export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="sk-your-omniroute-key"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key"
# Gemini CLI reads GOOGLE_GEMINI_BASE_URL at the ROOT (its SDK appends /v1beta/... itself)
export GOOGLE_GEMINI_BASE_URL="http://localhost:20128"
export GEMINI_API_KEY="sk-your-omniroute-key"
```

> Kwa a** seva ya mbali** badilisha `localhost:20128` na seva IP au kikoa, kwa mfano `http://<your-server-ip>:20128`.

---

### Hatua ya 4 — Sanidi Kila Zana

#### nambari Claude

```bash
# Create ~/.claude/settings.json:
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"
  }
}
EOF
```

Tumia mzizi uliounganishwa wa lango la Anthropic kwa Msimbo wa Claude. Usiambatishe `/v1` hapa.

**Mtihani:** `claude "say hello"`

---

#### OpenAI Codex

Codex ya kisasa (v0.137 +) inasoma `~/.codex/config.toml` tu — `config.yaml` ya zamani ni ya urithi wa npm CLI na inapuuzwa kimya kimya. Kitufe API hukaa katika utofauti wa mazingira `OMNIROUTE_API_KEY` (`env_key`), kamwe ndani ya faili:

```bash
mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF
model_provider = "omniroute"

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://localhost:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
EOF
export OMNIROUTE_API_KEY="sk-your-omniroute-key"
```

Rejea kamili (wasifu, `wire_api`, madirisha ya muktadha): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md).

**Mtihani:** `codex "what is 2+2?"`

---

#### OpenCode

```bash
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF
{
  "\$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "sk-your-omniroute-key"
      },
      "models": {
        "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" },
        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
        "gemini-3-flash": { "name": "gemini-3-flash" }
      }
    }
  }
}
EOF
```

**Mtihani:** `opencode`

> Tumia `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` kutuma anuwai za kufikiria.

---

#### Wakala wa Usimbaji wa Pi

Sakinisha kifurushi rasmi cha Wakala wa Usimbaji wa Pi na `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`. Pi husoma watoa huduma maalum kutoka `~/.pi/agent/models.json`; weka `PI_CODING_AGENT_DIR` kusogeza saraka nzima ya wakala. Dashibodi inafuata ubatilishaji huo. Pi haigundui miundo kutoka kwa sehemu maalum za mwisho, kwa hivyo OmniRoute huandika muundo uliochaguliwa katika `models[]` kwa kutumia `openai-completions` API ya Pi na sehemu ya mwisho ya OmniRoute OpenAI-patanifu `/v1`.

Katika**CLI Zana → Pi** , chagua sehemu ya mwisho, ufunguo wa API na muundo, kagua onyesho la kuchungulia la mtoa huduma, kisha utumie. Onyesho la kukagua ni kipande cha mtoa huduma: unganisha `providers.omniroute` kwenye `models.json` yako iliyopo wakati wa kusanidi Pi mwenyewe ili watoa huduma wengine na mipangilio ibaki sawa.

```json
{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "omniroute": {
      "baseUrl": "http://localhost:20128/v1",
      "api": "openai-completions",
      "apiKey": "sk-your-omniroute-key",
      "omnirouteManaged": true,
      "models": [{ "id": "auto/best-coding", "name": "auto/best-coding" }]
    }
  }
}
```

Pi hupakia tena `models.json` unapofungua `/model`. Jaribu njia iliyosanidiwa kwa kitambulisho cha mtoa huduma na kitambulisho cha modeli ulichochagua:

```bash
pi --provider omniroute --model auto/best-coding --print "Reply with a short greeting."
```

Marejeleo: [Miundo ya Pi na watoa huduma maalum](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md), [Vigeu vya mazingira vya Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/environment-variables.md), [maagizo ya usakinishaji wa Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md).

---

#### Cline ( msimbo CLI au VS )

**hali ya CLI :**

```bash
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
{
  "apiProvider": "openai",
  "openAiBaseUrl": "http://localhost:20128/v1",
  "openAiApiKey": "sk-your-omniroute-key"
}
EOF
```

**Njia ya msimbo wa VS :** mipangilio ya kiendelezi ya Cline → API huduma: `OpenAI Compatible` → Msingi URL: `http://localhost:20128/v1`

Au tumia OmniRoute dashibodi →**CLI → Cline → Tekeleza Usanidi** .

---

#### KiloCode ( msimbo CLI au VS )

**hali ya CLI :**

```bash
kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
```

**Mipangilio ya nambari VS :**

```json
{
  "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
  "kilo-code.apiKey": "sk-your-omniroute-key"
}
```

Au tumia OmniRoute dashibodi →**CLI → KiloCode → Tekeleza Usanidi** .

---

#### Endelea (VS Kiendelezi cha Msimbo)

Hariri `~/.continue/config.yaml`:

```yaml
models:
  - name: OmniRoute
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: sk-your-omniroute-key
    default: true
```

Anzisha tena Msimbo VS baada ya kuhariri.

---

#### VS Code Insiders (`chatLanguageModels.json`)

Tumia hii wakati VS Code Insiders imesanidiwa kwa miundo maalum ya mwisho na unataka OmniRoute ifanye kazi bila uga maalum wa kichwa.

**Eneo linalopendekezwa:**

- Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json`
- Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json`

**Mfano kwa kutumia jina la OmniRoute la ishara:**

```json
[
  {
    "vendor": "customendpoint",
    "id": "auto",
    "name": "OmniRoute Auto",
    "family": "gpt-4",
    "version": "1.0.0",
    "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions",
    "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models",
    "requestFormat": "openai-chat-completions",
    "contextWindow": 256000,
    "maxOutputTokens": 32768,
    "auth": {
      "type": "none"
    }
  }
]
```

**Vidokezo:**

- Badilisha `sk-your-omniroute-key` na kitufe cha API kilichoundwa OmniRoute.
- Sehemu ya `url` inapaswa kuelekeza kwa `/api/v1/vscode/{token}/chat/completions`.
- Sehemu ya `modelsUrl` inapaswa kuelekeza kwa `/api/v1/vscode/{token}/models`.
- Pendelea mtiririko wa kawaida wa kichwa cha `/v1` + mteja wakati mteja anatumia vichwa maalum.
- Tokeni zilizopachikwa URL ni njia mbadala ya uoanifu na zinaweza kuonekana katika kumbukumbu za wahariri au historia ya seva mbadala.

---

#### Kiro CLI (Amazon)

```bash
# Login to your AWS/Kiro account:
kiro-cli login

# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.
# Use kiro-cli alongside OmniRoute for other tools.
kiro-cli status
```

Kwa ajili ya**Kiro IDE** programu ya desktop, tumia mwisho wa MITM uliofunuliwa na OmniRoute chini `/dashboard/cli-tools → Kiro`.

---

## 10. CLI ya Ndani ya OmniRoute

Faili tekelezi ya `omniroute` hutoa amri za mzunguko wa maisha wa seva, usanidi, uchunguzi, na usimamizi wa watoa huduma. Sehemu ya kuanzia: `bin/omniroute.mjs`.

```bash
omniroute                              # Anzisha seva (mlango chaguo-msingi 20128)
omniroute setup                        # Msaidizi shirikishi wa usanidi
omniroute doctor                       # Kagua usanidi, DB, milango, mazingira ya utekelezaji
omniroute providers list               # Miunganisho ya watoa huduma iliyosanidiwa
omniroute providers test-all           # Jaribu kila muunganisho unaotumika
omniroute reset-password               # Weka upya nenosiri la msimamizi
omniroute logs                         # Tiririsha kumbukumbu za maombi
omniroute health                       # Hali ya kina (vikatiza mzunguko, akiba, kumbukumbu)
omniroute --version                    # Chapisha toleo
omniroute --help                       # Onyesha amri zote
```

### Usanidi na Uanzishaji

```bash
omniroute setup                        # Msaidizi shirikishi wa usanidi
omniroute setup --non-interactive      # Hali ya CI/otomatiki (husoma vigezo vya mazingira + bendera)
omniroute setup --password '<value>'   # Weka nenosiri la msimamizi moja kwa moja
omniroute setup --add-provider \
  --provider openai \
  --api-key '<value>' \
  --test-provider                      # Ongeza na ujaribu mtoa huduma kwa hatua moja
```

Vigezo vya mazingira vinavyotambuliwa kwa usanidi usio shirikishi:

| Kigezo              | Kusudi                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------- |
| `OMNIROUTE_API_KEY` | Ufunguo wa API wa mtoa huduma (umeunganishwa na `--api-key` kupitia Commander `.env()`) |
| `DATA_DIR`          | Batilisha saraka ya data ya OmniRoute                                                   |

Ingizo lingine lote lisilo shirikishi hupitishwa kama bendera, si vigezo vya mazingira:
`--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model`
(tazama chaguo za `omniroute setup` hapo juu).

### Uchunguzi

```bash
omniroute doctor                       # Kagua usanidi, DB, milango, mazingira ya utekelezaji, kumbukumbu, na uhai
omniroute doctor --json                # JSON inayoweza kusomwa na mashine
omniroute doctor --no-liveness         # Ruka uchunguzi wa afya wa HTTP
omniroute doctor --host 0.0.0.0        # Batilisha hosti ya ukaguzi wa uhai
omniroute doctor --liveness-url <url>  # Batilisha URL kamili ya ncha-tumizi ya afya
```

Amri ya doctor huendesha ukaguzi huu: `Config`, `Database`, `Storage/encryption`,
`Port availability`, `Node runtime`, `Native binary` (better-sqlite3),
`Memory`, na `Server liveness`. Hutoka kwa msimbo usio sifuri ikiwa ukaguzi wowote ni `fail`.

### Usimamizi wa Watoa Huduma

```bash
omniroute providers available                       # Katalogi ya watoa huduma ya OmniRoute
omniroute providers available --search openai       # Chuja katalogi kwa kitambulisho/jina/ibadala/kategoria
omniroute providers available --category api-key    # Chuja kwa kategoria (api-key, oauth, free, ...)
omniroute providers available --json                # JSON inayoweza kusomwa na mashine

omniroute providers list                            # Miunganisho ya watoa huduma iliyosanidiwa
omniroute providers list --json

omniroute providers test <id|name>                  # Jaribu muunganisho mmoja uliosanidiwa
omniroute providers test-all                        # Jaribu kila muunganisho unaotumika
omniroute providers validate                        # Uthibitishaji wa muundo wa ndani pekee
omniroute providers add <provider> --credential-env PROVIDER_KEY
omniroute providers import ./providers.json --dry-run --json
omniroute providers auth <provider>                 # Mtiririko uliopo wa OAuth
omniroute providers edit <id|name> --default-model <model>
omniroute providers remove <id|name> --yes
```

`providers add/import/auth/edit/remove` hutanguliza API na kwa hiyo hufanya kazi dhidi ya
muktadha amilifu wa ndani au wa mbali. Ingizo la kitambulisho linapaswa kutumia
`--credential-stdin` au `--credential-env`; `--dry-run --json` huripoti tu
uwepo/muundo uliofichwa. `providers available` husoma katalogi ya OmniRoute;
`providers list/test/test-all/validate` hudumisha tabia yake ya ndani ya SQLite na
haihitaji seva iwe inaendeshwa.

Kwa nodi maalum inayooana na OpenAI au Anthropic, ambatisha vitambulisho kwenye
kitambulisho cha nodi kilichorejeshwa na `omniroute nodes add`, ukitumia `omniroute keys add "$NODE_ID" --stdin`.
Hili linahitaji seva inayoendeshwa na uthibitishaji wa usimamizi kwa muktadha amilifu.
CLI hutumia `POST /api/providers`, ambayo huthibitisha nodi na kunakili mipangilio ya
ncha-tumizi yake kwenye muunganisho. Nodi inayokosekana, hitilafu ya uidhinishaji, au seva
isiyopatikana hurejesha hitilafu bila kuunda kitambulisho mbadala cha ndani.

`nodes add --base-url` huweka ncha-tumizi ya nodi; ni tofauti na anwani ya seva
katika `OMNIROUTE_BASE_URL`. Kwa faili za OpenAPI, tumia
`omniroute openapi dump --format json --out ./openapi.json`; `--output` ya kimataifa
huchagua uumbizaji wa onyesho la CLI, si jina la faili lengwa.

### Urejeshaji na Uwekaji Upya

```bash
omniroute reset-password                # Weka upya nenosiri la msimamizi (pia: omniroute-reset-password)
omniroute reset-encrypted-columns       # Onyesha onyo + jaribio kavu la kuweka upya vitambulisho vilivyosimbwa
omniroute reset-encrypted-columns --force  # Kwa hakika, weka vitambulisho vilivyosimbwa kuwa null katika SQLite
```

### Uhamishaji wa Vitambulisho (⚠ shughulikia kwa uangalifu)

```bash
omniroute auth export                                 # Onyesha onyo + hatua ya uthibitisho — hakuna ufikiaji wa DB
omniroute auth export --force                          # Hamisha vitambulisho VYOTE VILIVYOSIMBULIWA vya miunganisho kwenda stdout kama JSON
omniroute auth export --force --id <id>                 # Hamisha muunganisho unaolingana pekee
omniroute auth export --force --format env               # Toa mistari ya OMNIROUTE_<PROVIDER>_<FIELD>=<value>
omniroute auth export --force --out creds.json           # Andika kwenye faili (iliyoundwa kwa ruhusa za 0600)
```

`auth export` ni ya **ndani ya mashine pekee** (husoma SQLite moja kwa moja, bila njia ya HTTP) na kwa makusudi huchapisha/huandika
thamani za **maandishi wazi** za `apiKey`/`accessToken`/`refreshToken`/`idToken` — hicho ndicho kipengele, si
hitilafu. Hakuna chochote kinachosomwa kutoka kwenye hifadhidata, wala kusimbuliwa, bila `--force`. Bango la onyo kwenye stderr
huchapishwa kila mara kabla ya maandishi yoyote wazi kutolewa. Inahitaji `STORAGE_ENCRYPTION_KEY`
iwe imewekwa. Sehemu ambayo imeshindikana kusimbuliwa (ufunguo wa zamani, maandishi yaliyosimbwa yaliyoharibika) huripotiwa kama
`<field>DecryptFailed: true` badala ya kusitisha uhamishaji wote au kufichua hitilafu ya msingi.

### Amri nyingine ndogo

Hizi huchukulia kuwa seva ya OmniRoute inaendeshwa, isipokuwa pale ilipoelezwa vinginevyo:

```bash
omniroute status                       # Hali ya kina ya wakati wa utekelezaji
omniroute logs                         # Tiririsha kumbukumbu za maombi (--json, --search, --follow)
omniroute config list                  # Onyesha zana za CLI zilizosanidiwa

omniroute provider list                # Orodhesha watoa huduma wanaopatikana (jina mbadala la providers list)
omniroute provider add                 # Sajili OmniRoute kama mtoa huduma kwenye zana
omniroute keys add | list | remove     # Dhibiti funguo za API
omniroute models [provider]            # Orodhesha modeli (--json, --search)
omniroute combo list | switch | create | delete

omniroute backup                       # Tengeneza taswira ya usanidi + DB
omniroute restore                      # Rejesha kutoka kwenye taswira ya awali

omniroute health                       # Hali ya kina ya afya (vikatiza, akiba, kumbukumbu)
omniroute quota                        # Matumizi ya mgao wa mtoa huduma
omniroute cache                        # Hali ya akiba
omniroute cache clear                  # Futa akiba za kisemantiki + sahihi

omniroute mcp status | restart         # Hali / uanzishaji upya wa seva ya MCP
omniroute a2a status | card            # Hali ya seva ya A2A / kadi ya wakala

omniroute tunnel list | create | stop  # Dhibiti vichuguu (cloudflare/tailscale/ngrok)
omniroute env show | get <k> | set <k> <v>  # Kagua / weka vigeu vya mazingira (kwa muda)

omniroute test                         # Jaribio la haraka la muunganisho wa mtoa huduma
omniroute update                       # Angalia masasisho
omniroute completion                   # Tengeneza ukamilishaji wa shell
```

### Bendera za kawaida

| Bendera             | Maelezo                                                        |
| ------------------- | -------------------------------------------------------------- |
| `--no-open`         | Usifungue kivinjari kiotomatiki wakati wa kuanza               |
| `--port <n>`        | Badilisha port ya API (chaguo-msingi 20128)                    |
| `--mcp`             | Endesha kama seva ya MCP kupitia stdio (kwa IDE)               |
| `--non-interactive` | Hali ya CI (hakuna vidokezo; husoma kutoka env/bendera)        |
| `--json`            | Towe la JSON linalosomeka na mashine (doctor, providers, n.k.) |
| `--help`, `-h`      | Onyesha msaada mahususi wa amri                                |
| `--version`, `-v`   | Chapisha toleo lililosakinishwa                                |

---

## Endpointi za API Zinazopatikana

| Endpointi                  | Maelezo                              | Tumia Kwa                             |
| -------------------------- | ------------------------------------ | ------------------------------------- |
| `/v1/chat/completions`     | Gumzo la kawaida (watoa huduma wote) | Zana zote za kisasa                   |
| `/v1/responses`            | API ya majibu (muundo wa OpenAI)     | Codex, mitiririko ya kazi ya mawakala |
| `/v1/completions`          | Ukamilishaji wa maandishi wa zamani  | Zana za zamani zinazotumia `prompt:`  |
| `/v1/embeddings`           | Upachikaji wa maandishi              | RAG, utafutaji                        |
| `/v1/images/generations`   | Uundaji wa picha                     | GPT-Image, Flux, n.k.                 |
| `/v1/audio/speech`         | Maandishi-kuwa-matamshi              | ElevenLabs, OpenAI TTS                |
| `/v1/audio/transcriptions` | Matamshi-kuwa-maandishi              | Deepgram, AssemblyAI                  |

Mifano iliyo tayari kubandikwa yenye URL ya OmniRoute iliyowekewa tokeni:

```txt
Mfano wa tokeni: sk-a3ab3c080beaee3a-69f4a4-070d71af

Msingi wa kawaida wa OpenAI: http://localhost:20128/v1
Miundo ya VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models
Gumzo la VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions
Majibu ya VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses
Lebo za Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags
Gumzo la Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat
```

---

## Utatuzi wa Matatizo

| Hitilafu                                                    | Sababu                                    | Suluhisho                                                   |
| ----------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- |
| `Connection refused`                                        | OmniRoute haifanyi kazi                   | `omniroute serve`                                           |
| `401 Unauthorized`                                          | Ufunguo wa API si sahihi                  | Angalia katika `/dashboard/api-manager`                     |
| `No combo configured`                                       | Hakuna mchanganyiko amilifu wa uelekezaji | Sanidi katika `/dashboard/combos`                           |
| CLI inaonyesha "haijasakinishwa"                            | Faili tekelezi haipo katika PATH          | Angalia `which <command>`                                   |
| Dashibodi inaonyesha "haijatambuliwa" baada ya usakinishaji | Akiba imepitwa na wakati                  | Bofya "⟳ Onyesha upya utambuzi" katika dashibodi            |
| Kiungo cha zamani `/dashboard/cli-tools`                    | Alamisho la kabla ya v3.8.6               | Huelekezwa kiotomatiki kwenye `/dashboard/cli-code` (308)   |
| Kiungo cha zamani `/dashboard/agents`                       | Alamisho la kabla ya v3.8.6               | Huelekezwa kiotomatiki kwenye `/dashboard/acp-agents` (308) |

## Dhibiti sera ya ufunguo wa inferensi kwa kutumia OmniRoute CLI

Tumia muktadha wa usimamizi uliothibitishwa (tazama [Hali ya Mbali](../guides/REMOTE-MODE.md))
kukagua au kusasisha ufunguo uliopo wa inferensi kwa kutumia ID yake:

```bash
omniroute --output json keys policy show KEY_ID
omniroute keys policy set KEY_ID --unrestricted
omniroute --output json keys policy show KEY_ID
```

`--unrestricted` ni jina mbadala la `--model-access-mode all`. Sasisho huondoa
orodha ya miundo inayoruhusiwa. Huhifadhi mawanda, sheria za muunganisho, miundo iliyozuiwa, vikomo vya kasi
na vikomo vya gharama, kwa hivyo vidhibiti hivyo vingine bado vinaweza kukataa ombi. Thamani bayana ya
`--allowed-models ""` pia huchagua `all`; iunganishe na
`--model-access-mode restricted` ili kudumisha ufunguo uliozuiliwa bila miundo yoyote inayoruhusiwa.
Orodha isiyo tupu iliyotenganishwa kwa koma huchagua `restricted` isipokuwa ikiwa imebainishwa vinginevyo.
Mchanganyiko kinzani wa `all` pamoja na orodha isiyo tupu ya ruhusa hukataliwa kabla ya kutuma ombi.

`--rate-limit 30` huweka idadi ya maombi kwa dakika na huhifadhi sheria za vipindi vingine
vya muda. `--max-cost 5` huwezesha kikomo cha kila siku cha USD bila kubadilisha kikomo cha kila wiki;
`--max-cost 0` huondoa kikomo cha kila siku na huhifadhi kibadilishaji kilichopo cha kikomo cha matumizi
na kikomo cha kila wiki. Sehemu za sera zilizoachwa hubaki bila kubadilishwa. Mabadiliko ya kasi husoma
sera ya sasa kwanza; epuka kufanya mabadiliko ya wakati mmoja kwenye safu ya vikomo vya kasi ya ufunguo huo huo.

Amri za sera hutumia `GET`/`PATCH /api/keys/{id}` iliyothibitishwa na huheshimu
muktadha amilifu na chaguo la jumla la `--api-key`. Towe la JSON lina sehemu za sera pekee,
bila ufunguo uliohifadhiwa au uwakilishi wake uliofichwa. Kitambulisho cha inferensi pekee
hakiwezi kuidhinisha mabadiliko ya usimamizi. 401/403 inahitaji kukagua kitambulisho cha
usimamizi na muktadha; haithibitishi hitilafu ya tokeni ya ndani ya CLI au chumvi.
Tazama [Tokeni ya CLI](../security/CLI_TOKEN.md) kwa mkataba tofauti wa uthibitishaji wa ndani.