Configuración del proveedor

Cada proveedor de modelos vive en [providers.models.<type>.<alias>]. <type> es un slot de familia canónico (consulta el Catálogo para ver cada slot con su endpoint). <alias> es el nombre de instancia asignado por el operador; elige cualquier nombre descriptivo (home, work, cn, gpt5, …).

Ejemplo mínimo funcional

La configuración más pequeña que carga sin errores tiene cuatro encabezados de sección: una entrada de proveedor, un agente que hace referencia a ella y un perfil de riesgo contra el cual el agente aplica las restricciones. Configúralos a través del gateway, zerocode o zeroclaw config set; la referencia de configuración tiene el índice completo de campos.

Referencia de campos: entrada de proveedor

Casi todas las familias también toman los campos compartidos de ModelProviderConfig:

• api_key: credencial para proveedores que usan claves API de tipo bearer o de suscripción.
• uri: anulación completa del endpoint. Déjelo sin establecer para usar el resolvedor de endpoints de la familia.
• model: identificador del modelo enviado al proveedor.
• temperature: temperatura opcional de muestreo.
• timeout_secs: tiempo de espera de la solicitud HTTP en segundos. Si se establece un valor superior a 300, también se eleva el límite de inactividad del streaming del proveedor (el tope predeterminado de 300 segundos entre lecturas del stream) para OpenAI Responses y los proveedores compatibles con OpenAI.
• max_tokens: límite opcional de longitud de la respuesta.
• extra_headers: encabezados HTTP adicionales para puertas de enlace personalizadas o puentes de autenticación.
• fallback_models: IDs de modelo alternativos en el mismo alias de proveedor.
• fallback: lista ordenada de otros alias de proveedor con notación de puntos que se intentarán después de que este alias falle.
• wire_api, native_tools, provider_extra, think, thinking_passthrough y chat_template_kwargs: anulaciones avanzadas de protocolo y del cuerpo de la solicitud.
• vision: sobrescribe la capacidad de entrada de imágenes (visión) del proveedor. Déjelo sin definir para usar el valor predeterminado integrado de la familia. Establézcalo en false para un modelo solo de texto servido por una familia con capacidad de visión (por ejemplo, un modelo de texto detrás de llama.cpp), de modo que los mensajes con imágenes se envíen a un [multimodal] vision_model_provider configurado en lugar de producir un error; establézcalo en true para forzarla activa. Sin un proveedor de visión configurado, un turno sin visión continúa con los marcadores de medios reemplazados por un marcador de posición cuando ninguna de las referencias de imagen del último mensaje del usuario supera las comprobaciones de existencia, de estructura de URI de datos o de política de obtención remota (un archivo que falta, un URI de datos mal formado o una URL remota mientras multimodal.allow_remote_fetch está desactivado). Una ruta local solo cuenta si es absoluta, la política de sistema de archivos del agente la permite (la misma comprobación que usan las herramientas de archivos) y existe como archivo; las rutas que la política rechaza nunca se sondean. Si alguna referencia sí supera la comprobación, el turno aún falla con el error de capacidad de visión. La comprobación de resolubilidad evalúa como máximo 16 marcadores de ruta local absoluta por turno; para estos, la comprobación de política y la sonda de existencia se ejecutan juntas en un hilo bloqueante, fuera del ejecutor asíncrono. Un mensaje con más marcadores de este tipo trata el resto como resoluble sin ninguna comprobación, de modo que un mensaje demasiado grande falla hacia el error de capacidad de visión en lugar de degradarse en silencio.
• tool_result_image_policy: manejo de las imágenes adjuntas a los resultados nativos role = "tool" enviados a proveedores compatibles con chat-completions. Las imágenes de un resultado de herramienta se declaran en un array attachments junto al texto del resultado, en el contenedor del resultado de herramienta, y nunca se recuperan del propio texto del resultado; por tanto, la sintaxis de marcadores literal en la salida de una herramienta es solo texto. El valor predeterminado es "image_url" (envía las imágenes declaradas como partes image_url); con "omit" se descartan y se añade un aviso fijo. La política lee únicamente el array attachments de los contenedores nativos; un resultado de herramienta heredado (sin clave de array) se pasa tal cual con ambos valores, porque no declara nada y su contenido es texto. Esto no cambia las imágenes directas del usuario ni los proveedores de OpenAI Responses.
• cache_passthrough: activa el prompt caching de Anthropic en gateways de chat-completions que traducen a la Messages API de Anthropic. Añade como máximo dos breakpoints de cache_control por solicitud y muestra las lecturas de caché informadas por el gateway en el uso de tokens. Valor por defecto false; las solicitudes no cambian. Requiere calificación de la ruta antes de usarse en producción; consulte Prompt cache passthrough.
• cache_ttl: duración de vida de las entradas de caché solicitada para los marcadores de caché de Anthropic. "5m" (predeterminado) o "1h". Se aplica directamente al proveedor nativo de Anthropic y a las pasarelas de chat-completions detrás de cache_passthrough; sin passthrough no tiene efecto. Los proveedores que emiten sus propios marcadores de caché por otros medios (openrouter) ignoran esta configuración. Consulta Elegir una duración de caché de 1h.
• tls_ca_cert_path: ruta absoluta a un certificado CA codificado en PEM para conexiones TLS a este proveedor (una anulación de confianza por proveedor, distinta de la TLS del gateway ca_cert_path). No se realiza expansión de shell como ~; déjelo sin establecer para usar el almacén de confianza del sistema.

Las entradas específicas de cada familia añaden sus propios campos tipados sobre estos campos compartidos.

Anthropic: paso directo del pensamiento

thinking_passthrough = true en una entrada de proveedor compatible con OpenAI activa para ese alias el paso directo de extended thinking de Anthropic: el presupuesto de thinking del runtime se reenvía al gateway, las respuestas de thinking del gateway se normalizan en bloques firmados reproducibles, y los bloques firmados se reproducen en el historial saliente.

Antes de recurrir a este flag, verifica si la pasarela también expone un endpoint de Anthropic Messages. Si lo hace, apunta una entrada [providers.models.anthropic.<alias>] a él con uri; el proveedor nativo gestiona el razonamiento (thinking), la reproducción de bloques firmados y la caché de prompts sin traducción. thinking_passthrough es para pasarelas que ofrecen únicamente la superficie de Chat Completions.

[providers.models.custom.my-gateway]
uri = "https://your-gateway.example.com"
model = "claude-group/claude-fable-5"
api_key = "..."
wire_api = "chat_completions"
thinking_passthrough = true

