zclaw

Der kleinstmögliche KI-Personal-Assistent für ESP32.

zclaw ist in C geschrieben und läuft auf ESP32-Boards mit einem strengen All-In-Firmware-Budget von <= 888 KiB im Standard-Build. Es unterstützt geplante Aufgaben, GPIO-Steuerung, persistenten Speicher und die Erstellung benutzerdefinierter Tools durch natürliche Sprache.

Die 888 KiB-Grenze bezieht sich auf die gesamte Firmware-Größe, nicht nur auf den Anwendungscode. Es beinhaltet die zclaw-Logik sowie ESP-IDF/FreeRTOS-Laufzeit, Wi‑Fi/Netzwerk, TLS/Verschlüsselung und Zertifikatbundle-Overhead.

Macht Spaß zu benutzen, macht Spaß, daran herumzubasteln.

Vollständige Dokumentation

Nutzen Sie die Dokumentationsseite für vollständige Anleitungen und Referenzen.

• Vollständige Dokumentation
• Lokale Administrationskonsole
• Anwendungsfälle: nützlich + unterhaltsam
• Änderungsprotokoll (Web)
• Vollständige README (wörtlich)

Schnellstart

Einzeiliger Bootstrap (macOS/Linux):

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

Bereits geklont?

./install.sh

Nicht-interaktive Installation:

./install.sh -y

Highlights

• Chat über Telegram oder gehosteten Web-Relay
• Zeitzonenbewusste Zeitpläne (daily, periodic und einmalig once)
• Eingebaute + benutzerdefinierte Tools
• Für brandneue eingebaute Fähigkeiten fügen Sie ein Firmware-Tool (C-Handler + Registry-Eintrag) über die Dokumentation „Eigenes Tool erstellen“ hinzu.
• Laufzeitdiagnose über get_diagnostics (schnell/Laufzeit/Speicher/Raten/Zeit/alle Bereiche)
• GPIO-, DHT- und I2C-Steuerung mit Schutzmaßnahmen (einschließlich gpio_read_all, i2c_scan, i2c_read/i2c_write und dht_read)
• USB-lokale Administrationskonsole für Wiederherstellung, abgesicherten Modus und Vor-Netzwerk-Inbetriebnahme
• Persistenter Speicher über Neustarts hinweg
• Persona-Optionen: neutral, friendly, technical,

Hardware

Getestete Ziele: ESP32, ESP32-C3, ESP32-S3 und ESP32-C6. Klassische ESP32-WROOM/ESP32 DevKit-Platinen werden unterstützt. Testberichte für andere ESP32-Varianten sind sehr willkommen!

Empfohlenes Einstiegsboard: Seeed XIAO ESP32-C3

Lokale Entwicklung & Hacken

Typischer schneller Durchlauf:

./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101

Profileinrichtung einmalig, dann wiederverwenden:

./scripts/provision-dev.sh --write-template
# edit ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# if Telegram keeps replaying stale updates:
./scripts/telegram-clear-backlog.sh --show-config

Weitere Details im Leitfaden für lokale Entwicklung & Hacken.

Andere nützliche Skripte

Lokale Administrationskonsole

Wenn sich das Board im abgesicherten Modus befindet, nicht bereitgestellt ist oder der LLM-Pfad nicht verfügbar ist, können Sie es weiterhin über USB-Seriell ohne WLAN oder LLM-Roundtrip betreiben.

./scripts/monitor.sh /dev/cu.usbmodem1101
# then type:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

Verfügbare lokale Befehle:

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (zerstörerisch; löscht NVS und startet neu)

Vollständige Referenz: Lokale Administrationskonsole

Größenaufschlüsselung

Aktuelle Standard-esp32-Aufschlüsselung (gruppierte Image-Bytes aus idf.py -B build size-components):

Gesamtgröße des Images aus diesem Build beträgt 853034 Bytes; aufgefülltes zclaw.bin ist 853184 Bytes (~833.2 KiB), womit 56128 Bytes (~54.8 KiB) unter der 888‑KiB-Grenze verbleiben.

Latenz-Benchmarking

Relay-Pfad-Benchmark (beinhaltet Web-Relay-Verarbeitung + Geräte-Roundtrip):

./scripts/benchmark.sh --mode relay --count 20 --message "ping"

Direkter serieller Benchmark (Host-Roundtrip + erste Antwortzeit). Wenn die Firmware METRIC request ...-Zeilen protokolliert, enthält der Bericht auch die geräteseitige Zeitmessung:

./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --count 20 --message "ping"

Lizenz

MIT