# CLI Tools — OmniRoute (Español) 🌐 **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) · 🇪🇪 [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) --- Última actualización: 2026-08-23 OmniRoute se integra con tres categorías de herramientas CLI distribuidas en tres páginas específicas del panel: | Página | Ruta | Concepto | Cantidad | | --------------- | ----------------------- | -------------------------------------------------------------------------------------------- | -------------------- | | **Códigos CLI** | `/dashboard/cli-code` | Herramientas de programación que diriges a OmniRoute (Cliente → CLI → OmniRoute → Proveedor) | 26 | | **Agentes CLI** | `/dashboard/cli-agents` | Agentes autónomos que diriges a OmniRoute (mismo flujo, alcance más amplio) | 10 | | **Agentes ACP** | `/dashboard/acp-agents` | CLI que OmniRoute inicia como backend mediante stdio/ACP (flujo inverso) | consulta el registro | Las rutas heredadas redirigen mediante 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. --- ## Cómo funciona ``` Códigos CLI / Agentes CLI (flujo de consumo): Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ (todos apuntan a OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (OmniRoute dirige la solicitud al proveedor adecuado) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... Agentes ACP (flujo inverso de inicio): Solicitud del cliente → OmniRoute → inicia la CLI mediante stdio/ACP → respuesta ``` **Ventajas:** - Una única clave de API para gestionar todas las herramientas - Seguimiento de costes de todas las CLI en el panel - Cambio de modelo sin tener que reconfigurar cada herramienta - Funciona tanto localmente como en servidores remotos (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## Configuración automática con `setup-*` No es necesario escribir manualmente la configuración de cada herramienta. OmniRoute incluye un comando `setup-*` por cada CLI compatible que lee el catálogo de modelos **activo** de una instancia de OmniRoute en ejecución (local o remota) y escribe la configuración propia de la herramienta en tu máquina: ```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 ``` Cada uno acepta `--remote --api-key ` (para configurar una herramienta local con una instancia remota de OmniRoute), `--dry-run` (para obtener una vista previa sin escribir) y `--port`. Las herramientas sin detección automática de modelos (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) aceptan `--model ` (y `--yes` para ejecuciones no interactivas). `setup-5dive` es la única receta que no escribe en `$HOME`: configura una flota de agentes 5dive escribiendo un perfil de autenticación propiedad de root en el host de la flota, por lo que vuelve a ejecutarse mediante `sudo` y no tiene un modo remoto propio. Para iniciar una CLI con las variables de entorno correctas inyectadas y sin escribir ninguna configuración, utiliza el iniciador genérico `omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini — los destinos y alias proceden de `bin/cli/cli-manifest.mjs`); los iniciadores heredados específicos de cada herramienta `omniroute launch` (Claude Code) y `omniroute launch-codex` (Codex) siguen estando disponibles. Gemini CLI solo puede iniciarse: es un destino de `omniroute run`, pero no tiene una receta `setup-*`/`configure`. > **Referencia completa:** la tabla principal —qué escribe cada comando, todas las opciones, > local frente a remoto y qué herramientas requieren el sufijo `/v1`— se encuentra en > **[Integraciones de CLI](../guides/CLI-INTEGRATIONS.md)**. ### Ejecución dentro de un contenedor Un comando `setup-*` ejecutado dentro del contenedor de OmniRoute escribe en el directorio personal del propio contenedor, que ninguna CLI del host lee y que desaparece junto con el contenedor. OmniRoute detecta esta situación y termina con el código `2` y muestra instrucciones en lugar de escribir. Existen dos alternativas compatibles: instalar la CLI en el host y ejecutar `omniroute connect` para conectarse al contenedor, o montar mediante bind los directorios de configuración y establecer `CLI_CONFIG_HOME` (el perfil `host` de Compose). Todos los comandos `setup-*`, además de `omniroute configure` y `omniroute config set`, aceptan `--allow-container-write` cuando realmente se desea configurar las propias CLI del contenedor; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` hace lo mismo para el servidor. Consulta [Guía de Docker → Configuración de herramientas CLI del host](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker). El **endpoint de aplicación** del panel (`POST /api/cli-tools/apply`) aplica la misma protección: en un contenedor, una escritura cuyo destino no está montado mediante bind desde el host responde con **`422`**, `containerEphemeralTarget: true`, el texto de error seguro y —para las herramientas con una receta para el host (claude, codex, opencode, cline, kilo, continue)— un `hostSetupCommand` (por ejemplo, `omniroute setup-opencode`) que debe ejecutarse en el host; no se escribe nada. `dryRun: true` continúa funcionando en modo contenedor y devuelve una vista previa redactada junto con la ruta de destino sin modificar el disco. El contenido de la vista previa no es una configuración con credenciales que deba copiarse o importarse. Realiza la aplicación en el host con los valores originales de herramienta, URL base, clave de API y modelo, o utiliza el comando de configuración en el host indicado. Consulta [Seguridad de la configuración de CLI](../security/CLI-CONFIGURATION.md) para conocer la cabecera de vista previa y el contrato de solicitud. Este comportamiento es intencionado y está protegido contra regresiones mediante `tests/unit/api/cli-tools/apply-container-guard.test.ts`; nunca «corrijas» un error 422 eliminando la protección. --- ## Fuente de referencia El catálogo unificado se encuentra en `src/shared/constants/cliTools.ts` como `CLI_TOOLS: Record`. Cada entrada tiene estos campos (definidos en `src/shared/schemas/cliCatalog.ts`): | Campo | Tipo | Descripción | | ----------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `category` | `"code" \| "agent"` | Página en la que aparece la herramienta | | `vendor` | `string` | Origen de la herramienta ("Anthropic", "OSS (P. Gauthier)") | | `acpSpawnable` | `boolean` | También se puede usar como agente ACP (se muestra una insignia) | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | Nivel de compatibilidad con endpoints personalizados. `"none"` = pendiente de MITM | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Mecanismo de configuración | | `id`, `name`, `color`, `description`, `docsUrl` | estándar | Campos principales de visualización | Las entradas con `baseUrlSupport: "none"` **no se muestran** en las páginas del panel de control; están registradas en la lista de tareas pendientes de MITM para el plan 11 (consulta `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`). ### Niveles de capacidad (catalogado × detectable × configurable × ejecutable) No todas las herramientas catalogadas son detectables, configurables o ejecutables. Cada nivel tiene una fuente declarativa, y una prueba de divergencia las mantiene alineadas: | Nivel | Significado | Declarado en | | ---------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Catalogado** | Aparece en el catálogo del panel (nombre, proveedor, documentación y tipo de configuración) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`) | | **Detectable** | Detección del binario/configuración, comprobaciones de estado y rutas de configuración | `src/shared/services/cliRuntime.ts` (catálogo de ejecución `CLI_TOOLS`) | | **Configurable** | Compatible con `omniroute configure ` (existe una receta de configuración) | `bin/cli/cli-manifest.mjs` (`configure: true`) | | **Ejecutable** | Compatible con `omniroute run ` (inyección de entorno/argumentos definida) | `bin/cli/cli-manifest.mjs` (`run: true`) | `bin/cli/cli-manifest.mjs` es el manifiesto ejecutable canónico para las interfaces de comandos de la CLI: `run`, `configure` y los generadores de autocompletado del shell derivan de él sus listas de destinos, la resolución de alias (por ejemplo, `kilocode`/`kilo-code`/`kilo_cli` → `kilo`) y la integración del indicador `--model`. La protección contra divergencias `tests/unit/cli/cli-manifest-drift.test.ts` comprueba que el manifiesto, el catálogo de ejecución, el catálogo de la interfaz de usuario y todas las interfaces consumidoras permanezcan sincronizados: si se añade un destino a una interfaz sin añadirlo a las demás, el conjunto de pruebas falla en lugar de permitir que diverjan silenciosamente. --- ## 1. Catálogo de CLI Code (27 herramientas) Todas las herramientas que aparecen en `/dashboard/cli-code`. Las que tienen `baseUrlSupport: none` se conectan mediante MITM o una guía manual en lugar de una URL base personalizada: | id | nombre | proveedor | 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 (antes 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 (antes 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 | CLI personalizada | — | full | custom-builder | false | Las herramientas con `baseUrlSupport: "partial"` muestran una insignia "⚠ URL base parcial" en la tarjeta del panel. --- ## 2. Catálogo de agentes CLI (10 herramientas) Agentes autónomos que aparecen en `/dashboard/cli-agents`: | id | nombre | proveedor | compatibilidad con baseUrl | iniciable mediante 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. Agentes ACP (/dashboard/acp-agents) Esta página (renombrada desde `/dashboard/agents`) muestra las CLI que OmniRoute puede **iniciar** como motores de ejecución de backend mediante el protocolo stdio/ACP. El catálogo se mantiene por separado en `src/lib/acp/registry.ts` y **no** es el mismo que `CLI_TOOLS`. --- ## 4. Trabajo pendiente de MITM (no se muestra en el panel) Las siguientes CLI no admiten de forma nativa una URL base personalizada y **no aparecen** en las páginas CLI Code ni CLI Agents. Son candidatas para la interceptación MITM en el plan 11: | CLI | Motivo | | ------------------- | ---------------------------------------------------------------------- | | windsurf | BYOK limitado a determinados modelos de Claude + URL/token corporativo | | amp | Ecosistema cerrado (Sourcegraph) | | amazon-q / kiro-cli | Autenticación mediante AWS SSO, sin URL personalizada | | cowork | Anthropic Desktop, sin endpoint configurable | Consulta `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` para obtener la referencia cruzada completa. --- ## 5. API de detección por lotes Toda la detección de herramientas se agrega mediante un único endpoint: **`GET /api/cli-tools/all-statuses`** - Autenticación: `requireCliToolsAuth(request)` (igual que las demás rutas de `/api/cli-tools/`) - Devuelve: `Record` (tipo: `src/shared/types/cliBatchStatus.ts`) - Estrategia: `Promise.all` para todas las herramientas, con un tiempo de espera de 5 s por herramienta - Caché: LRU en memoria indexada por el `mtime` del archivo de configuración. La caché se invalida cuando cambia el mtime. Se restablece al reiniciar el servidor. Estructura de la respuesta por herramienta: ```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; // saneado, sin trazas de pila } ``` --- ## 6. Manejadores de configuración para nuevas herramientas Las nuevas herramientas con `configType: "custom"` tienen rutas de API de configuración específicas: | Ruta | Herramienta | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode (opción --base-url) | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, heredado) | | `POST /api/cli-tools/codewhale-settings` | CodeWhale (OPENAI_BASE_URL, sincronización principal + heredada con `~/.deepseek`) | | `POST /api/cli-tools/smelt-settings` | Smelt | | `POST /api/cli-tools/pi-settings` | Agente de programación 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` + clave `.env` específica) | Todas las rutas usan `sanitizeErrorMessage()` para las respuestas de error (regla estricta n.º 12). --- ## 7. Arquitectura de las páginas del panel ### CLI Code's (`/dashboard/cli-code`) - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — componente de servidor - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — cuadrícula del cliente - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — página de detalles de la herramienta - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 tarjetas especializadas de herramientas + `ToolDetailClient.tsx` ### CLI Agents (`/dashboard/cli-agents`) - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — componente de servidor - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — cuadrícula del cliente - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — reutiliza `ToolDetailClient` ### ACP Agents (`/dashboard/acp-agents`) - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — componente de servidor (movido desde `agents/`) ### Componentes de interfaz compartidos (`src/shared/components/cli/`) | Archivo | Propósito | | ----------------------- | -------------------------------------------------------------------- | | `CliToolCard.tsx` | Tarjeta de estado inteligente (detección + configuración + endpoint) | | `CliConceptCard.tsx` | Tarjeta explicativa de conceptos para cada página | | `CliComparisonCard.tsx` | Comparación en tres columnas entre tipos de CLI | | `BaseUrlSelect.tsx` | Menú desplegable de endpoints (local/nube/personalizado) | | `ApiKeySelect.tsx` | Selector de claves de API | | `ManualConfigModal.tsx` | Ventana modal con fragmento de configuración copiable | ### Hook compartido (`src/shared/hooks/cli/`) | Archivo | Propósito | | ------------------------- | --------------------------------------------------------------------------------- | | `useToolBatchStatuses.ts` | Obtiene `/api/cli-tools/all-statuses` y gestiona el estado de carga/actualización | --- ## 8. i18n Nuevos espacios de nombres añadidos en el plan 14 F9: | Espacio de nombres | Propósito | | ------------------ | ---------------------------------------------------------------------------------------------------------------- | | `cliCommon` | Cadenas compartidas (etiquetas de tarjetas, textos de conceptos/comparaciones, etiquetas de páginas de detalles) | | `cliCode` | Cadenas de la página de CLI Code | | `cliAgents` | Cadenas de la página de CLI Agents | | `acpAgents` | Cadenas de la página de ACP Agents | Se proporcionan traducciones completas para PT-BR y EN. Las otras 39 configuraciones regionales recurren automáticamente a EN mediante la combinación a nivel de espacio de nombres en `src/i18n/request.ts`. --- ## 9. Inicio rápido ### Paso 1 — Obtener una clave de API de OmniRoute 1. Abre `/dashboard/api-manager` → **Crear clave de API** 2. Asígnale un nombre (p. ej., `cli-tools`) y selecciona todos los permisos 3. Copia la clave; la necesitarás para cada CLI indicada a continuación > Tu clave tiene este aspecto: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Paso 2 — Instalar las herramientas de CLI Todas las herramientas basadas en npm requieren Node.js 22.22.2+ o 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 (se puede iniciar mediante `omniroute run gemini` → interfaz /v1beta) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Basado en Rust # Agente de programación Pi # Consulta https://github.com/zechnerj/pi-coding-agent para instalarlo # jcode # Consulta https://github.com/1jehuang/jcode para instalarlo ``` --- ### Paso 3 — Configurar mediante el panel 1. Ve a `http://localhost:20128/dashboard/cli-code` 2. Busca tu herramienta en la cuadrícula 3. Haz clic en la tarjeta para abrir la página de detalles de la herramienta 4. Selecciona tu clave de API y la URL base 5. Haz clic en **Aplicar configuración** o copia el fragmento de configuración manual --- ### Paso 4 — Establecer variables de entorno globales ```bash # Endpoint universal de 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 lee GOOGLE_GEMINI_BASE_URL en la RAÍZ (su SDK añade /v1beta/... por sí mismo) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > Para un **servidor remoto**, sustituye `localhost:20128` por la IP o el dominio del servidor, > p. ej., `http://:20128`. --- ### Paso 4 — Configurar cada herramienta #### Claude Code ```bash # Crear ~/.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 ``` Usa la raíz unificada de la puerta de enlace de Anthropic para Claude Code. No añadas `/v1` aquí. **Prueba:** `claude "say hello"` --- #### OpenAI Codex La versión moderna de Codex (v0.137+) solo lee `~/.codex/config.toml`; el antiguo `config.yaml` pertenece a la CLI heredada de npm y se ignora silenciosamente. La clave de API permanece en la variable de entorno `OMNIROUTE_API_KEY` (`env_key`), nunca dentro del archivo: ```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" ``` Referencia completa (perfiles, `wire_api`, ventanas de contexto): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md). **Prueba:** `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 ``` **Prueba:** `opencode` > Usa `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` > para enviar variantes de razonamiento. --- #### Cline (CLI o VS Code) **Modo 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 ``` **Modo VS Code:** Configuración de la extensión Cline → Proveedor de API: `OpenAI Compatible` → URL base: `http://localhost:20128/v1` También puedes usar el panel de OmniRoute → **Herramientas de CLI → Cline → Aplicar configuración**. --- #### KiloCode (CLI o VS Code) **Modo CLI:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **Configuración de VS Code:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` También puedes usar el panel de OmniRoute → **Herramientas de CLI → KiloCode → Aplicar configuración**. --- #### Continue (extensión de VS Code) Edita `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Reinicia VS Code después de editarlo. --- #### VS Code Insiders (`chatLanguageModels.json`) Usa esta opción cuando VS Code Insiders esté configurado para modelos con endpoints personalizados y quieras que OmniRoute funcione sin un campo de encabezado personalizado. **Ubicación recomendada:** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **Ejemplo usando el alias tokenizado de 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" } } ] ``` **Notas:** - Reemplaza `sk-your-omniroute-key` por una clave de API creada en OmniRoute. - El campo `url` debe apuntar a `/api/v1/vscode/{token}/chat/completions`. - El campo `modelsUrl` debe apuntar a `/api/v1/vscode/{token}/models`. - Da preferencia al flujo normal de `/v1` + encabezado Bearer cuando el cliente admita encabezados personalizados. - Los tokens incrustados en la URL son una alternativa de compatibilidad y pueden aparecer en los registros del editor o en el historial del proxy. --- #### Kiro CLI (Amazon) ```bash # Inicia sesión en tu cuenta de AWS/Kiro: kiro-cli login # La CLI utiliza su propia autenticación; OmniRoute no es necesario como backend para la propia CLI de Kiro. # Utiliza kiro-cli junto con OmniRoute para otras herramientas. kiro-cli status ``` Para la aplicación de escritorio **Kiro IDE**, utiliza el endpoint MITM expuesto por OmniRoute en `/dashboard/cli-tools → Kiro`. --- ## 10. CLI interna de OmniRoute El binario `omniroute` proporciona comandos para el ciclo de vida del servidor, la configuración, el diagnóstico y la gestión de proveedores. Punto de entrada: `bin/omniroute.mjs`. ```bash omniroute # Iniciar el servidor (puerto predeterminado 20128) omniroute setup # Asistente de configuración interactivo omniroute doctor # Comprobar configuración, BD, puertos y entorno de ejecución omniroute providers list # Conexiones de proveedores configuradas omniroute providers test-all # Probar todas las conexiones activas omniroute reset-password # Restablecer la contraseña de administrador omniroute logs # Transmitir registros de solicitudes omniroute health # Estado detallado (disyuntores, caché, memoria) omniroute --version # Mostrar la versión omniroute --help # Mostrar todos los comandos ``` ### Configuración e inicialización ```bash omniroute setup # Asistente de configuración interactivo omniroute setup --non-interactive # Modo CI/automatización (lee variables de entorno + opciones) omniroute setup --password '' # Establecer directamente la contraseña de administrador omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Añadir y probar un proveedor en una sola operación ``` Variables de entorno reconocidas para la configuración no interactiva: | Variable | Propósito | | ------------------- | ----------------------------------------------------------------------------------- | | `OMNIROUTE_API_KEY` | Clave de API del proveedor (vinculada a `--api-key` mediante `.env()` de Commander) | | `DATA_DIR` | Sobrescribir el directorio de datos de OmniRoute | Todas las demás entradas no interactivas se pasan como opciones, no como variables de entorno: `--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model` (consulte las opciones de `omniroute setup` anteriores). ### Diagnóstico ```bash omniroute doctor # Comprobar configuración, BD, puertos, entorno de ejecución, memoria y disponibilidad omniroute doctor --json # JSON legible por máquinas omniroute doctor --no-liveness # Omitir la comprobación de estado HTTP omniroute doctor --host 0.0.0.0 # Sobrescribir el host de comprobación de disponibilidad omniroute doctor --liveness-url # Sobrescribir la URL completa del endpoint de estado ``` El comando doctor ejecuta estas comprobaciones: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory` y `Server liveness`. Finaliza con un código distinto de cero si alguna comprobación devuelve `fail`. ### Gestión de proveedores ```bash omniroute providers available # Catálogo de proveedores de OmniRoute omniroute providers available --search openai # Filtrar el catálogo por id/nombre/alias/categoría omniroute providers available --category api-key # Filtrar por categoría (api-key, oauth, free, ...) omniroute providers available --json # JSON legible por máquinas omniroute providers list # Conexiones de proveedores configuradas omniroute providers list --json omniroute providers test # Probar una conexión configurada omniroute providers test-all # Probar todas las conexiones activas omniroute providers validate # Validación estructural exclusivamente local omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # Flujo OAuth existente omniroute providers edit --default-model omniroute providers remove --yes ``` `providers add/import/auth/edit/remove` usan primero la API y, por tanto, funcionan con el contexto local o remoto activo. Para introducir credenciales, se debe usar `--credential-stdin` o `--credential-env`; `--dry-run --json` informa únicamente de la presencia y la estructura ocultando los datos sensibles. `providers available` lee el catálogo de OmniRoute; `providers list/test/test-all/validate` conservan su comportamiento local con SQLite y no requieren que el servidor esté en ejecución. Para un nodo personalizado compatible con OpenAI o Anthropic, asocie las credenciales al ID de nodo devuelto por `omniroute nodes add` mediante `omniroute keys add "$NODE_ID" --stdin`. Esto requiere que haya un servidor en ejecución y autenticación de gestión para el contexto activo. La CLI utiliza `POST /api/providers`, que valida el nodo y copia la configuración de su endpoint en la conexión. Si falta el nodo, falla la autorización o el servidor no está disponible, se devuelve un error sin crear una credencial local alternativa. `nodes add --base-url` establece el endpoint del nodo; es distinto de la dirección del servidor en `OMNIROUTE_BASE_URL`. Para archivos OpenAPI, utilice `omniroute openapi dump --format json --out ./openapi.json`; la opción global `--output` selecciona el formato de visualización de la CLI, no un nombre de archivo de destino. ### Recuperación y restablecimiento ```bash omniroute reset-password # Restablecer la contraseña de administrador (también: omniroute-reset-password) omniroute reset-encrypted-columns # Mostrar advertencia + simulación del restablecimiento de credenciales cifradas omniroute reset-encrypted-columns --force # Anular realmente las credenciales cifradas en SQLite ``` ### Exportación de credenciales (⚠ manipular con precaución) ```bash omniroute auth export # Mostrar advertencia + solicitud de confirmación, sin acceso a la BD omniroute auth export --force # Exportar a stdout las credenciales DESCIFRADAS de TODAS las conexiones como JSON omniroute auth export --force --id # Exportar únicamente la conexión coincidente omniroute auth export --force --format env # Emitir líneas OMNIROUTE__= omniroute auth export --force --out creds.json # Escribir en un archivo (creado con permisos 0600) ``` `auth export` es **solo local** (lectura directa de SQLite, sin ruta HTTP) e imprime/escribe intencionadamente valores **en texto plano** de `apiKey`/`accessToken`/`refreshToken`/`idToken`: esa es la funcionalidad, no un error. No se lee nada de la base de datos ni se descifra nada sin `--force`. Siempre se muestra un aviso de advertencia en stderr antes de emitir cualquier texto plano. Requiere que `STORAGE_ENCRYPTION_KEY` esté definida. Si un campo no se puede descifrar (clave obsoleta, texto cifrado dañado), se indica `DecryptFailed: true` en lugar de cancelar toda la exportación o exponer el error subyacente. ### Otros subcomandos Estos presuponen que hay un servidor OmniRoute en ejecución, salvo que se indique lo contrario: ```bash omniroute status # Estado completo del entorno de ejecución omniroute logs # Transmitir registros de solicitudes (--json, --search, --follow) omniroute config list # Mostrar las herramientas CLI configuradas omniroute provider list # Enumerar los proveedores disponibles (alias de providers list) omniroute provider add # Registrar OmniRoute como proveedor en una herramienta omniroute keys add | list | remove # Gestionar claves de API omniroute models [provider] # Enumerar modelos (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Crear una instantánea de la configuración y la BD omniroute restore # Restaurar desde una instantánea anterior omniroute health # Estado detallado (disyuntores, caché, memoria) omniroute quota # Uso de la cuota del proveedor omniroute cache # Estado de la caché omniroute cache clear # Borrar las cachés semántica y de firmas omniroute mcp status | restart # Estado/reinicio del servidor MCP omniroute a2a status | card # Estado del servidor A2A/tarjeta del agente omniroute tunnel list | create | stop # Gestionar túneles (cloudflare/tailscale/ngrok) omniroute env show | get | set # Consultar/definir variables de entorno (temporales) omniroute test # Prueba rápida de conectividad del proveedor omniroute update # Buscar actualizaciones omniroute completion # Generar el autocompletado del shell ``` ### Opciones comunes | Opción | Descripción | | ------------------- | ---------------------------------------------------------- | | `--no-open` | No abrir automáticamente el navegador al iniciar | | `--port ` | Sobrescribir el puerto de la API (predeterminado: 20128) | | `--mcp` | Ejecutar como servidor MCP mediante stdio (para IDE) | | `--non-interactive` | Modo CI (sin preguntas; lee del entorno/opciones) | | `--json` | Salida JSON legible por máquinas (doctor, providers, etc.) | | `--help`, `-h` | Mostrar ayuda específica del comando | | `--version`, `-v` | Mostrar la versión instalada | --- ## Endpoints de API disponibles | Endpoint | Descripción | Uso | | -------------------------- | ------------------------------------- | ---------------------------------------- | | `/v1/chat/completions` | Chat estándar (todos los proveedores) | Todas las herramientas modernas | | `/v1/responses` | API Responses (formato de OpenAI) | Codex, flujos de trabajo agénticos | | `/v1/completions` | Completado de texto heredado | Herramientas antiguas que usan `prompt:` | | `/v1/embeddings` | Embeddings de texto | RAG, búsqueda | | `/v1/images/generations` | Generación de imágenes | GPT-Image, Flux, etc. | | `/v1/audio/speech` | Texto a voz | ElevenLabs, TTS de OpenAI | | `/v1/audio/transcriptions` | Voz a texto | Deepgram, AssemblyAI | Ejemplos listos para pegar con una URL de OmniRoute que incluye un token: ```txt Ejemplo de token: sk-a3ab3c080beaee3a-69f4a4-070d71af Base estándar de OpenAI: http://localhost:20128/v1 Modelos de VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models Chat de VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions Responses de VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Etiquetas de Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Chat de Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## Solución de problemas | Error | Causa | Solución | | --------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- | | `Connection refused` | OmniRoute no está ejecutándose | `omniroute serve` | | `401 Unauthorized` | Clave de API incorrecta | Comprobar en `/dashboard/api-manager` | | `No combo configured` | No hay una combinación de enrutamiento activa | Configurar en `/dashboard/combos` | | La CLI muestra "no instalado" | El binario no está en PATH | Comprobar `which ` | | El panel muestra "no detectado" después de la instalación | La caché está desactualizada | Hacer clic en "⟳ Actualizar detección" en el panel | | Enlace antiguo `/dashboard/cli-tools` | Marcador anterior a v3.8.6 | Redirigido automáticamente a `/dashboard/cli-code` (308) | | Enlace antiguo `/dashboard/agents` | Marcador anterior a v3.8.6 | Redirigido automáticamente a `/dashboard/acp-agents` (308) | ## Gestionar la política de claves de inferencia con la CLI de OmniRoute Utilice un contexto de administración autenticado (consulte [Modo remoto](../guides/REMOTE-MODE.md)) para inspeccionar o actualizar una clave de inferencia existente mediante su ID: ```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` es un alias de `--model-access-mode all`. La actualización borra la lista de modelos permitidos. Conserva los ámbitos, las reglas de conexión, los modelos bloqueados, los límites de frecuencia y los límites de coste, por lo que esos otros controles aún pueden denegar una solicitud. Un valor explícito de `--allowed-models ""` también selecciona `all`; combínelo con `--model-access-mode restricted` para mantener una clave restringida sin modelos permitidos. Una lista no vacía separada por comas selecciona `restricted`, salvo que se especifique explícitamente lo contrario. La combinación contradictoria de `all` con una lista de modelos permitidos no vacía se rechaza antes de enviar una solicitud. `--rate-limit 30` establece las solicitudes por minuto y conserva las reglas para otras ventanas de tiempo. `--max-cost 5` habilita el límite diario en USD sin modificar el límite semanal; `--max-cost 0` elimina el límite diario y conserva la configuración existente del límite de uso y el límite semanal. Los campos de política omitidos permanecen sin cambios. Los cambios de frecuencia primero leen la política actual; evite editar simultáneamente la matriz de límites de frecuencia de la misma clave. Los comandos de política utilizan `GET`/`PATCH /api/keys/{id}` autenticados y respetan el contexto activo y la opción global `--api-key`. La salida JSON contiene únicamente los campos de la política, sin la clave almacenada ni su representación enmascarada. Una credencial exclusiva para inferencia no puede autorizar cambios administrativos. Un error 401/403 requiere comprobar la credencial y el contexto de administración; no demuestra que exista un fallo en el token local de la CLI ni en el salt. Consulte [Token de la CLI](../security/CLI_TOKEN.md) para conocer el contrato independiente de autenticación local.