zclaw

ESP32向けの最小限のAIパーソナルアシスタント。

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）
• 組み込み + ユーザー定義ツール
• まったく新しい組み込み機能については、Build Your Own Toolのドキュメントを介してファームウェアツール（Cハンドラ + レジストリエントリ）を追加します。
• get_diagnosticsによるランタイム診断（quick/runtime/memory/rates/time/allスコープ）
• ガードレール付きの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