Administrar canales en AI Gateway

Un «canal (Channel)» es la configuración de un punto de acceso de proveedor en AI Gateway: guarda la dirección de un proveedor, la API Key real, los modelos disponibles, así como la información de precios y cuotas. AI Gateway utiliza estos canales para enrutar las solicitudes que envían las aplicaciones al proveedor correspondiente. Este artículo explica cómo agregar, configurar, probar y administrar canales.

Prerrequisitos

• ServBay instalado y en ejecución, y sesión iniciada en la cuenta de ServBay (se requiere iniciar sesión antes de agregar canales).
• Tener lista la API Key real del proveedor de destino (en proveedores locales como Ollama / LM Studio puede dejarse vacía).
• Si aún no conoces la arquitectura general de AI Gateway, te recomendamos leer primero Introducción a AI Gateway.

Agregar un canal

Ve a AI Gateway → Canales (Channels) y haz clic en Agregar (Add) para abrir el asistente. El asistente consta de tres pasos.

Paso 1: Seleccionar el proveedor

Los proveedores se muestran agrupados por categoría; haz clic en una tarjeta para seleccionarlo:

• Principales (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• China: DeepSeek, Qwen (Tongyi Qianwen), Zhipu GLM, Kimi, Doubao · Volcano, ERNIE Bot, Hunyuan, MiniMax, 01.AI, StepFun.
• Locales (Local): Ollama, LM Studio.
• Personalizados (Custom): OpenAI Compatible, Custom.

Después de seleccionar un proveedor, AI Gateway rellenará automáticamente la Base URL predeterminada de ese proveedor.

Cambio de doble región

Proveedores chinos como Qwen, Zhipu GLM, Kimi, Doubao · Volcano, Hunyuan, MiniMax y StepFun ofrecen simultáneamente dos conjuntos de endpoints: nacional y global. Al seleccionar este tipo de proveedor, el asistente mostrará un selector de «Región» (🇨🇳 Nacional / 🌐 Global); al cambiarlo, la Base URL se actualizará automáticamente a la dirección de la región correspondiente.

Paso 2: Completar la configuración

• Nombre del canal (obligatorio) — sirve para identificar el canal en la lista; puedes personalizarlo.
• Base URL (obligatorio) — dirección de la API del proveedor. En la mayoría de proveedores ya se rellena automáticamente; Azure OpenAI y Custom requieren que la introduzcas manualmente.
• API Key (opcional) — clave real del proveedor. Si se deja vacía, solo se puede probar si el endpoint es accesible, pero no se puede verificar la validez de la clave; los proveedores locales (Ollama / LM Studio) normalmente no requieren rellenarla.
• Modelos — hay dos formas, elige una:
  • Descubrimiento automático: al hacer clic en descubrir, AI Gateway llama a la interfaz de lista de modelos del proveedor para obtener los modelos disponibles, y tú los seleccionas varios mediante etiquetas (chips).
  • Relleno manual: introduce directamente el nombre del modelo. Los canales de Azure deben rellenarse con el nombre de implementación (Deployment name) en lugar del nombre del modelo.
• Prioridad / Peso — cuando varios canales pueden dar servicio al mismo modelo, AI Gateway decide según esto el enrutamiento y la distribución de carga.

Atención con Azure OpenAI

En el campo «Modelos» de los canales de Azure debe introducirse el nombre de implementación (Deployment name) que creaste en el portal de Azure, no el nombre del modelo subyacente. La Base URL también debe ser el endpoint de tu recurso de Azure.

Paso 3: Confirmar y enviar

Revisa el resumen de configuración y envíalo. Una vez enviado correctamente, el nuevo canal aparecerá en la lista de canales y mostrará su estado de salud en tiempo real.

Detección de capacidades y estrategia de enrutamiento

Después de agregar un canal, AI Gateway realiza una detección de capacidades (capability probing) sobre ese canal; este es el mecanismo de enrutamiento inteligente más importante de AI Gateway. El resultado de la detección determina si herramientas como Claude Code pueden usarlo directamente, si es necesario crear asignaciones de modelos y cómo elegir el modelo de destino.

Dos indicadores clave de la detección

AI Gateway detecta dos hechos centrales por cada canal (ambos con tres estados: true / false / no determinado):

Elemento de detección	Significado	true	false	No determinado
Reconoce nombres de modelos Claude (accepts_claude_names)	Si el canal reconoce de forma nativa nombres de modelo como claude-opus-* / claude-sonnet-* / claude-haiku-*	Conexión directa, sin necesidad de asignación	No los reconoce; es obligatorio crear una asignación que traduzca los nombres claude-* al nombre real del modelo en el proveedor	La detección no se ejecutó o falló; no se puede concluir
Distingue por nivel (tier_aware)	Si el proveedor devuelve por sí mismo modelos diferentes según el nivel opus / sonnet / haiku	El proveedor ya distingue por nivel; basta con delegarle el manejo	No distingue por nivel (devuelve el mismo modelo para todos los niveles); se requiere que AI Gateway cree una asignación	No se puede detectar o no se ha detectado

Por qué detectar en lugar de adivinar

El comportamiento varía mucho entre proveedores. OpenAI no reconoce de forma nativa los nombres de modelo claude-*; algunos proveedores intermediarios los reconocen mediante reenvío; y proveedores de planes de codificación (como la suscripción Claude Pro/Max) pueden reconocer solo nombres de modelos específicos vinculados a la suscripción. AI Gateway no adivina según el tipo de canal, sino que decide la estrategia de enrutamiento después de una detección real.

Determinación de enrutamiento: cinco estados

Cuando realizas la «toma de control con un clic» de Claude Code en AI Gateway → Gestión de integración → Cliente, AI Gateway agrega los resultados de detección de todos los canales candidatos y obtiene una determinación de enrutamiento:

Estado de los canales candidatos	Determinación	Significado
No hay canales candidatos disponibles (sin canales / todos no saludables / sin canales dentro del alcance de la clave virtual)	Sin canales candidatos	Debes agregar o reparar canales primero
El valor de detección de cualquier canal candidato no está determinado	Sin detectar	Primero debe ejecutarse una detección; no se puede crear una asignación sin verificarla
Todos los canales candidatos reconocen nombres de modelo claude	Conexión directa	No se crea asignación; las solicitudes se reenvían tal cual
Todos los canales candidatos no reconocen nombres de modelo claude	Asignación obligatoria	AI Gateway crea asignaciones de tres niveles para traducir claude-* al nombre real del modelo en el proveedor
Entre los candidatos hay tanto canales que los reconocen como canales que no	Mixto	Requiere decisión manual (los que los reconocen van directo; los que no, pasan por asignación)

Asignación de modelos: traducir claude-* al modelo real del proveedor

Cuando la determinación es «asignación obligatoria», AI Gateway crea tres reglas de asignación de modelos para Claude Code, que cubren respectivamente los tres niveles:

Nombre de modelo enviado por Claude Code	Regla de asignación (comodín)	Se asigna a
claude-opus-*	Coincide con todas las solicitudes de nivel opus	Modelo insignia entre los canales candidatos
claude-sonnet-*	Coincide con todas las solicitudes de nivel sonnet	Modelo insignia o modelo estándar entre los canales candidatos
claude-haiku-*	Coincide con todas las solicitudes de nivel haiku	Modelo ligero entre los canales candidatos

Reglas de selección del modelo de destino (con retroceso por prioridad):

1. Preajuste por familia: si entre los modelos candidatos aparece una palabra clave de familia conocida (como glm), se toma directamente el modelo insignia de esa familia (por ejemplo, glm-5.2) como destino del nivel opus/sonnet, y el modelo ligero de esa familia (por ejemplo, glm-4.7-flash) como destino del nivel haiku.
2. Coincidencia por palabras clave: cuando no hay preajuste de familia, opus/sonnet toman el primer modelo de la lista de candidatos; haiku toma el primer modelo de los candidatos que coincida con palabras clave de ligero (flash / mini / lite / air / small / turbo / haiku).
3. Respaldo: si aún no hay coincidencia, los tres niveles toman el primer modelo de la lista de candidatos.

El nivel haiku es el que más caro sale si se configura mal

Las llamadas al nivel haiku de Claude Code son las más numerosas (cada conversación usa llamadas ligeras con este nivel). Si se coloca por error un modelo insignia en el nivel haiku, la factura puede multiplicarse varias veces. La tabla de coincidencia por palabras clave de AI Gateway cubre 7 sufijos ligeros (flash / mini / lite / air / small / turbo / haiku), lo que garantiza que no se coloque un modelo pesado en el nivel haiku.

Mecanismo de escritura de asignaciones

Tras confirmar la toma de control, AI Gateway escribe los registros de asignación mediante la API /admin/model-mappings. Cada registro de asignación incluye:

• Protocolo de origen (source_protocol): anthropic (las solicitudes que envía Claude Code están en formato Anthropic)
• Coincidencia de modelo de origen (source_model_pattern): comodín, como claude-opus-*
• Protocolo de destino (target_protocol): openai (se convierte todo a formato OpenAI antes de enviarlo al proveedor)
• Modelo de destino (target_model): el nombre del modelo concreto seleccionado en la detección

La escritura es idempotente: volver a tomar el control no genera asignaciones duplicadas; antes de escribir, se obtiene la lista de asignaciones existentes para compararla.

Reglas de enrutamiento en tiempo de ejecución: failover y degradación

Además de las asignaciones estáticas escritas durante la fase de toma de control, AI Gateway también admite reglas de enrutamiento en tiempo de ejecución (routing rules), que deciden dinámicamente cuando las solicitudes pasan por AI Gateway:

Campo de la regla	Función
Condición de activación (condition_type)	Cuándo se activa la degradación, por ejemplo, cuando se agota la cuota del canal (quota_exhausted)
Umbral de costo (cost_threshold_usd)	Opcional: se activa cuando el costo acumulado de ese canal supera el umbral
Acción (action_type)	Qué hacer tras la activación, por ejemplo, cambiar a un canal de respaldo especificado (switch_to)
Canal de destino (target_channel_id)	Canal de respaldo al que se degrada
Modelo de destino (target_model)	Opcional: cambiar también el modelo al degradar al canal de respaldo

Combinando varias reglas de enrutamiento, puedes lograr: cuando se agota la cuota de suscripción del canal A, cambiar automáticamente al endpoint de pago por uso del canal B; cuando el costo de 24 horas de un canal supera el límite, degradar a un modelo más barato.

Balanceo de carga y prioridad

Cuando varios canales saludables pueden dar servicio al mismo modelo, AI Gateway elige según la siguiente estrategia:

• Modo por prioridad (predeterminado): solo se toma el canal con la prioridad más alta; entre canales de la misma prioridad, AI Gateway distribuye según pesos internos.
• Modo round robin (round_robin): se distribuyen las solicitudes por turnos entre todos los canales candidatos saludables.

La prioridad se establece en la configuración del canal (cuanto mayor sea el número, mayor será la prioridad); allowed_channels de la clave virtual limita el rango de canales seleccionables.

Prueba de conectividad

En la lista de canales se puede ejecutar una prueba de conectividad sobre un canal individual. La prueba tiene dos dimensiones:

• Accesibilidad del endpoint (reachable) — comprueba si la Base URL puede conectarse (si la red y la dirección son correctas).
• Validez de la clave (authenticated) — llama realmente a la interfaz del proveedor para verificar si la API Key es válida. Solo se verifica si se ha introducido una API Key.

El resultado de la prueba muestra: latencia de ida y vuelta (milisegundos), insignia de estado y mensaje de error.

TIP

En el asistente de agregar, si el endpoint no es accesible, se te impedirá pasar al siguiente paso; si el endpoint es accesible pero la clave no es válida, solo se mostrará una advertencia y podrás continuar (por ejemplo, si piensas añadir la clave más tarde).

Configuración avanzada

Al agregar o editar un canal, puedes expandir la configuración avanzada, que sirve para el cálculo de costos y el control de cuotas:

• Multiplicador de tarifa (Rate Multiplier) — multiplica el precio oficial del proveedor por un factor, para calcular según tu costo real o precio de reventa; valor predeterminado 1.0.
• Estructura de facturación — describe el método de facturación del canal, como pago por uso (pay as you go), suscripción (subscription), paquete (package).
• Saldo — la fuente del saldo puede ser un valor fijo, una factura de OSS o mantenimiento manual; al elegir factura de OSS también se puede especificar el tipo de factura. El saldo y la hora de actualización se muestran solo como lectura en los detalles del canal.
• Fecha de vencimiento de la suscripción — los canales de tipo suscripción / paquete pueden registrar la fecha de vencimiento.
• Límite de cuota — se puede fijar un límite por número de tokens, número de solicitudes o importe, y elegir el período (diario / semanal / mensual / personalizado). Cuando se agota la cuota, el canal se excluye automáticamente de la selección de ruta; es una válvula de seguridad para evitar sobregiros accidentales.

Editar y eliminar canales

• Editar — abre un canal en la lista de canales para modificar el nombre, la Base URL, la API Key, los modelos y la configuración avanzada.
• Eliminar — después de eliminar un canal, las claves virtuales que dependen de él ya no podrán enrutar hacia él; opera con cuidado.

Estado de salud

La lista de canales y la página de resumen muestran en tiempo real el estado de salud de cada canal (normal / degradado / no disponible), lo que te ayuda a detectar rápidamente configuraciones de proveedor no válidas.

Preguntas frecuentes (FAQ)

• P: ¿Al agregar un canal indica que hay que iniciar sesión?
  • R: AI Gateway es una función de valor agregado de ServBay; antes de agregar canales / claves hay que iniciar sesión en la cuenta de ServBay. Sigue las indicaciones de la interfaz para iniciar sesión.
• P: ¿Indica que se alcanzó el límite de canales?
  • R: La cantidad de canales que se pueden crear depende del plan de la cuenta. Si alcanzas el límite, puedes eliminar canales que no uses o mejorar el plan.
• P: ¿El descubrimiento automático de modelos no obtiene la lista?
  • R: Primero confirma que la Base URL sea correcta y que la API Key sea válida (puedes verificarlo con «Validez de la clave» en la prueba de conectividad). Algunos proveedores requieren una clave válida para devolver la lista de modelos; también puedes rellenar manualmente los nombres de los modelos.
• P: ¿Hay que introducir una Key para integrar Ollama / LM Studio locales?
  • R: Normalmente no. Basta con asegurarte de que el servicio local correspondiente esté iniciado y escuchando en el puerto predeterminado (Ollama 11434, LM Studio 1234).

Resumen

Los canales son la base para que AI Gateway enrute solicitudes. Mediante el asistente de tres pasos, puedes integrar casi 20 proveedores rápidamente; con el cambio de doble región, el descubrimiento automático de modelos y la prueba de conectividad en dos dimensiones, puedes asegurar que la configuración sea correcta; y con la configuración avanzada de precios y cuotas, puedes administrar los costos con precisión. Una vez configurados los canales, podrás crear claves virtuales para que las aplicaciones y herramientas las usen.