Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Vue d’ensemble de l’architecture

ZeroClaw est un espace de travail Rust en couches. Au sommet se trouve le runtime de l’agent ; en dessous, on trouve des fournisseurs, canaux, outils et mémoire interchangeables ; les crates de support gèrent la configuration, le sandboxing et le matériel.

Forme de haut niveau

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

Crates dans le périmètre

CrateRôle
zeroclaw-runtimeBoucle d’agent, application de la politique de sécurité, moteur SOP, planificateur cron, SubAgents, couche RPC pour zerocode
zeroclaw-configSchéma TOML, chiffrement des secrets, niveaux d’autonomie, résolution de l’espace de travail
zeroclaw-apiTraits publics : ModelProvider, Channel, Tool, Memory, Observer, RuntimeAdapter et Peripheral. L’ABI du kernel
zeroclaw-providersToutes les implémentations de clients LLM (Anthropic, OpenAI, Ollama, …) ainsi que le routage basé sur des indications, les nouvelles tentatives, le délai de refroidissement et le basculement entre profils
zeroclaw-channelsPlus de 30 intégrations de messagerie (Discord, Slack, Telegram, Matrix, email, voix, …)
zeroclaw-gatewayPasserelle HTTP / WebSocket, tableau de bord web, ingress de webhook
zeroclaw-toolsImplémentations d’outils appelables invoquées par l’agent (navigateur, HTTP, sondes matérielles)
zeroclaw-tool-call-parserAnalyse et normalisation de la syntaxe des appels d’outils côté modèle
zeroclaw-memoryMémoire de conversation, embeddings, récupération vectorielle
zeroclaw-pluginsHôte de plugins WASM sandboxé (modèle de composants WIT)
zeroclaw-hardwareCouche d’abstraction matérielle (GPIO, I2C, SPI, USB)
zeroclaw-infraPrise en charge au niveau du processus : backend de session SQLite, debouncers, watchdog anti-blocage
zeroclaw-logLa surface unique d’émission de logs : schéma JSONL, attribution, macros record!/scope!, lecteur /api/logs, pont Observer
zeroclaw-spawnWrapper sanctionné de tokio::spawn (macro spawn!) qui propage l’attribution
zeroclaw-macrosGénérer des macros pour la configuration et l’enregistrement des outils
zerocodeInterface utilisateur terminal

La feuille de route du micro-noyau (RFC #5574) poursuit activement la scission de zeroclaw-runtime : la couche noyau sera réduite à la boucle d’agent et à l’application des politiques, tout le reste étant déplacé derrière des feature flags.

Cycle de vie de la requête (court)

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

Détails complets : Cycle de vie de la requête.

Traits principaux

Les contrats de traits se trouvent dans zeroclaw-api ; les définitions de traits dans crates/zeroclaw-api/src/ sont la source de vérité pour les fournisseurs intégrés, les canaux, les outils, les backends mémoire et les périphériques. Pour les capacités qui doivent résider en dehors du binaire principal, commencez par les guides de plugins. Les puces ci-dessous pointent vers les docs adjacents les plus proches.

  • ModelProvider: utilisez custom ou une famille de fournisseurs existante pour les points de terminaison compatibles OpenAI ; implémentez ce trait lors de l’ajout d’une nouvelle famille de fournisseurs, d’un modèle d’authentification, d’une déclaration de capacités ou d’un protocole filaire. Voir Fournisseurs personnalisés.
  • Channel : à implémenter pour une nouvelle plateforme de messagerie. Les hooks entrants et sortants sont distincts. Voir Vue d’ensemble des canaux.
  • Outil : implémenter pour une nouvelle capacité intégrée de l’agent. Voir Vue d’ensemble des outils.
  • Memory` : implémenter pour un backend mémoire qui préserve la portée agent/session.
  • Périphérique : implémenter pour les cartes matérielles et les surfaces d’appareil. Voir Vue d’ensemble du matériel.

Les autres traits publics, y compris Observer et RuntimeAdapter, sont des contrats de bas niveau. Utilisez la carte d’architecture et le processus RFC avant de les modifier.

Les nouvelles implémentations doivent rester derrière les contrats de traits zeroclaw-api et passer par la fabrique, le registre ou le feature gate propriétaire de cette surface. La RFC #5574 continue de réduire les dépendances d’implémentation runtime, donc évitez d’ajouter de nouvelles dépendances runtime concrètes sauf si la conception les exige.

Où lire ensuite