Exécution des compétences Python
ZeroClaw peut exécuter des compétences Python, mais un travail Python réaliste nécessite généralement l’un des deux choix de déploiement explicites suivants :
- exécutez la skill sur un hôte de confiance dans un environnement Python, ou
- exécutez-le dans une image d’exécution Docker personnalisée qui contient déjà Python et les packages dont la compétence a besoin.
La configuration par défaut est volontairement prudente. Elle bloque de nombreux modèles de copier-coller Python jusqu’à ce que vous décidiez de la limite de confiance souhaitée.
Cette page traite des scripts Python invoqués via l’outil shell intégré. Si un SKILL.toml définit sa propre entrée [[tools]] avec kind = "shell" ou kind = "script", cet outil de skill s’exécute actuellement comme un sous-processus hôte sous la politique shell, et non via runtime.kind = "docker". Pour une exécution Python conteneurisée aujourd’hui, faites en sorte que les instructions du skill appellent les scripts Python via l’outil shell intégré, ou faites en sorte que la commande de l’outil de skill exécute explicitement la limite de conteneur souhaitée.
Les trois couches
L’exécution des compétences Python est contrôlée par trois couches distinctes.
| Couche | Surface de configuration | Ce qu’il détermine |
|---|---|---|
| Audit des compétences | [skills].allow_scripts | Indique si les fichiers d’assistance de type shell peuvent être chargés à partir d’un package de skill. Les assistants Python .py sont autorisés par défaut. |
| Politique de shell | [risk_profiles.<alias>].allowed_commands | Indique si l’outil shell peut invoquer python, python3, pip ou un autre exécutable. |
| Limite d’exécution | [risk_profiles.<alias>].sandbox_* et [runtime] | Où la commande autorisée s’exécute réellement, et quelles limites de système de fichiers, de réseau et de ressources s’appliquent. |
Les fichiers d’assistance Python ne nécessitent pas allow_scripts = true. N’activez les fichiers d’assistance de type shell qu’après avoir examiné le code source de la compétence, et autorisez l’interpréteur (python, python3, pip) dans les allowed_commands du profil de risque. allowed_commands est une liste d’autorisation stricte d’exécutables lorsqu’elle n’est pas vide. La politique shell vérifie tout de même les motifs destructeurs et les risques liés aux arguments de l’interpréteur en plus de cette liste d’autorisation.
Préférez l’installation des paquets Python lors de la création de l’image, dans un environnement virtuel local revu, ou dans une autre étape de configuration en dehors du tour de l’agent. N’ajoutez pip à un profil de confiance que lorsque l’installation de paquets à l’exécution fait intentionnellement partie de ce déploiement.
Ce qui reste bloqué
ZeroClaw bloque délibérément l’exécution d’interpréteurs en ligne tels que :
sh
python3 -c print("hello")
python3 -m http.server
python3 -m pip install requests
node -e `console.log(process.env)`
Pour les compétences Python, placez le code dans un fichier de script auditable et exécutez ce fichier :
sh
python3 skills/portfolio/run.py
Cela rend le fichier exécutable vérifiable par le chemin d’audit des compétences et évite de transformer une chaîne de commande shell en conteneur de code arbitraire.
Les préfixes de variables d’environnement tels que PYTHONPATH=... python3 script.py sont également sensibles du point de vue de la politique. Privilégiez un script wrapper, un environnement virtuel local au projet ou une configuration explicite à l’intérieur du script lorsque vous avez besoin d’une configuration stable de l’environnement d’exécution.
Modèle A : Python natif de confiance
Utilisez l’exécution native lorsque les skills sont approuvés et que vous souhaitez qu’ils utilisent l’installation Python de l’hôte, ses packages, ses autorisations de système de fichiers et son réseau.
Cela convient au développement local, à un poste de travail mono-utilisateur ou à un home lab où vous avez écrit le skill. Cela supprime le sandboxing au niveau du système d’exploitation pour les exécutions d’outils sous ce profil, de sorte que les permissions utilisateur normales et les vérifications de politique ZeroClaw constituent les garde-fous restants.
N’utilisez pas ce modèle pour des compétences tierces non vérifiées ou des déploiements multi-locataires.
Modèle B : Image d’exécution Docker personnalisée
Utilisez Docker lorsque vous souhaitez que les dépendances Python résident dans une image de conteneur reproductible et que vous voulez conserver une limite d’exécution autour de l’exécution intégrée du shell.
Créez une image avec les paquets dont vos compétences ont besoin :
# Dockerfile.skill-exec
FROM python:3.12-slim
RUN pip install --no-cache-dir \
pandas \
polars \
requests
WORKDIR /workspace
Compilez-le :
sh
docker build -f Dockerfile.skill-exec -t zeroclaw-python-skills:local .
Pointez ZeroClaw vers l’image via runtime.kind = "docker", qui exécute les invocations shell dans un conteneur éphémère. Les paramètres spécifiques à Docker pour l’image, le réseau, la mémoire, le CPU, le système de fichiers racine en lecture seule et le montage de l’espace de travail se trouvent sous runtime.docker.
Définissez sandbox_backend = "none" pour éviter d’encapsuler le runtime Docker dans un second conteneur sandbox distinct. Dans ce modèle, le runtime Docker constitue la frontière d’exécution pour les invocations shell intégrées, et runtime.docker est l’endroit où l’image et les limites de conteneur sont configurées.
Si un skill nécessite des requêtes HTTP sortantes, modifiez runtime.docker.network de manière délibérée. Si un skill doit écrire des caches de paquets, des rapports ou un état temporaire en dehors de l’espace de travail monté, vérifiez s’il ne devrait pas plutôt écrire sous /workspace, puis assouplissez read_only_rootfs uniquement lorsque cela ne suffit pas.
Montages d’espace de travail
Lorsque runtime.docker.mount_workspace = true, ZeroClaw monte l’espace de travail configuré sur /workspace dans le conteneur et y définit le répertoire de travail du conteneur. Les scripts de compétence doivent utiliser des chemins relatifs à l’espace de travail chaque fois que possible.
Si le chemin de votre espace de travail doit être davantage restreint, configurez la liste d’autorisation des espaces de travail. ZeroClaw valide le chemin de l’espace de travail hôte par rapport à cette liste d’autorisation avant d’ajouter le montage de volume Docker.
La validation des montages applique un refus par défaut. L’espace de travail doit exister et être résolu en chemin canonique, même lorsque la liste d’autorisation est vide. Chaque racine configurée dans la liste d’autorisation doit également exister et être canonisée ; une entrée obsolète ou non valide rejette la commande avant le démarrage de Docker, même si une autre racine correspond. Supprimez les entrées obsolètes ou créez les répertoires prévus avant la mise à niveau.
Choisir un modèle
- Utilisez du code Python natif de confiance lorsque vous avez écrit ou révisé les skills et que vous souhaitez la latence la plus faible sur un hôte mono-utilisateur.
- Utilisez une image runtime Docker personnalisée lorsque vous avez besoin de dépendances reproductibles, d’un packaging de production ou d’une limite de conteneur explicite pour les appels shell intégrés.
- Utilisez des profils de risque plus stricts, des listes d’autorisation de commandes plus restreintes et une exécution conteneurisée pour les sources de compétences non vérifiées ou multi-locataires.