Plugin 内部

​

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

​

外部互換性の方針

​

Pluginの形状

​

レガシーフック

• 動作を維持する
• レガシーとして文書化する
• モデル/プロバイダーの上書きには before_model_resolve を優先する
• プロンプト変更には before_prompt_build を優先する
• 実際の使用が減り、フィクスチャのカバレッジで移行安全性が証明された後にのみ削除する

​

互換性シグナル

​

アーキテクチャ概要

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

• マニフェスト/config検証は、Pluginコードを実行せずにマニフェスト/スキーマメタデータから動作するべきです
• ネイティブケイパビリティ検出では、非アクティブ化レジストリスナップショットを構築するために、信頼済みPluginのエントリコードを読み込む場合があります
• ネイティブランタイム動作は、api.registrationMode === "full" のPluginモジュールの register(api) パスから来ます

​

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

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

​

アクティベーション計画

• activation.* フィールドは明示的なプランナーヒントです
• providers、channels、commandAliases、setup.providers、contracts.tools、およびフックはマニフェスト所有権のフォールバックのままです
• 既存の呼び出し元向けに ids のみのプランナー API は引き続き利用できます
• plan 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 向けサーフェスは、テキストモデル、音声、画像、動画にまたがる場合でも 1 つの Plugin に存在します
• 他のベンダーも自分たちのサーフェス領域について同じことができます
• チャンネルは、どのベンダー Plugin がプロバイダーを所有しているかを気にしません。コアが公開する共有ケイパビリティ契約を利用します

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

​

ケイパビリティのレイヤー化

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

​

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

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";
import { createPluginBackedWebSearchProvider } from "openclaw/plugin-sdk/provider-web-search";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          ...req,
          provider: "exampleai",
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          ...req,
          provider: "exampleai",
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• 1 つの Plugin がベンダーサーフェスを所有します
• コアは引き続きケイパビリティ契約を所有します
• チャンネルと機能 Plugin はベンダーコードではなく api.runtime.* ヘルパーを利用します
• 契約テストでは、Plugin が所有すると主張するケイパビリティを登録していることを表明できます

​

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

​

契約と適用

• Plugin 作者は、安定した内部標準を1つ得られる
• core は、2つの Plugin が同じ provider id を登録するような所有権の重複を拒否できる
• startup は、不正な形式の登録に対して実行可能な診断を表示できる
• 契約テストは、バンドル Plugin の所有権を強制し、気づかないドリフトを防げる

​

契約に含めるべきもの

​

実行モデル

​

エクスポート境界

• バンドル Plugin 固有のヘルパー subpath
• 公開 API として意図されていないランタイム配管 subpath
• ベンダー固有の便利ヘルパー
• 実装詳細である setup/オンボーディングヘルパー

​

内部構造とリファレンス

​

関連

• Building plugins
• Plugin manifest
• Plugin SDK setup