Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

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.
  • 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 y chat_template_kwargs: protocolo avanzado y anulaciones del cuerpo de la solicitud.
  • vision: anula la capacidad de entrada de imagen (visión) del proveedor. Déjalo sin establecer para usar el valor predeterminado integrado de la familia. Establece false para un modelo de solo texto servido por una familia con capacidad de visión (por ejemplo, un modelo de texto tras llama.cpp) de modo que los mensajes con imágenes se enruten a un [multimodal] vision_model_provider configurado en lugar de generar un error; establece true para forzar su activación.
  • tool_result_image_policy: gestión de los marcadores de imagen en los resultados nativos de role = "tool" enviados a proveedores compatibles con chat-completions. De forma predeterminada, es "image_url"; establece "omit" para eliminar las cargas de URI/base64 de imagen y añadir un aviso fijo. Esto no cambia las imágenes directas de los usuarios ni los proveedores de OpenAI Responses.
  • 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.

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).

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:

sh

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.

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.

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.

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.

Ver también