Outils : Vue d’ensemble

Les Outils sont les mains de l’agent. Un outil est une capacité que le modèle peut invoquer en cours de conversation, exécuter une commande shell, récupérer une URL HTTP, ouvrir un navigateur, écrire un fichier ou lire un capteur. Chaque appel d’outil est soumis à la politique de sécurité. Les exécutions réussies peuvent inclure un reçu d’outil lorsque les reçus sont activés.

Les outils ne doivent pas être confondus avec les sous-commandes CLI de zeroclaw. Les commandes CLI sont destinées aux opérateurs ; les outils sont destinés à l’agent.

Un agent obtient ses outils via les bundles de compétences, de connaissances et de MCP qu’il référence ; consultez Agents pour savoir comment les bundles sont attachés à un agent. Pour le chemin au niveau de chaque tour, de l’appel d’outil du fournisseur à l’approbation, au dispatch, à la réception, à l’événement observateur et à l’entrée d’historique, consultez Cycle d’exécution des outils.

Avant d’ajouter un outil intégré ou de remplacer un outil existant par une intégration externe, utilisez l’Inventaire des outils intégrés pour choisir l’emplacement durable le plus réduit. Les intégrations intégrées fonctionnelles restent disponibles tant qu’un remplacement n’est pas réel, documenté et examiné indépendamment. Cette règle de remplacement d’abord correspond à la politique acceptée dans le RFC #6165, consignée dans la section Politique de remplacement d’abord de l’inventaire.

Outils minimaux et complets

Les configurations utilisent full sauf si elles sélectionnent minimal : chaque outil intégré fourni par ce binaire et autorisé par sa configuration existante, ses prérequis et ses règles de permission. La configuration initiale et la génération de configuration écrivent optional = ["*"]. Un fichier sans [tools], ou une section [tools] sans optional, se charge également en mode full, afin que la mise à niveau vers v0.8.6 conserve la disponibilité des outils existants. Les sélections explicites existantes sont conservées.

[tools]
optional = ["*"] # complet ; la valeur par défaut

Minimal est en activation explicite : onze outils intégrés dans Chat, ou huit dans Code/ACP, qui exclut toujours ses outils de mémoire persistante. Les onze outils de Chat sont shell, file_read, file_write, file_edit, glob_search, content_search, memory_recall, memory_store, memory_forget, web_fetch et git_operations. La politique existante peut restreindre l’un ou l’autre catalogue.

[tools]
optional = [] # minimal

Pour une installation minimale avec les extras sélectionnés, utilisez leurs noms d’appel :

[tools]
optional = ["calculator", "cron_list", "sessions_history"]

Le caractère générique est une union avec des entrées nommées : ["*", "calculator"] a la même sélection que ["*"], sans outil en double. Full n’est pas un nombre fixe d’outils ; les intégrations configurées, les capacités d’exécution et la politique déterminent le catalogue effectif. Il n’active pas toutes les intégrations. Sélectionner un outil n’installe pas de navigateur ni de CLI de fournisseur, ne fournit pas d’identifiants, n’active pas une intégration désactivée et n’accorde pas de permission. Full préserve également l’exclusion existante de la mémoire pour Code/ACP.

La sélection intervient avant l’exécution des constructeurs. Un outil non sélectionné n’apporte aucun schéma ni aucun texte de catalogue d’outils dans le prompt. Les profils de risque, la restriction par l’appelant, l’approbation, les politiques de chemin et de réseau, ainsi que les reçus restent applicables. Les serveurs MCP explicites, les compétences, les plugins et les périphériques conservent leurs chemins d’activation et d’autorité existants. La divulgation progressive des schémas est une fonctionnalité distincte, qui ne fait pas partie de ces paramètres.

Pour choisir minimal, définissez optional = [] dans [tools], ou exécutez :

zeroclaw config set tools.optional [] --no-interactive

