Enrutamiento

ZeroClaw usa el enrutamiento para dos decisiones diferentes:

1. El enrutamiento de agentes selecciona qué agente es responsable de un canal o una solicitud. Cada agente tiene su propio perfil de proveedor y política de ejecución.
2. El enrutamiento de proveedores y modelos selecciona un perfil de proveedor y un modelo configurados para una llamada y, a continuación, aplica la política de reintentos y conmutación por error de ese perfil.

Un servicio de enrutamiento externo como OpenRouter aún puede encargarse de seleccionar el proveedor dentro de un único perfil de proveedor. Es opcional: ZeroClaw también admite rutas de sugerencias de primera parte, conmutación por error del modelo dentro del mismo perfil y conmutación por error entre perfiles de proveedor.

Despacho por agente

Define cada destino de enrutamiento como su propio agente, luego apunta los canales al agente que debe gestionar su tráfico.

Cada canal se vincula a un agente. Los canales se mueven entre agentes editando channels = [...] en el agente que debe recibirlos; Config::validate() se asegura de que las referencias se resuelvan.

Para enrutamiento ad-hoc de varios pasos dentro de una sola conversación, la herramienta spawn_subagent permite que un agente ejecute un proceso hijo efímero bajo su propia identidad. El hijo hereda el conjunto de permisos del padre (consulta [risk_profiles.<alias>].allowed_tools) y devuelve su respuesta final al bucle de herramientas del padre.

Rutas de modelo basadas en sugerencias

Un mecanismo más acotado: [[model_routes]] permite que un agente anule el model_provider configurado para los prompts marcados con una cadena de pista. Es útil cuando un agente debe recurrir ocasionalmente a un modelo diferente sin tener que lanzar un segundo agente. Cada entrada de ruta incluye un hint (la cadena que un prompt debe declarar para activarla), un model_provider (el perfil con puntos <type>.<alias> al que cambiar, p. ej. deepseek.reasoner) y un model (el id del modelo local del proveedor, p. ej. deepseek-reasoner). Configure las rutas a través del gateway, zerocode o zeroclaw config set; consulte la referencia de configuración para ver el esquema de campos.

Las rutas solo se activan cuando un prompt incluye explícitamente la pista coincidente. La ruta de solicitud predeterminada usa el model_provider principal del agente.

Un hint:<name> desconocido registra una advertencia y permanece en el dominio de fiabilidad predeterminado, conservando la sugerencia literal como modelo solicitado. Una entrada predeterminada fijada sigue proporcionando su valor fijado activo/predeterminado. Una entrada predeterminada no fijada reenvía el valor literal, que el proveedor puede rechazar antes de que continúe el proceso normal de respaldo o gestión de errores.

model_provider siempre es una referencia a un perfil de proveedor con el formato <type>.<alias> delimitado por puntos, como anthropic.sonnet o openai.default. El perfil contiene el punto de conexión, la referencia a las credenciales, la variante de compatibilidad, la cadena de respaldo y un modelo predeterminado opcional. El campo model representa el estado local del proveedor dentro de ese perfil.

Limitación actual: La fijación de rutas depende del perfil de destino. El destino principal queda fijado al modelo activo/predeterminado utilizado para construir el enrutador, incluso cuando una indicación reconocida apunta de nuevo al perfil principal activo; el valor model_routes[].model de esa indicación no anula la fijación principal. Un destino no principal con un modelo de perfil configurado queda fijado a ese modelo, por lo que su modelo de ruta tampoco anula el modelo del perfil. Un destino no principal sin un modelo configurado permanece sin fijar y recibe el modelo de ruta; sus fallback_models no se materializan, aunque los perfiles de reserva referenciados se siguen recorriendo. Mantenga el modelo de ruta alineado con la fijación del destino cuando exista.

Respaldo de fiabilidad

Un perfil de proveedor puede declarar fallback_models para modelos alternativos en el mismo endpoint y fallback para otros perfiles de proveedor con notación de puntos. ZeroClaw materializa fallback_models solo cuando el perfil tiene un modelo principal efectivo; de lo contrario, ese perfil aporta una entrada sin modelo fijado. A continuación, recorre los perfiles de reserva en profundidad. Cada perfil de reserva conserva su propio endpoint, credenciales, encabezados, modelo opcional y declaraciones de reserva anidadas.

La ejecución efectiva puede diferir después de alcanzar un límite de solicitudes: las entradas de un perfil comparten una clave de periodo de enfriamiento, por lo que un 429 en el modelo principal puede omitir los modelos de respaldo restantes de ese perfil mientras el periodo de enfriamiento esté activo.

Configure la cadena a través del editor de ZeroCode Config, el panel o zeroclaw config set; consulta Configuración de proveedores. El Ciclo de vida del enrutamiento de proveedores documenta la construcción, la clasificación de reintentos, la recuperación de la transmisión, los límites de no repetición y la propiedad de la atribución.

Cambio de modelo en tiempo de ejecución

Los conmutadores en tiempo de ejecución usan el mismo contrato de provider-profile que el enrutamiento respaldado por configuración:

• /models <type>.<alias> selecciona el perfil de proveedor activo para la sesión del remitente. Los runtimes de canal también pueden aceptar la forma abreviada <type> cuando existe exactamente un alias configurado para esa familia de proveedores.
• /model <model-id> selecciona un modelo dentro del perfil de proveedor activo. Si el valor se resuelve mediante una entrada [[model_routes]], esa ruta puede seleccionar un perfil de proveedor diferente. Un destino fijado utiliza su fijación efectiva, que no tiene por qué ser model_routes[].model; un destino sin fijar que no tenga un modelo de perfil configurado recibe el modelo de la ruta.
• La herramienta model_switch utiliza model_provider = "<type>.<alias>" más model = "<provider-local-model-id>".

Los conmutadores en tiempo de ejecución son estado de sesión/tiempo de ejecución. No editan config.toml; los valores predeterminados persistentes requieren una escritura explícita en la configuración. Para los conmutadores controlados por herramientas, los nombres de familia de proveedor sin calificar, como openai, no son destinos de conmutación válidos porque no identifican qué perfil configurado, credencial, endpoint o modo de compatibilidad debe usarse.

Observabilidad

Las decisiones de despacho por agente son visibles en los registros de rastreo:

INFO channel=telegram.home routed to agent=fast
INFO agent=fast model_provider=anthropic.haiku turn_id=...
INFO model_provider=anthropic.haiku stream complete tokens={input=512, output=128}

Para implementaciones en producción, conecta la salida de los registros a Loki / Grafana. Consulta Operaciones → Registros y observabilidad.

Ver también

• Descripción general: modelo de proveedores y despacho por agente
• Configuración: esquema completo de [providers.*]
• Ciclo de vida del enrutamiento de proveedores: selección, reintento, alternativa, recuperación de la transmisión y responsabilidad de la atribución
• Catálogo de proveedores: cada slot canónico