Plugin の内部構造

これは OpenClaw Plugin システムの詳細なアーキテクチャリファレンスです。実践的なガイドについては、以下の目的別ページのいずれかから始めてください。

公開ケイパビリティモデル

ケイパビリティは、OpenClaw 内の公開ネイティブ Pluginモデルです。すべてのネイティブ OpenClaw Plugin は、1 つ以上のケイパビリティタイプに対して登録されます。

外部互換性に対する方針

ケイパビリティモデルはコアに導入され、現在バンドル済み / ネイティブ Plugin で使用されていますが、外部 Plugin の互換性には「エクスポートされているため固定されている」よりも厳格な基準が必要です。

ケイパビリティ登録が今後の方向性です。移行期間中、従来のフックは外部 Plugin にとって最も安全で破壊的変更のない方法です。エクスポートされたヘルパーのサブパスはすべて同等ではありません。付随的なヘルパーエクスポートよりも、範囲が狭く文書化された契約を優先してください。

Plugin の形態

OpenClaw は、読み込まれた各 Plugin を、静的メタデータだけでなく実際の登録動作に基づいて形態に分類します。

Plugin の形態とケイパビリティの内訳を確認するには、openclaw plugins inspect <id> を使用します。詳細については、CLI リファレンスを参照してください。

互換性シグナル

openclaw doctor、openclaw plugins inspect <id>、openclaw status --all、openclaw plugins doctor は、次の互換性通知を表示します。

現時点では、助言 / 警告シグナルによって Plugin が動作しなくなることはありません。これらのシグナルは openclaw status --all と openclaw plugins doctor にも表示されます。

アーキテクチャの概要

OpenClaw の Plugin システムには 4 つのレイヤーがあります。

Plugin CLI に限っては、ルートコマンドの検出は 2 つのフェーズに分かれます。

• 解析時のメタデータは registerCli(..., { descriptors: [...] }) から取得される
• 実際の Plugin CLI モジュールは遅延読み込みのままにし、最初の呼び出し時に登録できる

これにより、Plugin が所有する CLI コードを Plugin 内に保持しながら、OpenClaw が解析前にルートコマンド名を予約できます。

重要な設計境界は次のとおりです。

• マニフェスト / 設定の検証は、Plugin コードを実行せずにマニフェスト / スキーマメタデータから機能する必要がある
• ネイティブケイパビリティの検出では、信頼された Plugin エントリコードを読み込み、非アクティブ化レジストリのスナップショットを構築できる
• ネイティブランタイムの動作は、api.registrationMode === "full" を使用する Plugin モジュールの register(api) パスから提供される

この分離により、完全なランタイムがアクティブになる前に、OpenClaw は設定を検証し、欠落または無効化された Plugin を説明し、UI / スキーマのヒントを構築できます。

Plugin メタデータのスナップショットとルックアップテーブル

Gateway の起動時に、現在の設定スナップショット用の PluginMetadataSnapshot が 1 つ構築されます。このスナップショットにはメタデータのみが含まれます。インストール済み Plugin のインデックス、マニフェストレジストリ、マニフェスト診断、所有者マップ、Plugin ID ノーマライザー、マニフェストレコードが保存されます。読み込まれた Plugin モジュール、プロバイダー SDK、パッケージ内容、ランタイムエクスポートは保持しません。

Plugin 対応の設定検証、起動時の自動有効化、Gateway Plugin のブートストラップは、マニフェスト / インデックスのメタデータを個別に再構築する代わりに、このスナップショットを利用します。PluginLookUpTable は同じスナップショットから派生し、現在のランタイム設定に対応する起動時の Plugin プランを追加します。

