El modelo de seguridad

El modelo de seguridad de ZeroClaw controla lo que el agente puede hacer en tiempo de ejecución. Hay seis capas. De la más externa a la más interna:

Emparejamiento de canales y control de acceso

Antes de que un mensaje de un canal llegue al agente, se verifican el emparejamiento y la lista de permitidos del canal. allowed_users, allowed_chats, listas de IP permitidas para webhooks, todo se aplica en el adaptador del canal, antes de que el runtime vea el evento.

Docs: la página de cada canal en Canales.

Nivel de autonomía

La perilla de granularidad gruesa. Tres ajustes:

• ReadOnly: el agente puede observar (leer archivos, consultar memoria, obtener URLs que tiene permitido obtener) pero no puede escribir ni ejecutar comandos.
• Supervisado (predeterminado): las operaciones de bajo riesgo se ejecutan; las de riesgo medio consultan al operador; las de alto riesgo se bloquean.
• Full: sin puertas de aprobación; workspace_only está implícitamente deshabilitado. forbidden_paths, forbidden_commands y el sandbox del SO siguen aplicándose.

Documentación: Niveles de autonomía.

Reglas de límites del espacio de trabajo y de rutas

El agente opera dentro de un directorio de trabajo configurado. file_read, file_write y shell (para comandos que tocan el sistema de archivos) rechazan rutas fuera de este a menos que workspace_only = false.

Raíces de sandbox por sesión (ACP y WebSocket del gateway): Cuando se abre una sesión mediante ACP (session/new con un parámetro cwd) o mediante el WebSocket del gateway (parámetro cwd al momento de la conexión), esa ruta se convierte en el límite del workspace de SecurityPolicy para todas las herramientas de archivos y shell durante toda la vida de la sesión. El workspace_dir global del daemon sigue siendo el directorio de datos para la memoria, la identidad, cron y otros estados persistentes. El modelo es: session cwd = límite del proyecto que el agente puede tocar; workspace_dir = donde ZeroClaw almacena sus propios archivos. Nota: el system prompt del agente actualmente refleja el workspace_dir del daemon en lugar del cwd de la sesión; la aplicación de las reglas es correcta, pero la ubicación que el modelo reporta de sí mismo puede diferir.

Importante: el parámetro cwd cambia en qué directorio del host de ZeroClaw queda aislado (sandboxed) el agente; no afecta en qué máquina se ejecutan las herramientas. El uso de herramientas (comandos de shell, lecturas/escrituras de archivos) siempre se ejecuta en la máquina que ejecuta ZeroClaw. Si se conecta a una instancia remota de ZeroClaw a través del WebSocket del gateway, las llamadas a herramientas operan sobre el sistema de archivos de la máquina remota, no sobre su máquina local. Para implementaciones solo en localhost esta distinción no importa, pero las configuraciones remotas deben tenerla en cuenta.

Más allá del espacio de trabajo, los valores predeterminados de forbidden_paths incluyen /etc, /sys, /boot, ~/.ssh y otras raíces sensibles. Las entradas absolutas permitidas y prohibidas utilizan la especificidad del prefijo por componentes: gana la entrada coincidente más específica, y las prohibidas ganan en caso de empate a la misma profundidad. Esto permite que un subárbol prohibido anidado bloquee parte del espacio de trabajo o de una raíz permitida sin que valores predeterminados amplios como /home anulen un permiso más específico configurado por el operador.

Política de comandos de shell

Para invocaciones de shell:

• allowed_commands: si no está vacío, el shell solo ejecuta comandos cuyo nombre base esté en esta lista
• forbidden_commands: lista de denegación explícita (rm -rf /, shutdown, operaciones del kernel)
• validate_command_execution: una pasada de coincidencia de patrones que busca flags peligrosos, pipelines y formas de argumentos

El validador se ejecuta antes de que el comando llegue al shell. Un comando bloqueado se muestra como un error de herramienta que el modelo puede ver y responder.

Sandbox a nivel de sistema operativo

Cuando hay un backend de sandbox disponible, las invocaciones de herramientas se ejecutan dentro de él:

El sandbox limita el acceso al sistema de archivos al espacio de trabajo, elimina la conectividad de red excepto lo que la herramienta necesita explícitamente y quita el acceso a los secretos del proceso padre.

Documentación: Aislamiento de procesos (sandboxing).

Recibos de la herramienta

Los recibos de herramienta proporcionan evidencia HMAC de que una llamada de herramienta satisfactoria y su resultado pasaron por el entorno de ejecución. Cuando los recibos están habilitados, las salidas correctas de las herramientas reciben un recibo HMAC-SHA256 sobre la llamada y el resultado, y el recibo se reinyecta en la conversación junto con el resultado de la herramienta.

Los recibos ayudan a detectar afirmaciones de herramientas fabricadas. Hoy no son un registro de auditoría encadenado ni durable: las claves de los recibos son efímeras, los recibos no están cofirmados con el hash de la conversación, y el almacenamiento persistente de recibos sigue siendo trabajo futuro.

Documentación: Recibos de herramientas.

Compuertas adicionales

Más allá de las seis capas:

• Control por OTP: [security.otp] gated_actions = ["shell", "browser", "file_write"] requiere un código de un solo uso antes de cada acción listada. Útil para escenarios de acceso remoto.
• Parada de emergencia: zeroclaw estop detiene todas las llamadas a herramientas en curso. Con [security.estop] enabled = true, reanudar requiere una OTP.
• Protección contra inyección de prompts: analiza la salida del modelo en busca de patrones de inyección conocidos antes de que se validen las llamadas a herramientas.
• Detector de fugas: analiza las respuestas salientes del canal en busca de credenciales y redacta las coincidencias antes de la entrega. Cubre patrones deterministas de credenciales y también puede ejecutar una heurística independiente de tokens de alta entropía.
• Protección de emparejamiento: emparejamiento de dispositivos para la autenticación de canales; evita que las credenciales robadas funcionen en un dispositivo nuevo.

Configuración del detector de fugas

Configura la detección de fugas salientes en su propia sección TOML:

[security.leak_detection]
enabled = true
sensitivity = 0.7
high_entropy_tokens = true

enabled = false desactiva por completo el detector de fugas salientes. high_entropy_tokens = false desactiva solo la heurística de entropía independiente; los patrones deterministas de credenciales siguen ejecutándose. sensitivity acepta de 0.0 a 1.0; los valores más altos son más agresivos.

La tabla completa de campos y los valores predeterminados están en la Referencia de configuración.

Cuando las cosas salen mal

Una llamada de herramienta bloqueada no falla silenciosamente:

1. El validador de seguridad devuelve un error
2. El tiempo de ejecución lo envuelve como ToolResult::Err y lo devuelve al modelo.
3. El modelo ve “Error: Shell command blocked by policy: forbidden pattern rm -rf /” y puede reintentar, disculparse o preguntar al usuario

Si una herramienta se excluye del canal mediante [autonomy].non_cli_excluded_tools (que controla los canales no-CLI como grupo), simplemente no se anuncia al modelo en esos canales. El modelo nunca ve una herramienta que no puede usar.

Postura predeterminada

De serie:

• Autonomía: Supervisada
• Solo del espacio de trabajo: true
• Sandbox: detección automática (utiliza lo que proporcione el sistema operativo)
• Registro de auditoría: false (habilitar explícitamente)
• OTP: false
• E-stop: false

Este es un punto medio razonable, lo suficientemente seguro para una laptop, lo suficientemente permisivo para no frustrar. Súbelo para producción (OTP, auditoría, herramientas restringidas) o bájalo a YOLO para una máquina de desarrollo.