Plugin アーキテクチャの内部

​

ロードパイプライン

1. 候補となる Plugin ルートを検出する
2. ネイティブまたは互換バンドルのマニフェストとパッケージメタデータを読み取る
3. 安全でない候補を拒否する
4. Plugin 設定（plugins.enabled、allow、deny、entries、 slots、load.paths）を正規化する
5. 各候補について有効化するかどうかを決定する
6. 有効なネイティブモジュールをロードする: ビルド済みバンドルモジュールはネイティブローダーを使用し、 未ビルドのネイティブ Plugin は jiti を使用する
7. ネイティブな register(api) フックを呼び出し、登録内容を Plugin レジストリに収集する
8. レジストリをコマンド/ランタイムの各サーフェスに公開する

​

マニフェスト優先の動作

• Plugin を識別する
• 宣言されたチャネル/Skills/設定スキーマまたはバンドル capability を検出する
• plugins.entries.<id>.config を検証する
• Control UI のラベル/プレースホルダーを補強する
• インストール/カタログのメタデータを表示する
• Plugin ランタイムをロードせずに軽量な有効化記述子とセットアップ記述子を保持する

• CLIロードは、要求された主要コマンドを所有する Plugin に絞り込みます
• チャネルセットアップ/Plugin 解決は、要求された チャネルidを所有する Plugin に絞り込みます
• 明示的なプロバイダーセットアップ/ランタイム解決は、要求された プロバイダーidを所有する Plugin に絞り込みます

​

ローダーがキャッシュするもの

• 検出結果
• マニフェストレジストリデータ
• ロード済み Plugin レジストリ

• これらのキャッシュを無効にするには、OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 または OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 を設定します。
• キャッシュ時間は、OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS と OPENCLAW_PLUGIN_MANIFEST_CACHE_MS で調整します。

​

レジストリモデル

• Plugin レコード（識別子、ソース、オリジン、状態、診断）
• ツール
• レガシーフックと型付きフック
• チャネル
• プロバイダー
• Gateway RPCハンドラー
• HTTPルート
• CLIレジストラ
• バックグラウンドサービス
• Plugin 所有コマンド

• Plugin モジュール -> レジストリ登録
• コアランタイム -> レジストリ消費

​

会話バインディングコールバック

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // この Plugin + 会話に対するバインディングが存在するようになった。
        console.log(event.binding?.conversationId);
        return;
      }

      // 要求は拒否された。ローカルの保留状態を消去する。
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" または "denied"
• decision: "allow-once"、"allow-always"、または "deny"
• binding: 承認済み要求に対して解決されたバインディング
• request: 元の要求サマリー、デタッチヒント、送信者id、 会話メタデータ

​

プロバイダーランタイムフック

• マニフェストメタデータ: 安価なランタイム前参照のための providerAuthEnvVars、providerAuthAliases、providerAuthChoices、channelEnvVars
• 設定時フック: catalog（レガシーの discovery）および applyConfigDefaults
• ランタイムフック: 認証、モデル解決、 ストリームラップ、thinkingレベル、再生ポリシー、使用量エンドポイントをカバーする 40 以上のオプションフック。完全な一覧は フック順序と使い方 を参照してください。

​

フック順序と使い方

​

プロバイダーの例

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

組み込みの例

​

