Claude Code CLI — Configuration with OmniRoute (Español)

Inicio rápido

# Inicia Claude Code con un OmniRoute local (detecta automáticamente el contexto activo)
omniroute launch

# Con un OmniRoute remoto (después de `omniroute connect <host>`, esto es automático)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Genera perfiles por modelo y, a continuación, inicia uno
omniroute setup-claude            # escribe ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code usando glm/glm-5.2 mediante OmniRoute

---

Cómo se conecta Claude Code a un gateway

Claude Code se comunica con la API de mensajes de Anthropic y se dirige a un endpoint personalizado mediante variables de entorno (no tiene una opción --base-url):

Variable	Propósito
ANTHROPIC_BASE_URL	URL raíz del gateway (Claude Code añade /v1/messages). Sin el sufijo /v1.
ANTHROPIC_AUTH_TOKEN	Se envía como Authorization: Bearer …; usa tu token de acceso o clave de API de OmniRoute
ANTHROPIC_API_KEY	Alternativa: se envía como x-api-key. Si se establecen ambas, ANTHROPIC_AUTH_TOKEN tiene prioridad
ANTHROPIC_MODEL	Fuerza un modelo específico (sobrescribe el valor predeterminado del selector /model)
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → el selector nativo /model muestra los modelos claude*/anthropic* de /v1/models
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Limita los tokens de salida por respuesta (p. ej., 65536)
CLAUDE_CODE_AUTO_COMPACT_WINDOW	Umbral de tokens para la compactación automática

Las variables de entorno se leen una sola vez al iniciar; reinicia Claude Code después de cambiarlas.

omniroute launch configura todo esto por ti: resuelve la URL base y el token a partir del contexto activo (por lo que ejecutar omniroute connect <vps> y después omniroute launch funciona directamente), comprueba el estado del servidor y ejecuta claude.

---

Alias de descubrimiento: muestra modelos que no son de Claude en el selector /model

El descubrimiento de modelos del gateway de Claude Code solo muestra identificadores que comienzan por claude o anthropic, por lo que, con CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, el selector nativo /model normalmente muestra solo los modelos Claude/Anthropic de OmniRoute: un modelo como kimi/kimi-k2.6 o glm/glm-5.2 nunca aparece, aunque su enrutamiento funcione correctamente.

OmniRoute puede reflejar cualquier modelo habilitado (y combinación) bajo un identificador claude/… para que pase ese filtro y aparezca en el selector:

kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado

Cuando seleccionas uno de estos en Claude Code, OmniRoute elimina el envoltorio claude/ para recuperar el identificador real antes del enrutamiento; un identificador auténtico claude/<real-claude-model> (el proveedor OAuth real de Claude) siempre se deja intacto.

Esta opción está desactivada de forma predeterminada y se controla mediante una jerarquía de tres niveles (prevalece el más específico), por lo que una instalación estándar de OmniRoute nunca duplica su catálogo para clientes que no utilizan Claude Code:

Nivel	Ubicación
Modelo	Página de detalles del proveedor → opción por modelo «Mostrar en Claude Code»
Proveedor	Página de detalles del proveedor → opción a nivel de proveedor (abarca todos sus modelos)
Global	Configuración → Indicadores de funciones → EXPOSE_CC_DISCOVERY_ALIASES (desactivado de forma predeterminada)

La variable de entorno EXPOSE_CC_DISCOVERY_ALIASES activa forzosamente el nivel global y tiene prioridad sobre la configuración del panel (la pantalla de Indicadores de funciones muestra una nota de «activo mediante variable de entorno» cuando esto ocurre). Las opciones por proveedor y por modelo permiten precisar la configuración a partir de ahí; por ejemplo, si el nivel global está desactivado y el proveedor Kimi está activado, solo se muestran los modelos de Kimi.

⚠️ Discrepancia de ventana en modelos que no son de Claude. Claude Code presupone una ventana de contexto de 200K para cualquier identificador que no reconozca (no puede leer la ventana real desde /v1/models). Para un modelo con una ventana mayor (p. ej., los 256K de Kimi K2), configura CLAUDE_CODE_AUTO_COMPACT_WINDOW con un valor inferior a la ventana real del modelo para evitar que la compactación automática se active antes de tiempo. Los perfiles generados anteriormente ya lo hacen para cada modelo.

---

Bloque de incorporación en el panel

La tarjeta de la herramienta Claude (Panel → Código CLI) muestra el fragmento exacto de settings.json para esta instancia, junto al botón de información del alias de descubrimiento, con un botón para copiar:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

La URL base es la resuelta por la tarjeta (incluida cualquier sobrescritura personalizada que hayas introducido), ya normalizada: sin el sufijo /v1 ni una barra final. La clave nunca se muestra: el bloque incluye un marcador de posición, por lo que ni una captura de pantalla ni un fragmento pegado pueden filtrarla. Sustitúyelo por tu clave.