起動後、Gateway は現在のメタデータスナップショットを置換可能なランタイム成果物として保持します。ランタイムで繰り返されるプロバイダー検出では、プロバイダーカタログを処理するたびにインストール済みインデックスとマニフェストレジストリを再構築する代わりに、このスナップショットを借用できます。Gateway のシャットダウン時、設定 / Plugin インベントリの変更時、インストール済みインデックスへの書き込み時に、スナップショットはクリアまたは置換されます。互換性のある最新スナップショットが存在しない場合、呼び出し元はコールドなマニフェスト / インデックスパスへフォールバックします。ワークスペース Plugin はメタデータスコープの一部であるため、互換性チェックには plugins.load.paths やデフォルトのエージェントワークスペースなどの Plugin 検出ルートを含める必要があります。

スナップショットとルックアップテーブルにより、起動時に繰り返される判断が高速パスに維持されます。

• チャネルの所有権
• 遅延チャネル起動
• 起動時の Plugin ID
• プロバイダーと CLI バックエンドの所有権
• セットアッププロバイダー、コマンドエイリアス、モデルカタログプロバイダー、マニフェスト契約の所有権
• Plugin 設定スキーマとチャネル設定スキーマの検証
• 起動時の自動有効化の判断

安全性の境界は、スナップショットの変更ではなく置換です。設定、Plugin インベントリ、インストールレコード、永続化されたインデックスポリシーが変更された場合は、スナップショットを再構築してください。これを広範で変更可能なグローバルレジストリとして扱ったり、履歴スナップショットを無制限に保持したりしないでください。ランタイム Plugin の読み込みはメタデータスナップショットから分離されたままなので、古いランタイム状態がメタデータキャッシュの背後に隠されることはありません。

キャッシュ規則については、Plugin アーキテクチャの内部構造で説明されています。呼び出し元が現在のフローに対する明示的なスナップショット、ルックアップテーブル、またはマニフェストレジストリを保持していない限り、マニフェストと検出のメタデータは最新です。非公開のメタデータキャッシュと実時間ベースの TTL は、Plugin 読み込みの一部ではありません。コードまたはインストール済み成果物が実際に読み込まれた後も保持できるのは、ランタイムローダー、モジュール、依存関係成果物のキャッシュのみです。

一部のコールドパス呼び出し元では、Gateway PluginLookUpTable を受け取る代わりに、永続化されたインストール済み Plugin インデックスからマニフェストレジストリを直接再構築しています。このパスでは、必要に応じてレジストリを再構築するようになりました。呼び出し元が現在のルックアップテーブルまたは明示的なマニフェストレジストリをすでに保持している場合は、それをランタイムフローに渡すことを推奨します。

アクティベーション計画

アクティベーション計画はコントロールプレーンの一部です。呼び出し元は、より広範なランタイムレジストリを読み込む前に、具体的なコマンド、プロバイダー、チャネル、ルート、エージェントハーネス、またはケイパビリティに関連する Plugin を問い合わせることができます。

プランナーは、現在のマニフェスト動作との互換性を維持します。

• activation.* フィールドは明示的なプランナーヒント
• providers、channels、commandAliases、setup.providers、contracts.tools、およびフックは引き続きマニフェスト所有権のフォールバック
• ID のみを返すプランナー API は既存の呼び出し元向けに引き続き利用可能
• 計画 API は理由ラベルを報告するため、診断で明示的なヒントと所有権フォールバックを区別可能

チャネル Plugin と共有メッセージツール

チャネル Plugin は、通常のチャットアクション用に個別の送信、編集、リアクションツールを登録する必要はありません。OpenClaw はコアに単一の共有 message ツールを保持し、その背後にあるチャネル固有の検出と実行はチャネル Plugin が所有します。

現在の境界は次のとおりです。

• コアは共有 message ツールホスト、プロンプト配線、セッションおよびスレッドの記録管理、実行ディスパッチを所有
• チャネル Plugin はスコープ付きアクション検出、ケイパビリティ検出、およびチャネル固有のスキーマフラグメントを所有
• チャネル Plugin は、会話 ID にスレッド ID をエンコードする方法や親会話から継承する方法など、プロバイダー固有のセッション会話文法を所有
• チャネル Plugin はアクションアダプターを通じて最終アクションを実行