ランタイムヘルパー

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech は、ファイル/ボイスノート向けサーフェス用の通常のコアTTS出力ペイロードを返します。
• コアの messages.tts 設定とプロバイダー選択を使用します。
• PCM音声バッファー + サンプルレートを返します。Plugin 側でプロバイダー向けに再サンプリング/エンコードする必要があります。
• listVoices はプロバイダーごとに任意です。ベンダー所有の音声ピッカーやセットアップフローに使用してください。
• 音声一覧には、ロケール、性別、パーソナリティタグなど、プロバイダー認識型ピッカー向けのより豊かなメタデータを含められます。
• 現在、OpenAI と ElevenLabs は telephony をサポートしています。Microsoft はサポートしていません。

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• TTSポリシー、フォールバック、返信配信はコアに残してください。
• ベンダー所有の合成動作には speech provider を使用してください。
• レガシーな Microsoft edge 入力は microsoft プロバイダーidに正規化されます。
• 推奨される所有モデルは企業指向です。OpenClaw がこれらの capability 契約を追加していく中で、1つのベンダー Plugin が テキスト、音声、画像、将来のメディアプロバイダーを所有できます。

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• オーケストレーション、フォールバック、設定、チャネル配線はコアに残してください。
• ベンダー動作はプロバイダー Plugin 内に残してください。
• 加法的拡張は型付きのままにしてください: 新しい任意メソッド、新しい任意の 結果フィールド、新しい任意の capability。
• 動画生成もすでに同じパターンに従っています:
  • コアが capability 契約とランタイムヘルパーを所有する
  • ベンダー Plugin が api.registerVideoGenerationProvider(...) を登録する
  • 機能/チャネル Plugin が api.runtime.videoGeneration.* を利用する

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // MIME を確実に推定できない場合は任意:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* は、 画像/音声/動画理解向けの推奨共有サーフェスです。
• コアの media-understanding 音声設定（tools.media.audio）とプロバイダーフォールバック順序を使用します。
• 文字起こし出力が生成されなかった場合（たとえばスキップ/非対応入力）には { text: undefined } を返します。
• api.runtime.stt.transcribeAudioFile(...) は互換エイリアスとして引き続き残ります。

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider と model は、実行ごとの任意の上書きであり、永続的なセッション変更ではありません。
• OpenClaw は、信頼された呼び出し元に対してのみこれらの上書きフィールドを受け付けます。
• Plugin 所有のフォールバック実行では、運用者が plugins.entries.<id>.subagent.allowModelOverride: true でオプトインする必要があります。
• plugins.entries.<id>.subagent.allowedModels を使用すると、信頼された Plugin を特定の正規 provider/model ターゲットに制限できます。"*" を指定すると、任意のターゲットを明示的に許可します。
• 信頼されていない Plugin の subagent 実行も動作しますが、上書き要求は暗黙にフォールバックされるのではなく拒否されます。

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• プロバイダー選択、資格情報解決、共有リクエスト意味論はコアに残してください。
• ベンダー固有の検索転送には web-search provider を使用してください。
• api.runtime.webSearch.* は、エージェントツールラッパーに依存せず検索動作を必要とする機能/チャネル Plugin 向けの推奨共有サーフェスです。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): 設定された画像生成プロバイダーチェーンを使用して画像を生成します。
• listProviders(...): 利用可能な画像生成プロバイダーとその capability を一覧表示します。

​

Gateway HTTPルート

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: Gateway HTTPサーバー配下のルートパス。
• auth: 必須です。通常のGateway認証を要求するには "gateway" を、 Plugin 管理認証/Webhook 検証には "plugin" を使用します。
• match: 任意。"exact"（デフォルト）または "prefix"。
• replaceExisting: 任意。同じ Plugin が自分の既存ルート登録を置き換えることを許可します。
• handler: ルートがリクエストを処理した場合は true を返します。

• api.registerHttpHandler(...) は削除されており、Plugin ロードエラーの原因になります。代わりに api.registerHttpRoute(...) を使用してください。
• Plugin ルートは auth を明示的に宣言する必要があります。
• 正確に同じ path + match の競合は、replaceExisting: true でない限り拒否され、ある Plugin が別の Plugin のルートを置き換えることはできません。
• auth レベルが異なる重複ルートは拒否されます。exact/prefix のフォールスルーチェーンは同じ auth レベル内だけにしてください。
• auth: "plugin" ルートは、運用者ランタイムスコープを自動では受け取りません。これは特権付き Gateway ヘルパー呼び出しではなく、Plugin 管理の Webhook/署名検証向けです。
• auth: "gateway" ルートは Gateway リクエストランタイムスコープ内で実行されますが、そのスコープは意図的に保守的です:
  • 共有シークレットの bearer 認証（gateway.auth.mode = "token" / "password"）では、呼び出し元が x-openclaw-scopes を送信しても、Plugin ルートのランタイムスコープは operator.write に固定されます
  • 信頼されたID保持HTTPモード（たとえば trusted-proxy や、プライベート ingress 上の gateway.auth.mode = "none"）では、x-openclaw-scopes ヘッダーが明示的に存在する場合にのみそれを反映します
  • それらのID保持 Plugin ルートリクエストで x-openclaw-scopes がない場合、ランタイムスコープは operator.write にフォールバックします
