Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Configuration du fournisseur

Chaque fournisseur de modèle se trouve dans [providers.models.<type>.<alias>]. <type> est un emplacement de famille canonique (consultez le Catalog pour chaque emplacement avec son point de terminaison). <alias> est le nom d’instance attribué par l’opérateur, choisissez n’importe quel nom descriptif (home, work, cn, gpt5, …).

Exemple de travail minimal

La configuration minimale qui se charge sans erreur comporte quatre en-têtes de section : une entrée de fournisseur, un agent qui y fait référence, et un profil de risque sur lequel l’agent applique ses contrôles. Configurez-les via la passerelle, zerocode ou zeroclaw config set ; la référence de configuration contient l’index complet des champs.

Référence des champs : entrée de fournisseur

Presque chaque famille reprend également les champs communs de ModelProviderConfig :

  • api_key : identifiant pour les fournisseurs qui utilisent des clés API de type bearer ou d’abonnement.
  • uri : surcharge complète de l’endpoint. Laisser non défini pour utiliser le résolveur d’endpoint de la famille.
  • model : identifiant du modèle envoyé au fournisseur.
  • temperature : température d’échantillonnage optionnelle.
  • timeout_secs: délai d’attente de la requête HTTP en secondes.
  • max_tokens : limite optionnelle de la longueur de la réponse.
  • extra_headers: en-têtes HTTP supplémentaires pour des passerelles personnalisées ou des ponts d’authentification.
  • fallback_models : identifiants de modèles alternatifs sur le même alias de fournisseur.
  • fallback: liste ordonnée d’autres alias de fournisseurs en notation pointée à essayer après l’échec de cet alias.
  • wire_api, native_tools, provider_extra, think et chat_template_kwargs : surcharges avancées de protocole et de corps de requête.
  • vision : remplace la capacité d’entrée d’image (vision) du fournisseur. Laissez cette option non définie pour utiliser la valeur par défaut intégrée de la famille. Définissez false pour un modèle texte uniquement servi par une famille compatible avec la vision (par exemple, un modèle texte derrière llama.cpp) afin que les messages d’image soient acheminés vers un [multimodal] vision_model_provider configuré au lieu de générer une erreur ; définissez true pour la forcer.
  • tool_result_image_policy : gestion des marqueurs d’image dans les résultats natifs de role = "tool" envoyés aux fournisseurs compatibles avec les chat-completions. La valeur par défaut est "image_url" ; définissez-la sur "omit" pour supprimer les charges utiles URI/base64 des images et ajouter une notification fixe. Cela ne modifie pas les images utilisateur directes ni les fournisseurs OpenAI Responses.
  • tls_ca_cert_path : chemin absolu vers un certificat CA encodé en PEM pour les connexions TLS à ce fournisseur (une surcharge de confiance par fournisseur, distincte du ca_cert_path TLS de la passerelle). L’expansion shell telle que ~ n’est pas effectuée ; laisser non défini pour utiliser le magasin de confiance du système.

Les entrées spécifiques à la famille ajoutent leurs propres champs typés en plus de ces champs partagés.

Ordre de résolution des champs

