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

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

---

Apunta la CLI de **Claude Code** (`claude`) a OmniRoute —local o en un VPS remoto— con perfiles por modelo, replicando la configuración de Codex.

---

## Inicio rápido

```bash
# 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 y con un botón para copiar:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<tu OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<tu clave de API de OmniRoute>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}
```

La URL base es la resuelta por la tarjeta (incluida cualquier anulación personalizada que hayas introducido) y ya está
normalizada: sin el sufijo `/v1` ni una barra diagonal 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` en el mismo bloque `env` para cualquier modelo cuya ventana
de contexto real no sea de 200K. Claude Code presupone 200K para todos los identificadores 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, de modo 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`.

### Fijar una cuenta (opcional)

Para enviar todas las solicitudes de Claude Code a través de una cuenta específica del proveedor, añade el
encabezado `x-omniroute-connection` mediante `ANTHROPIC_CUSTOM_HEADERS` en el mismo bloque `env`:

```jsonc
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>"
```

Copia el identificador del chip `xxxxxxxx…` de la fila de conexión en la página del proveedor. La fijación solo
se aplica a identificadores de un único modelo (`provider/model`), no a combinaciones. Consulta
[Fijación de cuenta por solicitud](../reference/API_REFERENCE.md#account-pinning-per-request) para conocer el
comportamiento alternativo exacto.

---

## Perfiles (`CLAUDE_CONFIG_DIR`)

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

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

```jsonc
// ~/.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.** Inicia con
> `omniroute launch --profile <name>` (inyecta `ANTHROPIC_AUTH_TOKEN` desde el
> contexto activo), o exporta `ANTHROPIC_AUTH_TOKEN` tú mismo y ejecuta
> `CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude`.

**Sincronización automática después del descubrimiento de modelos (opcional).** OmniRoute puede regenerar automáticamente estos mismos
archivos `~/.claude/profiles/<name>/settings.json` cada vez que la sincronización de modelos de un proveedor
cambie el catálogo activo, de modo 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 CLI Code** ("Sincronización automática de perfiles de 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 la configuración activa o predeterminada de Claude, la autenticación ni `~/.claude/settings.json`.

### Generación y uso de perfiles

```bash
# OmniRoute local
omniroute setup-claude

# VPS remoto (incluye 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

# Escribir también perfiles para proveedores de CLI locales (zcode, auggie, devin-cli-agentic,
# codex-app-server) no detectados en este host (omitidos de forma predeterminada para un destino local)
omniroute setup-claude --include-local

# 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:

```bash
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](./REMOTE-MODE.md)), `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](../reference/ENVIRONMENT.md)) —, 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>`.