メインコンテンツまでスキップ

OpenClaw アーキテクチャ設計

· 約14分
tanzhuo

多くの AI アプリケーションはいまだに「チャットによる対話」という表層にとどまっています。ユーザーが質問を入力し、モデルがテキストを返すだけで、ローカルデバイスに実際に触れて具体的なタスクを実行することはできません。OpenClaw（旧称 Clawdbot/Moltbot/Molty）はこの限界を打ち破りました。大規模言語モデルの「推論能力」とローカル実行環境を徹底的に分離することで、AI を「対話アシスタント」から「自律的に行動できるエージェント」へと進化させたのです。本記事では、Peter Steinberger 氏が開発した TypeScript/Node.js 製のこのオープンソースツールを、全体アーキテクチャ・実行ロジック・設計上のハイライトという 3 つの観点から解説します。

全体アーキテクチャ設計：ハブ・アンド・スポーク+レイヤード分離による「OS レベル」のフレームワーク​

OpenClaw の中核となる設計哲学は「AI をプロンプトエンジニアリングの問題ではなく、インフラの問題として捉える」ことです。モデルは推論だけを担当し、状態管理・実行制御・セキュリティ保障・マルチチャネル連携はシステム側が引き受けます。アーキテクチャはハブ・アンド・スポーク（Hub-and-Spoke）とレイヤード分離を組み合わせた方式を採用しており、コアロジックの集中管理と各コンポーネントの柔軟性を両立させています。

ハブ・アンド・スポーク：Gateway が唯一のコントロールプレーン​

OpenClaw は **Gateway（ゲートウェイ）**を中心に据え、すべてのコンポーネント（クライアント、チャネルアダプター、Agent 実行器など）が Gateway を軸として放射状に接続されます。Gateway はシステムの「交通ハブ」であり、デフォルトではローカルループバックアドレス（127.0.0.1:18789）にバインドされ、ローカルデバイスからのアクセスのみを許可することで、データプライバシーを根本から保護します。その主な責務は次のとおりです。

  • 統一認証とセッション分離：ユーザーやデバイスごとにセッションを独立して管理し、データの相互汚染を防ぎます。
  • Lane Queue（レーン式シリアルキュー）：各セッションはデフォルトでタスクを直列実行し、マルチタスクの並行実行による状態の競合やログの混在を根本的に解消します（手動で並列モードを有効化することも可能です）。
  • メッセージルーティングとスケジューリング：標準化されたメッセージを対応する Agent へ正確に転送します。
  • ストリーミング対話のサポート：モデルの出力と「入力中」ステータスをリアルタイムに配信し、自然な会話体験を再現します。

レイヤードアーキテクチャ：外から内への能力分解​

OpenClaw のレイヤードアーキテクチャは、ユーザーとの対話からインフラまで段階的に構成されており、各レイヤーの責務が明確で、それぞれ独立して拡張できます。

1）クライアント層：マルチエントリーの対話インターフェース

ユーザーは専用アプリに依存することなく、次の方法で OpenClaw と対話できます。

  • コマンドラインツール（CLI）：技術系ユーザーの素早いデバッグに最適
  • Web UI：ビジュアルな操作パネル
  • macOS メニューバーアプリ、iOS/Android Node：モバイルデバイス向けの軽量エントリー
  • サードパーティのチャットプラットフォーム：WhatsApp、Telegram、Discord など 20 以上の一般的なアプリに対応し、ユーザーは使い慣れたツールから直接指示を出せます。

2）接続調整層：Gateway の「中枢機能」

前述のとおり、Gateway は接続調整の中核であり、異種の入力をシステムが認識できる形式に変換し、セッションのライフサイクルを管理します。

3）チャネル抽象層：プラットフォームプロトコルの壁を突破

チャットプラットフォームごとにメッセージプロトコルは大きく異なります（WhatsApp の Baileys プロトコル、Telegram の MTProto プロトコルなど）。**Channel Adapters（チャネルアダプター）**は「通訳者」の役割を担い、各プラットフォームのメッセージ（テキスト、画像、音声など）を OpenClaw 内部の標準形式に統一変換し、添付ファイルのダウンロード・キャッシュ・アクセス制御（「指定した連絡先からの指示のみ許可」など）を処理します。