• 実務上のルール: gateway-auth の Plugin ルートを暗黙の管理者サーフェスだと想定しないでください。ルートに管理者専用動作が必要なら、ID保持認証モードを要求し、明示的な x-openclaw-scopes ヘッダー契約を文書化してください。

​

Plugin SDKインポートパス

• index.js — バンドル済み Plugin エントリ
• api.js — ヘルパー/型 barrel
• runtime-api.js — ランタイム専用 barrel
• setup-entry.js — セットアップ Plugin エントリ

​

メッセージツールスキーマ

• セマンティックなプレゼンテーションブロック（text、context、divider、buttons、select）用の presentation
• ピン留め配信要求用の delivery-pin

​

チャネルターゲット解決

• messaging.inferTargetChatType({ to }) は、正規化済みターゲットを ディレクトリ検索前に direct、group、channel のどれとして扱うかを決定します。
• messaging.targetResolver.looksLikeId(raw, normalized) は、 入力をディレクトリ検索ではなく id 風解決へ直接進めるべきかどうかをコアへ伝えます。
• messaging.targetResolver.resolveTarget(...) は、正規化後または ディレクトリ不一致後にコアが最後のプロバイダー所有解決を必要とするときの、 Plugin フォールバックです。
• messaging.resolveOutboundSessionRoute(...) は、ターゲット解決後の プロバイダー固有セッションルート構築を所有します。

• peers/groups を検索する前に行うべきカテゴリ決定には inferTargetChatType を使用する
• 「これを明示的/ネイティブなターゲットidとして扱う」判定には looksLikeId を使用する
• プロバイダー固有の正規化フォールバックには resolveTarget を使用し、 広いディレクトリ検索には使わない
• チャットid、スレッドid、JID、ハンドル、ルームid のようなプロバイダーネイティブidは、 汎用SDKフィールドではなく target 値またはプロバイダー固有パラメータ内に保持する

​

設定ベースのディレクトリ

• allowlist 駆動のDM peer
• 設定済みチャネル/グループマップ
• アカウントスコープの静的ディレクトリフォールバック

• クエリフィルタリング
• limit の適用
• 重複排除/正規化ヘルパー
• ChannelDirectoryEntry[] の構築

​

プロバイダーカタログ

• 1つのプロバイダーエントリ用の { provider }
• 複数のプロバイダーエントリ用の { providers }

• simple: 単純なAPIキーまたは env 駆動のプロバイダー
• profile: 認証プロファイルが存在すると現れるプロバイダー
• paired: 複数の関連プロバイダーエントリを合成するプロバイダー
• late: 他の暗黙プロバイダー後の最終パス

• discovery はレガシーエイリアスとして引き続き動作します
• catalog と discovery の両方が登録されている場合、OpenClaw は catalog を使用します

​

読み取り専用チャネル検査

• resolveAccount(...) はランタイム経路です。資格情報が 完全に具体化されている前提で動作でき、必要なシークレットがない場合は即座に失敗して構いません。
• openclaw status、openclaw status --all、 openclaw channels status、openclaw channels resolve、doctor/config 修復フローのような読み取り専用コマンド経路では、 設定を説明するだけのためにランタイム資格情報を具体化する必要があるべきではありません。

