# CLI Tools — OmniRoute (Deutsch) 🌐 **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) · 🇬🇷 [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) · 🇰🇪 [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) --- Zuletzt aktualisiert: 2026-08-23 OmniRoute integriert drei Kategorien von CLI-Tools, die auf drei dedizierte Dashboard-Seiten verteilt sind: | Seite | Route | Konzept | Anzahl | | --------------- | ----------------------- | --------------------------------------------------------------------------------- | -------------- | | **CLI-Codes** | `/dashboard/cli-code` | Coding-Tools, die auf OmniRoute verweisen (Client → CLI → OmniRoute → Anbieter) | 26 | | **CLI-Agenten** | `/dashboard/cli-agents` | Autonome Agenten, die auf OmniRoute verweisen (gleicher Ablauf, breiterer Umfang) | 10 | | **ACP-Agenten** | `/dashboard/acp-agents` | CLIs, die OmniRoute über stdio/ACP als Backend startet (umgekehrter Ablauf) | siehe Registry | Veraltete Routen werden per 308 weitergeleitet: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. --- ## Funktionsweise ``` CLI-Codes / CLI-Agenten (Nutzungsablauf): Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ (alle verweisen auf OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (OmniRoute leitet an den richtigen Anbieter weiter) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ACP-Agenten (umgekehrter Startablauf): Client-Anfrage → OmniRoute → startet CLI über stdio/ACP → Antwort ``` **Vorteile:** - Ein API-Schlüssel zur Verwaltung aller Tools - Kostenverfolgung für alle CLIs im Dashboard - Modellwechsel, ohne jedes Tool neu konfigurieren zu müssen - Funktioniert lokal und auf Remote-Servern (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## Automatisch konfigurieren mit `setup-*` Sie müssen die Konfiguration der einzelnen Tools nicht von Hand schreiben. OmniRoute enthält für jede unterstützte CLI einen `setup-*`-Befehl, der den **aktuellen** Modellkatalog einer laufenden OmniRoute-Instanz (lokal oder remote) ausliest und die eigene Konfiguration des Tools auf Ihrem Rechner erstellt: ```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 ``` Jeder Befehl akzeptiert `--remote --api-key ` (um ein lokales Tool für eine entfernte OmniRoute-Instanz zu konfigurieren), `--dry-run` (Vorschau ohne Schreibvorgang) und `--port`. Tools ohne automatische Modellerkennung (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) akzeptieren `--model ` (und `--yes` für nicht interaktive Ausführungen). `setup-5dive` ist das einzige Rezept, das nicht unter `$HOME` schreibt: Es konfiguriert eine Flotte von 5dive-Agenten, indem es auf dem Flottenhost ein Authentifizierungsprofil im Besitz von root erstellt. Daher führt es sich über `sudo` erneut aus und verfügt über keinen eigenen Remote-Modus. Um eine CLI mit den korrekten injizierten Umgebungsvariablen zu starten, ohne überhaupt eine Konfiguration zu schreiben, verwenden Sie den generischen Starter `omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini — Ziele und Aliasse stammen aus `bin/cli/cli-manifest.mjs`); die älteren toolspezifischen Starter `omniroute launch` (Claude Code) und `omniroute launch-codex` (Codex) bleiben verfügbar. Gemini CLI kann nur gestartet werden: Es ist ein Ziel für `omniroute run`, verfügt jedoch über kein `setup-*`-/`configure`-Rezept. > **Vollständige Referenz:** Die Haupttabelle — was die einzelnen Befehle schreiben, alle Flags, lokale gegenüber entfernter Verwendung und welche Tools ein `/v1`-Suffix benötigen — finden Sie unter **[CLI-Integrationen](../guides/CLI-INTEGRATIONS.md)**. ### Ausführung dieser Befehle in einem Container Ein `setup-*`-Befehl, der innerhalb des OmniRoute-Containers ausgeführt wird, schreibt in das Home-Verzeichnis des Containers. Keine CLI auf dem Host liest dieses Verzeichnis, und es verschwindet zusammen mit dem Container. OmniRoute erkennt dies und beendet sich mit Code `2` und entsprechenden Anweisungen, anstatt zu schreiben. Es gibt zwei unterstützte Vorgehensweisen: Installieren Sie die CLI auf dem Host und verwenden Sie `omniroute connect`, um eine Verbindung zum Container herzustellen, oder binden Sie die Konfigurationsverzeichnisse per Bind-Mount ein und setzen Sie `CLI_CONFIG_HOME` (das Compose-Profil `host`). Jeder `setup-*`-Befehl sowie `omniroute configure` und `omniroute config set` akzeptiert `--allow-container-write`, wenn Sie tatsächlich die CLIs des Containers selbst konfigurieren möchten; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` bewirkt dasselbe für den Server. Siehe [Docker-Leitfaden → Konfigurieren von Host-CLI-Tools](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker). Der **Apply-Endpunkt** des Dashboards (`POST /api/cli-tools/apply`) erzwingt dieselbe Schutzmaßnahme: In einem Container wird eine Schreibanforderung, deren Ziel nicht per Bind-Mount vom Host eingebunden ist, mit **`422`**, `containerEphemeralTarget: true`, dem sicheren Fehlertext und — für Tools mit einem Host-Rezept (claude, codex, opencode, cline, kilo, continue) — einem `hostSetupCommand` (z. B. `omniroute setup-opencode`) beantwortet, der stattdessen auf dem Host ausgeführt werden soll; es wird nichts geschrieben. `dryRun: true` funktioniert weiterhin im Container-Modus und gibt eine redigierte Vorschau samt Zielpfad zurück, ohne auf den Datenträger zuzugreifen. Der Vorschauinhalt ist keine Konfiguration mit Anmeldedaten, die kopiert oder importiert werden kann. Wenden Sie die Konfiguration mit den ursprünglichen Tool-/Basis-URL-/API-Schlüssel-/Modelleingaben auf dem Host an oder verwenden Sie den angegebenen hostseitigen Einrichtungsbefehl. Informationen zum Vorschau-Header und zum Anfragevertrag finden Sie unter [Sicherheit der CLI-Konfiguration](../security/CLI-CONFIGURATION.md). Dieses Verhalten ist beabsichtigt und durch `tests/unit/api/cli-tools/apply-container-guard.test.ts` gegen Regressionen abgesichert — „beheben“ Sie einen 422-Fehler niemals, indem Sie die Schutzmaßnahme entfernen. --- ## Maßgebliche Quelle Der vereinheitlichte Katalog befindet sich in `src/shared/constants/cliTools.ts` als `CLI_TOOLS: Record`. Jeder Eintrag enthält diese Felder (definiert in `src/shared/schemas/cliCatalog.ts`): | Feld | Typ | Beschreibung | | ----------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `category` | `"code" \| "agent"` | Auf welcher Seite das Tool erscheint | | `vendor` | `string` | Herkunft des Tools ("Anthropic", "OSS (P. Gauthier)") | | `acpSpawnable` | `boolean` | Auch als ACP-Agent verwendbar (Badge wird angezeigt) | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | Unterstützungsstufe für benutzerdefinierte Endpunkte. `"none"` = MITM-Backlog | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Konfigurationsmechanismus | | `id`, `name`, `color`, `description`, `docsUrl` | Standard | Zentrale Anzeigefelder | Einträge mit `baseUrlSupport: "none"` werden auf den Dashboard-Seiten **nicht angezeigt** – sie sind im MITM-Backlog für Plan 11 registriert (siehe `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`). ### Funktionsstufen (katalogisiert × erkennbar × konfigurierbar × startbar) Nicht jedes katalogisierte Tool ist erkennbar, konfigurierbar oder startbar. Für jede Stufe gibt es genau eine deklarierende Quelle, und ein Drift-Test stellt sicher, dass sie aufeinander abgestimmt bleiben: | Stufe | Bedeutung | Deklariert in | | ------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | **Katalogisiert** | Erscheint im Dashboard-Katalog (Name, Anbieter, Dokumentation, Konfigurationstyp) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`) | | **Erkennbar** | Binärdatei-/Konfigurationserkennung, Integritätsprüfungen, Konfigurationspfade | `src/shared/services/cliRuntime.ts` (`CLI_TOOLS`-Laufzeitkatalog) | | **Konfigurierbar** | Wird von `omniroute configure ` unterstützt (Einrichtungsrezept vorhanden) | `bin/cli/cli-manifest.mjs` (`configure: true`) | | **Startbar** | Wird von `omniroute run ` unterstützt (Umgebungs-/Argumentinjektion definiert) | `bin/cli/cli-manifest.mjs` (`run: true`) | `bin/cli/cli-manifest.mjs` ist das kanonische ausführbare Manifest für die Oberflächen der CLI-Befehle: `run`, `configure` und die Generatoren für die Shell-Vervollständigung leiten daraus jeweils ihre Ziellisten, die Aliasauflösung (zum Beispiel `kilocode`/`kilo-code`/`kilo_cli` → `kilo`) und die Einbindung des Flags `--model` ab. Die Drift-Schutzprüfung `tests/unit/cli/cli-manifest-drift.test.ts` stellt sicher, dass das Manifest, der Laufzeitkatalog, der UI-Katalog und alle konsumierenden Oberflächen synchron bleiben – ein Ziel, das nur einer Oberfläche hinzugefügt wird, führt zum Fehlschlagen der Testsuite, anstatt unbemerkt abzuweichen. --- ## 1. CLI-Code-Katalog (27 Tools) Alle Tools, die unter `/dashboard/cli-code` angezeigt werden. Tools mit `baseUrlSupport: none` werden über MITM oder eine manuelle Anleitung statt über eine benutzerdefinierte Basis-URL eingebunden: | id | name | vendor | 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 (ehemals 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 (ehemals 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 | Benutzerdefinierte CLI | — | full | custom-builder | false | Tools mit `baseUrlSupport: "partial"` zeigen auf der Dashboard-Karte das Badge „⚠ Partielle Basis-URL“ an. --- ## 2. Katalog der CLI-Agenten (10 Tools) Autonome Agenten, die unter `/dashboard/cli-agents` angezeigt werden: | id | name | vendor | baseUrlSupport | acpSpawnable | | ------------ | ---------------- | ------------------------ | -------------- | ------------ | | 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. ACP-Agenten (/dashboard/acp-agents) Diese Seite (umbenannt von `/dashboard/agents`) zeigt CLIs, die OmniRoute über das stdio-/ACP-Protokoll als Backend-Ausführungs-Engines **starten** kann. Der Katalog wird separat in `src/lib/acp/registry.ts` gepflegt und ist **nicht** mit `CLI_TOOLS` identisch. --- ## 4. MITM-Backlog (nicht im Dashboard angezeigt) Die folgenden CLIs unterstützen nativ keine benutzerdefinierte Basis-URL und sind auf den Seiten „CLI Code“ und „CLI Agents“ **nicht aufgeführt**. Sie sind Kandidaten für die MITM-Interzeption in Plan 11: | CLI | Grund | | ------------------- | -------------------------------------------------------------------------------- | | windsurf | BYOK ist auf ausgewählte Claude-Modelle sowie Unternehmens-URL/-Token beschränkt | | amp | Geschlossenes Ökosystem (Sourcegraph) | | amazon-q / kiro-cli | AWS-SSO-Authentifizierung, keine benutzerdefinierte URL | | cowork | Anthropic Desktop, kein konfigurierbarer Endpunkt | Die vollständige Querverweisliste befindet sich unter `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`. --- ## 5. API zur Batch-Erkennung Die gesamte Tool-Erkennung wird über einen einzigen Endpunkt aggregiert: **`GET /api/cli-tools/all-statuses`** - Authentifizierung: `requireCliToolsAuth(request)` (wie bei anderen `/api/cli-tools/`-Routen) - Rückgabe: `Record` (Typ: `src/shared/types/cliBatchStatus.ts`) - Strategie: `Promise.all` über alle Tools, Zeitüberschreitung von 5 Sekunden pro Tool - Cache: In-Memory-LRU, indiziert nach `mtime` der Konfigurationsdatei. Der Cache wird bei einer Änderung von `mtime` invalidiert. Zurücksetzung bei einem Serverneustart. Antwortstruktur pro Tool: ```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; // bereinigt, keine Stacktraces } ``` --- ## 6. Einstellungs-Handler für neue Tools Neue Tools mit `configType: "custom"` verfügen über eigene API-Routen für Einstellungen: | Route | Tool | | ------------------------------------------- | ------------------------------------------------------------------------------ | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode (--base-url-Flag) | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, veraltet) | | `POST /api/cli-tools/codewhale-settings` | CodeWhale (OPENAI_BASE_URL, primär + veraltete `~/.deepseek`-Synchronisierung) | | `POST /api/cli-tools/smelt-settings` | Smelt | | `POST /api/cli-tools/pi-settings` | Pi-Coding-Agent | | `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` + eigener `.env`-Schlüssel) | Alle Routen verwenden `sanitizeErrorMessage()` für Fehlerantworten (verbindliche Regel Nr. 12). --- ## 7. Architektur der Dashboard-Seiten ### CLI-Codes (`/dashboard/cli-code`) - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — Serverkomponente - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — Client-Raster - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — Tool-Detailseite - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 spezialisierte Tool-Karten + `ToolDetailClient.tsx` ### CLI-Agenten (`/dashboard/cli-agents`) - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — Serverkomponente - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — Client-Raster - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — verwendet `ToolDetailClient` erneut ### ACP-Agenten (`/dashboard/acp-agents`) - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — Serverkomponente (aus `agents/` verschoben) ### Gemeinsame UI-Komponenten (`src/shared/components/cli/`) | Datei | Zweck | | ----------------------- | --------------------------------------------------------------- | | `CliToolCard.tsx` | Intelligente Statuskarte (Erkennung + Konfiguration + Endpunkt) | | `CliConceptCard.tsx` | Seitenspezifische Karte zur Erläuterung des Konzepts | | `CliComparisonCard.tsx` | Dreispaltiger Vergleich der CLI-Typen | | `BaseUrlSelect.tsx` | Endpunkt-Dropdown (lokal/Cloud/benutzerdefiniert) | | `ApiKeySelect.tsx` | API-Schlüsselauswahl | | `ManualConfigModal.tsx` | Modalfenster mit kopierbarem Konfigurationsausschnitt | ### Gemeinsamer Hook (`src/shared/hooks/cli/`) | Datei | Zweck | | ------------------------- | ----------------------------------------------------------------------------------- | | `useToolBatchStatuses.ts` | Ruft `/api/cli-tools/all-statuses` ab und verwaltet den Lade-/Aktualisierungsstatus | --- ## 8. i18n In Plan 14 F9 neu hinzugefügte Namespaces: | Namespace | Zweck | | ----------- | -------------------------------------------------------------------------------------- | | `cliCommon` | Gemeinsame Texte (Kartenbeschriftungen, Konzept-/Vergleichstexte, Detailseitenangaben) | | `cliCode` | Texte der CLI-Code-Seite | | `cliAgents` | Texte der CLI-Agents-Seite | | `acpAgents` | Texte der ACP-Agents-Seite | Vollständige Übersetzungen für PT-BR und EN sind enthalten. 39 weitere Gebietsschemas greifen über die Zusammenführung auf Namespace-Ebene in `src/i18n/request.ts` automatisch auf EN zurück. --- ## 9. Schnellstart ### Schritt 1 — OmniRoute-API-Schlüssel abrufen 1. Öffne `/dashboard/api-manager` → **API-Schlüssel erstellen** 2. Vergib einen Namen (z. B. `cli-tools`) und wähle alle Berechtigungen aus 3. Kopiere den Schlüssel — du benötigst ihn für jede der unten aufgeführten CLIs > Dein Schlüssel sieht folgendermaßen aus: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Schritt 2 — CLI-Tools installieren Alle npm-basierten Tools erfordern Node.js 22.22.2+ oder 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 (startbar über `omniroute run gemini` → /v1beta-Oberfläche) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Rust-basiert # Pi coding agent # Installationsanleitung unter https://github.com/zechnerj/pi-coding-agent # jcode # Installationsanleitung unter https://github.com/1jehuang/jcode ``` --- ### Schritt 3 — Über das Dashboard konfigurieren 1. Rufe `http://localhost:20128/dashboard/cli-code` auf 2. Suche dein Tool im Raster 3. Klicke auf die Karte, um die Detailseite des Tools zu öffnen 4. Wähle deinen API-Schlüssel und die Basis-URL aus 5. Klicke auf **Konfiguration anwenden** oder kopiere den manuellen Konfigurationsausschnitt --- ### Schritt 4 — Globale Umgebungsvariablen festlegen ```bash # Universeller OmniRoute-Endpunkt 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 liest GOOGLE_GEMINI_BASE_URL am STAMM (das SDK hängt /v1beta/... selbst an) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > Ersetze für einen **Remote-Server** `localhost:20128` durch die IP-Adresse oder Domain des Servers, > z. B. `http://:20128`. --- ### Schritt 4 — Jedes Tool konfigurieren #### Claude Code ```bash # ~/.claude/settings.json erstellen: mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key" } } EOF ``` Verwende für Claude Code den Stamm des vereinheitlichten Anthropic-Gateways. Hänge hier nicht `/v1` an. **Test:** `claude "say hello"` --- #### OpenAI Codex Modernes Codex (v0.137+) liest ausschließlich `~/.codex/config.toml` — die alte `config.yaml` gehört zur veralteten npm-CLI und wird stillschweigend ignoriert. Der API- Schlüssel verbleibt in der Umgebungsvariable `OMNIROUTE_API_KEY` (`env_key`) und steht niemals in der Datei: ```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" ``` Vollständige Referenz (Profile, `wire_api`, Kontextfenster): [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` > Verwende `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`, > um Thinking-Varianten zu senden. --- #### Cline (CLI oder VS Code) **CLI-Modus:** ```bash mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF { "apiProvider": "openai", "openAiBaseUrl": "http://localhost:20128/v1", "openAiApiKey": "sk-your-omniroute-key" } EOF ``` **VS-Code-Modus:** Cline-Erweiterungseinstellungen → API-Anbieter: `OpenAI Compatible` → Basis-URL: `http://localhost:20128/v1` Alternativ kannst du das OmniRoute-Dashboard verwenden → **CLI-Tools → Cline → Konfiguration anwenden**. --- #### KiloCode (CLI oder VS Code) **CLI-Modus:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **VS-Code-Einstellungen:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` Alternativ kannst du das OmniRoute-Dashboard verwenden → **CLI-Tools → KiloCode → Konfiguration anwenden**. --- #### Continue (VS-Code-Erweiterung) Bearbeite `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Starte VS Code nach der Bearbeitung neu. --- #### VS Code Insiders (`chatLanguageModels.json`) Verwende dies, wenn VS Code Insiders für Modelle mit benutzerdefinierten Endpunkten konfiguriert ist und OmniRoute ohne ein benutzerdefiniertes Header-Feld funktionieren soll. **Empfohlener Speicherort:** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **Beispiel unter Verwendung des tokenisierten OmniRoute-Alias:** ```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" } } ] ``` **Hinweise:** - Ersetzen Sie `sk-your-omniroute-key` durch einen in OmniRoute erstellten API-Schlüssel. - Das Feld `url` sollte auf `/api/v1/vscode/{token}/chat/completions` verweisen. - Das Feld `modelsUrl` sollte auf `/api/v1/vscode/{token}/models` verweisen. - Bevorzugen Sie den normalen Ablauf über `/v1` und einen Bearer-Header, wenn der Client benutzerdefinierte Header unterstützt. - In die URL eingebettete Token dienen als Kompatibilitätslösung und können in Editor-Protokollen oder im Proxy-Verlauf erscheinen. --- #### Kiro CLI (Amazon) ```bash # Bei Ihrem AWS-/Kiro-Konto anmelden: kiro-cli login # Die CLI verwendet ihre eigene Authentifizierung – OmniRoute wird nicht als Backend für die Kiro CLI selbst benötigt. # Verwenden Sie kiro-cli zusammen mit OmniRoute für andere Tools. kiro-cli status ``` Verwenden Sie für die Desktop-App **Kiro IDE** den von OmniRoute bereitgestellten MITM-Endpunkt unter `/dashboard/cli-tools → Kiro`. --- ## 10. Interne OmniRoute-CLI Das Binärprogramm `omniroute` stellt Befehle für den Serverlebenszyklus, die Einrichtung, Diagnose und Providerverwaltung bereit. Einstiegspunkt: `bin/omniroute.mjs`. ```bash omniroute # Server starten (Standardport 20128) omniroute setup # Interaktiver Einrichtungsassistent omniroute doctor # Konfiguration, DB, Ports und Laufzeit prüfen omniroute providers list # Konfigurierte Providerverbindungen omniroute providers test-all # Jede aktive Verbindung testen omniroute reset-password # Administratorpasswort zurücksetzen omniroute logs # Anforderungsprotokolle streamen omniroute health # Detaillierter Zustand (Unterbrecher, Cache, Arbeitsspeicher) omniroute --version # Version ausgeben omniroute --help # Alle Befehle anzeigen ``` ### Einrichtung & Initialisierung ```bash omniroute setup # Interaktiver Einrichtungsassistent omniroute setup --non-interactive # CI-/Automatisierungsmodus (liest Umgebungsvariablen + Flags) omniroute setup --password '' # Administratorpasswort direkt festlegen omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Einen Provider in einem Schritt hinzufügen und testen ``` Erkannte Umgebungsvariablen für die nicht interaktive Einrichtung: | Variable | Zweck | | ------------------- | ------------------------------------------------------------------------ | | `OMNIROUTE_API_KEY` | Provider-API-Schlüssel (über Commander `.env()` an `--api-key` gebunden) | | `DATA_DIR` | OmniRoute-Datenverzeichnis überschreiben | Alle anderen nicht interaktiven Eingaben werden als Flags und nicht als Umgebungsvariablen übergeben: `--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model` (siehe die Optionen von `omniroute setup` oben). ### Diagnose ```bash omniroute doctor # Konfiguration, DB, Ports, Laufzeit, Arbeitsspeicher und Erreichbarkeit prüfen omniroute doctor --json # Maschinenlesbares JSON omniroute doctor --no-liveness # HTTP-Zustandsprüfung überspringen omniroute doctor --host 0.0.0.0 # Host für die Erreichbarkeitsprüfung überschreiben omniroute doctor --liveness-url # Vollständige URL des Zustandsendpunkts überschreiben ``` Der Doctor führt folgende Prüfungen aus: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory` und `Server liveness`. Er wird mit einem Exit-Code ungleich null beendet, wenn eine Prüfung den Status `fail` aufweist. ### Providerverwaltung ```bash omniroute providers available # OmniRoute-Providerkatalog omniroute providers available --search openai # Katalog nach ID/Name/Alias/Kategorie filtern omniroute providers available --category api-key # Nach Kategorie filtern (api-key, oauth, free, ...) omniroute providers available --json # Maschinenlesbares JSON omniroute providers list # Konfigurierte Providerverbindungen omniroute providers list --json omniroute providers test # Eine konfigurierte Verbindung testen omniroute providers test-all # Jede aktive Verbindung testen omniroute providers validate # Rein lokale Strukturvalidierung omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # Bestehender OAuth-Ablauf omniroute providers edit --default-model omniroute providers remove --yes ``` `providers add/import/auth/edit/remove` sind API-orientiert und funktionieren daher mit dem aktiven lokalen oder entfernten Kontext. Anmeldedaten sollten über `--credential-stdin` oder `--credential-env` eingegeben werden; `--dry-run --json` meldet nur redigierte Angaben zu Vorhandensein und Struktur. `providers available` liest den OmniRoute-Katalog; `providers list/test/test-all/validate` behalten ihr lokales SQLite-Verhalten bei und erfordern keinen laufenden Server. Hängen Sie für einen benutzerdefinierten OpenAI- oder Anthropic-kompatiblen Knoten Anmeldedaten an die von `omniroute nodes add` zurückgegebene Knoten-ID an, indem Sie `omniroute keys add "$NODE_ID" --stdin` verwenden. Dies erfordert einen laufenden Server und eine Verwaltungsauthentifizierung für den aktiven Kontext. Die CLI verwendet `POST /api/providers`, wodurch der Knoten validiert und dessen Endpunkteinstellungen in die Verbindung kopiert werden. Bei einem fehlenden Knoten, einer fehlgeschlagenen Autorisierung oder einem nicht verfügbaren Server wird ein Fehler zurückgegeben, ohne lokale Ersatzanmeldedaten zu erstellen. `nodes add --base-url` legt den Knotenendpunkt fest; dieser unterscheidet sich von der Serveradresse in `OMNIROUTE_BASE_URL`. Verwenden Sie für OpenAPI-Dateien `omniroute openapi dump --format json --out ./openapi.json`; das globale `--output` bestimmt die Anzeigeformatierung der CLI und nicht den Namen einer Zieldatei. ### Wiederherstellung & Zurücksetzen ```bash omniroute reset-password # Administratorpasswort zurücksetzen (auch: omniroute-reset-password) omniroute reset-encrypted-columns # Warnung + Testlauf für das Zurücksetzen verschlüsselter Anmeldedaten anzeigen omniroute reset-encrypted-columns --force # Verschlüsselte Anmeldedaten in SQLite tatsächlich auf null setzen ``` ### Export von Anmeldedaten (⚠ mit Vorsicht behandeln) ```bash omniroute auth export # Warnung + Bestätigungsabfrage anzeigen — kein DB-Zugriff omniroute auth export --force # ENTSCHLÜSSELTE Anmeldedaten ALLER Verbindungen als JSON auf stdout exportieren omniroute auth export --force --id # Nur die übereinstimmende Verbindung exportieren omniroute auth export --force --format env # Zeilen im Format OMNIROUTE__= ausgeben omniroute auth export --force --out creds.json # In eine Datei schreiben (mit Berechtigungen 0600 erstellt) ``` `auth export` funktioniert **nur lokal** (direkter SQLite-Lesezugriff, keine HTTP-Route) und gibt absichtlich **unverschlüsselte** `apiKey`-/`accessToken`-/`refreshToken`-/`idToken`-Werte aus bzw. schreibt sie — das ist eine Funktion und kein Fehler. Ohne `--force` wird nichts aus der Datenbank gelesen und nichts entschlüsselt. Bevor unverschlüsselte Daten ausgegeben werden, erscheint auf stderr immer ein Warnhinweis. Erfordert, dass `STORAGE_ENCRYPTION_KEY` gesetzt ist. Bei einem Feld, das nicht entschlüsselt werden kann (veralteter Schlüssel, beschädigter Geheimtext), wird `DecryptFailed: true` gemeldet, statt den gesamten Export abzubrechen oder den zugrunde liegenden Fehler offenzulegen. ### Weitere Unterbefehle Diese setzen einen laufenden OmniRoute-Server voraus, sofern nicht anders angegeben: ```bash omniroute status # Umfassender Laufzeitstatus omniroute logs # Anforderungsprotokolle streamen (--json, --search, --follow) omniroute config list # Konfigurierte CLI-Tools anzeigen omniroute provider list # Verfügbare Anbieter auflisten (Alias für providers list) omniroute provider add # OmniRoute als Anbieter für ein Tool registrieren omniroute keys add | list | remove # API-Schlüssel verwalten omniroute models [provider] # Modelle auflisten (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Momentaufnahme von Konfiguration und DB erstellen omniroute restore # Aus einer früheren Momentaufnahme wiederherstellen omniroute health # Detaillierter Systemzustand (Schutzschalter, Cache, Arbeitsspeicher) omniroute quota # Nutzung des Anbieterkontingents omniroute cache # Cache-Status omniroute cache clear # Semantische und Signatur-Caches leeren omniroute mcp status | restart # MCP-Serverstatus / Neustart omniroute a2a status | card # A2A-Serverstatus / Agentenkarte omniroute tunnel list | create | stop # Tunnel verwalten (cloudflare/tailscale/ngrok) omniroute env show | get | set # Umgebungsvariablen anzeigen / festlegen (temporär) omniroute test # Schnelltest der Anbieterkonnektivität omniroute update # Nach Updates suchen omniroute completion # Shell-Vervollständigung generieren ``` ### Allgemeine Optionen | Option | Beschreibung | | ------------------- | ----------------------------------------------------------------------------- | | `--no-open` | Browser beim Start nicht automatisch öffnen | | `--port ` | API-Port überschreiben (Standardwert: 20128) | | `--mcp` | Als MCP-Server über stdio ausführen (für IDEs) | | `--non-interactive` | CI-Modus (keine Eingabeaufforderungen; liest aus Umgebungsvariablen/Optionen) | | `--json` | Maschinenlesbare JSON-Ausgabe (doctor, providers usw.) | | `--help`, `-h` | Befehlsspezifische Hilfe anzeigen | | `--version`, `-v` | Installierte Version ausgeben | --- ## Verfügbare API-Endpunkte | Endpunkt | Beschreibung | Verwendungszweck | | -------------------------- | --------------------------------- | ------------------------------------- | | `/v1/chat/completions` | Standard-Chat (alle Anbieter) | Alle modernen Tools | | `/v1/responses` | Responses API (OpenAI-Format) | Codex, agentenbasierte Arbeitsabläufe | | `/v1/completions` | Veraltete Textvervollständigungen | Ältere Tools mit `prompt:` | | `/v1/embeddings` | Texteinbettungen | RAG, Suche | | `/v1/images/generations` | Bilderzeugung | GPT-Image, Flux usw. | | `/v1/audio/speech` | Text-zu-Sprache | ElevenLabs, OpenAI TTS | | `/v1/audio/transcriptions` | Sprache-zu-Text | Deepgram, AssemblyAI | Direkt einsetzbare Beispiele mit einer tokenisierten OmniRoute-URL: ```txt Token-Beispiel: sk-a3ab3c080beaee3a-69f4a4-070d71af Standard-OpenAI-Basis: http://localhost:20128/v1 VS Code-Modelle: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models VS Code-Chat: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions VS Code-Responses: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Ollama-Tags: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Ollama-Chat: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## Fehlerbehebung | Fehler | Ursache | Lösung | | -------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- | | `Connection refused` | OmniRoute wird nicht ausgeführt | `omniroute serve` | | `401 Unauthorized` | Falscher API-Schlüssel | Unter `/dashboard/api-manager` prüfen | | `No combo configured` | Keine aktive Routing-Kombination | Unter `/dashboard/combos` einrichten | | CLI zeigt „nicht installiert“ an | Binärdatei nicht im PATH | `which ` prüfen | | Dashboard zeigt nach der Installation „nicht erkannt“ an | Veralteter Cache | Im Dashboard auf „⟳ Erkennung aktualisieren“ klicken | | Alter Link `/dashboard/cli-tools` | Lesezeichen von vor v3.8.6 | Automatische Weiterleitung zu `/dashboard/cli-code` (308) | | Alter Link `/dashboard/agents` | Lesezeichen von vor v3.8.6 | Automatische Weiterleitung zu `/dashboard/acp-agents` (308) | ## Richtlinie für Inferenzschlüssel mit der OmniRoute CLI verwalten Verwenden Sie einen authentifizierten Verwaltungskontext (siehe [Remote-Modus](../guides/REMOTE-MODE.md)), um einen vorhandenen Inferenzschlüssel anhand seiner ID zu überprüfen oder zu aktualisieren: ```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` ist ein Alias für `--model-access-mode all`. Durch die Aktualisierung wird die Modell-Zulassungsliste gelöscht. Gültigkeitsbereiche, Verbindungsregeln, gesperrte Modelle, Ratenbegrenzungen und Kostenlimits bleiben erhalten, sodass diese anderen Kontrollen eine Anfrage weiterhin ablehnen können. Ein explizites `--allowed-models ""` wählt ebenfalls `all`; kombinieren Sie es mit `--model-access-mode restricted`, um einen eingeschränkten Schlüssel ohne zulässige Modelle beizubehalten. Eine nicht leere, durch Kommas getrennte Liste wählt `restricted`, sofern nicht ausdrücklich anders angegeben. Die widersprüchliche Kombination aus `all` und einer nicht leeren Zulassungsliste wird vor dem Senden einer Anfrage abgelehnt. `--rate-limit 30` legt die Anzahl der Anfragen pro Minute fest und behält Regeln für andere Zeitfenster bei. `--max-cost 5` aktiviert die tägliche Obergrenze in USD, ohne die wöchentliche Obergrenze zu ändern; `--max-cost 0` entfernt die tägliche Obergrenze und behält den vorhandenen Schalter für das Nutzungslimit sowie die wöchentliche Obergrenze bei. Nicht angegebene Richtlinienfelder bleiben unverändert. Bei Änderungen der Ratenbegrenzung wird zunächst die aktuelle Richtlinie gelesen; vermeiden Sie gleichzeitige Änderungen am Ratenbegrenzungs-Array desselben Schlüssels. Richtlinienbefehle verwenden authentifizierte `GET`/`PATCH /api/keys/{id}`-Anfragen und berücksichtigen den aktiven Kontext sowie die globale Option `--api-key`. Die JSON-Ausgabe enthält ausschließlich Richtlinienfelder, nicht den gespeicherten Schlüssel oder dessen maskierte Darstellung. Eine ausschließlich für Inferenz vorgesehene Anmeldeinformation kann keine Verwaltungsänderungen autorisieren. Bei einem 401/403-Fehler müssen die Verwaltungsanmeldeinformationen und der Kontext überprüft werden; dies ist kein Nachweis für einen Fehler des lokalen CLI-Tokens oder Salts. Informationen zum separaten lokalen Authentifizierungsvertrag finden Sie unter [CLI-Token](../security/CLI_TOKEN.md).