はじめに
OpenClawは、自分のデバイス上で動く「パーソナルAIアシスタント」を実現するOSSプロジェクトです。WhatsApp、Telegram、Slack、Discord、iMessage、Microsoft Teamsなど、日常的に使うメッセージングプラットフォームをすべて1つのAIが横断的に対応します。
GitHub上で30,000以上のスターを獲得し、2026年2月時点でも活発に開発が続いています。
この記事では、実際にリポジトリをcloneしてソースコードを読み込み、OpenClawがどのような設計思想でこの仕組みを実現しているのかを技術的に解説します。
対象読者
- AIエージェントやLLMアプリケーションの設計に興味がある方
- マルチプラットフォーム対応のメッセージングシステムを設計したい方
- OSSの大規模TypeScriptプロジェクトのアーキテクチャを学びたい方
目次
全体アーキテクチャの概観
OpenClawは大きく分けて5つのレイヤーで構成されています。この記事では各レイヤーを順番に解説していきます。
それぞれのレイヤーが疎結合に設計されており、チャネルの追加やLLMプロバイダーの切り替えが容易になっています。
Layer 1: Input Sources - マルチチャネルシステム
最上位レイヤーは、ユーザーのメッセージが入ってくる入り口です。OpenClawの大きな特徴は、38以上のメッセージングプラットフォームを統一的に扱うプラグインシステムにあります。
チャネルプラグインアーキテクチャ
各チャネルは extensions/ ディレクトリ配下に独立したnpmパッケージとして実装されています。
A directory tree diagram showing the extension structure:
extensions/
├── whatsapp/
│ ├── package.json
│ ├── index.ts (plugin entry)
│ └── src/
│ ├── channel.ts (ChannelPlugin impl)
│ └── runtime.ts
├── telegram/
├── discord/
├── slack/
├── signal/
├── matrix/
├── bluebubbles/ (iMessage)
├── googlechat/
├── msteams/
├── irc/
├── line/
├── nostr/
└── ... (38+ channels)
Style: file tree with folder icons, syntax-highlighted, dark background
ChannelPlugin インターフェース
すべてのチャネルは共通の ChannelPlugin インターフェースを実装します。このインターフェースは複数のアダプターで構成されています。
// ChannelPlugin<ResolvedAccount> の主要アダプター
type ChannelPlugin = {
id: string // "whatsapp", "telegram" など
meta: ChannelMeta // 表示名、アイコンなど
// 設定管理：アカウント一覧、認証情報の解決
config: ChannelConfigAdapter
// 送信制御：テキスト分割、メディア送信、投票
outbound: ChannelOutboundAdapter
// セキュリティ：DMポリシー、許可リスト
security: ChannelSecurityAdapter
// グループ：メンション要否、ツールポリシー
groups: ChannelGroupAdapter
// ペアリング：デバイス認証フロー
pairing: ChannelPairingAdapter
// ケイパビリティ宣言
capabilities: ChannelCapabilities
}
この設計により、各チャネルの差異（メッセージ長制限、スレッド対応の有無、メディアの扱いなど）を吸収しつつ、Gateway側は統一的にメッセージを処理できます。
各チャネルの接続方式
主要チャネルがどのように外部プラットフォームと接続しているかを整理します。
| チャネル | 接続方式 | 利用ライブラリ |
|---|---|---|
| QRコードによるWeb認証 | @whiskeysockets/baileys | |
| Telegram | Bot Token + Long Polling | grammy |
| Slack | Socket Mode (WebSocket) | @slack/bolt |
| Discord | Bot Token + Gateway Events | discord.js |
| Signal | signal-cli (REST wrapper) | signal-cli HTTP API |
| iMessage | BlueBubbles macOSアプリ経由 | REST API + Webhook |
| Matrix | Homeserver + Access Token | matrix-js-sdk |
| Google Chat | Service Account + Webhook | Google Chat API |
| Teams | Bot Framework | Microsoft Bot Framework |
メッセージの正規化
各チャネルから受信したメッセージは、統一的な MsgContext 型に正規化されます。
type MsgContext = {
Channel: string // "whatsapp", "telegram" など
ChatType: 'direct' | 'group' | 'channel'
From: string // 送信者/グループID
To: string // 受信者ID
SenderId: string // グループ内の実際の送信者
SenderName?: string
Text: string
MediaUrl?: string
ReplyToId?: string
MessageId: string
}
チャネルごとにIDの形式は異なります（WhatsAppはE.164電話番号、TelegramはチャットID、Discordはユーザー/チャネルID）が、この正規化レイヤーを通すことで、上位のエージェントロジックはチャネルの差異を意識する必要がありません。
DMペアリングとセキュリティ
OpenClawでは、DMのセキュリティにペアリング方式を採用しています。
デフォルトではすべてのDMにペアリングが必要で、未承認のメッセージは処理されません。これはLLMへのプロンプトインジェクション攻撃に対する防御策でもあります。
Layer 2: WebSocket Gateway - 中央コントロールプレーン
Layer 1のチャネルから届いたメッセージは、すべてこのGatewayに集約されます。OpenClawの心臓部です。
Gateway Control Plane
ローカルで動作するWebSocket Gatewayが中核となり、すべてのクライアント（CLI、WebChat UI、macOSアプリ、iOS/Androidノード）を束ねます。
// Gateway はローカルの ws://127.0.0.1:18789 でリッスンする
// 接続フロー：challenge-nonce → handshake → 認証完了 → メッセージルーティング
Gatewayは以下の役割を担います。
- セッションの管理とルーティング
- チャネル接続の制御
- ツール実行の管理
- イベント配信
- 設定の永続化
接続認証の流れ
WebSocket接続には、公開鍵ベースのデバイス認証が採用されています。以下のシーケンス図で全体像を示します。
各ステップの解説
Step 1: チャレンジノンス
クライアントがWebSocket接続を確立した直後に、Gatewayは connect.challenge イベントを送信します。nonce は randomUUID() で生成されるワンタイム値です。
const connectNonce = randomUUID()
send({
type: 'event',
event: 'connect.challenge',
payload: { nonce: connectNonce, ts: Date.now() },
})
Source: src/gateway/server/ws-connection.ts
このnonceはリプレイ攻撃を防止するために使われます。クライアントはこのnonceを含むペイロードに署名することで、「今この瞬間に接続している」ことを証明します。
Step 2: connect RPC
クライアントは署名済みのデバイス情報を含む connect RPCを送信します。最初のメッセージは必ずこの connect でなければならず、他のメソッドを送ると即座に切断されます。
ここで重要なのが scopes フィールドです。デフォルトでは空配列（＝権限なし）であり、デバイスがペアリング時に明示的に承認されたスコープのみが付与されます。
// 署名対象のペイロード構築
// 各フィールドを「|」で結合した文字列に対してEd25519署名を行う
const buildDeviceAuthPayload = (params: DeviceAuthPayloadParams): string => {
return [
params.version,
params.deviceId,
params.clientId,
params.clientMode,
params.role,
JSON.stringify(params.scopes ?? []),
String(params.signedAt),
params.token ?? '',
params.nonce ?? '',
].join('|')
}
// Ed25519秘密鍵で署名し、Base64エンコードして返す
const signDeviceAuth = (payload: string, privateKey: Uint8Array): string => {
const signature = ed25519.sign(new TextEncoder().encode(payload), privateKey)
return Base64.encode(signature)
}
Source: src/gateway/device-auth.ts
Step 3: 6段階の検証
Gatewayは受信した connect パラメータを以下の順序で検証します。
- プロトコルバージョン -
minProtocolとmaxProtocolがGatewayのPROTOCOL_VERSIONと互換性があるか - ロール -
"operator"または"node"のみ許可。不正値は即切断 - オリジン検査 - ブラウザクライアント（WebChat、Control UI）の場合、
Originヘッダーがホストと一致するか - デバイス認証 - 公開鍵からdeviceIdを導出して一致を確認し、タイムスタンプの時刻差（10分以内）とnonceの一致をチェックした後、Ed25519署名を検証
- トークン認証 - 共有シークレットまたはデバイストークンで認証。失敗にはレートリミットが適用される
- ペアリング確認 - デバイスがペアリング済みか、ロールとスコープが承認済みかを確認。ローカル接続（loopback）は自動承認される
Step 4: hello-ok レスポンス
すべての検証に通過すると、Gatewayは hello-ok レスポンスを返します。このレスポンスには、認証されたロールとスコープ、利用可能なRPCメソッド一覧、現在のシステムスナップショットが含まれます。
// レスポンスに含まれる主要フィールド
{
type: "hello-ok",
protocol: PROTOCOL_VERSION,
features: {
methods: gatewayMethods, // 利用可能なRPCメソッド一覧
events: events, // 購読可能なイベント一覧
},
auth: {
deviceToken: token, // 次回接続用のデバイストークン
role: "operator", // 付与されたロール
scopes: [], // 付与されたスコープ（default-deny）
},
snapshot: { presence, health, config }
}
deviceToken は次回接続時に使い回せるトークンで、毎回の公開鍵認証をスキップできます。ただし、ロールやスコープの変更時には再ペアリングが必要です。
認証失敗時の挙動
認証に失敗した場合、Gatewayは具体的なエラーコードを返して即座にWebSocketを閉じます。
| 失敗理由 | エラーコード | 対応 |
|---|---|---|
| プロトコル不一致 | INVALID_REQUEST | クライアント更新が必要 |
| 不正なロール | INVALID_REQUEST | 即切断 |
| デバイスID不一致 | INVALID_REQUEST | 鍵ペア再生成が必要 |
| 署名期限切れ（10分超過） | INVALID_REQUEST | 時刻同期を確認 |
| nonce不一致 | INVALID_REQUEST | リプレイ攻撃の疑い |
| 署名検証失敗 | INVALID_REQUEST | 秘密鍵の不一致 |
| トークン/パスワード不一致 | INVALID_REQUEST | レートリミット加算 |
| 未ペアリング | NOT_PAIRED | 手動承認が必要 |
| ハンドシェイクタイムアウト | - | 即切断（応答なし） |
ハンドシェイクにはタイムアウトが設定されており、一定時間内に connect RPCが届かない場合も切断されます。
RPC メソッド群
Gatewayは多数のRPCメソッドを提供します。
agent- エージェントの呼び出しchat- チャットメッセージの処理sessions- セッション管理channels- チャネルステータスの取得nodes- リモートノードの制御cron- スケジュールジョブの操作browser- ブラウザ自動化
これらはすべてWebSocketフレーム上のRequest/Response形式で通信され、冪等性を保証するためのデデュプリケーションキャッシュが実装されています。
Layer 3: Agent Runtime - エージェント実行エンジン
Gatewayがメッセージをルーティングした先がこのレイヤーです。ユーザーの意図を解釈し、ツールを使い、応答を生成するエージェントの本体にあたります。
エージェントループの全体像
ユーザーからのメッセージが処理される流れを追います。
二段構成のランタイム
エージェントランタイムは外部ループと内部ループの二段構成になっています。
外部ループ（runEmbeddedPiAgent）
外部ループは以下を担当します。
- 認証プロファイルの管理とフォールオーバー
- コンテキストウィンドウのオーバーフロー検出
- 自動コンパクション（会話履歴の圧縮）
- 使用量の累積追跡
- リトライロジック
内部ループ（runEmbeddedAttempt）
内部ループは実際のLLM呼び出しを行います。
@mariozechner/pi-agent-coreによるセッション管理- ツールのセットアップと登録
- ストリーミングレスポンスの処理
- アボートシグナルとタイムアウトの管理
この二段構成により、LLMのAPI失敗やコンテキストオーバーフローが発生しても、上位でリカバリーできる設計になっています。
ツールシステム
OpenClawには50以上のツールが組み込まれています。
ツールの分類
read,write,edit- ファイル操作exec,bash- コマンド実行browser- Playwright によるブラウザ自動化message- チャネルへのメッセージ送信discord-actions,slack-actions- チャネル固有API操作cron- スケジュール実行canvas- A2UI レンダリングweb-search- Web検索
ツールポリシーによる制御
ツールの利用はきめ細かいポリシーで制御されます。
// ツールポリシーの適用階層（上が優先）
// 1. グループ固有のポリシー
// 2. エージェント固有のポリシー
// 3. グローバルポリシー
// 例：Slackの特定チャネルではブラウザツールを禁止
{
channels: {
slack: {
channels: {
"C0123ABC": {
tools: "allowlist",
toolsAllowFrom: ["U_OWNER_ID"]
}
}
}
}
}
Source: src/agents/pi-tools.policy.ts
ツールはデフォルトで無効（default-deny）であり、明示的に許可されたスコープ内でのみ実行できます。
スキルシステム
スキルは、エージェントの機能を拡張する自己完結型のモジュールです。各スキルは SKILL.md というフロントマター付きMarkdownで定義されます。
---
name: github
description: Interact with GitHub repositories
metadata:
openclaw:
emoji: "\U0001F4BB"
requires:
anyBins: ['gh']
env: ['GITHUB_TOKEN']
---
スキルの読み込み優先順位
スキルは複数のソースから読み込まれ、後のものが前のものを上書きします。
53個のバンドルスキルには、GitHub操作、Apple Notes連携、Discord操作、PDF処理、コード補完など多岐にわたるものが含まれています。
スキルのライフサイクル
- 発見 - 各ソースディレクトリからスキルを検出
- フィルタリング - プラットフォーム要件（macOS限定など）や設定による有効/無効の判定
- プロンプト注入 - 有効なスキルの説明文をLLMのシステムプロンプトに挿入
- 実行 - LLMがスキルを呼び出すと、SDK経由でスクリプトが実行される
- 結果返却 - stdout/stderrがキャプチャされ、ツール結果としてLLMに返る
Layer 4: LLM Providers - モデル抽象化レイヤー
Agent Runtimeがプロンプトを組み立てた後、実際のLLM呼び出しを行うのがこのレイヤーです。複数のプロバイダーを透過的に切り替える仕組みが実装されています。
プロバイダーの抽象化
OpenClawは以下のLLMプロバイダーに対応しています。
- Anthropic - Claude（推奨、プライマリ）
- OpenAI - GPTモデル
- Google - Gemini
- Ollama - ローカルモデル
- GitHub Copilot
- AWS Bedrock
// プロバイダー解決の流れ
// 1. 認証プロファイルの順序を解決
const profileOrder = resolveAuthProfileOrder({
cfg: config,
store: authStore,
provider,
preferredProfile: preferredProfileId,
})
// 2. モデルの解決
const { model, authStorage, modelRegistry } = resolveModel(provider, modelId, agentDir, config)
// 3. プロバイダー固有のストリーム関数を設定
// Ollama（ローカルモデル）の場合はカスタムストリーム
if (model.api === 'ollama') {
session.agent.streamFn = createOllamaStreamFn(ollamaBaseUrl)
} else {
session.agent.streamFn = streamSimple // SDK標準
}
Source: src/agents/embedded-agent.ts
認証とフォールオーバー
認証情報は環境変数、macOSのKeychain、AWSの認証情報、設定ファイルなど複数のソースから解決されます。
あるプロバイダーがレートリミットに引っかかった場合、自動的に次の認証プロファイルにフォールオーバーする仕組みになっています。失敗したプロファイルはクールダウン期間が設定され、一時的にスキップされます。
Layer 5: Output & Storage - 出力と永続化
LLMの応答が生成された後、それをユーザーに届け、状態を永続化するのがこのレイヤーです。セッション管理、メモリ、音声合成、Canvas/A2UIなど多くの出力系サブシステムが含まれます。
セッション管理
OpenClawのセッションは以下のように分類されます。
- main - デフォルトの1対1会話
- group - グループチャット（グループごとに分離）
- thread - スレッド会話（プラットフォームがサポートする場合）
セッションキーは agentId + accountId + peerId + channel の組み合わせで一意に決定されます。
会話履歴はSQLiteデータベースに永続化され、ブランチ（会話の分岐）もサポートされています。
メモリ/RAGシステム
OpenClawはベクトル検索ベースの長期記憶システムを備えています。
// メモリエントリの構造
type MemoryEntry = {
id: string
text: string
vector: number[] // 埋め込みベクトル
importance: number // 重要度スコア
category: MemoryCategory // facts, preferences, context など
createdAt: number
}
- 埋め込みにはOpenAIのtext-embedding-3モデルを使用
- ベクトルストレージにはLanceDB（SQLite-vec）を採用
- エージェント実行前にセマンティック検索が行われ、関連する記憶がコンテキストに注入されます
Cron/Webhookシステム
スケジュール実行
Cronジョブは、定期的にエージェントを起動して処理を実行する仕組みです。
// Cronジョブの定義例
{
payload: {
kind: "agentTurn",
prompt: "今日のニュースをまとめて"
},
schedule: {
cron: "0 9 * * MON-FRI", // 平日9時
timezone: "Asia/Tokyo"
},
delivery: {
channel: "telegram",
to: "123456789"
}
}
サブエージェントの生成、結果のベストエフォート配信、セッションの自動クリーンアップなどが実装されています。
Webhook
HTTPエンドポイントとして以下が提供されます。
POST /hooks/agent- エージェント呼び出しPOST /hooks/wake- テキスト入力によるウェイクPOST /hooks/schedule- Cronジョブの作成/更新POST /slack,POST /openai- 各プラットフォーム固有のWebhook
Webhookにはトークン認証とレートリミットが適用されます。
Canvas / A2UI
A2UI（Artifact to UI）は、エージェントがリアルタイムにUIをレンダリングするためのプロトコルです。
// Canvas ツールのアクション
const CANVAS_ACTIONS = [
'present', // Canvasを表示
'hide', // Canvasを非表示
'navigate', // URLを変更
'eval', // JavaScriptを実行
'snapshot', // スクリーンショットを取得
'a2ui_push', // A2UIの更新をプッシュ
'a2ui_reset', // A2UIの状態をリセット
]
Source: src/agents/tools/canvas.ts
A2UIのコンポーネントはReactで実装され、UMD形式にバンドルされてサンドボックス内のiframeで実行されます。
ネイティブアプリによる出力
OpenClawはCLIだけでなく、ネイティブアプリも出力先として提供しています。
- macOS - SwiftUI製メニューバーアプリ
- iOS - SwiftUI製コンパニオンアプリ
- Android - Kotlin製アプリ
いずれもGatewayへWebSocket接続し、Voice Wake（音声起動）やTalk Mode（音声対話）、Canvasレンダリングに対応しています。
横断的な仕組み
5つのレイヤーを横断する仕組みについても触れておきます。
設定システム
OpenClawの設定は ~/.openclaw/openclaw.json5 で管理されます。JSON5形式が採用されており、コメントを記述できます。
{
// Gateway設定
gateway: {
port: 18789,
},
// チャネル設定（Layer 1）
channels: {
telegram: {
enabled: true,
accounts: {
default: { token: 'BOT_TOKEN' },
},
},
},
// エージェント設定（Layer 3-4）
agents: {
default: {
model: 'anthropic/claude-opus-4-6',
},
},
// マルチエージェントルーティング（Layer 2）
bindings: [
{ agentId: 'default', match: { channel: 'telegram' } },
{ agentId: 'work-agent', match: { channel: 'slack' } },
],
}
設定スキーマはZodで定義されており、100以上の型が存在します。1つの設定ファイルで全レイヤーを横断的に制御できる点が特徴です。
ビルドシステム
OpenClawはpnpm workspacesによるモノレポ構成です。
A monorepo structure diagram:
openclaw/ (root)
├── src/ → Core TypeScript (tsdown でバンドル)
├── ui/ → Web UI (Lit + Vite)
├── apps/
│ ├── macos/ → Swift + SwiftUI
│ ├── ios/ → Swift + SwiftUI
│ └── android/ → Kotlin + Gradle
├── packages/
│ ├── clawdbot/ → 後方互換シム
│ └── moltbot/ → 後方互換シム
├── extensions/ → 38+ チャネルプラグイン (各npm pkg)
└── skills/ → 53+ バンドルスキル
Style: tree diagram with package icons, color-coded by type, dark background
バージョニングにはカレンダーバージョニング（v2026.2.15のような日付ベース）が採用されています。
デフォルト拒否のセキュリティモデル
すべてのレイヤーを貫くセキュリティ思想が「デフォルト拒否」です。
- Layer 1 - DMはペアリング必須、グループは許可リスト制
- Layer 2 - Gateway接続は公開鍵認証、認証失敗にはレートリミット
- Layer 3 - ツールスコープはデフォルトで空、チャネル/グループ単位のポリシー
- Layer 4 - 認証プロファイルの分離、クールダウンによる保護
- Layer 5 - セッション分離、Webhookのトークン認証
LLMを外部メッセージングに接続するという性質上、プロンプトインジェクション攻撃への耐性が求められるため、この徹底した設計は理にかなっています。
プラグインによる拡張性
38以上のチャネルが存在しますが、コアのGatewayコードはチャネルの詳細を知りません。すべて ChannelPlugin インターフェースを通じてやり取りされるため、新しいチャネルの追加はGatewayの変更なしに行えます。
// プラグインの最小実装
const myPlugin = {
id: 'my-channel',
name: 'My Channel',
register(api) {
api.registerChannel({ plugin: myChannelPlugin })
},
}
export default myPlugin
まとめ
OpenClawのアーキテクチャを5つのレイヤーに沿って調査した結果、以下のことが分かりました。
- Layer 1（Input Sources） - チャネルプラグインシステムにより38以上のメッセージングプラットフォームを統一的に扱い、
MsgContextへの正規化で差異を吸収している - Layer 2（Gateway） - WebSocket Gatewayが中央のコントロールプレーンとして機能し、すべてのクライアント・チャネル・エージェントを統合している
- Layer 3（Agent Runtime） - 二段構成のランタイムでLLMの障害やコンテキストオーバーフローからのリカバリーが考慮されている。ツールとスキルにより行動範囲を拡張できる
- Layer 4（LLM Providers） - 複数プロバイダーへの対応と自動フォールオーバーにより、特定のLLMに依存しない設計になっている
- Layer 5（Output & Storage） - SQLiteによるセッション永続化、ベクトル検索ベースのRAG、Canvas/A2UI、ネイティブアプリなど多彩な出力先を提供している
「パーソナルAIアシスタント」をOSSで実現するにあたって、チャネル統合・セキュリティ・拡張性のバランスをどう取るかという点で、参考になる設計判断が数多く含まれています。
参考リンク
- OpenClaw GitHub リポジトリ
- OpenClaw ドキュメント
- OpenClawの通信経路を追う — なぜDiscordからbashを操作できるのか
- OpenClawのセキュリティモデル — 攻撃事例と防御機構
この記事が参考になったら
この記事が役に立ったと思いましたら、よろしければフォローをお願いします。
XでフォローするOpenClawの導入やAIエージェントのアーキテクチャ設計に興味がありましたら、お気軽にご連絡ください。
お問い合わせ