tnm/zclaw

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

zclaw는 C 언어로 작성되었으며, 기본 빌드 시 엄격한 전체 펌웨어 예산 목표인 <= 888 KiB 내에서 ESP32 보드 상에서 동작합니다. 이 프로젝트는 예약된 작업(scheduled tasks), GPIO 제어, 영구 메모리(persistent memory), 그리고 자연어를 통한 커스텀 도구 구성(custom tool composition)을 지원합니다.

888 KiB 제한은 단순한 앱 코드가 아닌 전체 펌웨어 크기입니다.
여기에는 zclaw 로직뿐만 아니라 ESP-IDF/FreeRTOS 런타임, Wi-Fi/네트워킹, TLS/암호화(crypto), 그리고 인증서 번들(cert bundle) 오버헤드가 포함됩니다.

사용하기 즐겁고, 해킹하기에도 즐겁습니다.

전체 가이드와 참조를 위해 문서 사이트를 사용하세요.

전체 문서 (Full documentation)
로컬 관리 콘솔 (Local Admin Console)
사용 사례: 유용함 + 재미 (Use cases: useful + fun)
변경 이력 (Changelog, 웹)
전체 README (원문 그대로)

한 줄 부트스트랩 (macOS/Linux):

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

이미 클론(cloned)했다면?

./install.sh

비대화형 설치 (Non-interactive install):

./install.sh -y

설정 참고 사항

bootstrap.sh는 저장소를 클론/업데이트한 다음 ./install.sh를 실행합니다. 먼저 부트스트랩 흐름(ZCLAW_BOOTSTRAP_SHA256 무결성 검사 포함)을 검사/확인할 수 있습니다. 시작하기(Getting Started) 문서를 참조하세요.

Linux 의존성 설치는 ./install.sh 실행 중에 apt-get, pacman, dnf 또는 zypper를 자동으로 감지합니다.
비대화형 모드에서는 -y를 전달하지 않는 한(또는 저장된 설정/명시적 플래그가 적용되지 않는 한) 응답하지 않은 설치 프롬프트는 기본적으로 no로 설정됩니다.
플래시(flash) 내의 암호화된 자격 증명(credentials)을 위해서는 보안 모드(설치 흐름 중 --flash-mode secure 사용 또는 ./scripts/flash-secure.sh 직접 실행)를 사용하세요.
플래싱(flashing) 후에는 ./scripts/provision.sh를 사용하여 Wi-Fi + LLM 자격 증명을 프로비저닝(provision)하세요.
런타임 자격 증명(Wi-Fi SSID/비밀번호, LLM 백엔드/모델/API 키(또는 Ollama API URL), 그리고 Telegram 토큰/채팅 ID 허용 목록)을 업데이트하려면 언제든지 ./scripts/provision.sh 또는 ./scripts/provision-dev.sh를 다시 실행할 수 있습니다(재플래싱은 필요하지 않음).
기본 LLM 속도 제한(rate limits)은 100/hour 및 1000/day입니다. 컴파일 타임 제한은 main/config.h(RATELIMIT_*)에서 변경할 수 있습니다.

). - 빠른 검증 경로: ./scripts/web-relay.sh를 실행하고 테스트 메시지를 보내 장치가 응답할 수 있는지 확인하세요. - 시리얼 포트 (serial port)가 사용 중인 경우, ./scripts/release-port.sh를 실행하고 다시 시도하세요. - 비밀 정보를 다시 입력하지 않고 반복적으로 로컬 재프로비저닝 (reprovisioning)을 수행하려면, 로컬 프로필 파일과 함께 ./scripts/provision-dev.sh를 사용하세요 (provision-dev.sh는 provision.sh --yes를 래핑 (wraps) 합니다).