4）コアロジック層：Agent の「思考と実行エンジン」

コアロジック層は Agent Runner と Memory System で構成され、AI エージェントが「仕事をこなす」ための鍵となります。

  • Agent Runner：各チャネルやグループを独立した Agent インスタンスにマッピングでき（マルチ Agent 連携をサポート）、RPC で Pi Agent Runtime を呼び出して「指示の受信→モデルの呼び出し→ツールの実行→結果の生成」という完全なループを実行します。
  • Memory System：セッション履歴、ユーザーの長期記憶、ツールの能力記述などのコンテキスト管理を担当し、モデルに意思決定の根拠を提供します。

5）インフラ層：ローカル実行の「土台」

インフラ層はシステム稼働の基礎能力を提供します。

  • ローカル永続化：すべてのデータを Markdown と .jsonl 形式で保存（クラウドデータベースへの依存を回避）
  • WebSocket ストリーミング通信：クライアントと Gateway のリアルタイム接続を保証
  • サンドボックス実行：ツールのシステム権限を制限し、悪意ある操作を防止
  • 定期タスク（Cron）と Webhook：能動的なタスク起動をサポート（毎朝のレポート配信など）

コアコンポーネントの関係：各モジュールはどう連携するのか？​

アーキテクチャをより明確に理解するために、コアコンポーネントの関係を次のように整理できます。

  1. Gateway は「スケジューリングセンター」として、クライアントやチャネルアダプターからのメッセージを受け取り、対応する Agent に振り分けます。
  2. Agent Runner は Gateway の指示に基づき、モデルを呼び出して意思決定を生成し、ツール（ファイルの読み書き、ブラウザ操作など）を実行します。
  3. Channel Adapters はサードパーティプラットフォームのメッセージを「翻訳」し、ユーザーがツールを切り替えることなく対話できるようにします。
  4. Skills（スキルプラグイン）：~/.openclaw/workspace/skills ディレクトリに格納され、Agent が自律的に発見・インストール・呼び出しできます（ClawHub レジストリでのスキル共有もサポート）。
  5. Nodes（デバイス側実行器）：macOS や iOS などのデバイス上で動作し、WebSocket 経由でローカルハードウェアの能力（音声入力、カメラ、画面録画など）を公開します。
  6. Canvas：独立ポート（18793）で提供されるビジュアルワークスペースで、Agent が HTML/A2UI インターフェース（タスクの進捗バー、データダッシュボードなど）を生成できます。

実行ロジック：Agent Loop と能動的スケジューリングによる「仕事をこなす」仕組み​

OpenClaw の中核的な価値は「AI に本当に仕事をさせる」ことにあり、これは循環可能な Agent Loop（エージェントループ）と能動的スケジューリング機構によって支えられています。前者はユーザーが起動するタスクを処理し、後者は無人での自律稼働を実現します。

典型的なメッセージ処理フロー：入力から出力までの全経路​

ユーザーの指示（「デスクトップにある直近 3 日間のファイルを整理してリストを作成して」など）は、次のような流れで処理されます。

1）メッセージの受信と標準化

ユーザーが Telegram で指示を送信→Channel Adapter が Telegram のメッセージをシステム標準形式（テキスト内容、送信者情報、コンテキストを含む）に変換→標準化されたメッセージを Gateway の対応する Session Lane Queue に投入（直列実行で競合を回避）。

2）ルーティングと Agent の起動

Gateway は設定（「main セッションはデフォルト Agent にバインド」「main 以外のセッションは @ で起動」など）に基づき、メッセージを対象の Agent にルーティングします。たとえばユーザーが家族グループで OpenClaw をメンションすると、Gateway は「家族アシスタント」Agent を起動します。

3）コンテキストの組み立て：Agent に重要な情報を「覚えさせる」

