Configuración multimodelo

Una guía de los patrones habituales para usar varios proveedores de modelos: asignación por agente, enrutamiento por sugerencias, escalonado de costes, prioridad local con respaldo alojado, conmutación por error a un proveedor sin transmisión, gestión de límites de velocidad y recuperación de la transmisión.

El material de referencia para el sistema del proveedor se encuentra en:

• Model Providers → Overview: qué son los proveedores, estructura de configuración
• Proveedores de modelos → Enrutamiento: despacho de agentes, rutas de sugerencias y alternativa de proveedores
• Model Providers → Catálogo: la estructura de configuración de cada proveedor

Cuándo usar una configuración multimodelo

La configuración de múltiples modelos es útil para:

1. Niveles de costo: el modelo económico gestiona los canales de alto volumen; el modelo de razonamiento gestiona las solicitudes complejas
2. Enrutamiento por capacidades: modelo con capacidad de visión para canales con imágenes, modelo de razonamiento para flujos de trabajo de investigación
3. Desarrollo local primero: Ollama local para desarrollo, endpoint alojado para producción
4. Aislamiento por equipo: diferentes equipos usan diferentes agents con diferentes model_providers y credenciales
5. Gestión de límites de frecuencia sin streaming: cambiar a otro perfil de proveedor configurado después de un 429 reintentable

Idea central: despacho por agente

Cada entrada [agents.<alias>] parte de una única [providers.models.<type>.<alias>]. Ese perfil de proveedor puede declarar modelos alternativos mediante fallback_models y otros perfiles de proveedor mediante fallback. Consulta Enrutamiento para ver el patrón completo.

Para ejecutar varios modelos, ejecute varios agentes, cada uno vinculado a un proveedor de modelo. Cada canal se vincula a un agente a la vez. Para mover un canal a un agente diferente, edite la lista channels en el agente que debe tomarlo; Config::validate() se asegura de que las referencias se resuelvan al inicio.

Fiabilidad entre proveedores

Para las llamadas que no usan streaming, ZeroClaw puede recorrer un grafo ordenado de alternativas entre perfiles de proveedores. Cada perfil de alternativa conserva su propio punto de conexión, credenciales, modelo, encabezados, anulaciones de capacidades y declaraciones de alternativas anidadas. El tiempo de ejecución reintenta la operación o avanza según la clasificación del error y el estado de enfriamiento del perfil.

OpenRouter sigue siendo un proveedor de primera clase y puede realizar la selección de proveedores detrás de un único endpoint. Es una capa de enrutamiento externa opcional, no un requisito para el mecanismo de respaldo propio de ZeroClaw.

Reintento y alternativa sin streaming

Para errores transitorios, como un fallo de red, 503 o un tiempo de espera agotado, una llamada sin streaming vuelve a intentarlo mediante una espera exponencial acotada, configurable globalmente en reliability (valores predeterminados: 2 reintentos y 500 ms de espera inicial). Una vez agotada una entrada, el contenedor fiable avanza por los fallback_models del perfil y por los perfiles de reserva.

Límite de recuperación de streaming

Una llamada de streaming selecciona la primera entrada elegible, que no esté en periodo de enfriamiento y que admita las capacidades de streaming necesarias. No pasa a otra entrada después de que comienza ese streaming. Si el streaming falla antes de que la salida visible llegue a un consumidor inmutable, el tiempo de ejecución reintenta la llamada completa mediante la ruta sin streaming, que puede recorrer el grafo de respaldo. Una vez que existe salida visible, el tiempo de ejecución conserva la respuesta parcial y no vuelve a enviar la solicitud ni cambia de proveedor. Consulta Ciclo de vida del enrutamiento de proveedores para ver el contrato completo.

Limitación de la rotación de claves de API

No dependas de reliability.api_keys para la conmutación por error de credenciales. Ante un límite de frecuencia que permite reintentos, el envoltorio fiable selecciona y registra una clave alternativa, pero el trait ModelProvider no puede aplicarla al proveedor ya construido. El reintento sigue usando la credencial original. El issue n.º 9190 registra esta limitación.