Rechargez le démon après avoir modifié la sélection. Le schéma de configuration reste en version 3. zeroclaw config migrate enregistre optional = ["*"] pour un fichier existant sans [tools] ; les sauvegardes ordinaires conservent aussi l’intention du sélecteur.

Compilations et chemin de mise à niveau

Une matrice de publication comporte dix cibles, avec des noms d’archives inchangés. Android est expérimental et autorisé à échouer ; la publication requiert les neuf autres cibles. Il n’existe pas de seconde matrice d’archives de compatibilité ni d’image compat-tools dédiée. L’image Docker historique all-features reste plus large que dist, incluant des canaux et des fonctionnalités matérielles supplémentaires.

dist inclut tools-compat (tools-saas, tools-coding-cli, tools-external). dist-compat est un alias de compatibilité pour le même build. Les valeurs par défaut de Cargo restent plus légères : les builds depuis les sources personnalisées peuvent omettre les adaptateurs. Un adaptateur externe exclu à la compilation mais nommé dans optional génère un diagnostic explicite ; full ne sélectionne que les adaptateurs embarqués dans ce binaire et ne signale rien pour les autres. Les sections fournisseur/CLI activées conservent leur diagnostic existant de fonctionnalité manquante. La configuration à l’exécution ne peut pas ajouter de code exclu à la compilation. Compilez la sélection standard pour le récupérer :

# À partir d'un dépôt source ; utilisez la cible que vous comptez exécuter.
TARGET=x86_64-unknown-linux-gnu
FEATURES="$(cargo run --quiet --locked -p xtask --bin generate -- features --selection dist --target "$TARGET")"
cargo build --release --locked --bin zeroclaw --target $TARGET --no-default-features --features $FEATURES
# Pour une image Linux locale, résoudre les fonctionnalités de sa cible de compilation.
docker build -t zeroclaw-dist-local .

Pour une installation Homebrew dont la formule omet les adaptateurs, exécutez le binaire standard compilé depuis les sources en parallèle du binaire géré par le gestionnaire de paquets, et utilisez ses propres chemins de configuration, de données et de service. Un paramètre de configuration ne peut pas modifier les fonctionnalités compilées d’un bottle. Les utilisateurs depuis les sources peuvent aussi sélectionner individuellement des fonctionnalités tool-* existantes ou tools-compat ; ils ont tout de même besoin de la sélection à l’exécution.

Le dist standard inclut l’hôte de plugins et plugins-wasm-cranelift sur les sept cibles natives 64 bits prises en charge : Linux GNU et musl sur x86_64 et aarch64, les deux architectures macOS, et Windows x86_64 MSVC. Les ARMv6/ARMv7 omettent Cranelift et Prometheus ; Android expérimental omet Cranelift et WhatsApp Web. Les valeurs par défaut de Cargo n’incluent pas d’hôte de plugins. La compilation de l’hôte laisse plugins.enabled et plugins.auto_discover à false ; le consentement, la confiance, les autorisations et l’activation configurée s’appliquent toujours. La prise en charge runtime uniquement des .cwasm précompilés et Pulley ne remplace pas la compilation portable des .wasm du registre. La politique de cible provient de package.metadata.zeroclaw dans Cargo.toml.

Minimal est une sélection de catalogue à l’exécution. Le dist standard embarque toujours les adaptateurs natifs compilés, donc minimal seul ne constitue pas une preuve de taille binaire pour le travail d’extraction des outils. Les valeurs par défaut Container, Kubernetes et Nix omettent [tools] et se chargent en complet comme toute autre configuration ; définissez optional = [] dans celles-ci pour minimal.

Outils intégrés

Les capacités intégrées suivantes sont disponibles lorsqu’elles sont compilées et sélectionnées, ce que fait full pour toutes ; le jeu minimal de onze outils est listé ci-dessus. Cette liste n’est pas le jeu de base ; voir Niveaux et jeu de base conservé pour le jeu de base et le niveau de chaque outil construit par le registre d’exécution.

