zclaw

Самый маленький из возможных AI-персональный помощник для ESP32.

zclaw написан на C и работает на платах ESP32 с жестким бюджетом всей прошивки <= 888 KiB в сборке по умолчанию. Он поддерживает запланированные задачи, управление GPIO, постоянную память и создание пользовательских инструментов через естественный язык.

Ограничение 888 KiB — это полный размер прошивки, а не только код приложения. Он включает логику zclaw плюс среду выполнения ESP-IDF/FreeRTOS, Wi-Fi/сеть, TLS/криптографию и накладные расходы на пакет сертификатов.

Весело использовать, весело дорабатывать.

Полная документация

Используйте сайт документации для полных руководств и справки.

• Полная документация
• Локальная административная консоль
• Варианты использования: полезные + забавные
• Список изменений (веб)
• Полный README (дословно)

Быстрый старт

Однострочная загрузка (macOS/Linux):

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

Уже клонировано?

./install.sh

Неинтерактивная установка:

./install.sh -y

Основные возможности

• Чат через Telegram или размещенный веб-ретранслятор
• Расписания с учетом часового пояса (daily, periodic и однократные once)
• Встроенные + пользовательские инструменты
• Для совершенно новых встроенных возможностей добавьте инструмент прошивки (обработчик на C + запись в реестр) через документацию Build Your Own Tool.
• Диагностика времени выполнения через get_diagnostics (области: быстрая/выполнение/память/скорость/время/все)
• Управление GPIO, DHT и I2C с ограничениями (включая gpio_read_all, i2c_scan, i2c_read/i2c_write и dht_read)
• USB-локальная административная консоль для восстановления, безопасного режима и первичного запуска до сети
• Постоянная память между перезагрузками
• Варианты личности: neutral, friendly, technical,

Аппаратное обеспечение

Проверенные цели: ESP32, ESP32-C3, ESP32-S3 и ESP32-C6. Поддерживаются классические платы ESP32-WROOM/ESP32 DevKit. Отчеты о тестировании других вариантов ESP32 приветствуются!

Рекомендуемая стартовая плата: Seeed XIAO ESP32-C3

Локальная разработка и хакинг

Типичный быстрый цикл:

./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

Настройте профиль один раз, затем используйте повторно:

./scripts/provision-dev.sh --write-template
# отредактируйте ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# если Telegram продолжает повторять устаревшие обновления:
./scripts/telegram-clear-backlog.sh --show-config

Больше подробностей в руководстве Local Dev & Hacking.

Другие полезные скрипты

Локальная административная консоль

Когда плата находится в безопасном режиме, не настроена или путь LLM недоступен, вы все равно можете управлять ею через USB-последовательный порт без Wi-Fi или обращения к LLM.

./scripts/monitor.sh /dev/cu.usbmodem1101
# затем введите:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

Доступные локальные команды:

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (необратимо; стирает NVS и перезагружает)

Полная справка: Локальная административная консоль

Разбивка по размеру

Текущая разбивка для esp32 по умолчанию (сгруппированные байты образа из idf.py -B build size-components):

Общий размер образа из этой сборки: 853034 байт; дополненный zclaw.bin — 853184 байт (~833.2 KiB), остается 56128 байт (~54.8 KiB) до ограничения в 888 KiB.

Тестирование задержки

Тестирование пути ретранслятора (включает обработку веб-ретранслятора + круговой обход устройства):

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

Прямое тестирование последовательного порта (круговой обход хоста + время первого ответа). Если прошивка выводит строки METRIC request ..., отчет также включает временные метки на стороне устройства:

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

Лицензия

MIT