Descripción general de la arquitectura

ZeroClaw es un espacio de trabajo en capas escrito en Rust. En la parte superior se encuentra el entorno de ejecución del agente; debajo de este se encuentran los proveedores, canales, herramientas y memoria que son plug-and-play; los crates de soporte gestionan la configuración, el aislamiento y el hardware.

Forma de alto nivel

flowchart TB
    subgraph External["External world"]
        UI["CLI / chat platforms / gateway clients / ACP IDEs"]
        LLM["LLM providers<br/>Anthropic · OpenAI · Ollama · ..."]
        FS["Filesystem · shell · network"]
    end

    subgraph Edges["Edge crates: talk to the outside"]
        CH["zeroclaw-channels<br/>30+ messaging integrations"]
        GW["zeroclaw-gateway<br/>REST · WebSocket · dashboard"]
        PR["zeroclaw-providers<br/>LLM clients · retry · routing"]
        TL["zeroclaw-tools<br/>browser · HTTP · hardware"]
    end

    subgraph Core["Core"]
        RT["zeroclaw-runtime<br/>agent loop · security · SOP · cron · subagents"]
        MEM["zeroclaw-memory<br/>SQLite · embeddings · consolidation"]
        CFG["zeroclaw-config<br/>schema · autonomy · secrets"]
    end

    UI --> CH
    UI --> GW
    CH --> RT
    GW --> RT
    RT --> PR
    RT --> TL
    RT --> MEM
    RT --> CFG
    PR --> LLM
    TL --> FS

Cajas en el ámbito

Caja	Rol
`zeroclaw-runtime`	Bucle de agente, aplicación de políticas de seguridad, motor de SOP, planificador cron, SubAgents, capa RPC para zerocode
`zeroclaw-config`	Esquema TOML, cifrado de secretos, niveles de autonomía, resolución de espacios de trabajo
`zeroclaw-api`	Rasgos públicos: `ModelProvider`, `Channel`, `Tool`, `Memory`, `Observer`, `RuntimeAdapter` y `Peripheral`. La ABI del kernel
`zeroclaw-providers`	Todas las implementaciones de clientes LLM (Anthropic, OpenAI, Ollama, …), además del enrutamiento basado en sugerencias, los reintentos, el enfriamiento y la conmutación por error entre perfiles
`zeroclaw-channels`	Más de 30 integraciones de mensajería (Discord, Slack, Telegram, Matrix, correo electrónico, voz, …)
`zeroclaw-gateway`	Puerta de enlace HTTP / WebSocket, panel de control web, entrada de webhook
`zeroclaw-tools`	Implementaciones de herramientas invocables que el agente llama (navegador, HTTP, sondeos de hardware)
`zeroclaw-tool-call-parser`	Análisis y normalización de la sintaxis de llamadas a herramientas del lado del modelo
`zeroclaw-memory`	Memoria de conversación, incrustaciones, recuperación de vectores
`zeroclaw-plugins`	Host de complementos WASM aislado (modelo de componentes WIT)
`zeroclaw-hardware`	Capa de abstracción de hardware (GPIO, I2C, SPI, USB)
`zeroclaw-infra`	Soporte a nivel de proceso: backend de sesiones SQLite, debouncers, watchdog de bloqueos
`zeroclaw-log`	La superficie única de emisión de logs: esquema JSONL, atribución, macros `record!`/`scope!`, lector de `/api/logs`, puente `Observer`
`zeroclaw-spawn`	Wrapper autorizado de `tokio::spawn` (macro `spawn!`) que propaga la atribución
`zeroclaw-macros`	Generar macros para la configuración y el registro de herramientas
`zerocode`	Interfaz de línea de comandos

La hoja de ruta del microkernel (RFC #5574) está dividiendo activamente zeroclaw-runtime aún más: la capa del kernel se reducirá al bucle del agente y la aplicación de políticas, mientras que todo lo demás pasará a estar detrás de feature flags.

Ciclo de vida de la solicitud (corto)

sequenceDiagram
    participant U as User
    participant CH as Channel
    participant RT as Runtime
    participant SEC as Security
    participant PR as Provider
    participant TL as Tool

    U->>CH: message / DM / webhook
    CH->>RT: deliver_message(ctx)
    RT->>PR: chat(messages, tools)
    PR-->>RT: stream: text · tool_call
    RT->>SEC: validate(tool_call)
    SEC-->>RT: approved / blocked
    RT->>TL: invoke(args)
    TL-->>RT: result
    RT->>PR: chat(..., + tool_result)
    PR-->>RT: stream: text (final)
    RT-->>CH: reply (partial / final)
    CH-->>U: message

Detalles completos: Ciclo de vida de la solicitud.

Rasgos principales

Los contratos de traits viven en zeroclaw-api; las definiciones de traits en crates/zeroclaw-api/src/ son la fuente de verdad para los proveedores integrados, canales, herramientas, backends de memoria y periféricos. Para capacidades que deberían vivir fuera del binario principal, empieza por las guías de plugins. Las viñetas de abajo apuntan a la documentación adyacente más cercana.

ModelProvider: usa custom o una familia de proveedor existente para endpoints compatibles con OpenAI; implementa este trait al añadir una nueva familia de proveedor, modelo de autenticación, declaración de capacidades o protocolo de red. Consulta Custom providers.
Channel: implementar para una nueva plataforma de mensajería. Las entradas y salidas son hooks separados. Consulta Channels overview.
Tool: implementa para una nueva capacidad integrada del agente. Consulta Tools overview.
Memory: implementar para un backend de memoria que conserve el ámbito de agente/sesión.
Peripheral: implementar para placas de hardware y superficies de dispositivo. Ver Hardware overview.

Otros traits públicos, incluidos Observer y RuntimeAdapter, son contratos de nivel inferior. Usa el mapa de arquitectura y el proceso RFC antes de cambiarlos.

Las nuevas implementaciones deben permanecer detrás de los contratos de trait de zeroclaw-api y conectarse a través de la factoría, el registro o el feature gate propietario de esa superficie. El RFC #5574 sigue reduciendo las dependencias de implementación en tiempo de ejecución, así que evita añadir nuevas dependencias concretas de runtime salvo que el diseño las requiera.

Dónde leer a continuación

Crates: análisis detallado de cada crate
Ciclo de vida de la solicitud: streaming, llamadas a herramientas, aprobaciones
Proveedores de modelos → Descripción general
Seguridad → Resumen