AI Hub Icon
AIBit オープンソースプロジェクトを発見
ホーム / 実用的なオープンソースプロジェクト

zclaw – ESP32 用 888 KiB AI 個人アシスタント（C/C++）

February 27, 2026
カテゴリ: 実用的なオープンソースプロジェクト
タグ:
Open Source AI Assistant ESP32 Embedded C Microcontroller

イントロダクション

zclaw は、ESP32 ベースのマイクロコントローラ上で動作し、サイズ 888 KiB の制限を厳守するミニマルでフルファーティウェア型の AI 個人アシスタントです。プロジェクトはプレーン C で書かれ、ESP‑IDF と FreeRTOS を活用しており、ESP32‑C3、ESP32‑S3、ESP32‑C6 の任意のボードに簡単にフラッシュできます。

なぜ zclaw なのか？

従来のデバイス内 LLM ソリューションは、数ギガバイトの RAM か外部 GPU が必要です。zclaw は次の方法でそれらの制約を回避します。 * 小型で単一目的の LLM バックエンド（Ollama、OpenAI、Anthropic など）を組み込みます。 * コンパクトなスケジューリングと GPIO API を使用し、シンプルな “cron‑似た” タスクを実装します。 * ESP‑NVS にすべての認証情報と設定を保存し、必要に応じて AES 暗号化を適用します。 * Telegram チャットインターフェイスと軽量な Web リレイ（ブラウザ向け）を提供します。

結果として、850 KiB のフラッシュ領域で オフライン で動作し、自然言語クエリにリアルタイムで応答できるエッジ AI が完成します。

主な特徴

Feature Description
Tiny Footprint 858 KiB のデフォルトビルド。セキュア構成では ≤ 888 KiB
Scheduling タイムゾーンを考慮した日次、周期、ワンショットタスク
GPIO Control ガード付き読み書き、または一括 gpio_read_all()
Persisted State NVS への高速 I/O により再起動時もデータを保持
Custom Tools 独自の C 関数を LLM プラグインとして登録
Secure Mode フラッシュバックエンドの認証情報に AES‑256 暗号化
Chat Channels Telegram ボット + オプションの Web リレイ UI
LLM Backends Anthropic、OpenAI、OpenRouter、Ollama、または任意のカスタムエンドポイント
CLI Scripts Bootstrap、インストール、プロビジョニング、フラッシュ、モニタリング、ベンチマーク

前提条件

  1. ESP‑IDF – 最新 SDK を公式ガイドに従ってインストール。
  2. Git – リポジトリをクローン。
  3. Python 3.8+ – プロビジョニングとテストスクリプト用。
  4. Telegram Bot Token – （オプション、チャット用）または HTTP LLM エンドポイント。
  5. Wi‑Fi 環境情報 – デバイス起動用ネットワーク詳細。

一行で始める

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

ブートストラップスクリプトは次を実行します。 * 最新の zclaw ソースをクローンまたは pull します。 * ビルドを行う非対話型 install.sh を実行します。 * 選択したボードへビルドをフラッシュします。 * Wi‑Fi および LLM 認証情報をプロビジョンします。

すでにローカルクローンがある場合は、./install.sh または ./install.sh -y（ドライラン）を実行してください。

フラッシュとセキュアプロビジョニング

セキュアモードは、ESP‑NVS 暗号化を使用して API キーと Wi‑Fi パスワードを保護します。

# 暗号化を有効にし、簡単なパスフレーズを設定
./scripts/flash-secure.sh

フラッシュ後に ./scripts/provision.sh を実行。スクリプトは次を促します。 * Wi‑Fi SSID / パスワード * LLM プロバイダー名（例: ollama, openai） * プロバイダー エンドポイントおよび API キー * Telegram ボットトークンとチャット ID（オプション）

すべての値はフラッシュにハッシュ化して保存されます。 --flash-mode secure フラグは、将来のアップグレードでも暗号化を保持します。

チャットサービスの起動

プロビジョニング後、デバイスは Wi‑Fi で起動し、チャット接続を待機します。

  • Telegram – ボットは受信メッセージを自動的に転送し、返信を返します。
  • Web Relay – ./scripts/web-relay.sh をホストマシンから実行。ESP32 が接続する短時間だけ生存する HTTPS エンドポイントを開きます。与えられた URL をブラウザで開き、リアルタイムでチャットします。

両方のインターフェイスは LLM 出力をライブでストリームし、ネイティブに近い体験を提供します。

タスクのスケジューリング

zclaw のスケジューラは軽量な cron のように感じられます。

int main() {
    scheduler_register(""");
    // 毎日 3 AM に ping を実行
    scheduler_schedule("3 * * * *", "ping_device");
}

JSON 形式化された cron 構文はタイムゾーンを意識し、登録済みツールやカスタム C 関数を何でもトリガーできます。

GPIO と永続化

GPIO API は安全に設計されています：書き込みはピン範囲に制限でき、gpio_read_all() 呼び出しは連続ビットマップを返します。

永続メモリは NVS で簡易キー・バリュー API を介して公開されます。 

nvs_set("user_pref", 42);
int val = nvs_get("user_pref");

ユーザープロファイル、最後のプロンプト時刻、アプリケーション状態などを保存するために利用してください。

カスタムツールで zclaw を拡張する

zclaw は小さなプラグインシステムを備えています。新しいツールを追加するには: 1. zclaw_tool_t シグネチャに準拠した C 関数を作成。 2. main/config.h を編集してツールを登録。 3. ./scripts/build.sh で再ビルド。

新しいツールはチャットインターフェイスから tool: YourToolName で呼び出せます。

開発ワークフロー

典型的な開発サイクル: 

./scripts/test.sh host          # ホストテストを検証
./scripts/build.sh              # ファームウェアをコンパイル
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --write-template  # ローカル開発プロファイル設定
./scripts/monitor.sh /dev/cu.usbmodem1101

リポジトリには .github/workflows/ に完全な CI パイプラインがあり、コミットごとに自動でビルド、テスト、検証します。

コントリビューション

すべての貢献を歓迎します！ * Fork し、機能やバグ修正ブランチを作成。 * テストがローカルで通ることを確認。 * PR を開き、関連 issue を参照。 * ライセンスは MIT です – LICENSE を確認してください。

セキュリティ欠陥を発見した場合は、メンテナーへ直接メッセージを送るか、GitHub のセキュリティ報告機能を使用してください。

ライセンスとクレジット

zclaw は MIT ライセンスで公開されています。コードはオープンソースコミュニティの共同作業です。ESP‑IDF チーム、FreeRTOS コントリビューター、実機でテストしたすべてのユーザーに感謝します。

詳細は公式ドキュメント https://zclaw.dev か GitHub リポジトリを参照ください。

元の記事: オリジナルを見る

この記事を共有