Plugin アーキテクチャの内部構造

​

ロードパイプライン

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

• 解決されたエントリが plugin ルート外へ出ている
• パス（またはそのルートディレクトリ）が全ユーザーから書き込み可能である
• 同梱されていない plugin について、パスの所有者が現在の uid（または root）と一致しない

​

マニフェスト優先の動作

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

• CLI のロードでは、要求されたプライマリコマンドを所有する plugin に絞り込む
• チャンネルのセットアップ/plugin 解決では、要求された チャンネル ID を所有する plugin に絞り込む
• 明示的なプロバイダーのセットアップ/ランタイム解決では、要求された プロバイダー ID を所有する plugin に絞り込む
• Gateway の起動計画では、明示的な起動時 インポートに activation.onStartup を使用する。起動メタデータがない plugin は、より限定的な 有効化トリガーによってのみロードされる

​

Plugin キャッシュの境界

• PluginLoaderCacheState および互換性のある有効なランタイムレジストリ
• 同じランタイムサーフェスを繰り返しインポートしないために使用される jiti/module キャッシュおよび公開サーフェスローダーキャッシュ
• インストール済み plugin アーティファクト用のファイルシステムキャッシュ
• パスの正規化や重複解決のための、呼び出しごとの短命なマップ

• 検出結果
• 直接のマニフェストレジストリ
• インストール済み 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、および 会話メタデータ

​

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

• 実行前の低コストな検索に使用するマニフェストメタデータ： setup.providers[].envVars、providerAuthAliases、providerAuthChoices、 および channelConfigs。
• 設定時フック：catalog と applyConfigDefaults。
• ランタイムフック：認証、モデル解決、 ストリームのラップ、思考レベル、リプレイポリシー、使用量エンドポイントを扱う 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 出力ペイロードを返します。
• コアの tts 設定およびプロバイダー選択を使用します。
• PCM オーディオバッファーとサンプルレートを返します。Plugin はプロバイダー向けにリサンプリング／エンコードする必要があります。
• listVoices はプロバイダーごとにオプションです。ベンダー所有の音声選択画面またはセットアップフローに使用します。
• コアは解決済みのリクエスト期限をプロバイダーの listVoices フックに渡します。プロバイダー固有のタイムアウト設定で上書きできます。
• 音声一覧には、ロケール、性別、パーソナリティタグなど、プロバイダー対応の選択画面向けの詳細なメタデータを含めることができます。
• 現在、OpenAI と ElevenLabs はテレフォニーをサポートしています。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 ポリシー、フォールバック、および返信配信はコアに保持します。
• ベンダー所有の音声合成動作には、音声プロバイダーを使用します。
• 従来の Microsoft edge 入力は、microsoft プロバイダー ID に正規化されます。
• 推奨される所有モデルは企業単位です。OpenClaw がこれらの 機能コントラクトを追加するにつれて、1 つのベンダー Plugin がテキスト、音声、 画像、および将来のメディアプロバイダーを所有できます。

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

• オーケストレーション、フォールバック、設定、およびチャネル配線はコアに保持します。
• ベンダーの動作はプロバイダー Plugin に保持します。
• 追加的な拡張は型付けを維持する必要があります。新しいオプションメソッド、新しいオプションの 結果フィールド、新しいオプション機能を使用します。
• 動画生成はすでに同じパターンに従っています。
  • コアが機能コントラクトとランタイムヘルパーを所有します
  • ベンダー 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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* は、画像／音声／動画理解の推奨共有サーフェスです。
• extractStructuredWithModel(...) は、範囲が限定されたプロバイダー所有の画像優先抽出向けの Plugin-facing シームです。少なくとも 1 つの画像入力を含めてください。 テキスト入力は補足的なコンテキストです。製品 Plugin がルートとスキーマを所有し、 OpenClaw がプロバイダー／ランタイム境界を所有します。
• コアのメディア理解音声設定（tools.media.audio）およびプロバイダーのフォールバック順序を使用します。
• 文字起こし出力が生成されない場合（たとえば、スキップされた入力／サポートされていない入力）は、{ text: undefined } を返します。

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