Memory System は次の内容を自動的に組み立て、モデルへの入力コンテキストとします。

  • 現在のセッションの履歴メッセージ（Agent の「記憶喪失」を防止）
  • ユーザーの長期記憶（「ユーザーは Markdown でのファイル整理を好む」「デスクトップのパスは ~/Desktop」など）
  • システムプロンプト：AGENTS.md（Agent の行動基準、「ローカルツールを優先的に使用」など）、SOUL.md（性格設定、「簡潔で効率的」など）、TOOLS.md（ツールの能力記述、「file.read はローカルファイルを読み取れる」など）
  • インストール済みの Skills（「ファイル分類スキル」など）

コンテキストが長すぎる場合、システムが自動的に圧縮・要約し、モデルへの入力がコンテキストウィンドウに収まるようにします。

4）モデルの呼び出しと意思決定の生成

Agent Runner は設定された LLM（Claude、GPT、あるいは Llama 3 のようなローカルモデルに対応）を呼び出し、モデルはコンテキストに基づいて「ツールの実行が必要か？」を判断します。

  • ツールが不要な場合：自然言語の返答を直接生成します（「整理が完了しました。リストはデスクトップに保存済みです」など）。
  • ツールが必要な場合：ツール呼び出しの指示を生成します（{"name": "file.list", "parameters": {"path": "~/Desktop", "days": 3}} など）。

5）ツールの実行：タスク完了まで複数回のループ

ツールの実行にはループ機構が採用されています。

  1. Agent Runner はサンドボックス内でツールを実行します（main セッションはデフォルトでホスト権限を持ち、main 以外のセッションは Docker サンドボックスによる隔離を強制できます）。
  2. ツールが実行結果を返します（「5 個のファイルが見つかりました：report.pdf、photo.jpg...」など）。
  3. 結果がコンテキストに書き戻され、Agent Runner が再度モデルを呼び出し、さらなる操作が必要かを判断します（「リストを Markdown に変換すべきか？」など）。
  4. モデルがタスク完了と判断するまで、上記のステップを繰り返します。

6）出力と永続化

最終結果は Gateway を通じて元のチャネル（Telegram など）にストリーミング配信されます。同時に、すべての対話記録、ツール実行ログ、記憶の更新はローカルの .jsonl と Markdown ファイルに書き込まれ、データの追跡可能性とクラウド非依存が保証されます。

能動的稼働機構：AI の「自律性」の源泉​

従来のチャットボットはユーザーによる起動が必要ですが、OpenClaw は能動的な稼働をサポートしており、ユーザーの指示なしにタスクを完了できます。その実現方法は次の 3 つです。

1）定期タスク（Heartbeat Scheduler/Cron）

「毎朝 8 時に前日のメールを整理して要約を作成」「毎週日曜にデスクトップのファイルを外付けドライブにバックアップ」といった周期的なタスクを設定できます。Gateway は時間どおりに Agent を起こしてタスクを実行させ、結果は指定チャネル（ユーザーの WhatsApp など）に自動送信されます。

2）外部イベントトリガー（Webhook/Pub/Sub）

OpenClaw は Webhook 経由で外部イベントを受信できます。Gmail の新着メール、GitHub Issue の作成、スマートホームデバイスのトリガーなどです。たとえば重要な仕事のメールを受信した際に、OpenClaw が自動的に要点を抽出してユーザーに通知できます。

3）マルチ Agent 連携

Agent は組み込みツール（すべてのセッションを一覧する sessions_list、他の Agent にメッセージを送る sessions_send など）を通じて連携できます。たとえば「スケジュール管理 Agent」がユーザーの明日の会議を発見し、「ファイル整理 Agent」に会議資料の事前準備を通知する、といった具合です。

起動と稼働：数ステップでデプロイ完了​

OpenClaw のデプロイは非常に軽量で、一般ユーザーでもすぐに使い始められます。

# 最新バージョンをグローバルインストール
npm install -g openclaw@latest

# 初期化：チャットチャネル、LLM モデル、ワークスペースパスの設定をガイド
openclaw onboard

# 常駐稼働：Gateway をシステムデーモンとして登録し、24/7 稼働を実現
openclaw onboard --install-daemon

