Ejecución de skills de Python
ZeroClaw puede ejecutar habilidades de Python, pero el trabajo realista en Python normalmente requiere una de estas dos opciones de implementación explícitas:
- ejecuta la skill en un entorno de Python de un host de confianza, o
- ejecútalo dentro de una imagen de runtime de Docker personalizada que ya contiene Python y los paquetes que el skill necesita.
La configuración predeterminada es intencionalmente conservadora. Bloquea muchos patrones de Python de copiar y pegar hasta que decidas qué límite de confianza deseas.
Esta página cubre los scripts de Python invocados a través de la herramienta shell integrada. Si un SKILL.toml define su propia entrada [[tools]] con kind = "shell" o kind = "script", esa herramienta de skill se ejecuta actualmente como un subproceso del host bajo la política de shell, no a través de runtime.kind = "docker". Para la ejecución de Python en contenedores actualmente, haga que las instrucciones de la skill llamen a los scripts de Python a través de la herramienta shell integrada, o haga que el comando de la herramienta de skill ejecute explícitamente el límite del contenedor que desea.
Las Tres Capas
La ejecución de skills en Python está controlada por tres capas independientes.
| Capa | Superficie de configuración | Lo que decide |
|---|---|---|
| Auditoría de habilidades | [skills].allow_scripts | La capacidad de cargar archivos auxiliares tipo shell desde un paquete de skills. Los archivos auxiliares de Python .py están permitidos de forma predeterminada. |
| Política de shell | [risk_profiles.<alias>].allowed_commands | Si la herramienta de shell puede invocar python, python3, pip u otro ejecutable. |
| Límite de ejecución | [risk_profiles.<alias>].sandbox_* y [runtime] | Dónde se ejecuta realmente el comando permitido y qué límites de sistema de archivos, red y recursos se aplican. |
Los archivos auxiliares de Python no requieren allow_scripts = true. Habilita los archivos auxiliares de tipo shell solo después de haber revisado el código fuente de la skill, y permite el intérprete (python, python3, pip) en allowed_commands del perfil de riesgo. allowed_commands es una lista estricta de ejecutables permitidos cuando no está vacía. La política de shell sigue verificando patrones destructivos y riesgos en los argumentos del intérprete además de esa lista de permitidos.
Es preferible instalar paquetes de Python en el momento de la compilación de la imagen, en un entorno virtual local revisado o en otro paso de configuración fuera del turno del agente. Añade pip a un perfil de confianza solo cuando la instalación de paquetes en tiempo de ejecución sea una parte intencionada de ese despliegue.
Lo que permanece bloqueado
ZeroClaw bloquea deliberadamente la ejecución de intérpretes en línea como:
sh
python3 -c print("hello")
python3 -m http.server
python3 -m pip install requests
node -e 'console.log(process.env)'
En el caso de las skills de Python, coloca el código en un archivo de script auditable y ejecuta ese archivo:
sh
python3 skills/portfolio/run.py
Esto hace que el archivo ejecutable sea revisable por la ruta de auditoría de skills y evita convertir una cadena de comando de shell en un contenedor de código arbitrario.
Los prefijos de variables de entorno como PYTHONPATH=... python3 script.py también son sensibles a las políticas. Prefiere un script contenedor, un entorno virtual local del proyecto o una configuración explícita dentro del script cuando necesites una configuración estable del entorno de ejecución.
Patrón A: Native Python de confianza
Use la ejecución nativa cuando las skills son de confianza y quieres que utilicen la instalación de Python del host, los paquetes, los permisos del sistema de archivos y la red.
Esto es apropiado para desarrollo local, una estación de trabajo de un solo usuario o un laboratorio doméstico donde escribiste el skill. Elimina el aislamiento a nivel de sistema operativo para las ejecuciones de herramientas bajo ese perfil, por lo que los permisos normales de usuario y las comprobaciones de políticas de ZeroClaw son las medidas de protección restantes.
No utilice este patrón para skills de terceros sin revisar ni para implementaciones multiinquilino.
Patrón B: Imagen de tiempo de ejecución de Docker personalizada
Usa Docker cuando quieras que las dependencias de Python residan en una imagen de contenedor reproducible y aun así quieras un límite de ejecución alrededor de la ejecución integrada de shell.
Crea una imagen con los paquetes que necesitan tus skills:
# Dockerfile.skill-exec
FROM python:3.12-slim
RUN pip install --no-cache-dir \
pandas \
polars \
requests
WORKDIR /workspace
Constrúyelo:
sh
docker build -f Dockerfile.skill-exec -t zeroclaw-python-skills:local .
Apunta ZeroClaw a la imagen mediante runtime.kind = "docker", que ejecuta las invocaciones de shell en un contenedor efímero. Los ajustes específicos de Docker para imagen, red, memoria, CPU, rootfs de solo lectura y montaje del espacio de trabajo se encuentran bajo runtime.docker.
Establece sandbox_backend = "none" para evitar envolver el runtime de Docker en un segundo contenedor sandbox separado. En este patrón, el runtime de Docker es el límite de ejecución para las invocaciones de shell integradas, y runtime.docker es donde se configuran la imagen y los límites del contenedor.
Si una skill necesita HTTP saliente, cambia runtime.docker.network de forma deliberada. Si una skill necesita escribir cachés de paquetes, informes o estado temporal fuera del workspace montado, evalúa si debería escribir en su lugar bajo /workspace, y luego relaja read_only_rootfs solo cuando eso no sea suficiente.
Montajes del espacio de trabajo
Cuando runtime.docker.mount_workspace = true, ZeroClaw monta el workspace configurado en /workspace dentro del contenedor y establece allí el directorio de trabajo del contenedor. Los scripts de skills deben usar rutas relativas al workspace siempre que sea posible.
Si la ruta de su espacio de trabajo debe restringirse aún más, configure la lista de permitidos del espacio de trabajo. ZeroClaw valida la ruta del espacio de trabajo del host con esa lista de permitidos antes de agregar el montaje de volumen de Docker.
La validación de montajes aplica una política de denegación por defecto. El espacio de trabajo debe existir y resolverse como una ruta canónica incluso cuando la lista de permitidos está vacía. Cada raíz configurada de la lista de permitidos también debe existir y resolverse como una ruta canónica; una sola entrada obsoleta o no válida rechaza el comando antes de que se inicie Docker, incluso si otra raíz coincide. Elimina las entradas obsoletas o crea los directorios previstos antes de actualizar.
Elegir un patrón
- Usa Python nativo de confianza cuando hayas escrito o revisado las skills y quieras la menor latencia en un host de un solo usuario.
- Usa una imagen de runtime de Docker personalizada cuando necesites dependencias reproducibles, empaquetado para producción o un límite de contenedor explícito para las llamadas de shell integradas.
- Use perfiles de riesgo más estrictos, listas de comandos permitidos más restrictivas y ejecución en contenedores para fuentes de skills no revisadas o multiinquilino.