ZeroClaw Architektur und Runtime

1. Die Form des Workspace

Die offizielle Architekturdokumentation beschreibt ZeroClaw als einen geschichteten Rust-Workspace. Im Zentrum sitzt die Runtime, und drumherum liegen die pluggable Oberflächen, die mit der Außenwelt sprechen.

Der nützlichste Weg, die Codebase zu lesen, ist:

Bereich	Zweck
zeroclaw-runtime	Agent-Schleife, Durchsetzung der Sicherheit, SOP-Engine, Scheduling, Koordination
zeroclaw-config	TOML-Schema, Secrets-Handling, Autonomie-Einstellungen, Workspace-Auflösung
zeroclaw-api	Öffentliche Trait-Verträge wie ModelProvider, Channel und Tool
zeroclaw-providers	Modell-Provider-Clients, Retries, Routing
zeroclaw-channels	Messaging- und Ingress-Integrationen
zeroclaw-tools	Eingebaute aufrufbare Agent-Fähigkeiten
zeroclaw-gateway	HTTP, WebSocket, Dashboard, Webhook-Ingress
zeroclaw-memory	Memory und Retrieval
zerocode	Terminal-UI

Diese Struktur spiegelt eine wichtige Designentscheidung wider: ZeroClaw will, dass der Runtime-Kern von Traits und Registries abhängt, nicht von hartkodierten Plattform-Implementierungen.

2. Die drei wichtigsten Erweiterungspunkte

Der Architektur-Guide zu v0.8.1 nennt ausdrücklich drei trait-basierte Erweiterungspunkte:

• ModelProvider
• Channel
• Tool

Das bedeutet, dass die meiste "Ich will, dass ZeroClaw etwas Neues macht"-Arbeit in einem von drei Bereichen landet:

Du willst hinzufügen...	Du arbeitest meist in...
ein neues Modell-Backend oder Wire-Protokoll	zeroclaw-providers
eine neue Messaging- oder Ingress-Oberfläche	zeroclaw-channels
eine neue Agent-Fähigkeit	zeroclaw-tools

Der breitere Workspace umfasst auch dedizierte Memory- und Hardware-Crates, aber Provider, Channels und Tools sind die Erweiterungsoberflächen, auf die die meisten Entwickelnden zuerst stoßen.

3. Request-Lifecycle

Zur Laufzeit ist die Gesamtschleife unkompliziert, auch wenn die Implementierung nicht klein ist:

1. ein Channel empfängt eine Nachricht, ein Event oder eine Anfrage,
2. er liefert diesen Input an die Runtime,
3. die Runtime ruft einen Provider mit den aktuellen Nachrichten und dem Tool-Schema auf,
4. der Provider streamt Text und möglicherweise Tool-Calls zurück,
5. die Runtime führt diese Tool-Calls durch die Sicherheitsrichtlinie,
6. freigegebene Calls werden über Tools ausgeführt,
7. Ergebnisse fließen zurück in den Modell-Turn,
8. die finale Antwort kehrt über den Channel zurück.

Diese Form erklärt, warum ZeroClaw von außen wie sehr unterschiedliche Produkte aussehen kann:

• ein Terminal-Agent,
• ein Discord- oder Telegram-Bot,
• ein gateway-gestütztes Dashboard,
• ein IDE-verbundener Agent über ACP,
• eine Always-on-Automatisierungs-Runtime.

Unter der Haube sind das verschiedene Ränder rund um dieselbe Kernschleife.

4. Provider: mehr als einfache API-Wrapper

Provider sind nicht nur dünne HTTP-Clients. Die Projektdokumentation betont diese Runtime-Verantwortlichkeiten:

• pluggable Modellfamilien
• Retries beim selben Provider
• Fallback-Ketten
• Routing
• Unterstützung für OpenAI-kompatible Endpunkte

Deshalb ist die Provider-Konfiguration einer der wichtigsten Teile des Systems. Die Provider-Schicht ist der Ort, an dem ZeroClaw aus "mit einem Modell sprechen" eine operative Oberfläche macht, die reale Ausfälle und Anbieterunterschiede überstehen kann.

5. Channels: eine Runtime, viele Oberflächen

Channels sind der Weg, über den ZeroClaw die Außenwelt erreicht. Die offizielle Dokumentation teilt sie in breite Gruppen ein:

• Chat-Plattformen wie Discord, Telegram, Matrix, Slack und andere,
• Social-/Broadcast-Oberflächen,
• E-Mail,
• Voice/Telefonie,
• Webhooks und programmatische Oberflächen wie CLI, Gateway und ACP.

Der wichtige architektonische Punkt ist, dass eine ZeroClaw-Instanz mehrere Channels gleichzeitig binden kann. Das gibt dir eine Runtime mit gemeinsamer Richtlinie und gemeinsamem Modell-/Provider-Setup statt eines Bot-Prozesses pro Plattform.

Die Channel-Dokumentation betont außerdem das Feature-Gating zur Compile-Zeit. Ein minimaler Build muss nicht jede Plattform-Integration ausliefern.

6. Tools, Memory und Gateway

Tools

Tools sind die Aktionsoberfläche. Die README und die Architekturdokumentation heben Dinge hervor wie:

• Shell,
• Browser,
• HTTP,
• PDF-bezogene Arbeit,
• hardwarezugewandte Fähigkeiten,
• eigene MCP-gestützte Integrationen.

Memory

Memory ist ein dediziertes Subsystem und kein nachträglicher Einfall. Die Architekturdokumentation beschreibt einen zeroclaw-memory-Crate mit SQLite, Embeddings und Vektor-Retrieval im Umfang.

Gateway

Das Gateway ist ein eigenes erstklassiges Subsystem:

• HTTP- und WebSocket-Zugriff,
• Dashboard-UI,
• Webhook-Ingress,
• konfigurationsbezogene Workflows,
• Quickstart- und Runtime-Management-Oberflächen.

Das ist einer der Gründe, warum sich ZeroClaw wie eine Runtime-Plattform anfühlt und nicht nur wie eine TUI.

7. Sicherheit ist in der Schleife, nicht außerhalb

Ein feiner, aber wichtiger Punkt: Sicherheit wird nicht nach dem Tool-Call angeflanscht. Sie ist Teil des Runtime-Turns selbst.

Der upstream dokumentierte Request-Lifecycle fügt ausdrücklich eine Sicherheitsvalidierung zwischen der Tool-Absicht des Modells und der tatsächlichen Tool-Ausführung ein. Das passt zur breiteren Grundhaltung des Projekts:

• per Default beaufsichtigte Autonomie,
• Freigabe-Gates,
• Sandbox-Backends,
• Receipts und Auditierbarkeit.

Wenn du den Code liest, hilft es, ZeroClaw zu verstehen als:

eine Agent-Schleife plus eine Policy-Engine

nicht nur als Chat-Wrapper über Modell-APIs.

8. Weitere Runtime-Oberflächen, die man kennen sollte

Die README und die Dokumentation verweisen auf mehrere Fähigkeiten, die für fortgeschrittene Anwendungsfälle wichtig sind:

Oberfläche	Warum es wichtig ist
SOP-Engine	Event-getriggerte Standard Operating Procedures mit Freigaben und fortsetzbaren Läufen
ACP	Agent Client Protocol für IDE-/Editor-Integration über JSON-RPC
Hardware	GPIO, I2C, SPI, USB und Board-Integrationen
Service-Modus	Lässt die Runtime als langlebiges Hintergrundsystem laufen

Das sind die Bausteine, die ZeroClaw über "Chat mit Tools" hinaus zu einer "programmierbaren Agent-Runtime" machen.