Añade CLAUDE_CODE_AUTO_COMPACT_WINDOW bajo el mismo bloque env para cualquier modelo cuya ventana de contexto real no sea de 200K; Claude Code presupone 200K para cada id que no reconoce, por lo que, de lo contrario, la compactación automática se activa en el momento equivocado (consulta la advertencia de la sección anterior). El generador de fragmentos también acepta ese valor, por lo que un invocador que conozca la ventana del modelo de destino puede incluirlo directamente.

Fuente: src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet (generador puro, con pruebas unitarias), mostrado por ClaudeGatewayOnboardingBlock.

---

Perfiles (CLAUDE_CONFIG_DIR)

Claude Code no tiene archivos de perfil nativos (a diferencia de ~/.codex/<name>.config.toml de Codex). El mecanismo habitual es CLAUDE_CONFIG_DIR: un directorio de configuración independiente por perfil, cada uno con sus propios settings.json, credenciales, historial y caché.

omniroute setup-claude obtiene el catálogo activo de /v1/models y escribe un perfil por modelo en ~/.claude/profiles/<name>/settings.json, reutilizando los mismos nombres que setup-codex (glm52, kimi-k27, deepseek-pro, …):

~/.claude/profiles/glm52/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}

El token de autenticación nunca se escribe en el perfil. Inícialo con omniroute launch --profile <name> (inyecta ANTHROPIC_AUTH_TOKEN desde el contexto activo), o exporta tú mismo ANTHROPIC_AUTH_TOKEN y ejecuta CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude.

Sincronización automática tras el descubrimiento de modelos (opcional). OmniRoute puede regenerar automáticamente estos mismos archivos ~/.claude/profiles/<name>/settings.json cada vez que una sincronización de modelos del proveedor cambie el catálogo activo, para que los modelos nuevos o renombrados obtengan perfiles sin tener que volver a ejecutar el comando. Está desactivada de forma predeterminada: actívala desde el panel de Código CLI («Sincronización automática de perfiles CLI» → Claude Code), o establece OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true (también respeta CLI_ALLOW_CONFIG_WRITES, activado de forma predeterminada). Cuando está habilitada, solo escribe archivos de perfil; nunca cambia tu configuración activa o predeterminada de Claude, la autenticación ni ~/.claude/settings.json.

Generación y uso de perfiles

# OmniRoute local
omniroute setup-claude

# VPS remoto (incorpora la URL del VPS en cada perfil)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Solo algunos proveedores
omniroute setup-claude --only glm,kimi

# Vista previa sin escribir
omniroute setup-claude --dry-run

# Iniciar un perfil
omniroute launch --profile kimi-k27

---

Niveles de modelo (opcional)

Claude Code enruta las solicitudes a distintos niveles de capacidad. Asigna cada uno a un modelo de OmniRoute mediante variables de entorno / ajustes si quieres usar proveedores diferentes para cada nivel:

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

De lo contrario, se utiliza un único ANTHROPIC_MODEL (el que establecen los perfiles) para todo.

---

Modo remoto

Una vez que hayas ejecutado omniroute connect <host> (consulta Modo remoto), omniroute launch y omniroute setup-claude apuntan automáticamente a ese servidor remoto y usan su token de acceso con ámbito — no se necesitan indicadores adicionales. Sobrescribe esta configuración para una invocación concreta con --remote / --api-key.

---

Solución de problemas

Claude Code ignora la puerta de enlace — confirma que ANTHROPIC_BASE_URL no incluya /v1 y reinicia claude (las variables de entorno se leen una sola vez al iniciarse). omniroute launch se encarga de esto por ti.

El selector /model está vacío / faltan los modelos de la puerta de enlace — requiere Claude Code v2.1.219+ y CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Solo aparecen en el selector los ID de modelo claude* / anthropic*; fuerza cualquier otro modelo con ANTHROPIC_MODEL=<id> (esto es lo que hacen los perfiles).

400 Ambiguous model 'claude-…' — Claude Code siempre envía ID de modelo sin prefijo (p. ej., claude-opus-4-8), por lo que, cuando están conectados tanto el proveedor Claude Code (cc/…) como Claude (claude/…), el ID sin prefijo coincide con dos rutas y OmniRoute se niega a decidir por su cuenta. Puedes solucionarlo de cualquiera de estas formas: fija un ID con prefijo mediante ANTHROPIC_MODEL=cc/claude-opus-4-8, o activa Preferir Claude Code para modelos Claude sin prefijo — el conmutador de la página del proveedor Claude, o OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true (desactivado de forma predeterminada; consulta Entorno) —, lo que enruta los ID claude-* sin prefijo a Claude Code. Los prefijos explícitos de proveedor siempre tienen prioridad.

Errores de autenticación — el perfil no contiene ningún token. Usa omniroute launch --profile (lo inyecta) o exporta ANTHROPIC_AUTH_TOKEN.

Los perfiles no están aislados — cada perfil es un CLAUDE_CONFIG_DIR distinto; verifica que echo $CLAUDE_CONFIG_DIR dentro de la sesión apunte a ~/.claude/profiles/<name>.

---

Código fuente de OmniRoute (a58000c7685f)