Pour la plupart des familles, l’URL est résolue dans cet ordre :

  1. Substitution opérateur : champ uri sur l’entrée d’alias, s’il est défini.
  2. Endpoint de famille : l’énumération *Endpoint de la famille fournit l’URL (par ex. OpenAIEndpoint::Default -> https://api.openai.com/v1). Les familles multi-régions disposent d’un champ endpoint sur l’entrée d’alias qui sélectionne la variante (par ex. endpoint = "cn" pour Moonshot).
  3. Familles basées sur des modèles : Azure accepte des entrées typées (resource, deployment, api_version) et les substitue dans le modèle d’URI de la famille. Les champs manquants échouent explicitement à l’exécution.

Bedrock est une exception : le nom d’hôte de son point de terminaison est construit au moment de la requête à partir de la région de signature résolue via la chaîne d’identifiants AWS (AWS_REGION, AWS_DEFAULT_REGION, ou la region du profil credential_process ou IMDS actif). Le champ d’alias uri et le champ providers.models.bedrock.<alias>.region au niveau du schéma n’ont aucun effet dans l’implémentation actuelle.

Emplacements familiaux

Chaque slot, son endpoint par défaut et son exécution locale ou non figurent dans le Catalogue. Il existe une clé canonique par fournisseur : pas de synonymes.

Identifiants

Formes de saisie et de stockage des identifiants prises en charge :

  1. api_key = "..." en ligne dans l’entrée d’alias (acceptable en développement, risqué pour les configs versionnées).
  2. Références 1Password : définissez un champ secret sur op://vault/item/field. ZeroClaw conserve la référence dans la configuration et la résout à l’exécution avec op read, le CLI 1Password doit donc être installé et connecté.
  3. Magasin de secrets au niveau de la configuration : chiffré dans ~/.zeroclaw/secrets via un fichier de clé local.
  4. Substitution générique via variable d’environnement : ZEROCLAW_providers__models__<type>__<alias>__api_key=... définit providers.models.<type>.<alias>.api_key au démarrage. Consultez Variables d’environnement pour la grammaire complète.

Les substitutions d’environnement schema-mirror prévalent au démarrage. Elles remplacent l’identifiant en mémoire pour ce processus sans réécrire la valeur stockée inline, chiffrée ou op:// sur le disque.

zeroclaw quickstart écrit les identifiants dans le magasin de secrets par défaut. Les configurations que vous validez ne doivent pas contenir de clés en ligne. Pour les noms par défaut de l’écosystème que vous exportez déjà dans votre shell ($ANTHROPIC_API_KEY, $OPENROUTER_API_KEY, …), la référence env-vars présente les expansions bash d’une seule ligne qui font pointer un nom miroir du schéma vers la valeur existante.

Authentification OAuth et authentification par abonnement

Plusieurs fournisseurs acceptent des jetons OAuth ou de type abonnement au lieu de clés API brutes. Obtenez le jeton depuis le tableau de bord ou le flux CLI du fournisseur, puis insérez-le dans l’entrée d’alias de la même manière qu’une clé API :

  • Anthropic / Claude : Les clés API et les jetons de la console générés par claude setup-token pour Claude Max se placent dans api_key sur [providers.models.anthropic.<alias>]. Dans le Quickstart, choisissez api_key ou setup_token ; l’entrée de fournisseur enregistrée correspond toujours au champ canonique anthropic.
  • Abonnement OpenAI Codex : exécutez zeroclaw auth login --model-provider openai-codex (ou importez une connexion CLI Codex existante avec --import ~/.codex/auth.json), puis définissez requires_openai_auth = true et laissez api_key non défini dans [providers.models.openai.<alias>] ; le runtime lit le profil d’authentification openai-codex stocké par ZeroClaw.
  • Gemini CLI : [providers.models.gemini_cli.<alias>] délègue l’exécution à la CLI gemini ; utilisez le flux d’authentification propre à la CLI.
  • Grok Build CLI : [providers.models.grok_cli.<alias>] exécute une commande externe via l’interface ACP documentée grok agent stdio. Le prompt assemblé est transmis sous forme de JSON-RPC sur stdin, jamais via argv ni par un fichier de prompt. L’authentification utilise par défaut le cache de connexion de la CLI. Pour l’authentification par clé API, exportez XAI_API_KEY dans l’environnement du démon et ajoutez explicitement env_passthrough = ["XAI_API_KEY"] à l’alias ; l’alias typé api_key reste non pris en charge. Un working_directory absolu et existant est requis et définit à la fois le cwd du processus enfant et la limite de session ACP. L’environnement du processus enfant est vidé avant son lancement, et env_passthrough est vide par défaut. Les autres variables XAI_* appartenant au fournisseur et toutes les variables GROK_* sont rejetées. ZeroClaw utilise par défaut --sandbox strict, --permission-mode dontAsk, un ensemble vide d’outils intégrés et des réponses d’autorisation ACP qui refusent en cas d’échec. extra_args est l’activation explicite propre à chaque alias pour assouplir ces contrôles. Les options de contournement --always-approve, --dangerously-skip-permissions, --yolo et --permission-mode=bypassPermissions amènent le client ACP sans interface à sélectionner allow_once ; les autres modes d’autorisation continuent d’entraîner la sélection de reject_once. Les options ACP de transport, de modèle, de session et de cwd, ainsi que les arguments positionnels et courts, sont réservés ; les options longues inconnues qui prennent une valeur utilisent --flag=value. L’alias vision = true ne fait qu’autoriser ZeroClaw à envoyer des blocs d’image ACP ; Grok continue d’annoncer promptCapabilities.image = false jusqu’à la version 0.2.118 incluse et n’utilise pas de manière fiable le contenu de l’image — laissez ce paramètre non défini en production ; voir vision ACP / entrée d’image.
  • Qwen / MiniMax : définissez auth_mode = "o_auth" dans l’entrée d’alias, ainsi que les champs oauth_* pertinents (voir env-vars → OAuth et champs de chemin CLI).

Remplacements adaptés aux conteneurs

Lorsque ZeroClaw s’exécute dans un conteneur et qu’un fournisseur se trouve sur l’hôte (par ex. Ollama), définissez uri sur une adresse accessible depuis l’hôte. Le mécanisme générique de surcharge par variables d’environnement (ZEROCLAW_<dotted_path_with_double_underscores>=<value>) peut définir le même champ à l’exécution sans modifier la configuration :

sh

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

__ est le séparateur de chemin ; l’exemple ci-dessus définit providers.models.ollama.home.uri. Consultez Variables d’environnement pour la grammaire complète.

Capacité de vision par modèle

Utilisez vision lorsqu’une famille de fournisseurs peut servir à la fois des modèles multimodaux et des modèles texte uniquement. La valeur appartient à l’alias du fournisseur, de sorte que les chemins de routage et de repli la résolvent en même temps que le point de terminaison, les identifiants et le modèle de cet alias :

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

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

Laisser vision non défini préserve la valeur par défaut intégrée de la famille de fournisseurs. Pour les alias OpenAI Responses, définissez vision = true pour les modèles qui acceptent les entrées d’image ; cette activation explicite empêche que des modèles Responses uniquement textuels reçoivent accidentellement des charges utiles d’image.

Le paramètre vision = true est une affirmation explicite de l’opérateur selon laquelle l’alias sélectionné accepte les entrées d’image. Il modifie le routage des images : ZeroClaw conserve les pièces jointes d’image sur cet alias au lieu de les traiter comme du texte uniquement ou de les acheminer vers multimodal.vision_model_provider. Ne le définissez que pour une combinaison fournisseur et modèle testée. Pour grok_cli, le même champ contrôle uniquement si ZeroClaw envoie des blocs d’images ACP ; il ne modifie pas l’annonce promptCapabilities.image de Grok (toujours false jusqu’à la version 0.2.118) et ne permet pas à la CLI de décrire l’image de manière fiable. Voir vision ACP / entrée d’image.

Lorsque [multimodal] vision_model_provider désigne un alias de fournisseur avec point, son model est utilisé automatiquement. Un [multimodal] vision_model explicite est prioritaire sur le modèle de l’alias ; si aucun n’est défini, le modèle de tour principal est utilisé pour des raisons de rétrocompatibilité.

Affichage natif du raisonnement (Anthropic)

agent.thinking.display contrôle la manière dont le raisonnement étendu d’Anthropic est transmis lorsque le raisonnement natif est activé (agent.thinking.native_thinking = true). Valeurs acceptées :

  • off (par défaut) : aucun champ display n’est envoyé ; les requêtes sont identiques au niveau des octets à celles des versions précédentes de ZeroClaw et les requêtes de réflexion utilisent le mécanisme de secours sans streaming.
  • omitted : Anthropic omet le texte de réflexion de la réponse ; les blocs ne contiennent que la signature (thinking vide, signature requise), ce qui préserve la relecture tout en réduisant au minimum le raisonnement visible.
  • updates : la requête inclut la version bêta thinking-display-updates-2026-08-18 et utilise le chemin de réponse en streaming. La progression lisible de la réflexion est affichée en direct pendant que le modèle travaille ; la charge utile de raisonnement signée est conservée séparément pour la relecture de l’historique et n’est jamais affichée.
  • summarized : même comportement de streaming, en demandant un raisonnement résumé.
[agent.thinking]
native_thinking = true
display = "updates"

Ce paramètre nécessite un compte Anthropic inscrit au programme bêta thinking-display-updates ; sans inscription, l’API rejette la requête. Définissez display = "off" (ou supprimez le champ) pour revenir au comportement précédent au niveau du protocole.

Réglages par famille : exemples détaillés

Ollama

Ollama utilise par défaut le point de terminaison local, un alias local n’a donc besoin que du nom du modèle :

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

Définissez uri lorsque ZeroClaw ne s’exécute pas sur le même hôte qu’Ollama :

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

Les champs optionnels spécifiques à Ollama sont num_ctx, num_predict et temperature_override.

Azure OpenAI

Azure OpenAI détermine son point de terminaison à partir des champs Azure renseignés :

[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"

Les valeurs resource, deployment et api_version se trouvent dans cette configuration typée, elles ne sont pas lues à partir des variables d’environnement spécifiques à Azure. Utilisez uri uniquement lorsque vous devez remplacer complètement le point de terminaison calculé.

Amazon Bedrock

Bedrock nécessite un alias avec un modèle ; la région du point de terminaison provient actuellement du chemin d’environnement/profil d’authentification Bedrock :

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

Le fournisseur Bedrock utilise les chemins d’identification implémentés dans crates/zeroclaw-providers/src/bedrock.rs :

  1. api_key sur l’alias Bedrock, ou BEDROCK_API_KEY, utilise l’authentification par jeton porteur Bedrock et prévaut sur les identifiants SigV4.
  2. AWS_ACCESS_KEY_ID plus AWS_SECRET_ACCESS_KEY utilise SigV4. AWS_SESSION_TOKEN est optionnel. AWS_REGION ou AWS_DEFAULT_REGION sélectionne la région de signature et utilise us-east-1 par défaut.
  3. credential_process dans le profil actif issu de ~/.aws/config, ou de AWS_CONFIG_FILE, utilise SigV4. AWS_PROFILE sélectionne le profil et prend la valeur default par défaut.
  4. Les informations d’identification d’instance EC2 IMDSv2 constituent le dernier mécanisme de secours pour SigV4.

Le schéma de configuration définit en outre un champ providers.models.bedrock.<alias>.region, mais l’implémentation actuelle ne le lit pas. La région du point de terminaison est toujours résolue à partir de la chaîne d’informations d’identification AWS (variables d’environnement, credential_process ou IMDS) comme décrit ci-dessus.

Un profil statique normal dans ~/.aws/credentials n’est pas lu par l’implémentation Bedrock actuelle. ~/.zeroclaw/secrets ne stocke que les secrets de configuration ZeroClaw, tels qu’un alias api_key ; il n’exporte pas les variables AWS_* pour le fournisseur.

Pour réutiliser un profil AWS CLI via le chemin de profil implémenté, ajoutez un credential_process dans ~/.aws/config :

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

/usr/bin/aws est le chemin par défaut sur Debian et Ubuntu. Sur les autres systèmes, utilisez le chemin absolu obtenu avec command -v aws.

Ensuite, exécutez ZeroClaw avec AWS_PROFILE=zeroclaw-bedrock. Pour un service utilisateur systemd, consultez Gestion des services.

Multi-région (Moonshot / Qwen / GLM / MiniMax / …)

Un type par famille ; choisissez la région via le champ typé endpoint sur l’entrée d’alias.

Point de terminaison personnalisé compatible OpenAI

Le slot custom nécessite uri. Voir Custom providers.

Choix du fournisseur utilisé par un agent

Les agents référencent un fournisseur par alias pointé. Les entrées de fournisseur seules ne font rien.

risk_profile et runtime_profile référencent des tables d’alias indépendantes, leurs noms n’ont donc pas besoin de correspondre (runtime_profile est également facultatif). Config::validate() échoue bruyamment au démarrage si model_provider ne se résout pas en une entrée [providers.models.<type>.<alias>] configurée, ou si risk_profile ne se résout pas en une entrée [risk_profiles.<alias>] configurée.

Pour plusieurs agents pointant vers différents fournisseurs, consultez Routing.

Repli en cas d’échec

Lorsqu’une requête vers un fournisseur échoue après avoir épuisé ses tentatives (fournisseur indisponible, clé limitée en débit, modèle indisponible), l’alias peut basculer vers les alternatives que vous déclarez sur l’entrée de l’alias. Deux axes indépendants et ordonnés :

  • fallback_models : identifiants de modèles alternatifs essayés sur ce fournisseur, en utilisant le même endpoint, la même clé et les mêmes en-têtes. Seul l’identifiant du modèle change. Utilisez-le lorsqu’un fournisseur propose un modèle de secours (une variante plus petite ou plus ancienne) qui doit être essayé avant de quitter complètement le fournisseur.
  • fallback : une liste ordonnée d’autres alias de fournisseurs (références pointées <type>.<alias> vers [providers.models]). Chaque alias de secours est résolu avec ses propres identifiants, point de terminaison et modèle ; un alias de secours n’hérite jamais de la clé de l’alias défaillant.

Ordre des tentatives

Le parcours est en profondeur d’abord : la liste complète des modèles d’un alias est épuisée avant de le quitter, puis chaque alias fallback est parcouru à son tour, en appliquant récursivement les fallback_models et le fallback propres à cet alias. Supposons que anthropic.prod serve claude-sonnet-4-5, liste claude-haiku-4-5 dans ses fallback_models, et désigne openai.backup (servant gpt-4.1) dans son fallback. L’ordre des tentatives est alors :

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

Les alias de repli peuvent eux-mêmes déclarer fallback, donc la chaîne est aussi longue que votre configuration le permet, jusqu’à une profondeur maximale de 3 alias. Une chaîne qui boucle sur elle-même (a -> b -> a) est détectée et l’arête du cycle est élaguée, et une chaîne acyclique plus profonde que la limite voit ses liens restants élagués ; aucune ne boucle, ne se bloque ou ne provoque de débordement de pile.

Mauvaise configuration

Une entrée fallback qui désigne un alias non configuré, qui ferme un cycle, ou une chaîne qui dépasse la profondeur maximale est non fatale : Config::validate() réussit quand même, l’arête fautive est ignorée à l’exécution, et le problème est signalé sous forme d’avertissement de validation (dangling_fallback_ref / fallback_cycle / max_fallback_depth_exceeded) dans la CLI et dans le tableau de bord. Une entrée fallback_models vide ou qui duplique le model principal de l’alias est de même ignorée à l’exécution et signalée (empty_fallback_model / fallback_model_duplicates_primary). Un lien de repli défectueux se dégrade de manière contrôlée, il n’empêche jamais l’agent de s’exécuter.

Voir aussi