チャネル Plugin 向けの SDK サーフェスは ChannelMessageActionAdapter.describeMessageTool(...) です。この統合された検出呼び出しにより、Plugin は表示可能なアクション、ケイパビリティ、スキーマへの追加をまとめて返せるため、それらの間にずれが生じません。

メッセージアクション名には、すべてのトランスポートがすべてのアクションをレンダリングできるように、意図的に閉じたコア所有の語彙を使用します。Plugin にアクション名を追加するにはコアへの PR が必要です。ランタイム登録は意図的にサポートされていません。

チャネル固有のメッセージツールパラメーターにローカルパスやリモートメディア URL などのメディアソースが含まれる場合、Plugin は describeMessageTool(...) から mediaSourceParams も返す必要があります。コアはこの明示的なリストを使用して、Plugin 所有のパラメーター名をハードコードせずに、サンドボックスパスの正規化と送信メディアアクセスのヒントを適用します。プロファイル専用のメディアパラメーターが send のような無関係なアクションで正規化されないように、チャネル全体で共通のフラットなリストではなく、アクション単位のマップを使用してください。

コアは、その検出ステップにランタイムスコープを渡します。重要なフィールドには次が含まれます。

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• 信頼された受信 requesterSenderId

これは、コンテキスト依存の Plugin にとって重要です。チャネルは、コアの message ツールにチャネル固有の分岐をハードコードせずに、アクティブなアカウント、現在のルーム、スレッド、メッセージ、または信頼されたリクエスターの識別情報に基づいてメッセージアクションを非表示または表示できます。

このため、埋め込みランナーのルーティング変更も引き続き Plugin 側の作業です。共有 message ツールが現在のターンに適したチャネル所有のサーフェスを公開できるように、ランナーは現在のチャットおよびセッションの識別情報を Plugin 検出境界へ転送する責任を負います。