Telegram 또는 호스팅된 웹 릴레이 (web relay)를 통한 채팅
시간대 인식 스케줄 (timezone-aware schedules) (daily, periodic, 그리고 일회성 once)
내장 도구 및 사용자 정의 도구 (Built-in + user-defined tools)
완전히 새로운 내장 기능을 추가하려면, 'Build Your Own Tool' 문서를 통해 펌웨어 도구 (C 핸들러 + 레지스트리 엔트리)를 추가하세요.
get_diagnostics를 통한 런타임 진단 (quick/runtime/memory/rates/time/all 범위)
가드레일 (guardrails)이 적용된 GPIO, DHT 및 I2C 제어 (gpio_read_all, i2c_scan, i2c_read/i2c_write, dht_read 포함)
복구, 안전 모드 (safe mode) 및 네트워크 이전 구동을 위한 USB 로컬 관리자 콘솔
재부팅 시에도 유지되는 비휘발성 메모리 (Persistent memory)
페르소나 (Persona) 옵션: neutral, friendly, technical, witty
Anthropic, OpenAI, OpenRouter 및 Olllama (커스텀 엔드포인트) 제공자 지원

테스트된 대상: ESP32, ESP32-C3, ESP32-S3, 그리고 ESP32-C6.
클래식 ESP32-WROOM/ESP32 DevKit 보드도 지원됩니다.
다른 ESP32 변형 모델에 대한 테스트 보고서도 언제든 환영합니다!

추천 시작 보드: Seeed XIAO ESP32-C3

일반적인 빠른 루프 (fast loop):

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

프로필 설정은 한 번만 수행 후 재사용:

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

자세한 내용은 'Local Dev & Hacking' 가이드를 참조하세요.

스크립트 보기

./scripts/flash-secure.sh - 암호화와 함께 플래싱 (Flash with encryption)
./scripts/provision.sh - NVS에 자격 증명 프로비저닝 (Provision credentials to NVS)
./scripts/provision-dev.sh - 반복적인 프로비저닝을 위한 로컬 프로필 래퍼 (Local profile wrapper for repeat provisioning)
./scripts/telegram-clear-backlog.sh - 대기 중인 Telegram 업데이트 삭제
./scripts/erase.sh

NVS만 삭제 (--nvs) 또는 전체 플래시 (--all) 삭제 (가드레일 포함)
./scripts/monitor.sh
시리얼 모니터 (Serial monitor)
./scripts/emulate.sh
QEMU 프로파일 실행
./scripts/web-relay.sh
호스트 기반 릴레이 + 모바일 채팅 UI
./scripts/benchmark.sh
릴레이/시리얼 지연 시간 (latency) 벤치마크
./scripts/test.sh
호스트/장치 테스트 플로우 실행
./scripts/test-api.sh
라이브 프로바이더 API 체크 실행 (수동/로컬)

보드가 안전 모드(safe mode)에 있거나, 프로비저닝(unprovisioned)되지 않았거나, LLM 경로를 사용할 수 없는 경우에도 Wi-Fi나 LLM 왕복(round trip) 없이 USB 시리얼을 통해 작동할 수 있습니다.

./scripts/monitor.sh /dev/cu.usbmodem1101
# 그 다음 다음을 입력하세요:
/wifi status
...

사용 가능한 로컬 전용 명령:

/gpio [all|pin|pin high|pin low]

/diag [scope] [verbose]

/reboot

/wifi [status|scan]

/bootcount

/factory-reset confirm

(파괴적 작업; NVS를 삭제하고 재부팅함)

전체 참조: Local Admin Console

현재 기본 esp32 구성 분석 (idf.py -B build size-components에서 그룹화된 이미지 바이트):

세그먼트 (Segment)	바이트 (Bytes)	크기 (Size)	점유율 (Share)
zclaw 앱 로직 (`libmain.a`)	`39276`	~38.4 KiB	~4.6%
Wi-Fi + 네트워킹 스택 (networking stack)	`378624`	~369.8 KiB	~44.4%
TLS/암호화 스택 (crypto stack)	`134923`	~131.8 KiB	~15.8%
인증서 번들 (cert bundle) + 앱 메타데이터	`98425`	~96.1 KiB	~11.5%
기타 ESP-IDF/런타임/드라이버/libc	`201786`	~197.1 KiB	~23.7%

이 빌드의 총 이미지 크기는 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

tnm/zclaw

요약

핵심 포인트

설정 참고 사항

스크립트 보기

댓글