Fournisseur AnySearch

AnySearch est un backend explicite et activé manuellement pour web_search_tool :

[web_search]
search_provider = "anysearch"
# Facultatif ; à omettre pour utiliser le quota anonyme d'AnySearch, plus faible et soumis à une limite de débit.
anysearch_api_key = "..."

Les requêtes de recherche et la limite de résultats configurée sont envoyées à https://api.anysearch.com/v1/search. Lorsque anysearch_api_key est configurée, ZeroClaw ne l’envoie que dans un en-tête d’autorisation Bearer ; sans clé, aucun en-tête Authorization n’est envoyé. Sélectionner ce fournisseur envoie donc les requêtes de recherche à un service tiers, même en mode anonyme. Il ne modifie pas le fournisseur par défaut et n’est pas utilisé comme solution de repli automatique.

Intégrés de première partie supplémentaires, inclus dans la version complète mais pas dans la version minimale :

Les outils sélectionnés conservent également ces prérequis :

Découverte de schéma intégrée

Activez deferred_builtin_tools sur le profil d’exécution de l’agent via l’éditeur de configuration ZeroCode afin de réduire le catalogue d’outils intégrés envoyé au modèle. Sa valeur par défaut est false, ce qui conserve le chargement anticipé des schémas. Ce paramètre est indépendant de l’option deferred_loading de MCP.

Lorsqu’elle est activée, les schémas autorisés de shell, file_read, file_write, file_edit, memory_recall et memory_store restent visibles. Les autres outils intégrés activés apparaissent dans une liste de découverte compacte. Le modèle utilise tool_search avec des mots-clés ou select:<tool_name> pour récupérer les définitions complètes. Les schémas sélectionnés apparaissent dans les requêtes d’outils natifs suivantes ; les fournisseurs de texte reçoivent la définition dans le résultat de la recherche.

La découverte n’accorde jamais de permission et ne modifie jamais l’approbation des outils. La politique de l’agent, les restrictions des principaux et les listes d’autorisation des appelants continuent de s’appliquer, y compris après qu’une session a restreint ses outils. Les exécutables intégrés restent dans le registre à portée existant, de sorte que le routage de la mémoire ne conserve pas d’instance d’outil distincte et obsolète. Si la politique n’autorise pas tool_search, les schémas intégrés restants restent en chargement anticipé. Les points de terminaison de listage des outils continuent de lister l’ensemble complet du registre admis.

Protocoles d’extension

Au-delà des outils intégrés, ZeroClaw prend en charge la surface d’extension MCP (Model Context Protocol). Connectez n’importe quel serveur MCP (le système de fichiers de Claude Code, Playwright, le vôtre) et l’agent récupère ses outils au démarrage.

Pour une intégration côté IDE où un éditeur pilote ZeroClaw en tant que sous-processus, consultez ACP : Agent Client Protocol se trouve sous channels car il s’agit d’une surface entrante de gestion de sessions, et non d’un outil que l’agent invoque.

Création d’un outil

Implémentez le trait Tool dans zeroclaw-api :

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;   // Schéma JSON pour les arguments
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

Chaque Tool est également Attributable, de sorte que les émissions de journaux et les traces d’audit d’un appel d’outil portent la même attribution <kind>.<alias> que celle utilisée par le reste du runtime.

Enregistrez-vous via l’usine d’outils du runtime. Consultez Développement → Protocole des plugins pour le modèle complet.

Décrire des outils au modèle

Les descriptions d’outils sont des chaînes Mozilla Fluent : une par outil, localisée par locale. Cela permet de garder les descriptions d’outils concises dans la fenêtre de contexte du modèle tout en autorisant la localisation de l’interface utilisateur.

Source of truth : crates/zeroclaw-runtime/locales/en/tools.ftl. Les traductions sont générées et maintenues via cargo fluent fill --locale <code> (voir Maintainers → Docs & Translations).

Risques et approbation

