zclaw

ESP32를 위한 가장 작은 AI 개인 비서.

zclaw는 C로 작성되었으며, 기본 빌드에서 <= 888 KiB의 엄격한 올인 펌웨어 예산 목표로 ESP32 보드에서 실행됩니다. 예약 작업, 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)
• 내장 + 사용자 정의 도구
• 완전히 새로운 내장 기능을 위해 Build Your Own Tool 문서를 통해 펌웨어 도구(C 핸들러 + 레지스트리 항목)를 추가하세요.
• get_diagnostics를 통한 런타임 진단 (빠른/런타임/메모리/속도/시간/모든 범위)
• 가드레일이 있는 GPIO, DHT 및 I2C 제어 (gpio_read_all, i2c_scan, i2c_read/i2c_write, dht_read 포함)
• 복구, 안전 모드 및 네트워크 사전 부팅을 위한 USB 로컬 관리 콘솔
• 재부팅 시에도 유지되는 영구 메모리
• 페르소나 옵션: neutral, friendly, technical, witty
• Anthropic, OpenAI, OpenRouter 및 Ollama(사용자 정의 엔드포인트) 지원

하드웨어

테스트된 대상: 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
# 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

자세한 내용은 로컬 개발 및 해킹 가이드를 참조하세요.

기타 유용한 스크립트

로컬 관리 콘솔

보드가 안전 모드, 프로비저닝되지 않았거나 LLM 경로를 사용할 수 없는 경우에도 Wi-Fi 또는 LLM 왕복 없이 USB 직렬을 통해 작동할 수 있습니다.

./scripts/monitor.sh /dev/cu.usbmodem1101
# then type:
/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)이며, 888 KiB 제한까지 56128 바이트(~54.8 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