中枢神経系のアナロジー
ほとんどの人は、AIアシスタントを独立した脳として考えます—処理して応答する単一のエンティティ。clawbotは異なります: 生物学的神経系のように設計されています。あなたの脳(AIモデル)は筋肉を直接制御しません。信号は神経(チャネル)を通過し、脊髄(Gateway)で処理され、運動ニューロン(システムツール)を通じて実行されます。
この分散アーキテクチャが、clawbotがWhatsAppを同時に聞き、Telegram経由で応答し、シェルコマンドを実行し、メモリを更新できる理由です—すべて並行して。従来のモノリシックAIはこれができません。なぜなら、すべての機能が密結合しているからです。 clawbotのモジュラー設計は、各コンポーネントを明確に定義されたプロトコルを通じて通信する独立したサービスとして扱います。
clawbotシステムアーキテクチャ
コンポーネントの詳細:各ピースがどのように機能するか
🌐 Gateway:中央指令
Gatewayはclawbotの心臓部です—決して眠らない永続的なNode.jsプロセスです。なぜ各チャネルでAIを直接実行するのではなく、専用サービスなのか? 3つの重要な理由があります:
- 統一された状態:すべてのチャネルにわたる会話履歴の単一の真実の源
- リソース効率:15以上の別々の接続の代わりに、AI APIへの1つの接続
- 障害の分離:WhatsAppがクラッシュしてもTelegramは動作し続ける—チャネルは交換可能なプラグイン
GatewayはHTTPではなくWebSocketを介して通信します。なぜ? HTTPはクライアントが常に「更新はありますか?」と尋ねる必要があります(ポーリング)。WebSocketは永続的な双方向接続を維持します—Gatewayは準備ができ次第、チャネルにメッセージをプッシュできるため、リアルタイムのストリーミング応答が可能になります。
💬 チャネル:感覚インターフェース
チャネルは、メッセージングプラットフォームプロトコルとGatewayの統一されたメッセージ形式の間を変換する独立したプロセスです。プロトコルアダプターと考えてください—WhatsAppはBaileysを話し、TelegramはBot APIを話しますが、両方とも同一のJSON構造でGatewayにメッセージを提示します。
この抽象化は強力です:新しいメッセージングプラットフォームを追加するには、システム全体を変更するのではなく、1つのチャネルプラグインを書くだけで済みます。各チャネルはサンドボックス化されています—クラッシュしても、Gatewayは他のチャネルに影響を与えることなく自動的に再接続を試みます。
🧠 AIモデルルーター:インテリジェンスバックボーン
clawbotは単一のAIプロバイダーにロックインされません。モデルルーターは動的プロバイダー選択を実装します: 複雑な推論にはClaudeを選択し、クリエイティブタスクにはGPT-4を、プライバシー重視の操作にはローカルOllamaを—すべて同じ会話内で。
これは技術的にどのように機能しますか? 各AIプロバイダーには標準化されたインターフェース(OpenAI Completion APIパターンに従う)があります。ルーターは設定されたすべてのプロバイダーへの接続プールを維持し、設定された設定に基づいてリクエストをルーティングし、プロバイダーが利用できない場合は自動フェイルオーバーを処理します。
高度:カスタムモデルルーティングロジック
~/.clawbot/clawbot.jsonでカスタムルーティングルールを設定できます:
- コーディングタスクをClaudeにルーティング(プログラミングに優れている)
- クリエイティブライティングをGPT-4にルーティング(より想像力豊か)
- 機密データ処理をローカルOllamaにルーティング(外部送信ゼロ)
- プライマリが失敗した場合の自動フォールバックをセカンダリプロバイダーに
💾 永続メモリ:会話状態管理
リクエスト間ですべてを忘れるステートレスなAI APIとは異なり、clawbotは耐久性のある会話履歴を~/.clawbot/conversations/のMarkdownファイルに保存します。各会話は、メッセージ、ツール実行、AI応答の完全なログです。
なぜデータベースではなくMarkdown? 3つの理由:
- 人間が読める:AI会話をgrep、検索、バージョン管理できます
- ポータブル:フォルダをコピーするだけで会話履歴全体を移動
- AIフレンドリー:AIモデルはコンテキスト取得のためにMarkdown形式をネイティブに理解
Gatewayは自動的にコンテキストウィンドウを管理します—会話がモデルのトークン制限を超えると、重要なコンテキストを保持しながら古いメッセージを賢く要約します。これにより、劣化することなく何週間にもわたる会話が可能になります。
⚙️ 実行エンジン:安全なシステムコントロール
ここがclawbotをチャットボットと区別する点です:真のタスク実行。AIがシェルコマンドが必要だと判断すると、実行エンジンは複数の保護層を通じて安全に処理します:
- サンドボックス化:コマンドは制限されたファイルシステムアクセスを持つ制限された環境で実行
- パーミッションゲート:コマンドパターンのユーザー設定可能な許可/拒否リスト
- 確認プロンプト:破壊的操作には明示的なユーザー承認が必要
- 監査ログ:実行されたすべてのコマンドはタイムスタンプ、ユーザー、結果とともにログに記録
- タイムアウト保護:コマンドは設定可能な期間後に自動的に終了
🔌 スキルシステム:拡張可能な機能
スキルはclawbotのプラグインシステムです—AIに新しい機能を教えるSKILL.mdファイルを含むフォルダ。
Markdownファイルはどのように機能を拡張するのか? AIはスキル定義を読み、次のことを学習します:
- スキルが何をするか、いつ使用するか
- どのパラメータを受け入れるか
- それをトリガーするコマンドの例
- 期待される動作とエッジケース
スキルには、シェルスクリプト、Node.jsモジュール、またはAPI統合コードを含めることができます。AIは構造化された関数呼び出しを通じてこれらのツールを呼び出し、結果を受け取り、応答に組み込みます。これがclawbotがスマートホームを制御したり、クラウドインフラを管理したり、独自の内部システムと統合できる方法です—誰でもスキルを書くことができます。
テクノロジースタック:clawbotを支えるもの
ランタイム: Node.js 22+
リアルタイム通信のための優れた非同期I/Oパフォーマンスを持つモダンなJavaScriptランタイム。WebSocket、HTTP/2、ワーカースレッドのネイティブサポートにより、並列タスク実行が可能です。
言語: TypeScript
型安全な開発により、バグのカテゴリ全体を防止します。WebSocketメッセージ、AI応答、設定の強力な型付けにより、堅牢なエラー処理が保証されます。
通信: WebSocketプロトコル
Gatewayとすべてのクライアント間の双方向、永続的な接続。リアルタイムメッセージストリーミング、即座の通知、AI応答のサブ秒レイテンシを実現します。
ストレージ: ファイルベースの状態
会話はMarkdownとして、設定はJSONとして、スキルは構造化されたフォルダとして保存されます。データベースの依存関係なし—よりシンプルなデプロイ、より簡単なバックアップ、grepフレンドリーなデバッグ。
WhatsApp: Baileysライブラリ
リバースエンジニアリングされたWhatsApp Webプロトコル実装。ブラウザが使用するのと同じプロトコルを使用して永続的な接続を維持—非公式APIや電話番号の共有はありません。
Telegram: grammYフレームワーク
TypeScriptサポート付きの公式Telegram Bot APIラッパー。柔軟なデプロイのためのロングポーリングとwebhookサポート、ファイルアップロード、インラインキーボード、完全なbot機能。
AI統合: プロバイダー抽象化
Anthropic Claude、OpenAI GPT-4、Ollamaローカルモデル、Google Geminiをサポートする統一インターフェース。シームレスなプロバイダー切り替えのための異なるAPI形式間の自動変換。
セキュリティ: サンドボックス化された実行
シェルコマンドは設定可能な権限を持つ制限された環境で実行されます。ユーザー定義の信頼境界により、偶発的なシステムダメージや不正な操作を防止します。
メッセージフロー:システムを通じたリクエストの追跡
WhatsApp経由で「2時間後にママに電話するようリマインドして」と送信したときに何が起こるかを追跡しましょう。
{"from": "user", "text": "リマインド...", "channel": "whatsapp"}schedule_reminder(time="+2h", message="ママに電話")を呼び出すこの19ステップの振り付けは2秒未満で発生します。分散アーキテクチャにより、各コンポーネントが独立して動作できます—WhatsAppチャネルはClaudeについて知らず、ClaudeはWhatsAppについて知りませんが、Gatewayのオーケストレーションを通じてシームレスに調整されます。
なぜこのアーキテクチャが重要なのか
ほとんどのAIアシスタントはモノリシックです—すべてのロジックが1つのアプリケーションにあり、特定のプラットフォームに密結合しています。clawbotの分散設計により、従来のアーキテクチャでは不可能な機能が可能になります:
- ホットスワップ可能なコンポーネント:チャネルを再起動せずにAIモデルをアップグレード。Gatewayに触れることなくWhatsAppをTelegramに置き換える。
- 水平スケーリング:異なるマシン上で複数のチャネルインスタンスを実行し、すべてが1つのGatewayに接続。
- フォールトトレランス:1つのチャネルがクラッシュしても、他のチャネルは動作し続けます。Gatewayが再起動しても、チャネルは自動的に再接続します。
- マルチテナンシー:1つのGatewayが分離された会話スペースで複数のユーザーにサービスを提供できます—家族でのデプロイに最適。
- 拡張性:コミュニティメンバーは、コアコードにアクセスすることなく、新しいチャネル、スキル、またはツールを構築できます。
🔐 アーキテクチャによるセキュリティ
分散設計は柔軟性だけでなく、セキュリティ境界でもあります。チャネルは制限された権限を持つ別々のプロセスで実行されます。チャネルが侵害された場合、攻撃者はそのメッセージングプラットフォームのみにアクセスでき、システム全体にはアクセスできません。Gatewayは認証を強制し、実行エンジンはシステムコマンドを実行する前に追加のサンドボックス化を適用します。
技術的決定とトレードオフ
なぜHTTP RESTの代わりにWebSocketなのか?
HTTPはリクエスト-レスポンスです:クライアントが尋ね、サーバーが答えます。AI応答には通常5-15秒かかります。WebSocketがなければ、ポーリング(無駄)またはロングポーリング(複雑)が必要です。WebSocketはストリーミング応答を可能にします—AIは単語を生成するとすぐに送信を開始し、即座の応答性の認識を作り出します。
なぜデータベースの代わりにファイルストレージなのか?
データベースはデプロイの複雑さを追加します—インストール、設定、バックアップ戦略。パーソナルAI(1-10ユーザー)の場合、ファイルはポータブル、検査可能、バージョン管理可能なままで十分なパフォーマンスを提供します。会話履歴をgrepしたり、Dropboxでバックアップしたり、Gitで変更を追跡したりできます。
なぜPython/Go/Rustの代わりにNode.jsなのか?
Node.jsはI/Oバウンドタスク(リアルタイム通信、API呼び出し)に優れています。JavaScriptのasync/awaitモデルはAIワークフロー(リクエストを送信、応答を待つ、結果を処理)に自然にマッピングされます。npmエコシステムは、すべてのメッセージングプラットフォーム向けの成熟したライブラリを提供します。TypeScriptは開発速度を犠牲にすることなく安全性を追加します。
独自のものをデプロイする準備はできましたか?
アーキテクチャを理解することはステップ1です。ステップ2はそれを構築することです。