Chaque invocation d’outil est classée par niveau de risque :

• Faible (lecture seule, sans effets de bord) : file_read, memory_recall, http_request GET vers les domaines autorisés
• Moyen (modifie l’état local) : file_write, shell avec des commandes connues comme sûres
• Élevé (effets de bord destructeurs ou distants) : shell avec des commandes inconnues, http_request POST vers des URL non restreintes

Le niveau d’autonomie détermine ce que chaque niveau de risque peut faire sans l’approbation de l’opérateur. Par défaut (Supervised) : les exécutions de faible intensité sont autorisées, celles de moyenne intensité demandent une vérification, et celles de haute intensité sont bloquées.

Lorsque les reçus sont activés, les exécutions réussies reçoivent un reçu d’outil. Les appels refusés, bloqués, remplacés, échoués ou interrompus ne reçoivent pas de reçus.

Désactivation des outils sur les canaux non-CLI

Le schéma ne possède pas de champ tools_allow / tools_deny par canal. Le contrôle d’accès aux outils se trouve dans le profil de risque de l’agent ([risk_profiles.<alias>]) :

• excluded_tools supprime les outils répertoriés de chaque canal non-CLI (Discord, Telegram, Bluesky, Matrix, Slack, etc.) tout en laissant l’interface CLI locale intacte. La granularité est binaire (CLI vs non-CLI), et non par canal. Cela soustrait également les éléments de la liste d’autorisation des délégués agentiques résolue au moment de l’exécution, ce qui constitue le seul moyen de bloquer les noms MCP <server>__<tool> individuels qui seraient autrement automatiquement admis par la règle ci-dessous.
• allowed_tools est une liste d’autorisation. Omis et une liste explicitement vide (allowed_tools = []) signifient le même état hérité : aucune contrainte d’autorisation. Une liste non vide constitue un ensemble fermé pour les outils intégrés (et, via l’exception MCP ci-dessous, admet automatiquement les outils MCP à espace de noms). Une liste vide ne signifie pas un refus total ; pour cela, définissez l’option sœur deny_all_tools = true, qui refuse de la même façon les outils intégrés, les outils MCP et les outils définis par les compétences. Définir à la fois deny_all_tools = true et une allowed_tools non vide est une erreur de configuration, rejetée au chargement.
• Exception MCP : lorsque allowed_tools n’est pas vide, les outils MCP découverts au moment de l’exécution (tout nom contenant __, selon la convention <server>__<tool>) sont automatiquement admis dans la liste d’autorisation effective sans avoir à y être répertoriés individuellement. Cela permet de conserver l’utilisation du comportement MCP par défaut postérieur au #7464 pour les agents qui définissent déjà une liste d’autorisation explicite. Pour bloquer des outils MCP individuels, répertoriez-les dans excluded_tools.
• L’exception MCP s’applique uniquement au champ allowed_tools du profil de risque. Les listes d’autorisation par exécution fournies par l’appelant (le allowed_tools d’une tâche cron, les invocations de délégué restreintes, etc.) sont toujours traitées comme des intersections strictes de listes explicites. Une tâche qui se restreint elle-même à allowed_tools = ["cron_add"] n’exposera pas les wrappers MCP découverts au moment de l’exécution qu’elle n’a pas nommés, même lorsque le profil de risque de l’agent les admettrait automatiquement.

Si vous avez besoin d’un contrôle plus fin en autonomie complète, placez les outils sensibles dans la liste always_ask du profil : ils demandent toujours confirmation (ou échouent en mode fermé) même lorsque level = "full". Il n’est nécessaire de passer le profil en read_only ou supervised que si vous voulez appliquer l’ensemble de la matrice des niveaux de risque, et non seulement quelques exceptions.

Consultez Niveaux d’autonomie pour l’ensemble complet des champs par profil.

Voir aussi

• MCP
• Cycle de vie d’exécution des outils
• ACP
• Automatisation du navigateur
• Sécurité → Aperçu