• provider および model は、永続的なセッション変更ではなく、実行ごとのオプションの上書きです。
• toolsAlsoAllow は、呼び出し元 Plugin によって登録された、所有者が一意に特定できる正確なツール名を受け付けます。コアの名前および曖昧な名前は拒否されます。これは通常のプロファイルに追加されますが、オペレーターの許可リストと拒否設定が引き続き優先されます。
• OpenClaw は、信頼された呼び出し元に対してのみ、これらの上書きフィールドを受け入れます。
• Plugin 所有のフォールバック実行では、オペレーターが plugins.entries.<id>.subagent.allowModelOverride: true を使用して明示的に有効化する必要があります。
• 信頼された Plugin を特定の正規 provider/model ターゲットに制限するには plugins.entries.<id>.subagent.allowedModels を使用し、任意のターゲットを明示的に許可するには "*" を使用します。
• 信頼されていない Plugin のサブエージェント実行も引き続き動作しますが、上書きリクエストは暗黙にフォールバックするのではなく拒否されます。
• Plugin が作成したサブエージェントセッションには、作成元の Plugin ID がタグ付けされます。フォールバックの api.runtime.subagent.deleteSession(...) が削除できるのは、それらの所有セッションのみです。任意のセッションを削除するには、引き続き管理者スコープの Gateway リクエストが必要です。

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 検索プロバイダーを使用します。
• api.runtime.webSearch.* は、エージェントツールラッパーに依存せずに検索動作を必要とする機能／チャネル Plugin 向けの推奨共有サーフェスです。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "親しみやすいロブスターのマスコット", size: "1024x1024" },
});

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

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

​

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" または "plugin"。通常の Gateway 認証を要求するには "gateway" を、Plugin が管理する認証/Webhook 検証には "plugin" を使用します。
• match: 省略可能。"exact"（デフォルト）または "prefix"。
• handleUpgrade: 同じルートでの WebSocket アップグレードリクエスト用の、省略可能なハンドラー。
• replaceExisting: 省略可能。同じ Plugin が自身の既存のルート登録を置き換えられるようにします。
• handler: ルートがリクエストを処理した場合は true を返します。

• api.registerHttpHandler(...) は削除されており、使用すると Plugin の読み込みエラーが発生します。代わりに api.registerHttpRoute(...) を使用してください。
• Plugin のルートでは auth を明示的に宣言する必要があります。
• 完全一致する path + match の競合は、replaceExisting: true でない限り拒否されます。また、ある Plugin が別の Plugin のルートを置き換えることはできません。
• auth レベルが異なる重複ルートは拒否されます。exact/prefix のフォールスルーチェーンは、同じ認証レベル内にのみ維持してください。
• auth: "plugin" ルートには、オペレーターのランタイムスコープが自動的に付与されることはありません。これは Plugin が管理する Webhook/署名検証用であり、特権 Gateway ヘルパー呼び出し用ではありません。
• auth: "gateway" ルートは Gateway リクエストのランタイムスコープ内で実行されます。デフォルトのサーフェス（gatewayRuntimeScopeSurface: "write-default"）は意図的に保守的です。
  • 共有シークレットによる Bearer 認証（gateway.auth.mode = "token" / "password"）および信頼済みプロキシ以外の認証方式には、呼び出し元が x-openclaw-scopes を送信した場合でも、単一の operator.write スコープが付与されます
  • 明示的な x-openclaw-scopes ヘッダーのない trusted-proxy 呼び出し元も、従来の operator.write のみのサーフェスを維持します
  • x-openclaw-scopes を送信する trusted-proxy 呼び出し元には、代わりに宣言されたスコープが付与されます
  • ルートは gatewayRuntimeScopeSurface: "trusted-operator" を有効にすることで、アイデンティティを伴う認証モードでは常に x-openclaw-scopes を尊重できます（ヘッダーがない場合は CLI のデフォルトスコープ一式にフォールバックします）
