Un proveedor conecta a Comal con un transporte y un modelo. Un perfil reúne esa conexión y sus capacidades; el nombre de la sesión identifica la instancia ante ti y otros agentes.

## Empezar con el residente local

Por defecto Comal busca un servidor compatible con OpenAI en `http://llama.local:11438/` y descubre el modelo en `/v1/models` si no lo indicas.

```sh
node bin/comal.mjs --name residente
node bin/comal.mjs --base-url http://127.0.0.1:8080/v1 --model ID
```

Acepta raíces, bases terminadas en `/v1` y la URL convencional de Chat Completions. El servidor debe estar funcionando; Comal no inicia ni descarga el modelo.

## Elegir un perfil

```sh
node bin/comal.mjs --providers-config examples/comal-providers.json --profile residente --name residente
```

El ejemplo incluye residente local, Codex, visión con MiniMax vía Ollama y un perfil Gemini para completar. No contiene claves. Un perfil no es una instancia nueva de otro agente: consulta [sesiones](sesiones) si necesitas dos procesos.

## Cambiar durante la sesión

```text
/models
/model ID
/effort
/effort low
/capabilities
/capabilities refresh
```

`/model ID` conserva historial y UUID; restablece esfuerzo a `auto`. `/provider PERFIL` cambia proveedor y modelo. Si el modelo está trabajando, los cambios se encolan y se aplican entre turnos. La petición activa mantiene su selección. Un cambio inválido no reemplaza el proveedor anterior.

## Qué significa effort

`effort` es un control de razonamiento del proveedor, **no** el presupuesto de salida ni un permiso. `auto` omite el parámetro. Comal sólo ofrece niveles respaldados por metadatos y por un adaptador que pueda enviarlos.

En el residente inspeccionado, el servidor anunció `auto/off/low/medium/xhigh`; eso no significa que todos los modelos compartan esos valores. `high` no se convierte silenciosamente en `xhigh`. Consulta `/effort` antes de elegir.

## Capacidades y límites conocidos

| Transporte | Funciones implementadas | Qué debe anunciar o habilitar el modelo |
| --- | --- | --- |
| OpenAI compatible | Texto, herramientas, imágenes | Visión y controles de esfuerzo; video y búsqueda nativa no tienen adaptador aquí |
| Anthropic | Texto, herramientas, imágenes | Capacidades y esfuerzo anunciado |
| Gemini | Texto, herramientas, imágenes, video y búsqueda nativa | Capacidades habilitadas; pensamiento no implica niveles de esfuerzo conocidos |
| Codex con suscripción | Responses streaming, herramientas e imágenes | Catálogo de la cuenta y niveles anunciados |

Se distingue dato detectado, configuración y desconocido. Nunca se deduce visión sólo porque un ID contenga «vision». La ventana anunciada puede reducir el presupuesto configurado; no lo amplía sin que lo pidas.

`--thinking` conserva compatibilidad con extensiones de llama.cpp. Para controles nuevos prefiere `--effort` o `/effort`; otros endpoints pueden rechazar extensiones de thinking.

## Ventana de contexto adaptativa

Comal consulta metadatos del proveedor y adapta el presupuesto al iniciar, cambiar modelo/proveedor o refrescar capacidades. No deduce la capacidad por el nombre del modelo. En la cabecera aparece junto a Effort, Thinking y Visión:

```text
E:auto · Ctx:500k · think · visión
```

`Ctx` es la ventana efectiva. `k/M` redondean la cifra; `/context` muestra los tokens exactos, capacidad anunciada, límite explícito, fuente y reserva de salida. `Ctx:32k~` señala un límite elegido; `Ctx:45k?` señala el fallback porque la capacidad efectiva no se conoce. El uso porcentual inferior sigue indicando la ocupación de la llamada, y el total de tokens de la sesión es consumo acumulado.

Sin límite humano se usa lo anunciado, hasta el máximo de 2,000,000 admitido por Comal. Con `--context-window N` o `COMAL_CONTEXT_WINDOW=N` se usa el menor entre ese límite y el anunciado. El flag prevalece sobre la variable. Esa configuración corresponde al proceso actual; al reabrirlo conserva tus flags/variables si deseas el mismo límite explícito. Una ventana mayor no amplía la del servidor ni convierte todo su espacio en entrada: se descuentan salida, herramientas y margen.

Para llama.cpp se consulta el n_ctx del servidor cuando está disponible. En Ollama, el máximo de arquitectura se conserva como modelContextWindow; no se convierte en contexto activo sin un num_ctx configurado. Para proveedores que no publican límites, configura el presupuesto explícitamente. Los metadatos anuncian capacidades; no constituyen una prueba de llenado completo.