@openclaw/fs-safe para operaciones locales de archivos sensibles para la seguridad: lecturas/escrituras limitadas a una raíz, reemplazo atómico, extracción de archivos comprimidos, espacios de trabajo temporales, estado JSON y manejo de archivos de secretos.
Es una barrera de biblioteca para código confiable de OpenClaw que recibe nombres de ruta no confiables, no un sandbox. Los permisos del sistema de archivos del host, los usuarios del SO, los contenedores y la política del agente/herramienta siguen definiendo el radio de impacto real.
Predeterminado: sin ayudante de Python
OpenClaw establece el ayudante POSIX de Python de fs-safe en desactivado de forma predeterminada:- el Gateway no debe iniciar un sidecar persistente de Python a menos que un operador lo habilite explícitamente;
- la mayoría de las instalaciones no necesitan el endurecimiento adicional contra mutaciones del directorio padre;
- desactivar Python mantiene el comportamiento en tiempo de ejecución predecible en entornos de escritorio, Docker, CI y aplicaciones empaquetadas.
FS_SAFE_PYTHON_MODE y FS_SAFE_PYTHON.
Usa require (no auto) cuando el ayudante forme parte de tu postura de seguridad; auto vuelve silenciosamente al comportamiento solo con Node si el ayudante no puede iniciarse.
Qué sigue protegido sin Python
Con el ayudante desactivado, OpenClaw sigue obteniendo las barreras solo con Node de fs-safe:- rechaza escapes de rutas relativas (
..), rutas absolutas y separadores de ruta donde solo se permiten nombres simples; - resuelve operaciones mediante un manejador de raíz confiable en lugar de comprobaciones ad hoc con
path.resolve(...).startsWith(...); - rechaza patrones de enlaces simbólicos y enlaces duros en las API que requieren esa política;
- abre archivos con comprobaciones de identidad donde la API devuelve o consume contenido de archivo;
- escribe archivos de estado/configuración mediante un temporal hermano atómico + cambio de nombre;
- aplica límites de bytes para lecturas y extracción de archivos comprimidos;
- aplica modos de archivo privados para secretos y archivos de estado donde la API los requiere.
Qué agrega Python
En POSIX, el ayudante opcional mantiene un proceso persistente de Python y usa operaciones del sistema de archivos relativas a fd para mutaciones del directorio padre: cambio de nombre, eliminación, mkdir, stat/list y algunas rutas de escritura. Eso reduce las ventanas de carrera con el mismo UID donde otro proceso intercambia un directorio padre entre la validación y la mutación: defensa en profundidad en hosts donde procesos locales no confiables pueden modificar los mismos directorios en los que opera OpenClaw. Si tu despliegue tiene ese riesgo y Python tiene garantizada su disponibilidad, establece:Guía para Plugin y núcleo
- El acceso a archivos orientado a Plugins debe pasar por los ayudantes de
openclaw/plugin-sdk/*, no porfssin procesar, cuando una ruta proviene de un mensaje, salida de modelo, configuración o entrada de Plugin. - El código del núcleo debe usar los envoltorios de fs-safe bajo
src/infra/*para que la política de proceso de OpenClaw se aplique de forma coherente. - La extracción de archivos comprimidos debe usar los ayudantes de archivo comprimido de fs-safe con límites explícitos de tamaño, cantidad de entradas, enlaces y destino.
- Los secretos deben usar los ayudantes de secretos de OpenClaw o los ayudantes de secretos/estado privado de fs-safe; no implementes manualmente comprobaciones de modo alrededor de
fs.writeFile. - Para aislamiento frente a usuarios locales hostiles, no dependas solo de fs-safe. Ejecuta Gateways separados bajo usuarios/hosts de SO separados, o usa sandboxing.