Utiliza perfiles de proveedor independientes con sus propias credenciales, o un servicio de enrutamiento externo, cuando se requiera la conmutación por error a nivel de credenciales.

Desarrollo local con alternativa alojada

Ejecuta un agente con Ollama local y un agente con proveedor alojado en paralelo; enruta cada canal al que quieras que utilice.

El agente dev se ejecuta desde la CLI (no requiere vinculación de canal, zeroclaw agent -a dev es suficiente). Cuando Ollama está caído, el agente dev falla rápidamente y muestra el error. Los canales de producción no se ven afectados.

Perfil local-pequeño sin texto alternativo

Los modelos locales pequeños suelen necesitar un perfil de ejecución, no un modo específico del proveedor. Mantén el proveedor Ollama centrado en los detalles de conexión y luego usa [runtime_profiles.<alias>] para ajustar el comportamiento del ciclo de prompt/herramientas. ZeroClaw expone un ajuste preestablecido de ejecución integrado local_small para rutas de código que instalan ajustes preestablecidos de ejecución directamente. Si editas la configuración a mano, usa este bloque equivalente:

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

[agents.local]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.local_small]
agentic                 = true
compact_context          = true
strict_tool_parsing      = true
max_tool_iterations      = 4
max_actions_per_hour     = 10
max_cost_per_day_cents   = 100
shell_timeout_secs       = 30
max_delegation_depth     = 1
delegation_timeout_secs  = 60
agentic_timeout_secs     = 120
max_history_messages     = 20
max_context_tokens       = 8000
parallel_tools           = false
max_system_prompt_chars  = 4000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

Este perfil compone primitivas existentes:

• compact_context mantiene el contexto de inicio reducido.
• strict_tool_parsing trata el texto alternativo con apariencia de XML/JSON como texto del asistente, a menos que el proveedor devuelva llamadas a herramientas nativas.
• max_tool_iterations, max_context_tokens, max_system_prompt_chars y max_tool_result_chars limitan los bucles descontrolados y el contexto excesivo de prompt/herramienta.
• max_actions_per_hour, max_cost_per_day_cents, y los campos de tiempo de espera/delegación mantienen las ejecuciones locales con la misma forma de presupuesto que el preset integrado.
• parallel_tools = false y keep_tool_context_turns = 1 mantienen las ejecuciones locales secuenciales y limitan el contexto de herramientas retenido.

Con Ollama, este es un perfil sin texto de respaldo: las herramientas autorizadas permanecen configuradas en risk_profile, pero el marcado de herramientas en forma de texto del modelo no se ejecuta. Úsalo para agentes locales orientados al chat, o para proveedores que devuelven llamadas a herramientas nativas/estructuradas. Si un modelo local debe usar la sintaxis de herramientas de texto de respaldo de ZeroClaw, establece strict_tool_parsing = false y mantén los demás límites de modelos pequeños.

Niveles de costo: modelo pesado cuando sea necesario, modelo rápido en caso contrario

Ejecuta dos agentes y enruta los canales al nivel apropiado. La herramienta delegate permite que un agente transfiera la conversación a otro a mitad de la misma. La delegación está restringida: el perfil de riesgo del llamador debe establecer delegation_policy mode = "allow", y el destino debe ser accesible desde el llamador (un par del mismo perfil, o una entrada explícita en la lista delegates del llamador). Los agentes de primera línea y de carga pesada que se muestran a continuación se ejecutan en el mismo perfil de riesgo trusted, por lo que se alcanzan mutuamente como pares del mismo perfil; difieren en el modelo y el perfil de tiempo de ejecución (presupuesto de iteración), no en la superficie de confianza.