• auth: "gateway" ルートを使用するサンドボックス化された外部 Control UI タブでは、認証済みのブートストラップのみが発行する短期間有効な署名付き Cookie グラントを使用します。Plugin 認証のタブは、直接 iframe パスを維持します。マウント前に、親は同じ不透明なサンドボックス内でルート所有のプローブを実行し、ブラウザーのプライバシーポリシーによって Cookie がブロックされる場合はフェイルクローズします。グラントは、所有する Plugin、一致するルートのルートパス、現在の認証世代に紐付けられます。プロセスごとにランダムな Cookie 名により、同じホスト上の信頼済み Gateway 同士が互いに上書きすることを防ぎますが、Cookie が TCP ポートを分離することはありません。したがって、Gateway のホスト名は単一のクレデンシャル境界です。他のポートを含め、そのホスト名上で相互に信頼されていないサービスを同居させないでください。ルートディスパッチは、別の Plugin が所有するネストされたルートに対する再利用を拒否します。サンドボックスの子孫は Cookie の観点ではクロスサイトとなるため、グラントは operator.read を伴う GET と HEAD のみを受け入れます。変更操作と WebSocket アップグレードは、明示的に Gateway 認証されたサーフェスに留まります。この Cookie は意図的に CHIPS を使用できません。現在のブラウザーではパーティションキーにクロスサイト祖先ビットが含まれるため、ネストされた不透明なサンドボックスフレームは同一ルートのアセットにアクセスできなくなるからです。この Cookie にはセキュアコンテキストとクロスサイト Cookie に対するブラウザーの許可が必要です。そのため、Gateway 認証を使用する外部タブは、平文 HTTP の LAN オリジンや、サードパーティー Cookie が完全にブロックされている環境では利用できません。HTTPS/Tailscale Serve、または互換性のある Cookie ポリシーを備えたブラウザー信頼済みのループバックを使用してください。
• このグラントは、Gateway Bearer トークンの漏えいと、意図しないルート/スコープの再利用を防止します。ネイティブ Plugin 間にセキュリティ境界を作成するものではありません。ネイティブ Plugin のコードと、それが提供する UI コンテンツは、同じ信頼済みインプロセス Plugin 境界の一部であり続けます。
• 実用上のルール: Gateway 認証された Plugin ルートを暗黙の管理者サーフェスだと想定しないでください。ルートに管理者専用の動作が必要な場合は、trusted-operator スコープサーフェスを有効にし、アイデンティティを伴う認証モードを要求し、明示的な x-openclaw-scopes ヘッダーの契約を文書化してください。
• ルートの照合と認証後、通常のハンドラーは Gateway のルートワーク受付に参加します。準備中または再起動中の Gateway は、ハンドラーを呼び出す前に 503 を返します。限定的な例外は、マニフェストで権限を付与された auth: "gateway" ルートであり、さらにルート固有の trusted-operator サーフェスを有効にしている場合です。このルートは、停止制御のディスパッチが到達不能にならないようアクセス可能なままとなりますが、同じ Plugin の通常の兄弟ルートは受付境界の背後に留まります。WebSocket の handleUpgrade 所有権にも、同じアトミックな受付境界が適用されます。ハンドラーがソケットを受け入れた後のソケットの存続期間は Plugin が所有し、この境界では追跡されません。

​

Plugin SDK のインポートパス

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

​

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

• セマンティックなプレゼンテーションブロック（text、context、 divider、chart、table、buttons、select）には presentation
• 固定配信リクエストには delivery-pin

​

チャンネルターゲットの解決

