# CLI Tools — OmniRoute (Polski) 🌐 **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) · 🇵🇹 [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) · 🇰🇪 [sw](../../../sw/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) --- Ostatnia aktualizacja: 2026-08-23 OmniRoute integruje się z trzema kategoriami narzędzi CLI rozmieszczonymi na trzech dedykowanych stronach panelu: | Strona | Ścieżka | Koncepcja | Liczba | | -------------- | ----------------------- | ------------------------------------------------------------------------------------------ | -------------- | | **CLI Code's** | `/dashboard/cli-code` | Narzędzia programistyczne kierowane do OmniRoute (Klient → CLI → OmniRoute → Dostawca) | 26 | | **CLI Agents** | `/dashboard/cli-agents` | Autonomiczni agenci kierowani do OmniRoute (ten sam przepływ, szerszy zakres) | 10 | | **ACP Agents** | `/dashboard/acp-agents` | Narzędzia CLI uruchamiane przez OmniRoute jako backend przez stdio/ACP (przepływ odwrotny) | zobacz rejestr | Starsze ścieżki wykonują przekierowanie 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. --- ## Jak to działa ``` CLI Code's / CLI Agents (przepływ użycia): Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ (wszystkie wskazują na OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (OmniRoute kieruje żądanie do właściwego dostawcy) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ACP Agents (odwrotny przepływ uruchamiania): Żądanie klienta → OmniRoute → uruchamia CLI przez stdio/ACP → odpowiedź ``` **Korzyści:** - Jeden klucz API do zarządzania wszystkimi narzędziami - Śledzenie kosztów wszystkich narzędzi CLI w panelu - Przełączanie modeli bez ponownego konfigurowania każdego narzędzia - Działa lokalnie i na serwerach zdalnych (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## Automatyczna konfiguracja za pomocą `setup-*` Nie musisz ręcznie tworzyć konfiguracji każdego narzędzia. OmniRoute udostępnia polecenie `setup-*` dla każdego obsługiwanego CLI, które odczytuje **aktualny** katalog modeli z działającej instancji OmniRoute (lokalnej lub zdalnej) i zapisuje właściwą konfigurację narzędzia na Twoim komputerze: ```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 ``` Każde z nich obsługuje `--remote --api-key ` (konfiguracja lokalnego narzędzia do pracy ze zdalną instancją OmniRoute), `--dry-run` (podgląd bez zapisywania) oraz `--port`. Narzędzia bez automatycznego wykrywania modeli (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) przyjmują `--model ` (oraz `--yes` w przypadku uruchomień nieinteraktywnych). `setup-5dive` to jedyna procedura, która nie zapisuje danych w `$HOME`: konfiguruje flotę agentów 5dive, zapisując profil uwierzytelniania należący do użytkownika root na hoście floty, dlatego uruchamia się ponownie przez `sudo` i nie ma własnego trybu zdalnego. Aby uruchomić CLI z odpowiednimi zmiennymi środowiskowymi, bez zapisywania jakiejkolwiek konfiguracji, użyj ogólnego programu uruchamiającego `omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini — cele i aliasy pochodzą z `bin/cli/cli-manifest.mjs`); starsze programy uruchamiające dla poszczególnych narzędzi, `omniroute launch` (Claude Code) i `omniroute launch-codex` (Codex), pozostają dostępne. Gemini CLI można tylko uruchamiać: jest celem `omniroute run`, ale nie ma procedury `setup-*`/`configure`. > **Pełna dokumentacja:** główna tabela — co zapisuje każde polecenie, wszystkie flagi, > tryb lokalny i zdalny oraz informacje o tym, które narzędzia wymagają sufiksu `/v1` — znajduje się w > **[Integracjach CLI](../guides/CLI-INTEGRATIONS.md)**. ### Uruchamianie tych poleceń wewnątrz kontenera Polecenie `setup-*` wykonane wewnątrz kontenera OmniRoute zapisuje dane w katalogu domowym samego kontenera, którego nie odczytuje żaden CLI na hoście i który znika wraz z kontenerem. OmniRoute wykrywa taką sytuację i kończy działanie z kodem `2`, wyświetlając instrukcje zamiast zapisywać dane. Istnieją dwa obsługiwane rozwiązania — zainstalowanie CLI na hoście i użycie `omniroute connect` w celu połączenia z kontenerem albo zamontowanie katalogów konfiguracyjnych jako bind mount i ustawienie `CLI_CONFIG_HOME` (profil compose `host`). Każde polecenie `setup-*`, a także `omniroute configure` i `omniroute config set`, obsługuje `--allow-container-write`, jeśli rzeczywiście chcesz skonfigurować narzędzia CLI samego kontenera; ustawienie `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` daje ten sam efekt dla serwera. Zobacz [Przewodnik po Dockerze → Konfigurowanie narzędzi CLI hosta](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker). **Punkt końcowy stosowania zmian** w panelu (`POST /api/cli-tools/apply`) egzekwuje to samo zabezpieczenie: w kontenerze próba zapisu do miejsca docelowego, które nie jest zamontowane z hosta jako bind mount, zwraca **`422`** z `containerEphemeralTarget: true`, bezpiecznym komunikatem błędu oraz — w przypadku narzędzi mających procedurę dla hosta (claude, codex, opencode, cline, kilo, continue) — polem `hostSetupCommand` (np. `omniroute setup-opencode`) wskazującym polecenie do uruchomienia na hoście; nic nie zostaje zapisane. `dryRun: true` nadal działa w trybie kontenera i zwraca zredagowany podgląd oraz ścieżkę docelową bez modyfikowania danych na dysku. Treść podglądu nie jest konfiguracją zawierającą dane uwierzytelniające, którą należy kopiować lub importować. Zastosuj konfigurację na hoście, używając pierwotnych danych wejściowych narzędzia, bazowego adresu URL, klucza API i modelu, albo użyj wskazanego polecenia konfiguracji po stronie hosta. Informacje o nagłówku podglądu i kontrakcie żądania zawiera dokument [Bezpieczeństwo konfiguracji CLI](../security/CLI-CONFIGURATION.md). To zachowanie jest zamierzone i chronione przed regresją przez `tests/unit/api/cli-tools/apply-container-guard.test.ts` — nigdy nie „naprawiaj” błędu 422 przez usunięcie tego zabezpieczenia. --- ## Źródło prawdy Ujednolicony katalog znajduje się w `src/shared/constants/cliTools.ts` jako `CLI_TOOLS: Record`. Każdy wpis zawiera następujące pola (zdefiniowane w `src/shared/schemas/cliCatalog.ts`): | Pole | Typ | Opis | | ----------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `category` | `"code" \| "agent"` | Strona, na której pojawia się narzędzie | | `vendor` | `string` | Pochodzenie narzędzia („Anthropic”, „OSS (P. Gauthier)”) | | `acpSpawnable` | `boolean` | Czy może być również używane jako agent ACP (wyświetlana jest odznaka) | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | Poziom obsługi niestandardowego punktu końcowego. `"none"` = zaległe zadania MITM | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Mechanizm konfiguracji | | `id`, `name`, `color`, `description`, `docsUrl` | standard | Podstawowe pola wyświetlania | Wpisy z `baseUrlSupport: "none"` **nie są wyświetlane** na stronach panelu — są zarejestrowane na liście zaległych zadań MITM dla planu 11 (zobacz `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`). ### Poziomy możliwości (skatalogowane × wykrywalne × konfigurowalne × uruchamialne) Nie każde skatalogowane narzędzie jest wykrywalne, konfigurowalne lub uruchamialne. Każdy poziom ma jedno źródło deklaracji, a test rozbieżności zapewnia ich zgodność: | Poziom | Znaczenie | Zadeklarowano w | | ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Skatalogowane** | Pojawia się w katalogu panelu (nazwa, dostawca, dokumentacja, typ konfiguracji) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`) | | **Wykrywalne** | Wykrywanie pliku binarnego/konfiguracji, kontrole stanu, ścieżki konfiguracji | `src/shared/services/cliRuntime.ts` (katalog środowiska uruchomieniowego `CLI_TOOLS`) | | **Konfigurowalne** | Obsługiwane przez `omniroute configure ` (istnieje procedura konfiguracji) | `bin/cli/cli-manifest.mjs` (`configure: true`) | | **Uruchamialne** | Obsługiwane przez `omniroute run ` (zdefiniowano wstrzykiwanie zmiennych środowiskowych/argumentów) | `bin/cli/cli-manifest.mjs` (`run: true`) | `bin/cli/cli-manifest.mjs` jest kanonicznym wykonywalnym manifestem dla interfejsów poleceń CLI: `run`, `configure` oraz generatory uzupełniania powłoki pobierają z niego listy celów, rozwiązywanie aliasów (na przykład `kilocode`/`kilo-code`/`kilo_cli` → `kilo`) oraz konfigurację flagi `--model`. Mechanizm ochrony przed rozbieżnościami `tests/unit/cli/cli-manifest-drift.test.ts` sprawdza, czy manifest, katalog środowiska uruchomieniowego, katalog interfejsu użytkownika i wszystkie interfejsy konsumenckie pozostają zsynchronizowane — cel dodany do jednego interfejsu bez uwzględnienia pozostałych powoduje niepowodzenie zestawu testów zamiast cichego powstania rozbieżności. --- ## 1. Katalog CLI Code (27 narzędzi) Wszystkie narzędzia widoczne w `/dashboard/cli-code`. Te z `baseUrlSupport: none` są podłączane przez MITM lub zgodnie z instrukcją ręczną zamiast za pomocą niestandardowego bazowego adresu URL: | id | nazwa | dostawca | baseUrlSupport | configType | acpSpawnable | | ------------ | ----------------------- | ------------------------ | -------------- | -------------- | ------------ | | claude | Claude Code | Anthropic | full | env | true | | codex | OpenAI Codex CLI | OpenAI | full | custom | true | | zcode | ZCode (GLM Coding Plan) | Z.ai | none | custom | false | | cline | Cline | OSS (dawniej Claude Dev) | full | custom | true | | kilo | Kilo Code | Kilo-Org | full | custom | false | | roo | Roo Code | Roo (OSS) | full | guide | false | | continue | Continue | continue.dev | full | guide | false | | aider | Aider | OSS (P. Gauthier) | full | guide | true | | forge | ForgeCode | Antinomy HQ | full | custom | true | | jcode | jcode | 1jehuang (OSS) | full | custom | false | | deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false | | codewhale | CodeWhale | Hmbown (OSS) | full | custom | false | | opencode | OpenCode | Anomaly (dawniej SST) | full | guide | true | | droid | Factory Droid | Factory AI | partial | guide | false | | copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false | | cursor-cli | Cursor CLI | Anysphere | partial | guide | true | | smelt | Smelt | leonardcser (OSS) | full | custom | false | | pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false | | grok-build | Grok Build | xAI | full | custom | false | | crush | Crush | OSS (Charm) | full | custom | false | | qwen | Qwen Code | Alibaba | full | guide | true | | zed | Zed | Zed Industries | full | guide | false | | cursor | Cursor | Anysphere | none | guide | false | | antigravity | Antigravity | Google | none | mitm | false | | hermes | Hermes | Nous Research | none | guide | false | | kiro | Kiro AI | Amazon | none | mitm | false | | custom | Niestandardowy CLI | — | full | custom-builder | false | Narzędzia z `baseUrlSupport: "partial"` wyświetlają na karcie panelu plakietkę „⚠ Częściowa obsługa bazowego adresu URL”. --- ## 2. Katalog agentów CLI (10 narzędzi) Autonomiczni agenci dostępni w `/dashboard/cli-agents`: | id | nazwa | dostawca | obsługa baseUrl | możliwość uruchomienia przez ACP | | ------------ | ---------------- | ------------------------ | --------------- | -------------------------------- | | hermes-agent | Hermes Agent | Nous Research | full | false | | openclaw | OpenClaw | OSS (P. Steinberger) | full | true | | goose | Goose | Block / Linux Foundation | full | true | | interpreter | Open Interpreter | OSS | full | true | | warp | Warp AI | Warp Inc. | partial | true | | agent-deck | Agent Deck | asheshgoplani (OSS) | full | false | | omp | Oh My Pi | OSS | full | true | | letta | Letta CLI | Letta | full | false | | prime-agent | Prime Agent | Prime Intellect (OSS) | full | false | | 5dive | 5dive | OSS (5dive-ai) | full | false | --- ## 3. Agenty ACP (/dashboard/acp-agents) Ta strona (wcześniej `/dashboard/agents`) przedstawia narzędzia CLI, które OmniRoute może **uruchamiać** jako backendowe silniki wykonawcze za pośrednictwem protokołu stdio/ACP. Katalog jest utrzymywany oddzielnie w `src/lib/acp/registry.ts` i **nie** jest tym samym co `CLI_TOOLS`. --- ## 4. Lista zadań MITM (niewidoczna w panelu) Poniższe narzędzia CLI nie obsługują natywnie niestandardowego bazowego adresu URL i **nie są wymienione** na stronach CLI Code ani CLI Agents. Są one kandydatami do przechwytywania MITM w planie 11: | CLI | Powód | | ------------------- | ---------------------------------------------------------------------------- | | windsurf | BYOK ograniczone do wybranych modeli Claude oraz firmowego adresu URL/tokenu | | amp | Zamknięty ekosystem (Sourcegraph) | | amazon-q / kiro-cli | Uwierzytelnianie AWS SSO, brak niestandardowego adresu URL | | cowork | Anthropic Desktop, brak konfigurowalnego punktu końcowego | Pełne zestawienie znajduje się w `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`. --- ## 5. Interfejs API wykrywania zbiorczego Wykrywanie wszystkich narzędzi jest agregowane za pośrednictwem jednego punktu końcowego: **`GET /api/cli-tools/all-statuses`** - Uwierzytelnianie: `requireCliToolsAuth(request)` (tak samo jak w przypadku innych tras `/api/cli-tools/`) - Zwraca: `Record` (typ: `src/shared/types/cliBatchStatus.ts`) - Strategia: `Promise.all` dla wszystkich narzędzi, limit czasu 5 s na narzędzie - Pamięć podręczna: LRU w pamięci, indeksowana według `mtime` pliku konfiguracyjnego. Pamięć podręczna jest unieważniana po zmianie mtime. Resetowana po ponownym uruchomieniu serwera. Struktura odpowiedzi dla każdego narzędzia: ```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; // oczyszczony, bez śladów stosu } ``` --- ## 6. Procedury obsługi ustawień dla nowych narzędzi Nowe narzędzia z `configType: "custom"` mają dedykowane trasy API ustawień: | Trasa | Narzędzie | | ------------------------------------------- | -------------------------------------------------------------------------- | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode (flaga --base-url) | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, starsze rozwiązanie) | | `POST /api/cli-tools/codewhale-settings` | CodeWhale (OPENAI_BASE_URL, synchronizacja główna + starsza `~/.deepseek`) | | `POST /api/cli-tools/smelt-settings` | Smelt | | `POST /api/cli-tools/pi-settings` | Agent programistyczny Pi | | `POST /api/cli-tools/grok-build-settings` | Grok Build (~/.grok/config.toml, `[model.omniroute]`) | | `POST /api/cli-tools/qwen-settings` | Qwen Code (`~/.qwen/settings.json` + dedykowany klucz `.env`) | Wszystkie trasy używają `sanitizeErrorMessage()` w odpowiedziach błędów (twarda reguła nr 12). --- ## 7. Architektura stron panelu ### Kody CLI (`/dashboard/cli-code`) - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — komponent serwerowy - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — siatka kliencka - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — strona szczegółów narzędzia - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 wyspecjalizowanych kart narzędzi + `ToolDetailClient.tsx` ### Agenci CLI (`/dashboard/cli-agents`) - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — komponent serwerowy - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — siatka kliencka - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — ponownie wykorzystuje `ToolDetailClient` ### Agenci ACP (`/dashboard/acp-agents`) - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — komponent serwerowy (przeniesiony z `agents/`) ### Współdzielone komponenty interfejsu użytkownika (`src/shared/components/cli/`) | Plik | Przeznaczenie | | ----------------------- | -------------------------------------------------------------------- | | `CliToolCard.tsx` | Inteligentna karta stanu (wykrywanie + konfiguracja + punkt końcowy) | | `CliConceptCard.tsx` | Karta objaśniająca koncepcję dla danej strony | | `CliComparisonCard.tsx` | Trójkolumnowe porównanie typów CLI | | `BaseUrlSelect.tsx` | Lista rozwijana punktów końcowych (lokalny/chmurowy/niestandardowy) | | `ApiKeySelect.tsx` | Selektor klucza API | | `ManualConfigModal.tsx` | Okno modalne z fragmentem konfiguracji do skopiowania | ### Współdzielony hook (`src/shared/hooks/cli/`) | Plik | Przeznaczenie | | ------------------------- | ------------------------------------------------------------------------------------- | | `useToolBatchStatuses.ts` | Pobiera dane z `/api/cli-tools/all-statuses`, zarządza stanem ładowania i odświeżania | --- ## 8. i18n Nowe przestrzenie nazw dodane w planie 14 F9: | Przestrzeń nazw | Przeznaczenie | | --------------- | -------------------------------------------------------------------------------------------- | | `cliCommon` | Współdzielone ciągi znaków (etykiety kart, teksty pojęć/porównań, etykiety stron szczegółów) | | `cliCode` | Ciągi znaków strony CLI Code | | `cliAgents` | Ciągi znaków strony CLI Agents | | `acpAgents` | Ciągi znaków strony ACP Agents | Dostępne są pełne tłumaczenia PT-BR i EN. Pozostałe 39 ustawień regionalnych automatycznie korzysta z EN dzięki scalaniu na poziomie przestrzeni nazw w `src/i18n/request.ts`. --- ## 9. Szybki start ### Krok 1 — Uzyskaj klucz API OmniRoute 1. Otwórz `/dashboard/api-manager` → **Utwórz klucz API** 2. Nadaj mu nazwę (np. `cli-tools`) i wybierz wszystkie uprawnienia 3. Skopiuj klucz — będzie potrzebny dla każdego z poniższych narzędzi CLI > Twój klucz wygląda tak: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Krok 2 — Zainstaluj narzędzia CLI Wszystkie narzędzia oparte na npm wymagają Node.js 22.22.2+ lub 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 (uruchamiane przez `omniroute run gemini` → interfejs /v1beta) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Oparte na języku Rust # Agent programistyczny Pi # instrukcje instalacji: https://github.com/zechnerj/pi-coding-agent # jcode # instrukcje instalacji: https://github.com/1jehuang/jcode ``` --- ### Krok 3 — Skonfiguruj za pomocą panelu 1. Przejdź do `http://localhost:20128/dashboard/cli-code` 2. Znajdź swoje narzędzie w siatce 3. Kliknij kartę, aby otworzyć stronę szczegółów narzędzia 4. Wybierz klucz API i bazowy adres URL 5. Kliknij **Zastosuj konfigurację** lub skopiuj fragment konfiguracji ręcznej --- ### Krok 4 — Ustaw globalne zmienne środowiskowe ```bash # Uniwersalny punkt końcowy OmniRoute 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 odczytuje GOOGLE_GEMINI_BASE_URL z KATALOGU GŁÓWNEGO (jego SDK samodzielnie dodaje /v1beta/...) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > W przypadku **serwera zdalnego** zastąp `localhost:20128` adresem IP lub domeną serwera, > np. `http://:20128`. --- ### Krok 4 — Skonfiguruj każde narzędzie #### Claude Code ```bash # Utwórz ~/.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 ``` Użyj głównego adresu ujednoliconej bramy Anthropic dla Claude Code. Nie dodawaj tutaj `/v1`. **Test:** `claude "say hello"` --- #### OpenAI Codex Nowoczesny Codex (v0.137+) odczytuje wyłącznie `~/.codex/config.toml` — stary plik `config.yaml` należy do starszej wersji CLI npm i jest po cichu ignorowany. Klucz API pozostaje w zmiennej środowiskowej `OMNIROUTE_API_KEY` (`env_key`), nigdy wewnątrz pliku: ```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" ``` Pełna dokumentacja (profile, `wire_api`, okna kontekstu): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md). **Test:** `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 ``` **Test:** `opencode` > Użyj `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`, > aby wysyłać warianty z rozumowaniem. --- #### Cline (CLI lub VS Code) **Tryb 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 ``` **Tryb VS Code:** Ustawienia rozszerzenia Cline → Dostawca API: `OpenAI Compatible` → Bazowy adres URL: `http://localhost:20128/v1` Możesz też użyć panelu OmniRoute → **Narzędzia CLI → Cline → Zastosuj konfigurację**. --- #### KiloCode (CLI lub VS Code) **Tryb CLI:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **Ustawienia VS Code:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` Możesz też użyć panelu OmniRoute → **Narzędzia CLI → KiloCode → Zastosuj konfigurację**. --- #### Continue (rozszerzenie VS Code) Edytuj `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Po zakończeniu edycji uruchom ponownie VS Code. --- #### VS Code Insiders (`chatLanguageModels.json`) Użyj tej opcji, gdy VS Code Insiders jest skonfigurowany do obsługi modeli z niestandardowych punktów końcowych i chcesz, aby OmniRoute działał bez niestandardowego pola nagłówka. **Zalecana lokalizacja:** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **Przykład użycia tokenizowanego aliasu OmniRoute:** ```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" } } ] ``` **Uwagi:** - Zastąp `sk-your-omniroute-key` kluczem API utworzonym w OmniRoute. - Pole `url` powinno wskazywać na `/api/v1/vscode/{token}/chat/completions`. - Pole `modelsUrl` powinno wskazywać na `/api/v1/vscode/{token}/models`. - Gdy klient obsługuje niestandardowe nagłówki, preferuj standardowy przepływ z `/v1` i nagłówkiem Bearer. - Tokeny osadzone w adresie URL stanowią rozwiązanie awaryjne zapewniające zgodność i mogą pojawiać się w dziennikach edytora lub historii serwera proxy. --- #### Kiro CLI (Amazon) ```bash # Zaloguj się na swoje konto AWS/Kiro: kiro-cli login # CLI korzysta z własnego uwierzytelniania — OmniRoute nie jest potrzebny jako backend dla samego Kiro CLI. # Używaj kiro-cli razem z OmniRoute dla innych narzędzi. kiro-cli status ``` W przypadku aplikacji desktopowej **Kiro IDE** użyj punktu końcowego MITM udostępnianego przez OmniRoute w sekcji `/dashboard/cli-tools → Kiro`. --- ## 10. Wewnętrzny interfejs CLI OmniRoute Plik binarny `omniroute` udostępnia polecenia do zarządzania cyklem życia serwera, konfiguracji, diagnostyki oraz dostawców. Punkt wejścia: `bin/omniroute.mjs`. ```bash omniroute # Uruchom serwer (domyślny port 20128) omniroute setup # Interaktywny kreator konfiguracji omniroute doctor # Sprawdź konfigurację, bazę danych, porty i środowisko uruchomieniowe omniroute providers list # Skonfigurowane połączenia z dostawcami omniroute providers test-all # Przetestuj każde aktywne połączenie omniroute reset-password # Zresetuj hasło administratora omniroute logs # Wyświetlaj strumieniowo dzienniki żądań omniroute health # Szczegółowy stan systemu (bezpieczniki, pamięć podręczna, pamięć) omniroute --version # Wyświetl wersję omniroute --help # Pokaż wszystkie polecenia ``` ### Konfiguracja i inicjalizacja ```bash omniroute setup # Interaktywny kreator konfiguracji omniroute setup --non-interactive # Tryb CI/automatyzacji (odczytuje zmienne środowiskowe i flagi) omniroute setup --password '' # Ustaw hasło administratora bezpośrednio omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Dodaj i przetestuj dostawcę w jednym kroku ``` Rozpoznawane zmienne środowiskowe dla konfiguracji nieinteraktywnej: | Zmienna | Przeznaczenie | | ------------------- | ------------------------------------------------------------------------------------ | | `OMNIROUTE_API_KEY` | Klucz API dostawcy (powiązany z `--api-key` za pomocą `.env()` biblioteki Commander) | | `DATA_DIR` | Zastępuje katalog danych OmniRoute | Wszystkie pozostałe dane wejściowe konfiguracji nieinteraktywnej są przekazywane jako flagi, a nie zmienne środowiskowe: `--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model` (zobacz powyższe opcje polecenia `omniroute setup`). ### Diagnostyka ```bash omniroute doctor # Sprawdź konfigurację, bazę danych, porty, środowisko uruchomieniowe, pamięć i dostępność omniroute doctor --json # JSON przeznaczony do odczytu maszynowego omniroute doctor --no-liveness # Pomiń sondę stanu HTTP omniroute doctor --host 0.0.0.0 # Zastąp hosta sondy dostępności omniroute doctor --liveness-url # Zastąp pełny URL punktu końcowego stanu ``` Polecenie diagnostyczne wykonuje następujące testy: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory` oraz `Server liveness`. Kończy działanie z niezerowym kodem, jeśli dowolny test ma wynik `fail`. ### Zarządzanie dostawcami ```bash omniroute providers available # Katalog dostawców OmniRoute omniroute providers available --search openai # Filtruj katalog według identyfikatora/nazwy/aliasu/kategorii omniroute providers available --category api-key # Filtruj według kategorii (api-key, oauth, free, ...) omniroute providers available --json # JSON przeznaczony do odczytu maszynowego omniroute providers list # Skonfigurowane połączenia z dostawcami omniroute providers list --json omniroute providers test # Przetestuj jedno skonfigurowane połączenie omniroute providers test-all # Przetestuj każde aktywne połączenie omniroute providers validate # Wyłącznie lokalna walidacja strukturalna omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # Istniejący przepływ OAuth omniroute providers edit --default-model omniroute providers remove --yes ``` Polecenia `providers add/import/auth/edit/remove` korzystają przede wszystkim z API, dlatego działają w aktywnym kontekście lokalnym lub zdalnym. Dane uwierzytelniające należy przekazywać za pomocą `--credential-stdin` lub `--credential-env`; `--dry-run --json` raportuje jedynie zanonimizowaną obecność i strukturę danych. Polecenie `providers available` odczytuje katalog OmniRoute; `providers list/test/test-all/validate` zachowują lokalne działanie oparte na SQLite i nie wymagają uruchomionego serwera. W przypadku niestandardowego węzła zgodnego z OpenAI lub Anthropic przypisz dane uwierzytelniające do identyfikatora węzła zwróconego przez `omniroute nodes add`, używając `omniroute keys add "$NODE_ID" --stdin`. Wymaga to uruchomionego serwera oraz uwierzytelnienia administracyjnego w aktywnym kontekście. CLI używa `POST /api/providers`, które weryfikuje węzeł i kopiuje ustawienia jego punktu końcowego do połączenia. Brak węzła, niepowodzenie autoryzacji lub niedostępność serwera powodują zwrócenie błędu bez tworzenia lokalnych zastępczych danych uwierzytelniających. `nodes add --base-url` ustawia punkt końcowy węzła; różni się on od adresu serwera określonego w `OMNIROUTE_BASE_URL`. W przypadku plików OpenAPI użyj `omniroute openapi dump --format json --out ./openapi.json`; globalna opcja `--output` wybiera format wyświetlania danych przez CLI, a nie nazwę pliku docelowego. ### Odzyskiwanie i resetowanie ```bash omniroute reset-password # Zresetuj hasło administratora (również: omniroute-reset-password) omniroute reset-encrypted-columns # Pokaż ostrzeżenie i wykonaj przebieg próbny resetowania zaszyfrowanych danych uwierzytelniających omniroute reset-encrypted-columns --force # Faktycznie wyzeruj zaszyfrowane dane uwierzytelniające w SQLite ``` ### Eksport danych uwierzytelniających (⚠ zachowaj ostrożność) ```bash omniroute auth export # Pokaż ostrzeżenie i monit o potwierdzenie — bez dostępu do bazy danych omniroute auth export --force # Wyeksportuj ODSZYFROWANE dane uwierzytelniające WSZYSTKICH połączeń do standardowego wyjścia jako JSON omniroute auth export --force --id # Wyeksportuj tylko pasujące połączenie omniroute auth export --force --format env # Wygeneruj wiersze OMNIROUTE__= omniroute auth export --force --out creds.json # Zapisz do pliku (utworzonego z uprawnieniami 0600) ``` `auth export` działa **wyłącznie lokalnie** (bezpośredni odczyt SQLite, bez trasy HTTP) i celowo wyświetla/zapisuje wartości `apiKey`/`accessToken`/`refreshToken`/`idToken` w postaci **zwykłego tekstu** — jest to funkcja, a nie błąd. Bez opcji `--force` żadne dane nie są odczytywane z bazy danych ani odszyfrowywane. Przed wyemitowaniem jakichkolwiek danych w postaci zwykłego tekstu na stderr zawsze wyświetlany jest baner ostrzegawczy. Wymaga ustawienia `STORAGE_ENCRYPTION_KEY`. Pole, którego nie uda się odszyfrować (nieaktualny klucz, uszkodzony szyfrogram), jest raportowane jako `DecryptFailed: true` zamiast przerywania całego eksportu lub ujawniania bazowego błędu. ### Inne podpolecenia Poniższe polecenia zakładają, że serwer OmniRoute jest uruchomiony, chyba że zaznaczono inaczej: ```bash omniroute status # Kompleksowy stan środowiska wykonawczego omniroute logs # Strumieniowe przesyłanie dzienników żądań (--json, --search, --follow) omniroute config list # Wyświetlanie skonfigurowanych narzędzi CLI omniroute provider list # Wyświetlanie dostępnych dostawców (alias polecenia providers list) omniroute provider add # Rejestrowanie OmniRoute jako dostawcy w narzędziu omniroute keys add | list | remove # Zarządzanie kluczami API omniroute models [provider] # Wyświetlanie modeli (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Migawka konfiguracji i bazy danych omniroute restore # Przywracanie z wcześniejszej migawki omniroute health # Szczegółowy stan systemu (wyłączniki, pamięć podręczna, pamięć) omniroute quota # Wykorzystanie limitów dostawcy omniroute cache # Stan pamięci podręcznej omniroute cache clear # Czyszczenie semantycznej pamięci podręcznej i pamięci podręcznej sygnatur omniroute mcp status | restart # Stan / ponowne uruchomienie serwera MCP omniroute a2a status | card # Stan serwera A2A / karta agenta omniroute tunnel list | create | stop # Zarządzanie tunelami (cloudflare/tailscale/ngrok) omniroute env show | get | set # Wyświetlanie / ustawianie zmiennych środowiskowych (tymczasowo) omniroute test # Podstawowy test łączności z dostawcą omniroute update # Sprawdzanie dostępności aktualizacji omniroute completion # Generowanie uzupełniania poleceń powłoki ``` ### Typowe opcje | Opcja | Opis | | ------------------- | ------------------------------------------------------------------- | | `--no-open` | Nie otwieraj automatycznie przeglądarki podczas uruchamiania | | `--port ` | Zastąpienie portu API (domyślnie 20128) | | `--mcp` | Uruchomienie jako serwer MCP przez stdio (dla IDE) | | `--non-interactive` | Tryb CI (bez monitów; odczyt ze środowiska/opcji) | | `--json` | Dane wyjściowe JSON do odczytu maszynowego (doctor, providers itp.) | | `--help`, `-h` | Wyświetlenie pomocy dotyczącej danego polecenia | | `--version`, `-v` | Wyświetlenie zainstalowanej wersji | --- ## Dostępne punkty końcowe API | Punkt końcowy | Opis | Zastosowanie | | -------------------------- | ----------------------------------- | ------------------------------------- | | `/v1/chat/completions` | Standardowy czat (wszyscy dostawcy) | Wszystkie nowoczesne narzędzia | | `/v1/responses` | Responses API (format OpenAI) | Codex, przepływy pracy agentów | | `/v1/completions` | Starsze uzupełnianie tekstu | Starsze narzędzia używające `prompt:` | | `/v1/embeddings` | Osadzanie tekstu | RAG, wyszukiwanie | | `/v1/images/generations` | Generowanie obrazów | GPT-Image, Flux itp. | | `/v1/audio/speech` | Zamiana tekstu na mowę | ElevenLabs, OpenAI TTS | | `/v1/audio/transcriptions` | Zamiana mowy na tekst | Deepgram, AssemblyAI | Gotowe do wklejenia przykłady z tokenem w adresie URL OmniRoute: ```txt Przykładowy token: sk-a3ab3c080beaee3a-69f4a4-070d71af Standardowa baza OpenAI: http://localhost:20128/v1 Modele VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models Czat VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions Odpowiedzi VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Tagi Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Czat Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## Rozwiązywanie problemów | Błąd | Przyczyna | Rozwiązanie | | -------------------------------------------- | ------------------------------------ | ------------------------------------------------------------ | | `Connection refused` | OmniRoute nie jest uruchomiony | `omniroute serve` | | `401 Unauthorized` | Nieprawidłowy klucz API | Sprawdź w `/dashboard/api-manager` | | `No combo configured` | Brak aktywnej kombinacji routingu | Skonfiguruj w `/dashboard/combos` | | CLI wyświetla „not installed” | Plik binarny nie znajduje się w PATH | Sprawdź `which ` | | Panel wyświetla „not detected” po instalacji | Pamięć podręczna jest nieaktualna | Kliknij „⟳ Refresh detection” w panelu | | Stary link `/dashboard/cli-tools` | Zakładka sprzed wersji v3.8.6 | Automatycznie przekierowano do `/dashboard/cli-code` (308) | | Stary link `/dashboard/agents` | Zakładka sprzed wersji v3.8.6 | Automatycznie przekierowano do `/dashboard/acp-agents` (308) | ## Zarządzanie zasadami klucza inferencji za pomocą OmniRoute CLI Użyj uwierzytelnionego kontekstu zarządzania (zobacz [Tryb zdalny](../guides/REMOTE-MODE.md)), aby sprawdzić lub zaktualizować istniejący klucz inferencji na podstawie jego identyfikatora: ```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` jest aliasem opcji `--model-access-mode all`. Aktualizacja czyści listę dozwolonych modeli. Zachowuje zakresy, reguły połączeń, zablokowane modele, limity żądań i limity kosztów, więc te pozostałe mechanizmy kontroli nadal mogą odrzucić żądanie. Jawne użycie `--allowed-models ""` również wybiera tryb `all`; połącz je z `--model-access-mode restricted`, aby zachować klucz z ograniczeniami bez dozwolonych modeli. Niepusta lista rozdzielona przecinkami wybiera tryb `restricted`, chyba że określono go jawnie. Sprzeczne połączenie trybu `all` z niepustą listą dozwolonych modeli jest odrzucane przed wysłaniem żądania. `--rate-limit 30` ustawia liczbę żądań na minutę i zachowuje reguły dla innych przedziałów czasowych. `--max-cost 5` włącza dzienny limit w USD bez zmiany limitu tygodniowego; `--max-cost 0` usuwa dzienny limit i zachowuje istniejące ustawienie limitu użycia oraz limit tygodniowy. Pominięte pola zasad pozostają bez zmian. Zmiany limitu żądań najpierw odczytują bieżące zasady; unikaj równoczesnego edytowania tablicy limitów żądań tego samego klucza. Polecenia zasad używają uwierzytelnionych żądań `GET`/`PATCH /api/keys/{id}` oraz uwzględniają aktywny kontekst i globalną opcję `--api-key`. Dane wyjściowe JSON zawierają tylko pola zasad, bez zapisanego klucza ani jego zamaskowanej reprezentacji. Poświadczenie służące wyłącznie do inferencji nie może autoryzować zmian administracyjnych. Odpowiedź 401/403 wymaga sprawdzenia poświadczeń administracyjnych i kontekstu; nie świadczy o błędzie lokalnego tokenu CLI ani soli. Informacje o odrębnym kontrakcie uwierzytelniania lokalnego znajdziesz w sekcji [Token CLI](../security/CLI_TOKEN.md).