完了後は、CLI、Web UI、またはチャットアプリから Gateway に接続すれば利用開始できます。

主要な設計ハイライトとセキュリティ機構：ローカルファーストのプライバシー保護​

OpenClaw の設計は「ユーザーのコントロール権」と「プライバシーの安全性」を軸に展開されています。以下がその主なハイライトです。

ローカルファースト：データは常にあなたの手の中に​

すべてのデータ（セッション履歴、記憶、ツール実行ログ）はローカルデバイスに保存され、Gateway はデフォルトで 127.0.0.1（ローカルループバックアドレス）のみをリッスンし、クラウドへは一切データを送信しません。ネットワークが切断されても、OpenClaw はローカルタスク（ファイル操作、ローカルモデルの呼び出しなど）を正常に実行できます。

セキュリティ隔離：多層防御でリスクを回避​

OpenClaw は多層の仕組みでシステムの安全性を保証します。

  • DM ペアリング承認：サードパーティチャットプラットフォームからの DM による指示はユーザーの手動承認が必要です（Telegram ユーザーが /pair を送信すると OpenClaw が確認コードを送り、ユーザーが認証して初めて対話可能になります）。
  • サンドボックス実行：main 以外のセッションのツール実行はデフォルトで Docker サンドボックス内で行われ、ホストシステムへのアクセスが制限されます。
  • ツールブラックリスト：Agent による危険なツール（システムコマンドを実行する system.exec など）の呼び出しを禁止する設定が可能です。
  • 明示的なコントロール：/think high（モデルの思考の深さを引き上げる）、/verbose on（ツール実行の詳細を表示する）などのコマンドで Agent の挙動を微調整できます。

拡張性：プラグインアーキテクチャによるカスタマイズ​

OpenClaw のすべてのコアコンポーネントはホットスワップに対応しています。

  • チャネル拡張：新しい Channel Adapter（WeChat、Signal など）を自作できます。
  • モデル拡張：任意の LLM を接続できます（標準インターフェースを実装するだけです）。
  • スキル拡張：ユーザーはカスタム Skills（「Obsidian ノートの自動同期」「PPT アウトラインの生成」など）を作成でき、Agent が Skill の契約ファイルを自律的に読み取って呼び出します。
  • メモリ拡張：Memory System をベクトルデータベース（Pinecone など）に置き換え、長期記憶の検索効率を高められます。

記憶システム：4 層構造で Agent が「使うほど賢くなる」​

OpenClaw の記憶システムは 4 層に分かれており、Agent が履歴情報を効率的に活用できるようになっています。

  1. SOUL 層：Agent の性格と価値観（「ユーザーのプライバシー保護を最優先」「簡潔に回答する」など）
  2. TOOLS 層：ツールの能力記述と使用方法
  3. USER ベクトル記憶：ユーザーの長期的な好み（「紅茶よりコーヒーが好き」「よく使うファイルパス」など）。ベクトルストレージにより高速検索を実現
  4. Session 短期記憶：現在のセッションの履歴メッセージ。自動圧縮により冗長性を回避

システムは定期的に記憶の「圧縮（compaction）」を行い、重要な情報を残して重複を削除することで、Agent の「記憶」をより効率的にします。

まとめ​

OpenClaw は「OS レベル」のアーキテクチャによって、「AI はどうすれば本当に仕事をこなせるのか」という問いに答えました。Gateway が唯一のコントロールプレーンとして統一的にスケジューリングを行い、レイヤード設計によりチャネル・モデル・スキルをそれぞれ独立して置き換えられます。Agent Loop の複数回にわたるツールループと、定期タスクや Webhook といった能動的な仕組みの組み合わせにより、AI は指示に応答するだけでなく無人で稼働することもできます。そしてローカルファーストのストレージ戦略、サンドボックス隔離、ペアリング承認は、能力と安全性の間に明確な境界線を引いています。大規模言語モデルを実際のワークフローに組み込みたい人にとって、この設計には参考になる点が数多くあるはずです。

COMMENTS