El agente de primera línea gestiona todos los mensajes entrantes con Haiku. Cuando necesita un razonamiento más profundo, llama a la herramienta delegate con agent = "heavy"; dado que ambos agentes comparten el perfil de riesgo trusted y ese perfil permite la delegación, el agente más pesado retoma la subtarea con Opus.

Gestión de errores sin streaming

Para las llamadas que no son de streaming, los fallos reintentables incluyen:

1. Timeout: el proveedor no respondió dentro del tiempo de espera configurado
2. Error de conexión: fallo de red o de DNS
3. Límite de solicitudes (429): coloca el perfil del proveedor en un periodo de enfriamiento temporal en memoria y avanza cuando existe otra entrada
4. Servicio no disponible (503): problema temporal del servicio

Los reintentos NO se activan por:

1. Solicitud no válida (400): entrada con formato incorrecto; reintentar no servirá de nada
2. Fallo de autenticación permanente: formato de clave de API no válido
3. Errores de salida del modelo: el modelo respondió pero devolvió una carga útil de error

Cuando todas las entradas materializadas se han agotado o están en periodo de enfriamiento, el fallo se propaga al canal invocador con los fallos de intento recopilados.

Depuración

Los registros persistentes ("rolling" es el valor predeterminado) capturan el comportamiento de reintento, enfriamiento y alternativa. Luego consulta las trazas:

zeroclaw doctor traces --contains retry
zeroclaw doctor traces --contains "429"
zeroclaw doctor traces --contains "model_provider"

Buenas prácticas

1. Un agente por intención de enrutamiento. Si dos canales necesitan un comportamiento de modelo diferente, nombra dos agentes.
2. Asigna explícitamente la propiedad a los perfiles de respaldo. Mantén cada punto de conexión, credencial, modelo y sobrescritura de capacidades en el perfil que lo proporciona.
3. Trata OpenRouter como una capa de enrutamiento opcional. Úsalo cuando sea útil que el servidor seleccione el proveedor; usa los perfiles de respaldo de ZeroClaw cuando el entorno de ejecución deba controlar el orden.
4. No dependas de reliability.api_keys. Usa perfiles construidos por separado hasta que se corrija el problema n.º 9190.
5. Prueba de humo de cada agente de forma aislada. zeroclaw agent -a <alias> ejecuta un agente sin que la infraestructura de canales se interponga.
6. Documentar la intención del agente. Añade líneas # comment que expliquen qué canales atiende cada agente y por qué.
7. Inyecta secretos mediante env, no en línea. ZEROCLAW_providers__models__<type>__<alias>__api_key=... establece api_key al inicio; consulta Variables de entorno.
8. Separa los agentes de dev y prod. Cada entorno obtiene su propia entrada [agents.<alias>] vinculada a sus propios canales.

Resolución de credenciales

Cada entrada de proveedor resuelve las credenciales en este orden:

1. api_key en línea en la entrada del proveedor.
2. Almacén de secretos en ~/.zeroclaw/secrets.
3. Anulación genérica por variable de entorno: ZEROCLAW_providers__models__<type>__<alias>__api_key=... al inicio. Si tu shell ya exporta ANTHROPIC_API_KEY, OPENROUTER_API_KEY u otro nombre predeterminado de proveedor similar, puentéala a esta variable espejo del esquema antes del inicio, a menos que la familia de proveedores documente explícitamente un puente de entorno nativo en tiempo de ejecución. Consulta Variables de entorno para ver la gramática completa y ejemplos de puentes.

Las credenciales no se comparten entre los perfiles de proveedor; configúralas para cada perfil. model_routes[].api_key, definido a nivel de ruta, es una sobrescritura de mayor precedencia cuando se construye su destino enrutado. Los destinos de las rutas se deduplican por model_provider, por lo que la primera credencial de ruta coincidente puede construir el proveedor compartido por varias sugerencias. Prefiere las credenciales propias del perfil cuando las rutas compartan un destino.

Documentación relacionada

• Proveedores de modelos → Descripción general
• Proveedores de modelos → Enrutamiento
• Variables de entorno