Plugin の内部構造

​

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

​

外部互換性に対する方針

​

Plugin の形態

​

互換性シグナル

​

アーキテクチャの概要

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

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

​

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

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

​

アクティベーション計画

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

​

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

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

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

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

​

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

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

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

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

​

ケイパビリティの階層化

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

​

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

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { exampleAiMedia } from "./exampleai-media.js";

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 が所有すると宣言したケイパビリティを登録したことを検証可能

​

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

​

契約と適用

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

​

契約に含めるべきもの

​

実行モデル

​

エクスポート境界

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

​

内部構造とリファレンス

​

関連項目

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