Qué hace

• Lado de la solicitud: cuando el runtime proporciona parámetros nativos de thinking, los cuerpos de las solicitudes ganan un objeto con forma de Anthropic en el nivel superior: {"thinking": {"type": "enabled", "budget_tokens": N}}. Una clave provider_extra explícita siempre tiene prioridad sobre el objeto inyectado, de modo que puedes fijar una forma personalizada mediante la vía de escape. La normalización de temperature y max_tokens sigue al objeto que realmente se envía, por lo que un {type = "off"} explícito conserva tu temperatura y tu límite, y un objeto enabled explícito con su propio budget_tokens eleva max_tokens por encima de ese presupuesto. Cuando se inyecta un objeto de thinking, la temperature de la solicitud se fija en 1.0, como exige Anthropic; las temperaturas explícitas solo se aplican cuando thinking está desactivado. Cuando se inyecta un presupuesto fijo de thinking, max_tokens también se eleva a budget_tokens + 1 si el límite configurado no es superior al presupuesto, como exige Anthropic.
• Captura: las respuestas de razonamiento del gateway se normalizan al mismo formato JSON firmado, delimitado por saltos de línea, que el proveedor nativo de Anthropic almacena en reasoning_content (una línea {"thinking": ..., "signature": ...} por bloque). Los bloques solo con firma (texto vacío, firma válida: la forma que emite TrueFoundry) se conservan. Con el flag desactivado, las respuestas de reasoning_content / thinking_blocks del gateway siguen fluyendo exactamente como antes, por lo que el comportamiento de razonamiento de DeepSeek/GLM/Qwen no se altera.
• Replay: el historial firmado reconstruye un array thinking_blocks en los mensajes del asistente salientes y suprime los campos de cadena. La reconstrucción es de todo o nada; consulta la limitación más abajo. La anulación replay_assistant_reasoning = false sigue prevaleciendo: los proveedores que rechazan la entrada de razonamiento no reciben nada con ninguna combinación de flags.

Requisitos y limitaciones

• Requiere una pasarela de traducción. El flag solo tiene sentido en endpoints compatibles con OpenAI que traducen entre OpenAI Chat Completions y la API Anthropic Messages (LiteLLM documenta esta traducción; el formato se verificó contra una pasarela TrueFoundry en funcionamiento). Si se apunta a un upstream que no traduce, el objeto thinking inyectado es un parámetro desconocido y la solicitud falla con HTTP 400. Ese es el modo de fallo previsto: ruidoso, en la primera solicitud, no silencioso.
• El razonamiento sin firmar invalida la reproducción. Los bloques de razonamiento que Anthropic acepta como entrada deben incluir una firma válida. El historial cuyo razonamiento no está firmado (texto transmitido en streaming o una pasarela que elimina las firmas) no envía ningún razonamiento, en lugar de fabricar bloques que una pasarela rechazaría: cualquier línea no analizable o línea de razonamiento sin firma invalida la reproducción completa del mensaje (no se permiten secuencias parciales). Los bloques redacted_thinking estructuralmente no válidos (sin carga útil de datos) se omiten individualmente, mientras que sus bloques hermanos válidos se reproducen. La lista blanca de bloques capturados es exactamente thinking (requiere texto y/o firma) y redacted_thinking (requiere data opaco, se reproduce textualmente y sin firma por diseño); cualquier otro tipo de bloque que emita una pasarela se omite durante la captura y nunca se reenvía en la reproducción. La ruta de respaldo guiada por prompt reproduce los mismos bloques validados, de modo que un segundo respaldo de esquema no descarta la trayectoria firmada.
• Los bloques de contenido anidados no se capturan. Solo se leen los campos de nivel superior reasoning_content, reasoning y thinking_blocks. Los bloques con formato de Anthropic anidados dentro de un array content no se capturan; abre una incidencia con una muestra del protocolo si tu gateway los emite.
• Passthrough desactiva el streaming en el nodo final. La normalización de capturas se aplica a respuestas no streaming, y los fotogramas SSE de razonamiento del gateway son territorio no verificado; por ello, el proveedor se declara como no streaming: cuando es el proveedor que sirve la solicitud, todo el bucle de herramientas se ejecuta por el canal no streaming, donde la captura firmada y la reproducción siguen siendo correctas. Hay dos casos límite: un Router que resuelve a este proveedor despacha su ruta no streaming y sintetiza los eventos de stream estándar, y un dominio de fiabilidad que contenga un respaldo con capacidad de streaming puede servir el turno a través de ese respaldo (mostrando el aviso estándar de respaldo), por lo que los operadores que requieran que todos los turnos se ejecuten en el proveedor optado deben configurar un dominio exclusivamente no streaming. El streaming turno a turno en el nodo final se reanudará cuando llegue el soporte de streaming wire-first.
• La forma del pensamiento sigue al modelo. El objeto inyectado coincide con la resolución de estilo del proveedor nativo: los modelos de presupuesto fijo reciben {"type": "enabled", "budget_tokens": N}, y los modelos solo adaptativos (Opus 4.7, toda la familia Fable 5) reciben {"type": "adaptive"} sin clave de presupuesto. Los IDs de modelo de la pasarela pueden llevar prefijos de enrutamiento (claude-group/...); la resolución coincide por subcadenas, así que los IDs con prefijo se resuelven a la misma forma que los nombres simples. Cuando el runtime solicita un modo de visualización, la clave display en snake_case se incluye en ambas formas (omitted, updates, summarized); si no se solicita ningún modo de visualización, la clave se omite por completo.
• Vía de escape: para formas que esta función no cubre, provider_extra sigue fusionando JSON arbitrario de nivel superior en el cuerpo de cada solicitud, incluido un objeto thinking estático, bajo tu propia responsabilidad y sin ningún tratamiento de la respuesta.

Ver también

• Pensamiento extendido nativo en el proveedor Anthropic: #10542.
• Vía de escape para el cuerpo de la solicitud: provider_extra arriba; referencia.

Orden de resolución de campos

Para la mayoría de las familias, la URL se resuelve en este orden:

1. Anulación del operador: campo uri en la entrada del alias, si está establecido.
2. Endpoint de familia: el enum *Endpoint de la familia proporciona la URL (p. ej. OpenAIEndpoint::Default -> https://api.openai.com/v1). Las familias multirregión tienen un campo endpoint en la entrada del alias que selecciona la variante (p. ej. endpoint = "cn" para Moonshot).
3. Familias con plantillas: Azure toma entradas tipadas (resource, deployment, api_version) y las sustituye en la plantilla de URI de la familia. Los campos faltantes provocan un error explícito en tiempo de ejecución.

Bedrock es una excepción: el nombre de host del endpoint se construye en el momento de la solicitud a partir de la región de firma resuelta mediante la cadena de credenciales de AWS (AWS_REGION, AWS_DEFAULT_REGION o region del credential_process activo o del perfil de IMDS). El campo de alias uri y el campo providers.models.bedrock.<alias>.region del nivel del esquema no tienen ningún efecto en la implementación actual.

Espacios familiares

Cada slot, su endpoint predeterminado y si se ejecuta localmente está en el Catálogo. Hay una clave canónica por proveedor: sin sinónimos.

Credenciales

Formas de entrada y almacenamiento de credenciales compatibles:

1. api_key = "..." en línea en la entrada de alias (aceptable para desarrollo, arriesgado para configuraciones incluidas en el control de versiones).
2. Referencias de 1Password: establece un campo secreto en op://vault/item/field. ZeroClaw mantiene la referencia en la configuración y la resuelve en tiempo de ejecución con op read, por lo que el CLI de 1Password debe estar instalado y con sesión iniciada.
3. Almacén de secretos a nivel de configuración: cifrado en ~/.zeroclaw/secrets mediante un archivo de clave local.
4. Anulación genérica por variable de entorno: ZEROCLAW_providers__models__<type>__<alias>__api_key=... establece providers.models.<type>.<alias>.api_key al iniciar. Consulta Variables de entorno para la gramática completa.

Las anulaciones de entorno schema-mirror prevalecen al iniciar. Reemplazan la credencial en memoria de ese proceso sin reescribir el valor almacenado inline, cifrado o op:// en disco.

zeroclaw quickstart escribe las credenciales en el almacén de secretos de forma predeterminada. Las configuraciones que confirmes no deben contener claves en línea. Para los nombres predeterminados del ecosistema que ya exportas en tu shell ($ANTHROPIC_API_KEY, $OPENROUTER_API_KEY, …), la referencia de env-vars muestra las expansiones de bash de una sola línea que apuntan un nombre espejo del esquema al valor existente.

Autenticación OAuth y autenticación por suscripción

Varios proveedores aceptan tokens de OAuth o de tipo suscripción en lugar de claves de API sin procesar. Obtén el token desde el panel de control o el flujo de la CLI del propio proveedor y luego colócalo en la entrada del alias de la misma manera que lo harías con una clave de API:

• Anthropic / Claude: Las claves de API de la consola y los tokens generados por claude setup-token para Claude Max van en api_key en [providers.models.anthropic.<alias>]. En Quickstart, elige api_key o setup_token; la entrada de proveedor guardada sigue siendo la ranura canónica anthropic.
• OpenAI Codex subscription: ejecuta zeroclaw auth login --model-provider openai-codex (o importa un inicio de sesión existente de Codex CLI con --import ~/.codex/auth.json), luego establece requires_openai_auth = true y deja api_key sin definir en [providers.models.openai.<alias>]; en tiempo de ejecución se lee el perfil de autenticación openai-codex almacenado de ZeroClaw.
• Gemini CLI: [providers.models.gemini_cli.<alias>] ejecuta el CLI gemini mediante shell; usa el flujo de autenticación propio del CLI.
• Grok Build CLI: [providers.models.grok_cli.<alias>] ejecuta un proceso externo mediante la interfaz ACP documentada de grok agent stdio. El prompt ensamblado se envía como JSON-RPC por stdin, nunca mediante argv ni un archivo de prompt. De forma predeterminada, la autenticación usa la caché de inicio de sesión de la CLI. Para la autenticación mediante clave de API, exporta XAI_API_KEY al entorno del demonio y añade explícitamente env_passthrough = ["XAI_API_KEY"] al alias; el alias tipado api_key sigue sin admitirse. Se requiere un working_directory absoluto existente, que define tanto el cwd del proceso hijo como el límite de la sesión ACP. El entorno del proceso hijo se vacía antes de iniciarlo, y env_passthrough está vacío de forma predeterminada. Los demás nombres XAI_* propios del proveedor y todos los nombres GROK_* se rechazan. De forma predeterminada, ZeroClaw usa --sandbox strict, --permission-mode dontAsk, un conjunto vacío de herramientas integradas y respuestas de permisos ACP con denegación por defecto en caso de fallo. extra_args es la activación explícita por alias para relajar esos controles. Las opciones de omisión --always-approve, --dangerously-skip-permissions, --yolo y --permission-mode=bypassPermissions hacen que el cliente ACP sin interfaz seleccione allow_once; los demás modos de permisos siguen seleccionando reject_once. Las opciones de transporte, modelo, sesión y cwd de ACP, además de los argumentos posicionales y abreviados, están reservados; las opciones largas desconocidas que aceptan valores usan --flag=value. El alias vision = true solo habilita a ZeroClaw para enviar bloques de imagen ACP; Grok sigue anunciando promptCapabilities.image = false hasta la versión 0.2.118 y no usa de forma fiable el contenido de imagen - déjalo sin establecer en producción; consulta Visión de ACP / entrada de imágenes.
• Qwen / MiniMax: establece auth_mode = "o_auth" en la entrada del alias, junto con los campos oauth_* relevantes (consulta env-vars → OAuth y campos de ruta de CLI).

Configuración de OpenAI Astra

OpenAI, la ID de modelo de su API pública es gpt-6-astra. La guía del modelo requiere la API de Responses para las llamadas a herramientas y enumera temperature entre los parámetros no compatibles. Configure la ruta de la API pública en un alias openai con una clave de API y un protocolo Responses explícito:

[providers.models.openai.astra_api]
api_key        = "op://platform/openai/api-key"
model          = "gpt-6-astra"
wire_api       = "responses"
vision         = true
context_window = 1050000
max_tokens     = 32000

[runtime]
reasoning_effort = "high"

[runtime_profiles.astra]
agentic             = true
max_tool_iterations = 12
max_history_messages = 80
max_context_tokens  = 200000

[agents.astra]
model_provider  = "openai.astra_api"
runtime_profile = "astra"
risk_profile    = "supervised"

El valor numérico anterior es un presupuesto local intencional, no una recomendación para llenar la ventana anunciada del modelo. La entrada del proveedor registra la capacidad del endpoint y el límite de salida, mientras que el perfil de ejecución mantiene un presupuesto estimado de entrada más pequeño y limita el bucle de herramientas. Ajústalos según la carga de trabajo y deja margen para la salida. Los campos tienen propietarios distintos:

• providers.models.openai.astra_api.context_window registra la ventana de entrada del modelo que utiliza el presupuesto consciente del proveedor.
• providers.models.openai.astra_api.max_tokens limita la salida generada; no es un límite del historial de entrada.
• runtime_profiles.astra.max_context_tokens es el umbral estimado de recorte local de ZeroClaw. Puede ser menor que context_window.
• runtime_profiles.astra.max_tool_iterations limita el bucle de herramientas agéntico, mientras que max_history_messages limita por separado los turnos completos de usuario conservados, incluidos sus intercambios de herramientas. La caché de remitentes del canal conserva su propio límite basado en filas.
• runtime.reasoning_effort es el nivel de razonamiento global orientado al proveedor. ZeroClaw acepta actualmente minimal, low, medium, high y xhigh. La API pública de Astra acepta low, medium, high, xhigh y max, así que usa un valor compartido hasta que llegue soporte para max reasoning.

No establezcas temperature en el proveedor para Astra. El adaptador de Responses reenvía el valor configurado y no corrige parámetros de muestreo no compatibles. Mantén los errores de validación de la API separados de las restricciones de cuenta, de nivel de uso, de región o de acceso al backend.

vision = true es la afirmación del operador de que este modelo y endpoint exactos aceptan entrada de imágenes. La especificación pública del modelo Astra actualmente indica que admite entrada de imágenes, pero verifica la cuenta y el endpoint configurados antes de habilitarlo. La serialización de imágenes en resultados de herramientas es un límite de adaptador independiente, seguido en #9599.

La ruta de suscripción de Codex usa requires_openai_auth = true en lugar de una clave de API y debe usar un ID de modelo exacto que sirva ese backend. La disponibilidad en la API pública no demuestra la disponibilidad en el backend de Codex; sigue la guía de suscripción de Codex y prueba la cuenta antes de enrutar tráfico de producción.

La API pública puede admitir capacidades que ZeroClaw aún no expone para este adaptador. Haga seguimiento de la continuidad del estado de razonamiento en #10706, de las herramientas de función asíncronas en #10704, del control de respuestas activas en #10708 y de las llamadas programáticas a herramientas en #10707. Son propuestas hasta que se verifiquen sus implementaciones en ZeroClaw y las rutas del proveedor.

Anulaciones compatibles con contenedores

Cuando ZeroClaw se ejecuta dentro de un contenedor y un proveedor está en el host (p. ej., Ollama), establezca uri en una dirección accesible desde el host. El mecanismo genérico de sobrescritura mediante variables de entorno (ZEROCLAW_<dotted_path_with_double_underscores>=<value>) puede establecer el mismo campo en tiempo de ejecución sin editar la configuración:

ZEROCLAW_providers__models__ollama__home__uri=http://ollama:11434 zeroclaw agent -a assistant

__ es el separador de rutas; el ejemplo anterior establece providers.models.ollama.home.uri. Consulta Variables de entorno para conocer la gramática completa.

Capacidad de visión por modelo

Utiliza vision cuando una familia de proveedores puede servir tanto modelos multimodales como modelos de solo texto. El valor pertenece al alias del proveedor, por lo que las rutas de enrutamiento y de reserva lo resuelven junto con el endpoint, las credenciales y el modelo de ese alias:

[providers.models.openai.vision]
model = "gpt-4o"
wire_api = "responses"
vision = true

[providers.models.llamacpp.text]
model = "qwen3-4b"
vision = false

Dejar vision sin definir conserva el valor predeterminado integrado de la familia del proveedor. Para los alias de OpenAI Responses, establece vision = true para los modelos que aceptan entrada de imagen; esta habilitación explícita evita que los modelos de Responses de solo texto reciban cargas de imagen accidentalmente.

Configurar vision = true es una afirmación explícita del operador de que el alias seleccionado acepta entradas de imagen. Cambia el enrutamiento de imágenes: ZeroClaw mantiene los archivos adjuntos de imagen en ese alias en lugar de tratarlos como contenido de solo texto o enrutarlos a multimodal.vision_model_provider. Configúralo solo para una combinación de proveedor y modelo probada. Para grok_cli, el mismo campo solo controla si ZeroClaw envía bloques de imagen de ACP; no modifica el anuncio de promptCapabilities.image de Grok (sigue siendo false hasta la versión 0.2.118) ni hace que la CLI describa la imagen de forma fiable. Consulta visión de ACP / entrada de imágenes.

Cuando [multimodal] vision_model_provider nombra un alias de proveedor con puntos, su model se usa automáticamente. Un [multimodal] vision_model explícito tiene prioridad sobre el modelo del alias; si no se establece ninguno, se usa el modelo de turno principal por compatibilidad con versiones anteriores.

Visualización nativa del razonamiento (Anthropic)

agent.thinking.display controla cómo se entrega el razonamiento extendido de Anthropic cuando el razonamiento nativo está habilitado (agent.thinking.native_thinking = true). Valores aceptados:

• off (predeterminado): no se envía ningún campo display; las solicitudes son idénticas a nivel de bytes a las de versiones anteriores de ZeroClaw y las solicitudes de razonamiento usan la alternativa sin transmisión.
• omitted: Anthropic omite el texto de razonamiento de la respuesta; los bloques llegan solo con la firma (thinking vacío, firma obligatoria), manteniendo intacta la reproducción y minimizando el razonamiento visible.
• updates: la solicitud incluye la versión beta thinking-display-updates-2026-08-18 y usa la ruta de respuesta de streaming. El progreso legible del razonamiento se muestra en directo mientras el modelo trabaja; la carga útil de razonamiento firmada se conserva por separado para reproducir el historial y nunca se muestra.
• summarized: mismo comportamiento de streaming, solicitando un razonamiento resumido.

[agent.thinking]
native_thinking = true
display = "updates"

Esta configuración requiere una cuenta de Anthropic inscrita en la versión beta thinking-display-updates; sin la inscripción, la API rechaza la solicitud. Establece display = "off" (o elimina el campo) para volver al comportamiento anterior del protocolo.

Passthrough de caché de prompts (gateways de chat-completions)

cache_passthrough = true en un alias de proveedor de chat-completions activa en sus solicitudes el almacenamiento en caché de prompts de Anthropic. Úsalo en gateways que traducen Chat Completions a la API de Messages de Anthropic (LiteLLM, TrueFoundry y similares); la familia nativa de Anthropic ya almacena en caché por defecto e ignora este campo.

Antes de recurrir a este flag, comprueba si la pasarela también expone un endpoint de Anthropic Messages. Si lo hace, apunta una entrada [providers.models.anthropic.<alias>] a él con uri y omite por completo el passthrough; el proveedor nativo coloca sus propios breakpoints. cache_passthrough es para pasarelas que solo ofrecen la superficie de Chat Completions.

Con la marca activada, las solicitudes incorporan como máximo dos puntos de interrupción cache_control: uno en el prompt del sistema y otro de tipo rodante en el último mensaje, una vez que la conversación tiene más de un mensaje que no sea del sistema, la misma condición que aplica el proveedor nativo de Anthropic. En un mensaje que termina con una imagen, el punto de interrupción rodante se coloca en el último bloque de texto del mensaje; la imagen queda cubierta por el turno siguiente. Con merge_system_into_user, el rol de sistema nunca se envía a la API, así que el primer mensaje de usuario fusionado (o el mensaje de usuario sintético que contiene el texto del sistema) lleva en su lugar el punto de interrupción equivalente al del sistema. Solo los mensajes que llevan puntos de interrupción cambian su serialización.

El flag también se aplica a las rutas de solicitudes estructuradas: turnos de agente, llamadas a herramientas y streaming estructurado. Los helpers de solo texto (chat_with_system, chat_with_history, y las APIs heredadas de streaming por fragmentos) no emiten puntos de interrupción a propósito, incluso con el flag activado, porque sus respuestas descartan por completo el uso de tokens; una escritura de caché premium que dispararan nunca aparecería en la contabilidad. En esos helpers el flag no tiene efecto, lo que también significa que los reintentos de fallback que pasan por ellos envían solicitudes sin marcar. Con el flag desactivado (el valor por defecto), los cuerpos de las solicitudes son idénticos byte a byte a las versiones anteriores.

[providers.models.custom.claude-via-gateway]
uri = "https://<gateway-host>/v1"
model = "<anthropic-routed model>"
api_key = "op://platform/gateway/api-key"
cache_passthrough = true

Requisitos y advertencias:

• El soporte de la pasarela es obligatorio. El punto de interrupción llega a Anthropic solo cuando la pasarela reenvía contenido en forma de bloques con cache_control a la API nativa de Messages. Las rutas que hacen proxy de la API de OpenAI propiamente dicha ignoran el campo. Un modelo no enrutado a Anthropic detrás de la misma pasarela no falla de forma visible: el campo se acepta y se descarta, y la pasarela puede seguir contabilizando los tokens de escritura de caché en esa ruta según su propio registro de uso. Para los modelos enrutados a Anthropic, cree un alias dedicado en lugar de activar la marca en una entrada mixta.
• Tamaño y TTL. Anthropic solo almacena en caché prefijos de al menos 1024 tokens (2048 en algunos modelos más pequeños), y las entradas caducan tras aproximadamente cinco minutos, renovándose en cada lectura. Las conversaciones cortas o poco frecuentes no obtienen ningún beneficio. La duración se puede configurar por proveedor con cache_ttl; consulta Elegir una duración de caché de 1h.
• Las escrituras en caché tienen un costo superior. Los tokens escritos en la caché se facturan con un recargo sobre el precio de entrada; la ruta observada factura las escrituras del valor predeterminado de 5 minutos a 1,25x. Las escrituras con una duración de 1 h pueden facturarse a una tarifa diferente; consulta Elegir una duración de caché de 1 h para ver la cifra de planificación. Las lecturas tienen un descuento considerable. Una ruta que escribe la caché en cada solicitud sin leerla nunca cuesta más que no usar caché en absoluto.
• Verifica primero la ruta exacta. Una pasarela expone muchos alias de modelo para la misma cuenta upstream, y un alias que acepta y factura las escrituras de caché puede seguir sin poder servir nunca lecturas de caché. Antes de depender del flag en producción, envía una solicitud con el flag y comprueba que el uso reportado tenga cache_creation_input_tokens > 0; a continuación, repite inmediatamente la solicitud byte a byte idéntica y comprueba que tenga cache_read_input_tokens > 0. La creación de caché por sí sola no es evidencia de que la caché funcione. Vuelve a ejecutar el par después de cualquier cambio de alias de modelo o de ruta en la pasarela.
• Reporte de uso. Cuando el gateway reenvía los contadores de uso con forma de Anthropic, cache_read_input_tokens completa la cifra de entrada en caché en el reporte de uso de tokens y de costos, y cache_creation_input_tokens se escribe en el registro de depuración solo con recuentos. Una respuesta que informa cero lecturas de caché mantiene la cifra en caché en cero en lugar de sustituirla por el contador con forma de OpenAI. Esta contabilidad cubre únicamente las rutas estructuradas, y por eso los helpers sin captura de uso permanecen inertes más arriba.
• Las definiciones de herramientas no se marcan por separado. El proveedor nativo de Anthropic marca además la última definición de herramienta, lo que cubre los tokens del esquema de herramientas cuando no existe un prompt de sistema. Esta marca no marca las definiciones de herramientas; las solicitudes con herramientas pero sin prompt de sistema solo almacenan en caché el punto de interrupción móvil de los mensajes. La calificación de la pasarela en vivo mostró que, cuando hay un prompt de sistema presente, los tokens del esquema de herramientas quedan dentro del prefijo almacenado en caché de todos modos.

Elegir una duración de caché de 1 h

cache_ttl = "1h" solicita una vida útil de una hora para las entradas de caché que crean los marcadores de este proveedor, en lugar del valor predeterminado de cinco minutos. Úsalo cuando las conversaciones se reanuden con regularidad más de cinco minutos después de la solicitud anterior: cada turno reanudado paga una reescritura de caché a precio completo por un prefijo que una vida útil más larga habría mantenido activo.

La aritmética del punto de equilibrio, con P como el precio base de entrada del prefijo: una escritura en caché de 5m cuesta 1,25P y una escritura de 1h cuesta 2P, así que elegir la duración de 1h cuesta 0,75P más por cada escritura en caché (un acierto renueva la entrada, así que la prima se paga en cada escritura, no por hora). Cada expiración que evita la duración más larga ahorra 1,25P menos la lectura de 0,1P, unos 1,15P. Para un prefijo de 140k tokens a una tarifa de entrada de $10/M, P es $1,40: unos $1,05 de prima de escritura adicional por cada escritura de 1h, unos $1,61 ahorrados por cada expiración evitada, así que la primera pausa evitada deja un neto de unos $0,56 y cada pausa posterior deja el neto completo de $1,61. El ahorro está acotado: existe para un prefijo reutilizado tras una pausa mayor de cinco minutos y menor de una hora, y una pausa superior a la hora vuelve a pagar la escritura de 2x sin ningún ahorro. Además de la prima de escritura, la duración de 1h añade un pequeño coste en cada cola añadida: unos pocos miles de tokens multiplicados por 0,75 y por la tarifa de entrada, dos o tres centavos por turno para una cola de unos pocos miles de tokens a esa tarifa. (La tarifa de lectura de 0.1x es la cifra habitual; algunos modelos difieren, así que consulta la tabla de precios de almacenamiento en caché de prompts de Anthropic para el modelo en cuestión.) Las conversaciones que hacen pausas de entre cinco minutos y una hora favorecen "1h"; las conversaciones que permanecen activas, terminan rápido o pausan más de una hora favorecen el valor por defecto.

Planifique con base en el precio nominal de escritura en caché de Anthropic, que es 2 veces la tarifa de entrada. Una pasarela delante de la API puede facturar las escrituras de 1h a su propia tarifa. El libro mayor calcula el precio de las escrituras en caché con la tarifa cache_write_per_mtok configurada o en vivo cuando existe, y con la tarifa de entrada estándar cuando solo se aplica el valor de reserva del catálogo (el catálogo no incluye una tarifa de escritura). cache_ttl no selecciona una tarifa de escritura: un operador que cambie una entrada a "1h" debe establecer la tarifa de escritura del proveedor para que coincida con lo que la ruta realmente cobra.

Dos salvedades de la calificación de la ruta en vivo: la supervivencia más allá de cinco minutos se demostró dos veces, a los seis y a los cuarenta y nueve minutos; no se midió una vida útil completa de una hora. Además, un mismo TTL se aplica a todos los marcadores que genera esta implementación: los marcadores de system, tool y de mensajes continuos (rolling) del proveedor nativo de Anthropic, así como los breakpoints de passthrough compatibles, todos conservan la vida útil configurada. El cache_control suministrado por el operador (mediante campos del cuerpo de provider_extra o JSON de herramienta sin procesar) queda fuera de esa garantía, y cualquier combinación de vidas útiles mixtas en una misma solicitud debe cumplir la regla de orden de Anthropic (un marcador de 1h antes que uno de 5m).

[providers.models.custom.claude-via-gateway]
uri = "https://<gateway-host>/v1"
model = "<anthropic-routed model>"
api_key = "op://platform/gateway/api-key"
cache_passthrough = true
cache_ttl = "1h"

On una entrada nativa de Anthropic, la misma clave funciona sin cache_passthrough:

[providers.models.anthropic.direct]
model = "claude-sonnet-4-5"
cache_ttl = "1h"

Límites de entrada de imágenes

[multimodal] limita cada imagen que entra en el flujo de la solicitud, sin importar su origen: los adjuntos de los canales, los adjuntos que declara una herramienta y la carga desde el panel web.

[multimodal]
max_image_size_mb = 20   # per image, decoded bytes (default: 20, clamped to 1-20)
max_images        = 4    # most images kept per request (default: 4, clamped to 1-16)

max_image_size_mb se mide antes de la codificación en base64, por lo que la carga útil que llega al proveedor es aproximadamente un tercio más grande. El límite de 20 MiB es la cota más baja, por imagen o por solicitud, entre las API de visión compatibles, y como las imágenes se almacenan en búfer completas, también limita la memoria del gateway por cada carga. Reduzca el valor para limitar el costo de carga por turno.

Los proveedores aplican sus propios límites además de este ajuste. Anthropic rechaza una sola imagen de más de 10 MB codificada en base64, unos 7,5 MiB decodificados, y su cliente aplica este límite independientemente de lo que permita max_image_size_mb. El coste en contexto del modelo no depende del tamaño en bytes: los proveedores rasterizan las imágenes y facturan según sus dimensiones en píxeles, de modo que un archivo grande y uno pequeño con la misma resolución cuestan aproximadamente lo mismo.

max_images cuenta cada imagen que sigue en la conversación, no solo las nuevas, por lo que una sesión larga la alcanza. Al superar el límite, las imágenes más antiguas se eliminan en un solo lote, hasta la mitad del límite redondeada hacia arriba (4 a 2, 16 a 8), y luego el recuento vuelve a crecer hasta el límite antes del siguiente lote. Eliminar una imagen modifica un mensaje anterior, así que la caché de prompts del proveedor se reconstruye desde ese mensaje; el procesamiento por lotes hace que esto ocurra una vez cada max_images / 2 + 1 imágenes nuevas en lugar de en cada una. Justo después de un lote, el modelo ve menos imágenes antiguas de las que permite el límite. Aumenta el límite para sesiones con muchas capturas de pantalla.

Ajustes por familia: ejemplos prácticos

Ollama

Ollama usa como valor predeterminado el extremo local, por lo que un alias local solo necesita el nombre del modelo:

[providers.models.ollama.local]
model = "llama3.1"

Establece uri cuando ZeroClaw no se esté ejecutando en el mismo host que Ollama:

[providers.models.ollama.host]
model = "llama3.1"
uri = "http://host.docker.internal:11434"

Los campos opcionales específicos de Ollama son num_ctx, num_predict y temperature_override.

Hailo-Ollama

Hailo-Ollama usa una ranura separada hailo_ollama porque su API nativa requiere una estructuración de solicitudes más estricta que la de Ollama normal. Una instancia local usa http://localhost:8000 por defecto; el descubrimiento de modelos lee su respuesta activa de /api/tags.

[providers.models.hailo_ollama.edge]
model = "qwen3:1.7b"
context_window = 2048
max_tokens = 256
timeout_secs = 90
queue_timeout_secs = 30

Configure uri con la URL base de Hailo-Ollama cuando se ejecute en otro host. La URL debe usar http o https y no puede contener credenciales, query ni fragment. Un alias api_key se envía como encabezado Authorization de tipo Bearer, y extra_headers se reenvían tanto a las solicitudes nativas de chat como a las de catálogo. No configure a la vez api_key y un encabezado extra Authorization explícito: ZeroClaw rechaza esa combinación ambigua de credenciales. Serializa la generación a una única solicitud activa por endpoint normalizado, incluso cuando varios alias apuntan a ese endpoint, y rechaza el trabajo en cola después de queue_timeout_secs.

Para un endpoint que no es de loopback, http sin cifrar envía los prompts y las respuestas sin cifrado de transporte ni autenticación; usa https cuando la red no sea un enlace aislado de confianza. El proveedor acepta HTTP sin cifrar para despliegues locales y para redes LAN explícitamente confiables, porque el endpoint nativo de Hailo-Ollama no tiene un contrato de autenticación.

Hailo-Ollama rechaza las opciones de transporte que no puede respetar en lugar de ignorarlas silenciosamente. En particular, tls_ca_cert_path, think=true, vision=true, el thinking nativo a nivel de llamada, provider_extra, api_path, wire_api y chat_template_kwargs no son compatibles. Establezca native_tools = false (o déjelo sin definir).

Si una solicitud aceptada alcanza su tiempo de espera HTTP o termina con otro fallo de transporte posterior a la conexión, ZeroClaw pone en cuarentena ese endpoint durante el resto del proceso, porque Hailo podría seguir generando respuesta después de que el cliente se desconecte. Confirme que el backend está inactivo (reinícielo si es necesario) y, a continuación, reinicie ZeroClaw para eliminar la cuarentena. Un fallo al establecer la conexión no pone en cuarentena el endpoint.

Para mantener la compatibilidad con el backend nativo, ZeroClaw omite los campos de transmisión think y num_ctx no compatibles, en lugar de afirmar que los controla. El servicio nativo analiza cada mensaje decodificado como JSON de prompt estructurado por segunda vez, por lo que ZeroClaw escapa tanto las barras invertidas literales como los caracteres de control CR/LF/tab en el valor de la API para conservar su significado original durante ese análisis. context_window controla el presupuesto local de historial de ZeroClaw, realizado con el mejor esfuerzo posible. Omítalo para evitar una suposición de contexto a nivel de proveedor; configure un valor positivo para habilitar el presupuesto local. El cero explícito es rechazado por el diagnóstico de configuración compartido. Deliberadamente no se envía a Hailo-Ollama. Las solicitudes de razonamiento nativo a nivel de llamada se rechazan antes de cualquier solicitud al backend. Las respuestas deben ser una respuesta completa no en streaming (done=true), y una respuesta completa vacía se trata como un error. Un context_window bajo descarta los turnos antiguos completos anclados en el usuario, usando el presupuesto agregado configurado de mejor esfuerzo. Las instrucciones del sistema se fusionan en el primer mensaje de usuario conservado antes de esa verificación. Cuando se configura un context_window distinto de cero, si el turno completo más reciente por sí solo supera el presupuesto configurado, la solicitud falla localmente antes del transporte, en lugar de descartar ese turno o sustituirlo por un prompt sintético. Cuando se omite context_window, no se aplica ningún presupuesto local a nivel de proveedor. No existe un límite a nivel de proveedor por número de caracteres o de mensajes; el HEF/runtime nativo sigue siendo la autoridad sobre la capacidad de contexto realmente soportada.

Si la respuesta nativa no tiene contenido visible pero sí contiene razonamiento interno no vacío, el proveedor usa ese campo como alternativa de texto normal de último recurso, por compatibilidad con los modelos que colocan toda su salida ahí. No expone un canal de razonamiento independiente, y quienes llaman al proveedor no deben interpretar este mecanismo de respaldo como evidencia de que se admite el pensamiento extendido.

No se anuncian la llamada nativa a herramientas, el streaming ni la visión. Como el DTO de chat de Hailo-Ollama 0.5.1 no tiene campo de imagen, vision=true se rechaza en lugar de anular esa capacidad solo de texto; configure un proveedor independiente con capacidad de visión en su lugar. Las llamadas a herramientas guiadas por prompt y sus resultados siguen disponibles como historial de texto plano siempre que el protocolo de herramientas inyectado completo quepa en el primer mensaje acotado; ZeroClaw rechaza un protocolo demasiado grande en lugar de enviar instrucciones de herramientas truncadas.

Azure OpenAI

Azure OpenAI calcula su extremo a partir de los campos de Azure escritos:

[providers.models.azure.work]
api_key = "op://platform/azure-openai/api-key"
model = "gpt-4o"
resource = "example-resource"
deployment = "gpt-4o-prod"
api_version = "2024-10-21"

Los valores de resource, deployment y api_version residen en esta configuración tipada; no se leen de variables de entorno específicas de Azure. Usa uri solo cuando necesites invalidar por completo el endpoint calculado.

Amazon Bedrock

Bedrock necesita un alias con un modelo; la región del endpoint actualmente proviene de la ruta de entorno/perfil de autenticación de Bedrock:

[providers.models.bedrock.work]
model = "anthropic.claude-sonnet-4-6"

El proveedor Bedrock utiliza las rutas de credenciales implementadas en crates/zeroclaw-providers/src/bedrock.rs:

1. api_key en el alias de Bedrock, o BEDROCK_API_KEY, usa la autenticación por token bearer de Bedrock y tiene prioridad sobre las credenciales SigV4.
2. AWS_ACCESS_KEY_ID más AWS_SECRET_ACCESS_KEY utiliza SigV4. AWS_SESSION_TOKEN es opcional. AWS_REGION o AWS_DEFAULT_REGION selecciona la región de firma y usa us-east-1 como valor predeterminado.
3. credential_process en el perfil activo de ~/.aws/config, o de AWS_CONFIG_FILE, usa SigV4. AWS_PROFILE selecciona el perfil y tiene como valor predeterminado default.
4. Las credenciales de instancia EC2 IMDSv2 son el recurso SigV4 de último recurso.

El esquema de configuración también define un campo providers.models.bedrock.<alias>.region, pero la implementación actual no lo lee. La región del endpoint siempre se resuelve a partir de la cadena de credenciales de AWS (variables de entorno, credential_process o IMDS) como se describe anteriormente.

La implementación actual de Bedrock no lee un perfil estático normal en ~/.aws/credentials. ~/.zeroclaw/secrets solo almacena secretos de configuración de ZeroClaw, como un alias api_key; no exporta variables AWS_* para el proveedor.

Para reutilizar un perfil de AWS CLI a través de la ruta de perfil implementada, coloca un credential_process en ~/.aws/config:

[profile zeroclaw-bedrock]
credential_process = /usr/bin/aws configure export-credentials --profile my-existing-profile
region = us-east-1

/usr/bin/aws es la ruta predeterminada en Debian y Ubuntu. En otros sistemas, utiliza la ruta absoluta de command -v aws.

Luego ejecuta ZeroClaw con AWS_PROFILE=zeroclaw-bedrock. Para un servicio de usuario systemd, consulta Gestión de servicios.

Multirregión (Moonshot / Qwen / GLM / MiniMax / …)

Un tipo por familia; selecciona la región mediante el campo tipado endpoint en la entrada del alias.

Endpoint personalizado compatible con OpenAI

La ranura custom requiere uri. Consulta Proveedores personalizados.

Elección del proveedor que utiliza un agente

Los agentes hacen referencia a un proveedor mediante un alias con puntos. Las entradas de proveedor por sí solas no hacen nada.

risk_profile y runtime_profile hacen referencia a mapas de alias independientes, por lo que sus nombres no tienen por qué coincidir (runtime_profile también es opcional). Config::validate() falla de forma explícita al iniciar si model_provider no se resuelve a una entrada [providers.models.<type>.<alias>] configurada, o si risk_profile no se resuelve a una entrada [risk_profiles.<alias>] configurada.

Para varios agentes que apuntan a distintos proveedores, consulta Routing.

Soporte de una sola ronda de herramientas

El ajuste single_tool_rounds del perfil de runtime del agente está desactivado por defecto. Consulta Rondas de una sola herramienta para la configuración, la contabilidad y el comportamiento de reversión. Solo solicita una llamada por respuesta cuando la ruta real del modelo y cada alternativa accesible admiten un control nativo.

Responses y Anthropic envían el control tanto en las solicitudes con streaming como en las que no lo usan. OpenAI chat-completions utiliza su implementación existente sin streaming, incluso cuando un router presenta esa respuesta como eventos de streaming. Las solicitudes sin herramientas mantienen su formato de protocolo existente. Compartir un adaptador con un proveedor compatible no implica soporte para otro endpoint. Una cadena de respaldo mixta permanece en modo por lotes aunque su proveedor principal admita el control.

Respaldo en caso de fallo

Cuando una solicitud a un proveedor falla después de agotar sus reintentos (proveedor caído, clave con límite de velocidad alcanzado, modelo no disponible), el alias puede conmutar a las alternativas que declares en la entrada del alias. Dos ejes independientes y ordenados:

• fallback_models: IDs de modelos alternativos que se intentan en este proveedor, usando el mismo endpoint, clave y encabezados. Solo cambia el identificador del modelo. Úselo cuando un proveedor ofrece un modelo de respaldo (una variante más pequeña o más antigua) que debe intentarse antes de abandonar el proveedor por completo.
• fallback: una lista ordenada de otros alias de proveedor (referencias con puntos <type>.<alias> a [providers.models]). Cada alias de respaldo se resuelve con sus propias credenciales, endpoint y modelo; un respaldo nunca hereda la clave del alias que falla.

Orden de intentos

El recorrido es en profundidad: la lista completa de modelos de un alias se agota antes de abandonarlo, luego se desciende por cada alias de fallback por turno, aplicando recursivamente los propios fallback_models y fallback de ese alias. Supongamos que anthropic.prod sirve claude-sonnet-4-5, incluye claude-haiku-4-5 en sus fallback_models y nombra a openai.backup (que sirve gpt-4.1) en su fallback. El orden de intentos es entonces:

anthropic.prod/claude-sonnet-4-5
  -> anthropic.prod/claude-haiku-4-5
  -> openai.backup/gpt-4.1
  -> (request fails)

Los alias de fallback pueden a su vez declarar fallback, por lo que la cadena es tan larga como tu configuración lo determine, hasta una profundidad máxima de 3 aliases. Una cadena que forma un bucle sobre sí misma (a -> b -> a) se detecta y la arista del ciclo se elimina, y a una cadena acíclica más profunda que el límite se le eliminan los enlaces restantes; en ningún caso se producen bucles, bloqueos ni desbordamientos de la pila.

Configuración incorrecta

Una entrada fallback que nombra un alias que no está configurado, una que cierra un ciclo, o una cadena que excede la profundidad máxima es no fatal: Config::validate() aún tiene éxito, el enlace problemático se omite en tiempo de ejecución, y el problema se muestra como una advertencia de validación (dangling_fallback_ref / fallback_cycle / max_fallback_depth_exceeded) en la CLI y en el dashboard. Una entrada fallback_models que está en blanco o duplica el model primario del alias se omite igualmente en tiempo de ejecución y se muestra (empty_fallback_model / fallback_model_duplicates_primary). Un enlace de fallback incorrecto se degrada con elegancia, nunca impide que el agente se ejecute.

Rechazos y respaldo de Anthropic

Las solicitudes nativas de Anthropic pueden devolver un refusal (rechazo): un HTTP 200 cuyo stop_reason es "refusal", emitido por los clasificadores de seguridad de Fable en lugar de una finalización normal. ZeroClaw trata un rechazo como un error tipado para que el fallback pueda recuperarlo de dos maneras:

• Lado del cliente (fallback_models, arriba): la negativa aparece como un error, y ZeroClaw pasa al siguiente modelo o alias igual que con cualquier otro fallo del proveedor, por lo que la respuesta proviene de un modelo distinto.
• Del lado del servidor (server_fallback_models en [providers.models.anthropic.<alias>]): Anthropic reintenta la solicitud rechazada contra un modelo incluido en la lista, de su lado, en una sola llamada sin streaming. Las entradas deben indicar destinos de respaldo permitidos, por ejemplo, asignar claude-fable-5 a claude-opus-4-8.

En cualquier caso, la respuesta entregada incluye un pie de página breve que indica los modelos solicitado y servido, para que el cambio sea visible para el usuario. En el chat del panel web, el mismo cambio aparece como un aviso en línea justo antes de la respuesta, que muestra únicamente los nombres del modelo solicitado y del modelo servido. Cuando un fallo habitual del proveedor ya había trasladado la solicitud a una alternativa del lado del cliente antes de que Anthropic cambiara de modelo en su lado, la respuesta conserva también el aviso habitual de alternativa, de modo que el modelo originalmente solicitado siga visible y las dos causas no se confundan.

Streaming tiene un límite: una negativa que llega después de que la salida en streaming ha comenzado mantiene el comportamiento existente de respuesta interrumpida; el fallback solo se aplica a las negativas detectadas antes de que empiece la salida.

Los protocolos compatibles con OpenAI y Responses no pueden transportar los metadatos nativos de rechazo y fallback de Anthropic; para obtener este comportamiento, enruta los modelos de Anthropic a través de [providers.models.anthropic.<alias>].

Ver también

• Visión general
• Catálogo de proveedores: ejemplo de configuración concreto para cada familia
• Streaming
• Enrutamiento
• Proveedores personalizados