チャネル所有の実行ヘルパーについては、チャネル Plugin が実行ランタイムを自身の Plugin モジュール内に保持する必要があります。コアは src/agents/tools 配下の Discord、Slack、Telegram、WhatsApp のメッセージアクションランタイムを所有しなくなりました。個別の plugin-sdk/*-action-runtime サブパスは公開しません。これらの Plugin は、自身が所有する Plugin モジュールからローカルランタイムコードを直接インポートする必要があります。

同じ境界は、一般的なプロバイダー名付き SDK シームにも適用されます。コアは、Discord、Signal、Slack、WhatsApp、または類似する Plugin のチャネル固有の便利なバレルをインポートしてはなりません。コアで特定の動作が必要な場合は、バンドルされた Plugin 自身の api.ts / runtime-api.ts バレルを使用するか、その要件を共有 SDK の限定的で汎用的なケイパビリティへ昇格させます。

バンドルされた Plugin にも同じルールが適用されます。バンドルされた Plugin の runtime-api.ts から、その Plugin 固有のブランド名付き openclaw/plugin-sdk/<plugin-id> ファサードを再エクスポートしてはなりません。これらのブランド名付きファサードは、外部 Plugin と古い利用者向けの互換性シムとして残りますが、バンドルされた Plugin はローカルエクスポートと、openclaw/plugin-sdk/channel-policy、openclaw/plugin-sdk/runtime-store、openclaw/plugin-sdk/webhook-ingress などの限定的で汎用的な SDK サブパスを使用する必要があります。既存の外部エコシステムとの互換性境界で必要な場合を除き、新しいコードで Plugin ID 固有の SDK ファサードを追加してはなりません。

投票には、具体的に次の 2 つの実行パスがあります。

• outbound.sendPoll は共通の投票モデルに適合するチャネル向けの共有ベースライン
• actions.handleAction("poll") はチャネル固有の投票セマンティクスや追加の投票パラメーター向けの推奨パス

コアは、Plugin の投票ディスパッチがアクションを処理しないと判断するまで共有投票の解析を遅延するようになりました。これにより、Plugin 所有の投票ハンドラーは、汎用投票パーサーに先に阻止されることなく、チャネル固有の投票フィールドを受け入れられます。

起動シーケンス全体については、Plugin アーキテクチャの内部構造を参照してください。

ケイパビリティ所有権モデル

OpenClaw は、ネイティブ Plugin を、無関係な統合を寄せ集めたものではなく、企業または機能の所有権境界として扱います。

つまり、次のようになります。

• 企業 Plugin は通常、その企業に関する OpenClaw 向けサーフェスをすべて所有
• 機能 Plugin は通常、自身が導入する機能サーフェス全体を所有
• チャネルはプロバイダー動作を場当たり的に再実装せず、共有コアケイパビリティを使用

目指す最終状態は次のとおりです。

• ベンダーの OpenClaw 向けサーフェスは、テキストモデル、音声、画像、動画にまたがる場合でも単一の Plugin に配置
• 他のベンダーも自身のサーフェス領域について同様に対応可能
• チャネルはどのベンダー Plugin がプロバイダーを所有しているかを意識せず、コアが公開する共有ケイパビリティ契約を使用

重要な違いは次のとおりです。

• Plugin = 所有権境界
• ケイパビリティ = 複数の Plugin が実装または使用できるコア契約

したがって、OpenClaw に動画などの新しいドメインを追加する場合、最初に問うべきことは「どのプロバイダーに動画処理をハードコードするか」ではありません。最初に問うべきことは「コアの動画ケイパビリティ契約をどのように定義するか」です。その契約が存在すれば、ベンダー Plugin はそれに対して登録でき、チャネルおよび機能 Plugin はそれを使用できます。

ケイパビリティがまだ存在しない場合、通常は次の対応が適切です。

これにより、単一のベンダーや一度限りの Plugin 固有コードパスに依存するコア動作を避けながら、所有権を明確に保てます。

ケイパビリティの階層化

コードの配置先を判断する際は、次のメンタルモデルを使用してください。

たとえば、TTS は次の構造に従います。

• コアは返信時の TTS ポリシー、フォールバック順序、設定、チャネル配信を所有
• elevenlabs、google、microsoft、openai は合成実装を所有
• voice-call は電話通話用 TTS ランタイムヘルパーを使用

今後のケイパビリティでも、同じパターンを優先してください。

複数ケイパビリティを持つ企業 Plugin の例

企業 Plugin は、外部から見て一貫したまとまりを持つ必要があります。OpenClaw にモデル、音声、リアルタイム文字起こし、リアルタイム音声、メディア理解、画像生成、動画生成、Web 取得、Web 検索の共有契約がある場合、ベンダーはすべてのサーフェスを 1 か所で所有できます。

  export default definePluginEntry({  id: "exampleai",  name: "ExampleAI",  description: "ExampleAI のモデルとメディアケイパビリティ。",  register(api) {    api.registerProvider({      id: "exampleai",      // 認証、モデルカタログ、ランタイムフック    });     api.registerSpeechProvider({      id: "exampleai",      // ベンダーの音声設定 — SpeechProviderPlugin インターフェースを直接実装    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      describeImage: (req) => exampleAiMedia.describeImage(req),      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),      describeVideo: (req) => exampleAiMedia.describeVideo(req),    });     api.registerWebSearchProvider({      id: "exampleai-search",      createTool() {        // ベンダー所有の Web 検索ツールを返す。      },    });  },});

重要なのは、正確なヘルパー名ではありません。重要なのは構造です。

• 単一の Plugin がベンダーサーフェスを所有
• コアは引き続きケイパビリティ契約を所有
• プロバイダーリクエストの変換と HTTP ヘルパーはベンダー Plugin 内に保持
• チャネルおよび機能 Plugin はベンダーコードではなく api.runtime.* ヘルパーを使用
• 契約テストで、Plugin が所有すると宣言したケイパビリティを登録したことを検証可能

ケイパビリティの例: 動画理解

OpenClaw はすでに画像、音声、動画の理解を 1 つの共有ケイパビリティとして扱っています。同じ所有権モデルがここにも適用されます。

これにより、あるプロバイダーの動画に関する前提をコアに組み込むことを避けられます。Plugin はベンダー側のサーフェスを所有し、コアは機能契約とフォールバック動作を所有します。

動画生成でも、すでに同じ手順を使用しています。コアが型付き機能契約とランタイムヘルパーを所有し、ベンダー Plugin がその契約に対して api.registerVideoGenerationProvider(...) の実装を登録します。

具体的な展開チェックリストが必要ですか？機能クックブックを参照してください。

契約と適用

Plugin API サーフェスは、意図的に OpenClawPluginApi に型付けして集約されています。この契約は、サポートされる登録ポイントと、Plugin が利用できるランタイムヘルパーを定義します。

これが重要な理由：

• Plugin 作者が安定した単一の内部標準を利用できる
• 同じプロバイダー ID を 2 つの Plugin が登録する場合など、所有権の重複をコアが拒否できる
• 不正な登録に対して、起動時に対処可能な診断情報を提示できる
• 契約テストで同梱 Plugin の所有権を適用し、気付かないまま乖離することを防止できる

適用には 2 つの層があります：

実際には、どの Plugin がどのサーフェスを所有するかを OpenClaw が事前に把握できます。所有権が暗黙的ではなく、宣言され、型付けされ、テスト可能であるため、コアとチャネルをシームレスに構成できます。

契約に含めるべきもの

判断に迷う場合は、抽象化レベルを引き上げてください。まず機能を定義し、その後で Plugin がそこへ組み込めるようにします。

実行モデル

ネイティブ OpenClaw Plugin は Gateway と同じプロセス内で実行されます。サンドボックス化されていません。読み込まれたネイティブ Plugin は、コアコードと同じプロセスレベルの信頼境界を持ちます。

OpenClaw は現在、互換バンドルをメタデータ／コンテンツパックとして扱うため、デフォルトではより安全です。現在のリリースでは、主に Skills のバンドルを指します。

同梱されていない Plugin には、許可リストと明示的なインストール／読み込みパスを使用してください。ワークスペース Plugin は本番環境のデフォルトではなく、開発時のコードとして扱ってください。

同梱ワークスペースパッケージ名では、Plugin ID を npm 名に固定してください。デフォルトは @openclaw/<id> です。パッケージが意図的により限定された Plugin の役割を公開する場合は、-provider、-plugin、-speech、-sandbox、-media-understanding など、承認済みの型付きサフィックスを使用します。

エクスポート境界

OpenClaw がエクスポートするのは、実装上の利便性ではなく機能です。

機能登録は公開したままにします。契約に含まれないヘルパーのエクスポートは削減してください：

• 同梱 Plugin 固有のヘルパーサブパス
• 公開 API を意図していないランタイム配管用サブパス
• ベンダー固有の便利なヘルパー
• 実装の詳細であるセットアップ／オンボーディング用ヘルパー

予約済みの同梱 Plugin 用ヘルパーサブパスは、生成される SDK エクスポートマップから廃止されました。所有者固有のヘルパーは、それを所有する Plugin パッケージ内に保持してください。再利用可能なホスト動作のみを、plugin-sdk/gateway-runtime、plugin-sdk/security-runtime、注入される Plugin API 機能などの汎用 SDK 契約へ昇格させてください。

内部構造とリファレンス

読み込みパイプライン、レジストリモデル、プロバイダーのランタイムフック、Gateway HTTP ルート、メッセージツールスキーマ、チャネルターゲットの解決、プロバイダーカタログ、コンテキストエンジン Plugin、新しい機能を追加するためのガイドについては、Plugin アーキテクチャの内部構造を参照してください。

関連項目

• Plugin の構築
• Plugin マニフェスト
• Plugin SDK のセットアップ