Cajas
El workspace está dividido en capas. Los crates edge se comunican con el mundo exterior; los crates core orquestan; los crates de soporte proporcionan utilidades. Cada crate tiene su propio rustdoc, consulta API (rustdoc).
Capa: Núcleo
zeroclaw-runtime
El bucle del agente, la aplicación de políticas de seguridad, el motor SOP, el planificador cron, el ciclo de vida de SubAgent y la capa RPC para zerocode. Depende de todos los demás crates core y edge.
Submódulos destacados:
agent/: el bucle principal de solicitud/respuesta, streaming, orquestación de llamadas a herramientassecurity/: tipos de políticas, detección de sandbox, OTP, parada de emergenciasop/: motor de Procedimientos Operativos Estándar (ver SOP → Overview)subagent/: Creación y ciclo de vida de SubAgents (ver Delegación y SubAgents)cron/,daemon/,heartbeat/: programación de tareas y gestión de procesos de larga duraciónskills/: compilación y ejecución de habilidadesservice/: integración con systemd / launchctl / Servicios de Windowsrpc/: la capa RPC de zerocode
zeroclaw-config
Esquema TOML y su validación. Maneja:
- Enum de nivel de autonomía (
ReadOnly/Supervised/Full) - Almacén de secretos cifrados (archivo de clave local)
- Resolución del espacio de trabajo (variables de entorno, rutas de Homebrew, XDG, detección de contenedores)
- Versionado de esquemas y migración
Todas las claves de configuración visibles para el usuario están documentadas en Referencia → Config, que se genera a partir de este crate.
zeroclaw-api
La ABI del kernel. Define los traits públicos principales, incluyendo:
ModelProvider: interfaz de cliente LLM con indicadores de capacidad de streamingChannel: superficie de mensajería entrante/salienteTool: capacidades invocables por agentesMemory: almacenamiento y recuperación de conversacionesObserver: receptor (sink) tipado de métricas/observabilidad
El tiempo de ejecución depende únicamente de estos rasgos, no de implementaciones concretas. Esto es lo que hace que la adición de proveedores/canales/herramientas sea una cuestión de implementar un rasgo en lugar de parchear el núcleo.
Capa: Borde
zeroclaw-providers
Todas las implementaciones de cliente LLM más los wrappers de enrutamiento y reintento. Consulta Proveedores de modelos → Descripción general para ver la lista.
Estructura:
traits.rs: reexportaciones dezeroclaw-apimás funciones auxiliares internas del proveedoranthropic.rs,openai.rs,ollama.rs, …: un archivo por cada proveedor nativocompatible.rs: una única implementación compatible con OpenAI reutilizada por más de 20 proveedores (Groq, Mistral, xAI, Venice, etc.)router.rs: selección de ruta de modelo por llamada basada en sugerenciasreliable.rs: reintentos / espera progresiva / periodo de enfriamiento y envoltorio de respaldo ordenado de proveedores de modelosstreaming.rs: análisis de SSE, estimación de tokens, deltas de llamadas a herramientas
zeroclaw-channels
Más de 30 integraciones de mensajería. Consulta Canales → Descripción general para ver el catálogo.
Todos los canales implementan el trait Channel de zeroclaw-api. Cada uno está condicionado por una feature; una compilación mínima incluye solo los canales que compiles.
El submódulo orchestrator/ se encarga del streaming de mensajes, actualizaciones de borradores, divisiones de múltiples mensajes y del servidor ACP.
zeroclaw-gateway
Puerta de enlace HTTP/WebSocket. Expone el tiempo de ejecución a través de:
- API REST (gestión de sesiones, memoria, estado y cron)
- WebSocket para respuestas en streaming
- Panel web (activos estáticos + autenticación)
- Puntos finales de webhook (entrantes desde canales que envían)
El emparejamiento es obligatorio de forma predeterminada; [gateway.allow_public_bind = true] permite la vinculación a 0.0.0.0.
zeroclaw-tools
Herramientas invocables que el agente llama. No confundir con los subcomandos de CLI zeroclaw.
Incluye: browser, http_request, web_search, shell, file_read, file_write, sondas de hardware (hardware_board_info, hardware_memory_read), y más. Consulta Herramientas → Descripción general.
Cada herramienta se registra a través de una fábrica y se describe al modelo mediante cadenas localizadas de forma fluente.
Capa: Soporte
zeroclaw-memory
Memoria de conversación y recuperación. SQLite es el backend predeterminado; PostgreSQL está disponible detrás de --features memory-postgres para implementaciones multi-instancia que necesitan un almacén compartido con escrituras concurrentes. Opcional:
- Backends de incrustación (OpenAI, Ollama, local)
- Recuperación de vectores sobre conversaciones almacenadas (pgvector cuando se usa PostgreSQL)
- Consolidación de memoria (resúmenes, extracción de hechos)
zeroclaw-tool-call-parser
Análisis de la sintaxis de las llamadas a herramientas del lado del modelo. Maneja las variaciones entre proveedores:
- JSON de
tool_callsal estilo de OpenAI - Bloques
<tool_use>al estilo de Anthropic - Formatos de llamada a funciones de Qwen/Ollama
- Deltas de transmisión de llamadas de herramientas nativas
zeroclaw-plugins
Host de complementos WASM en sandbox: carga complementos del modelo de componentes (tool, channel, memory, skill bundles) en proceso bajo WASI con combustible por llamada y límites de memoria. Ver Desarrollo → Protocolo de complementos.
zeroclaw-hardware
Abstracción de hardware: GPIO, I2C, SPI, USB. Condicionado por plataforma. Consulte Hardware → Información general.
zeroclaw-log
La superficie de emisión única para cada evento de log en el workspace. Es propietaria del esquema JSONL en disco (LogEvent), del registro de atribución vinculado a alias (ATTRIBUTION_FIELDS + COMPOSITE_PREFIXES), del Layer de tracing-subscriber que captura cada llamada tracing::*, de las macros record! y scope!, del escritor con recorte rotativo, del lector de cursor paginado detrás de /api/logs y del puente hacia el Observer tipado para los consumidores de Prometheus / OTel. Consulte architecture/logging.md.
zeroclaw-spawn
El wrapper autorizado alrededor de tokio::spawn. Proporciona la macro spawn!, que instrumenta cada tarea en segundo plano con el span de atribución actual del invocador, de modo que un record! emitido dentro del future generado hereda el agent_alias / channel / session_key del padre. Los sitios de llamada usan spawn! en lugar de tokio::spawn directamente.
zeroclaw-infra
Soporte a nivel de proceso: debouncers, watchdogs, el backend de sesiones de SQLite. No es una capa de tracing/métricas, eso es zeroclaw-log. Consulta Runtime state and persistence para los límites de propiedad y durabilidad del estado entre config, sesiones, memoria, logs, costs, cron y metadata del gateway.
zeroclaw-macros
Genera macros para el esquema de configuración, el registro de herramientas y el registro de canales. Reduce el código repetitivo en todo el espacio de trabajo.
zerocode
Interfaz de terminal, construida como una aplicación independiente bajo apps/zerocode/. Es su propio miembro del workspace sin dependencia de crates zeroclaw-* (consulta Docs & Translations → zerocode strings para su catálogo de i18n independiente).
Banderas de características
La hoja de ruta del microkernel (RFC #5574) define una taxonomía de indicadores de función. El resultado práctico para un usuario es:
default: una compilación base razonableci-all: todo activado, para CIchannel-<name>: habilitación opcional por canal (p. ej.,channel-matrix,channel-discord)hardware: habilitar el subsistema de hardwaregateway,acp-bridge,whatsapp-web: grupos de capacidades opcionales (opt-in)
Los proveedores no están restringidos por feature gates; todos se compilan. La selección de canal es el principal ajuste por compilación. Consulta la tabla [features] del Cargo.toml de nivel superior para ver la lista completa.