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

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

読み込みパイプライン

1. 候補 Plugin root を検出する
2. ネイティブまたは互換 bundle manifest と package metadata を読み取る
3. 安全でない候補を拒否する
4. plugin config (plugins.enabled, allow, deny, entries, slots, load.paths) を正規化する
5. 各候補の有効化を決定する
6. 有効化された native modules を読み込む: ビルド済み bundled modules は native loader を使い、 third-party local source TypeScript は緊急用の Jiti fallback を使う
7. native register(api) hooks を呼び出し、registrations を plugin registry に収集する
8. registry を commands/runtime surfaces に公開する

​

Manifest-first の動作

• plugin を識別する
• 宣言された channels/skills/config schema または bundle capabilities を検出する
• plugins.entries.<id>.config を検証する
• Control UI labels/placeholders を補強する
• install/catalog metadata を表示する
• plugin runtime を読み込まずに、低コストな activation と setup descriptors を保持する

• CLI loading は、要求された primary command を所有する plugins に絞り込む
• channel setup/plugin resolution は、要求された channel id を所有する plugins に絞り込む
• explicit provider setup/runtime resolution は、要求された provider id を所有する plugins に絞り込む
• Gateway startup planning は、明示的な startup imports と startup opt-outs に activation.onStartup を使用する。startup metadata のない plugins は、より狭い activation triggers 経由でのみ読み込む

​

Plugin cache boundary

• PluginLoaderCacheState と compatible active runtime registries
• 同じ runtime surface を繰り返し import することを避けるために使われる jiti/module caches と public-surface loader caches
• installed plugin artifacts の filesystem caches
• path normalization または duplicate resolution のための short-lived per-call maps

• discovery results
• direct manifest registries
• installed plugin index から再構築された manifest registries
• provider owner lookup、model suppression、provider policy、または public-artifact metadata
• manifest、installed index、または load path の変更が次の metadata read で可視になるべき、その他の manifest-derived answer

​

Registry モデル

• plugin records (identity, source, origin, status, diagnostics)
• tools
• legacy hooks と typed hooks
• channels
• providers
• gateway RPC handlers
• HTTP routes
• CLI registrars
• background services
• plugin-owned commands

• plugin module -> registry registration
• core runtime -> registry consumption

​

Conversation binding callbacks

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" または "denied"
• decision: "allow-once"、"allow-always"、または "deny"
• binding: approved requests の resolved binding
• request: original request summary、detach hint、sender id、および conversation metadata

​

Provider runtime hooks

• Manifest metadata: 低コストな pre-runtime lookup 用: setup.providers[].envVars、deprecated compatibility providerAuthEnvVars、 providerAuthAliases、providerAuthChoices、および channelEnvVars。
• Config-time hooks: catalog (legacy discovery) と applyConfigDefaults。
• Runtime hooks: auth、model resolution、 stream wrapping、thinking levels、replay policy、usage endpoints を対象にする 40 個以上の optional hooks。完全な一覧は Hook order and usage を参照してください。

​

Hook order and usage

​

プロバイダー例

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 は現在テレフォニーをサポートしています。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.5",
  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向け境界です。少なくとも 1 つの画像入力を含めます。テキスト入力は補足コンテキストです。プロダクトPluginは自分のルートとスキーマを所有し、OpenClaw はプロバイダー/ランタイム境界を所有します。
• コアのメディア理解音声設定（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 でオプトインする必要があります。
• 信頼済み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: "A friendly lobster mascot", 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 認証を要求するには "gateway" を使用し、Plugin管理の認証/Webhook 検証には "plugin" を使用します。
• match: 任意。"exact"（デフォルト）または "prefix"。
• replaceExisting: 任意。同じPluginが自身の既存ルート登録を置き換えられるようにします。
• handler: ルートがリクエストを処理した場合に true を返します。

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

​

Plugin SDK インポートパス

• index.js — バンドル済みプラグインエントリ
• api.js — ヘルパー/型バレル
• runtime-api.js — 実行時専用バレル
• setup-entry.js — セットアッププラグインエントリ

​

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

• presentation: セマンティックプレゼンテーションブロック (text, context, divider, buttons, select) 用
• delivery-pin: ピン留め配信リクエスト用

​

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

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

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

​

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

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

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

​

プロバイダーカタログ

• { provider }: 1 つのプロバイダーエントリ
• { 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": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "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: ドキュメントナビゲーションサーフェス向けに、チャネルを内部/非公開としてマークする
• 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", (ctx) => ({
    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", (ctx) => ({
    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. core 契約を定義する core が所有すべき共有動作を決めます。policy、fallback、config merge、lifecycle、channel-facing semantics、runtime helper shape です。
2. 型付き Plugin 登録/ランタイムサーフェスを追加する OpenClawPluginApi および/または api.runtime を、最小限で有用な型付き capability サーフェスで拡張します。
3. core とチャネル/feature consumer を配線する チャネルと feature Plugin は、vendor 実装を直接インポートするのではなく、core を通じて新しい capability を使用すべきです。
4. vendor 実装を登録する その後、vendor Plugin が capability に対して backend を登録します。
5. 契約 coverage を追加する 所有権と登録形状が時間が経っても明示的に保たれるよう、テストを追加します。

​

capability チェックリスト

• src/<capability>/types.ts の core 契約型
• src/<capability>/runtime.ts の core runner/runtime helper
• src/plugins/types.ts の Plugin API 登録サーフェス
• src/plugins/registry.ts の Plugin レジストリ配線
• feature/チャネル Plugin がそれを使用する必要がある場合の src/plugins/runtime/* の Plugin runtime exposure
• src/test-utils/plugin-registration.ts の capture/test helper
• src/plugins/contracts/registry.ts の ownership/contract assertion
• docs/ の operator/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"]);

• core は capability 契約と orchestration を所有する
• vendor Plugin は vendor 実装を所有する
• feature/チャネル Plugin は runtime helper を使用する
• 契約テストは所有権を明示的に保つ

​

関連

• Plugin アーキテクチャ — 公開 capability model と shape
• Plugin SDK サブパス
• Plugin SDK セットアップ
• Plugin の構築