• messaging.inferTargetChatType({ to }) は、正規化されたターゲットをディレクトリ検索の前に direct、group、channel のどれとして扱うべきかを決定します。
• messaging.targetResolver.looksLikeId(raw, normalized) は、入力がディレクトリ検索ではなく ID のような値としての解決に直接進むべきかどうかをコアに通知します。
• messaging.targetResolver.reservedLiterals は、そのプロバイダーにおいて チャンネル/セッション参照となる単独の語を一覧化します。解決処理は、予約済みリテラルを拒否する前に 設定済みのディレクトリエントリを維持し、その後ディレクトリ検索に失敗した場合はフェイルクローズします。
• messaging.targetResolver.resolveTarget(...) は、正規化後または ディレクトリ検索失敗後にコアが最終的なプロバイダー所有の解決を必要とする場合の Plugin フォールバックです。
• messaging.resolveOutboundSessionRoute(...) は、ターゲットの解決後に プロバイダー固有のセッションルート構築を所有します。

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

​

設定に基づくディレクトリ

• 許可リストに基づく DM ピア
• 設定済みのチャンネル/グループマップ
• アカウントスコープの静的ディレクトリフォールバック

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

​

プロバイダーカタログ

• { provider }（単一のプロバイダーエントリ用）
• { providers }（複数のプロバイダーエントリ用）

• simple：通常の API キーまたは環境変数駆動のプロバイダー
• profile：認証プロファイルが存在するときに表示されるプロバイダー
• paired：関連する複数のプロバイダーエントリを合成するプロバイダー
• late：他の暗黙的プロバイダーの後に行う最終パス

• discovery は従来のエイリアスとして引き続き動作しますが、非推奨警告が出力されます
• catalog と discovery の両方が登録されている場合、OpenClaw は catalog を使用し、 警告を出力します
• augmentModelCatalog は非推奨です。バンドルされたプロバイダーは registerModelCatalogProvider を通じて補足行を公開する必要があります

​

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

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

• 説明用のアカウント状態のみを返します。
• enabled と configured を保持します。
• 必要に応じて、次のような認証情報のソース／状態フィールドを含めます。
  • tokenSource、tokenStatus
  • botTokenSource、botTokenStatus
  • appTokenSource、appTokenStatus
  • signingSecretSource、signingSecretStatus
• 読み取り専用の可用性を報告するだけなら、生のトークン値を返す必要はありません。 状態表示用コマンドには、tokenStatus: "available"（および対応するソース フィールド）を返せば十分です。
• 認証情報が 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": "Nextcloud Talk の Webhook ボットを介したセルフホスト型チャット。",
      "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：ドキュメントのナビゲーション画面で、チャネルを内部用／非公開として示す
• 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", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

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

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

​

新しいケイパビリティの追加

1. コアコントラクトを定義します。 コアが所有すべき共有動作を決定します。 ポリシー、フォールバック、設定のマージ、ライフサイクル、チャンネル向けのセマンティクス、 およびランタイムヘルパーの形式が含まれます。
2. 型付きの Plugin 登録／ランタイムサーフェスを追加します。 OpenClawPluginApi や api.runtime を、実用上必要最小限の型付き ケイパビリティサーフェスで拡張します。
3. コアとチャンネル／機能のコンシューマーを接続します。 チャンネルおよび機能 Plugin は、 ベンダー実装を直接インポートせず、コアを介して新しいケイパビリティを 使用する必要があります。
4. ベンダー実装を登録します。 その後、ベンダー Plugin が 各バックエンドをケイパビリティに登録します。
5. コントラクトのカバレッジを追加します。 所有権と登録形式が 長期にわたって明示的に保たれるよう、テストを追加します。

​

ケイパビリティのチェックリスト

• 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 内のキャプチャ／テストヘルパー
• src/plugins/contracts/registry.ts 内の所有権／コントラクトアサーション
• docs/ 内のオペレーター／Plugin ドキュメント

​

ケイパビリティのテンプレート

// 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(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• コアはケイパビリティのコントラクトとオーケストレーションを所有する
• ベンダー Plugin はベンダー実装を所有する
• 機能／チャンネル Plugin はランタイムヘルパーを使用する
• コントラクトテストは所有権を明示的に保つ

​

関連項目

• Plugin アーキテクチャ — 公開ケイパビリティモデルと形式
• Plugin SDK のサブパス
• Plugin SDK のセットアップ
• Plugin の構築