• 説明的なアカウント状態のみを返す
• enabled と configured を保持する
• relevant な場合は資格情報ソース/状態フィールドを含める。たとえば:
  • tokenSource、tokenStatus
  • botTokenSource、botTokenStatus
  • appTokenSource、appTokenStatus
  • signingSecretSource、signingSecretStatus
• 読み取り専用の 可用性を報告するだけなら、生のトークン値を返す必要はありません。 tokenStatus: "available"（および対応するソースフィールド）を返せば、 status 系コマンドには十分です。
• 資格情報が SecretRef 経由で設定されているが、 現在のコマンド経路では利用できない場合は configured_unavailable を使用する

​

パッケージパック

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• チャネル登録そのもの
• Gateway が待ち受け開始する前に利用可能でなければならない HTTPルート
• 同じ時間帯に存在していなければならない Gateway メソッド、ツール、またはサービス

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

チャネルカタログメタデータ

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Webhook bot を介したセルフホストの Nextcloud Talk チャット。",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: より豊かなカタログ/状態サーフェス向けの副次ラベル
• docsLabel: ドキュメントリンクのリンクテキストを上書きする
• preferOver: このカタログエントリが上位に来るべき、優先度の低い Plugin /チャネルid
• selectionDocsPrefix、selectionDocsOmitLabel、selectionExtras: 選択サーフェス向けコピー制御
• markdownCapable: アウトバウンド書式決定で、そのチャネルを markdown 対応としてマークする
• exposure.configured: false に設定すると、設定済みチャネル一覧サーフェスからそのチャネルを隠す
• exposure.setup: false に設定すると、対話型セットアップ/設定ピッカーからそのチャネルを隠す
• exposure.docs: ドキュメントナビゲーションサーフェス向けに、そのチャネルを internal/private としてマークする
• showConfigured / showInSetup: 互換性のために引き続き受け付けられるレガシーエイリアスです。exposure を推奨します
• quickstartAllowFrom: 標準クイックスタート allowFrom フローへそのチャネルをオプトインする
• forceAccountBinding: アカウントが1つしか存在しない場合でも、明示的なアカウントバインディングを要求する
• preferSessionLookupForAnnounceTarget: 通知ターゲット解決時にセッション検索を優先する

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

コンテキストエンジン Plugin

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

新しい capability の追加

1. コア契約を定義する コアが所有すべき共有動作を決めます: ポリシー、フォールバック、設定マージ、 ライフサイクル、チャネル向け意味論、ランタイムヘルパー形状。
2. 型付き Plugin 登録/ランタイムサーフェスを追加する OpenClawPluginApi および/または api.runtime を、 最小限で有用な型付き capability サーフェスで拡張します。
3. コア + チャネル/機能コンシューマーを配線する チャネルや機能 Plugin は、新しい capability をコア経由で利用するべきであり、 ベンダー実装を直接インポートするべきではありません。
4. ベンダー実装を登録する その後、ベンダー Plugin がその capability に対してバックエンドを登録します。
5. 契約カバレッジを追加する 時間が経っても所有権と登録形状が明示的なままになるよう、テストを追加します。

​

capability チェックリスト

• src/<capability>/types.ts のコア契約型
• src/<capability>/runtime.ts のコアランナー/ランタイムヘルパー
• src/plugins/types.ts の Plugin API登録サーフェス
• src/plugins/registry.ts の Plugin レジストリ配線
• 機能/チャネル Plugin がそれを利用する必要がある場合は src/plugins/runtime/* の Plugin ランタイム公開
• src/test-utils/plugin-registration.ts の capture/test ヘルパー
• src/plugins/contracts/registry.ts の所有権/契約アサーション
• docs/ の運用者/Plugin ドキュメント

​

capability テンプレート

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• コアが capability 契約 + オーケストレーションを所有する
• ベンダー Plugin がベンダー実装を所有する
• 機能/チャネル Plugin がランタイムヘルパーを利用する
• 契約テストが所有権を明示的に保つ

​

関連

• Plugin architecture — 公開 capability モデルと形状
• Plugin SDK subpaths
• Plugin SDK setup
• Building plugins